diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index 19a9a092ac..a270e637ab 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -389,10 +389,7 @@ It should instead be simplified to make it easier for everyone to read: - Proper names should be capitalized in the description whenever applicable (e.g. use `A tool for interacting with a Git repository.` instead of ``A tool for interacting with a `git` repository.``). - Acronym expansions (i.e. protocols, tools, etc) must not be translated unless there is a recognized native equivalent for them. -- When documenting keycaps or a keyboard shortcut for a utility, make it stand out in the description: - -1. If it is not translatable, enclose it with backticks (i.e. ``Print the last lines of a given file and keep reading it until `Ctrl + C`:``) -2. If it is translatable, enclose it with double angled brackets inside a placeholder (i.e. ``:wq{{<>}}``). +- When documenting keycaps or a keyboard shortcut for a utility, use the same [keypress syntax](#keypress-syntax) as in example commands. Make sure to enclose it in backticks so that it is not invisible to markdown renderers (i.e. ``Print the last lines of a given file and keep reading it until ``:``). ### Short option mnemonics @@ -492,6 +489,19 @@ When documenting optional placeholders like paths or file extensions, it is sugg - Use `{{path/to/source.ext}}` instead of `{{path/to/source.tar[.gz|.bz2|.xz]}}`. +### Keypress syntax + +To mark keypresses for TUI or GUI programs, use angle brackets `<` and `>`. + +- Single character example: ``. +- Special keys are to be written with [`PascalCase`](https://www.theserverside.com/definition/Pascal-case): ``, ``, ``, ``, ``, `` instead of marking it with shift. Otherwise always mark characters in lowercase. +- Mark simultaneous keypresses inside the same angle brackets separated by a single space: ``, ``, ``, ``. +- Consecutive keypresses need to be contained in their own angle brackets with no space in between: ``, ``, `<~><.>`, ``. +- Keys that are typed into a prompt do not need to be marked as keypresses: `<:>help`. Note that the context switching keypress is marked in angle brackets despite printing on the prompt. + ### Help and version commands - We generally put, **in this order**, the help and version commands as the **last two** examples of the page to highlight more practical commands at the beginning of the page. They can be replaced to accommodate other useful examples if required.