Copy command-line documentation into USAGE.md & add documentation for -additionaldir
#623
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
winterheart
reviewed
Oct 7, 2024
USAGE.md
Outdated
|
|
||
| The following command-line options are available in Descent 3. You can set command-line options on the Misc. tab of the Setup section of the Descent 3 launcher or by creating a shortcut to `Descent3.exe`. Case is not significant in command-line options, and `-`, `--`, and `+` are all accepted. | ||
|
|
||
| <table> |
There was a problem hiding this comment.
Please use markdown-style syntax for table. USAGE.md file is included to source tarball, available to users as file and must be easy to read.
There was a problem hiding this comment.
Do you really think that a Markdown table would be easy to read? I’m looking at the table in BUILD.md right now, and it’s kind of difficult to read because the lines are over 400 characters long. The table in this PR would be even harder to read because the lines would be even longer. Plus, both of the text editors that I tried using defaulted to using word wrap, so I had to disable word wrap before I could start trying to read the table that was in BUILD.md.
There was a problem hiding this comment.
I agree that HTML formatting for a file we ship in releases is not ideal, it's likely to be opened raw in a text editor. To be honest I'm not fond of md tables either, a good old list - option: description is as easy to read on a simple text editor :D
There was a problem hiding this comment.
Do you really think that a Markdown table would be easy to read?
There was a problem hiding this comment.
We can reorder table into plain bullet list like in Linux man pages.
There was a problem hiding this comment.
We can reorder table into plain bullet list like in Linux man pages.
OK, I just pushed a new version of this PR that turns the HTML table into a few Markdown bullet lists. How do you think it looks now?
There was a problem hiding this comment.
OK, I just pushed a new version of this PR that turns the HTML table into a few Markdown bullet lists. How do you think it looks now?
Lgt2x
reviewed
Oct 7, 2024
Jayman2000
added a commit
to Jayman2000/Descent3-pr
that referenced
this pull request
Oct 20, 2024
Before this change, USAGE.md had an HTML table that contained documentation for all of Descent 3’s command-line options. A concern was raised that an HTML table might not be easy to read if someone downloaded Descent 3 and opened USAGE.md in a plain text editor [1]. This commit alleviates that concern by converting the HTML table into bulleted lists. Credit for this idea goes to @Lgt2x [2]. The main motivation behind this change is to help get DescentDevelopers#623 merged. [1]: <DescentDevelopers#623 (comment)> [2]: <DescentDevelopers#623 (comment)>
Jayman2000
force-pushed
the
document-additionaldir
branch
from
44dac2a to
a461d38
Compare
Jayman2000
added a commit
to Jayman2000/nixpkgs-pr
that referenced
this pull request
Nov 13, 2024
By default, Descent 3 will only look for game files in the current working directory. In order to function properly, Descent 3 needs to look for some of its files in the Nix store. This commit creates a wrapper around the main Descent3 executable that automatically looks in the correct path in the Nix store. Hopefully, this wrapper will only exist temporarily. I have an unfinished Descent 3 pull request that adds a DEFAULT_ADDITIONAL_DIRS CMake option [1]. Once I can finish that pull request (DescentDevelopers/Descent3#623 needs to get merged first), we’ll be able to get rid of this wrapper and use DEFAULT_ADDITIONAL_DIRS instead. Additionally, if DescentDevelopers/Descent3#628 gets merged first, then that pull request will also probably make this wrapper unnecessary. [1]: <DescentDevelopers/Descent3#471>
Jayman2000
added a commit
to Jayman2000/nixpkgs-pr
that referenced
this pull request
Nov 14, 2024
By default, Descent 3 will only look for game files in the current working directory. In order to function properly, Descent 3 needs to look for some of its files in the Nix store. This commit creates a wrapper around the main Descent3 executable that automatically looks in the correct path in the Nix store. Hopefully, this wrapper will only exist temporarily. I have an unfinished Descent 3 pull request that adds a DEFAULT_ADDITIONAL_DIRS CMake option [1]. Once I can finish that pull request (DescentDevelopers/Descent3#623 needs to get merged first), we’ll be able to get rid of this wrapper and use DEFAULT_ADDITIONAL_DIRS instead. Additionally, if DescentDevelopers/Descent3#628 gets merged first, then that pull request will also probably make this wrapper unnecessary. [1]: <DescentDevelopers/Descent3#471>
Jayman2000
added a commit
to Jayman2000/nixpkgs-pr
that referenced
this pull request
Nov 15, 2024
By default, Descent 3 will only look for game files in the current working directory. In order to function properly, Descent 3 needs to look for some of its files in the Nix store. This commit creates a wrapper around the main Descent3 executable that automatically looks in the correct path in the Nix store. Hopefully, this wrapper will only exist temporarily. I have an unfinished Descent 3 pull request that adds a DEFAULT_ADDITIONAL_DIRS CMake option [1]. Once I can finish that pull request (DescentDevelopers/Descent3#623 needs to get merged first), we’ll be able to get rid of this wrapper and use DEFAULT_ADDITIONAL_DIRS instead. Additionally, if DescentDevelopers/Descent3#628 gets merged first, then that pull request will also probably make this wrapper unnecessary. [1]: <DescentDevelopers/Descent3#471>
mkg20001
pushed a commit
to mkg20001/nixpkgs
that referenced
this pull request
Dec 17, 2024
By default, Descent 3 will only look for game files in the current working directory. In order to function properly, Descent 3 needs to look for some of its files in the Nix store. This commit creates a wrapper around the main Descent3 executable that automatically looks in the correct path in the Nix store. Hopefully, this wrapper will only exist temporarily. I have an unfinished Descent 3 pull request that adds a DEFAULT_ADDITIONAL_DIRS CMake option [1]. Once I can finish that pull request (DescentDevelopers/Descent3#623 needs to get merged first), we’ll be able to get rid of this wrapper and use DEFAULT_ADDITIONAL_DIRS instead. Additionally, if DescentDevelopers/Descent3#628 gets merged first, then that pull request will also probably make this wrapper unnecessary. [1]: <DescentDevelopers/Descent3#471>
mkg20001
pushed a commit
to mkg20001/nixpkgs
that referenced
this pull request
Dec 17, 2024
By default, Descent 3 will only look for game files in the current working directory. In order to function properly, Descent 3 needs to look for some of its files in the Nix store. This commit creates a wrapper around the main Descent3 executable that automatically looks in the correct path in the Nix store. Hopefully, this wrapper will only exist temporarily. I have an unfinished Descent 3 pull request that adds a DEFAULT_ADDITIONAL_DIRS CMake option [1]. Once I can finish that pull request (DescentDevelopers/Descent3#623 needs to get merged first), we’ll be able to get rid of this wrapper and use DEFAULT_ADDITIONAL_DIRS instead. Additionally, if DescentDevelopers/Descent3#628 gets merged first, then that pull request will also probably make this wrapper unnecessary. [1]: <DescentDevelopers/Descent3#471>
Before this change, USAGE.md said that -dedicated was a boolean option and that it took 0 arguments. This is not correct, and it contradicts the wiki’s documentation for -dedicated [1]. This commit fixes that issue. [1]: <https://github.com/DescentDevelopers/Descent3/wiki/Running-Descent-3#command-line-options>
Before this change, the documentation for the command-line options that take arguments was inconsistent. There was a <placeholder> in the “option” cell for almost all of the command-line options that take arguments. -display was the only command-line option that takes arguments that didn’t have a <placeholder>. This change makes the documentation more consistent by ensuring that all command-line options that take arguments have <placeholders>.
This commit takes all of the command-line options documentation from the wiki [1] and merges it with the command-line options documentation that’s in USAGE.md. This change will eventually allow us to remove the command-line options documentation from the wiki so that we only have one list of command-line options instead of two. Before this change, USAGE.md used a Markdown table and the wiki used an HTML table. I ended up replacing the Markdown table in USAGE.md with an HTML table because it was easier to copy and paste the HTML table from the wiki than to convert the HTML table from the wiki into a Markdown table. The main motivation behind this change is to make it easier to create a future commit. That future commit will add documentation for the -additionaldir command-line option. Making sure that there’s only one list of command-line options instead of two will make it so that -additionaldir doesn’t need to be documented in two different places. This is related DescentDevelopers#618, but it doesn’t fully fix that issue. [1]: <https://github.com/DescentDevelopers/Descent3/wiki/Running-Descent-3#command-line-options>
Before this change, the documentation for -logfile did not format its code spans correctly. Specifically, it used back ticks to create code spans. Unfortunately, you can’t create code spans using back ticks if the code spans are embedded in an HTML block. This change fixes the formatting by replacing the back ticks with <code> and </code>.
Before this change, USAGE.md talked about “main.exe”. In Descent 3 v1.4.0, there was indeed an executable named MAIN.EXE. However, that executable was renamed to Descent3.exe in v1.5.0.
Before this change, USAGE.md had an HTML table that contained documentation for all of Descent 3’s command-line options. A concern was raised that an HTML table might not be easy to read if someone downloaded Descent 3 and opened USAGE.md in a plain text editor [1]. This commit alleviates that concern by converting the HTML table into bulleted lists. Credit for this idea goes to @Lgt2x [2]. The main motivation behind this change is to help get DescentDevelopers#623 merged. [1]: <DescentDevelopers#623 (comment)> [2]: <DescentDevelopers#623 (comment)>
Jayman2000
force-pushed
the
document-additionaldir
branch
from
a461d38 to
d45576c
Compare
|
I pushed a new version of this PR that resolves merge conflicts. The new version also adds a new commit titled “Add missing <placeholder> for -display”. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request Type
Description
This pull request takes the table of command-line options that’s on the wiki and merges it with the one in
USAGE.md. It also adds documentation for the-additionaldircommand-line option.Related Issues
This is related #618, but it doesn’t fully fix that issue.
Checklist
Additional Comments