lilith/tldr
1
0
Fork 0
mirror of https://github.com/tldr-pages/tldr.git synced 2025-04-29 23:24:55 +02:00
Code Activity

style-guide: add keypress documentation instructions. (#15798)

Browse source 
Co-authored-by: Machiavelli <145562237+MachiavelliII@users.noreply.github.com>
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
This commit is contained in:
Managor 2025-03-05 01:42:24 +02:00 • committed by GitHub
parent c0a8d5a576
commit 8b686dc8b1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 14 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
contributing-guides/style-guide.md
View file

@ -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{{<<Enter>>}}``).
- 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 `<Ctrl c>`:``).
### 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: `<a>`.
- Special keys are to be written with [`PascalCase`](https://www.theserverside.com/definition/Pascal-case): `<Ctrl>`, `<Super>`, `<Alt>`, `<Shift>`, `<Cmd>`, `<Option>`, `<Windows>`, `<Enter>`, `<Home>`, `<Space>`, `<Esc>`, `<ArrowUp>`, `<ArrowLeft>`, `<ArrowKeys>`, `<PageUp>`, `<F5>`, `<F12>`, `<LeftClick>`, `<MiddleClick>`, ...
- When writing simultaneous keypresses, keep the following order: `<Ctrl>` -> `<Super>` / `<Windows>` -> `<Alt>` -> `<AltGr>` -> `<Shift>` -> everything else.
- Special keys can be translated if they have culturally relevant translations.
- When a program takes in uppercase character literals mark them as `<A>` 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: `<Ctrl c>`, `<Alt F4>`, `<Ctrl Shift k>`, `<Super Shift PrtSc>`.
- Consecutive keypresses need to be contained in their own angle brackets with no space in between: `<Esc><u>`, `<Ctrl k><Ctrl s>`, `<Enter><~><.>`, `<d><o>`.
- Keys that are typed into a prompt do not need to be marked as keypresses: `<:>help<Enter>`. 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.