Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Encourage using long parameter options and mnemonic tags in our style guide #8304

Closed
reinhart1010 opened this issue Aug 5, 2022 · 3 comments

Comments

@reinhart1010
Copy link
Collaborator

reinhart1010 commented Aug 5, 2022

There's another two writing rules, undocumented on our style guide which we have also practiced instead in reviewing pull requests for new pages:

  1. Prefer long parameter formats (e.g. --verbose instead of -v) as possible,
  2. When the documented program does not include long parameter formats, documenters may use parameter mnemonic tags (e.g. [v]erbose)

Which I personally liked, and in order to standardize how we should treat these cases we should put them in our style guide.

This is because most of our documented commands practiced at least one of these conventions:

  1. The convention deriving from DOS where all parameters are used using forward slashes, such as cd {{path/to/directory}} /d to switch directories.
  2. The Unix-like convention as accepted by many major, cross-platform apps, such as firefox --profile profile1 and git --help.
  3. The PowerShell convention where long parameters are also using single dash instead of 2 in Unix, like Invoke-WebRequest -Method Post -Body @{ name='bob' } http://example.com/form

Where many (1)-type commands may not introduce long parameter formats, as discussed on #8201, while some (2)-type commands also don't introduce long parameters as well, like in #8200. Here are some examples for the case of slmgr.vbs (#8201)

- Display the current license's e[xp]i[r]ation date and time:

`slmgr /xpr`

- [c]lears the current license's [p]roduct [k]e[y] from the Windows Registry. This will not deactivate or uninstall the current license, but prevents the key from being stolen by malicious programs in the future:

`slmgr /cpky`

Mnemonic tags aren't mandatory for translations as well. However, when including these tags into translations, make sure that the the tags do correspond to the same terms as in the English version or the original language where these short parameters correspond to the terms of the language (e.g. [c] for [c]arregar in Portuguese-based programs).

For example, in #8298,

- Hentikan hak akses terhadap [g]rup untuk mengeksekusi suatu file:

`chmod g-x {{jalan/menuju/file}}`
@marchersimon
Copy link
Collaborator

We actually have documented that we prefer long options in CONTRIBUTING.md. But we should definitively move this to the style guide.

@github-actions github-actions bot added the Stale label Sep 20, 2022
@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Dec 30, 2022
@kbdharun kbdharun reopened this Dec 30, 2022
@EmilyGraceSeville7cf
Copy link
Contributor

EmilyGraceSeville7cf commented Dec 30, 2022

@reinhart1010, long portable options are required now in style guide. Mnemonics are gonna to be allowed and mandated for everything, check out my PR. :)

@vitorhcl
Copy link
Member

vitorhcl commented Jan 2, 2024

Fixed by #11619

@vitorhcl vitorhcl closed this as completed Jan 2, 2024
@kbdharun kbdharun moved this from Todo to Done in Roadmap May 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

No branches or pull requests

5 participants