* [: use posix-compliant example for equals comparison
the previous example worked fine for bash, but some
other shells (zsh, in my case) will not work when
using "==" for comparison. the posix spec only requires
"=", so I think it makes a little more sense to use
that in the example.
* test: use posix-compliant example for equals comparison
the previous example worked fine for bash, but some
other shells (zsh, in my case) will not work when
using "==" for comparison. the posix spec only requires
"=", so I think it makes a little more sense to use
that in the example.
* *: fix typos in command names
* command name fixes in other languages
* fix incorrectly translated commands
* change incorrect file name
* qm move disk alias pages
---------
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
* ipconfig: add German translation
* change descriptions to imperative form
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
---------
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* ollama: add page
* ollama: move page to common
* ollama: add example for running a model with a single prompt
* Update pages/common/ollama.md
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
---------
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
* scripts/test.sh: remove TLDR005 from ignore list for languages
* scripts/test.sh: ignore TLDR005 in Chinese pages
* scripts/test.sh: fix indentation
* scripts/test.sh: reorder ignore list
* add: unimatrix
* Update pages/common/unimatrix.md
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* Update pages/common/unimatrix.md
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* use long options instead
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* correct typo
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* use long options instead
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* use long options instead
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* correct formatting
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* correct formatting
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
* realign order of args
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
* change examples to show clearer opts
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* rephrase program purpose
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* remove optional `=` from args
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
---------
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* readonly, {un,}compress, zbarcam: use proper syntax for IO streams
* style-guide: add guidelines for standard streams
* duckdb, perl: add backticks around stdin and stdout
Option --list-targets is no longer available in the recent versions of pw-record; in order to list objects use either wpctl status or pw-cli ls or pw-dump instead.
https://wiki.archlinux.org/title/PipeWire#Microphone_is_not_detected_by_PipeWire
Co-authored-by: Managor <42655600+Managor@users.noreply.github.com>
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
* ac: add missing comma in German translation
* Use imperative wording ("Zeigt" => "Zeige")
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
---------
Co-authored-by: Juri Dispan <juri.dispan@posteo.net>
* CI/codespell: revert changed-files action removal
This reverts commit eca9c1e539 from #10704.
Post this change codespell doesn't show annotations for the PR contents
as it now scanning the whole pages directory and completes execution
after showing a limited number of strings. This effectively made
Codespell unusable. Therefore I have reverted the change to fix
Codespell, the only issue being this would reintroduce the false
detection with annotations being
made in translation PRs on non-English pages.
* CI/codespell: use point release instead of master
Using the development branch isn't ideal for production as it is prone to breakage with a faulty bug or PR. So in this commit, I am updating the codespell action to use the point release instead for more stability and versatility.
Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
---------
Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
* [ko]: add rsync.md for common
* [ko]: update rsync.md
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
---------
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
* dir: update Dutch translation
* Update pages.nl/windows/dir.md
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
* Update pages.nl/windows/dir.md
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
---------
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
* winget: add Hindi translation
---------
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
* az-*: update links and page description
* az-aks: update link and page description
* az-*: fix typos in Spanish translation
* az-*: update links and description in Spanish translation
* style-guide: use the new note syntax
* MAINTAINERS: use the new note syntax, use full month names
* CONTRIBUTING: use the new note syntax
* maintainers-guide: use the new note syntax
* CLIENT-SPECIFICATION: use the new note syntax
* COMMUNITY-ROLES: use the new note syntax
* git-terminal: use the new note syntax
---------
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
* Adding an az-acr commands lists
* Removing white spaces and heading formating
* Removing whitespaces
* Adding a new line in end of the file
* Removing unnecessary lines
* Update pages/common/az-acr.md
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
---------
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
* windows: dir: add "bare" format
Add "dir /B" to the cheat sheet. It is quite useful for creating file
lists, playlists and the like, without having to manually mangle the
output.
* Change parameters to lowercase and reword description
As I understand the documentation, 'module' is more specific:
https://docs.npmjs.com/about-packages-and-modules
Note that the 'package' term is used in CLI help:
$ npm install --help
Install a package
Usage:
npm install [<package-spec> ...]
* gh-repo: update the command
The flags changed around listing source repositories. This change reflects that.
* Update pages/common/gh-repo.md
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
---------
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
* Adding page for resolvconf command
* Added trailing newline that was causing test failure
* Added additional information on the command.
* Added additional information on the command.
* Removed the postconf file.
* addressed comments
* magick: update resizing example
Update according to the example on https://imagemagick.org/Usage/resize/
---------
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* convert to f string
* use a next function instead of a for-loop
* remove uneeded else statement
* use in operator instead of multi comparison
* conver to f string
* adds extra line between function defs
* revert/change to PR comment around looping
* remove uneeded loops
* revert to keep old style choice
Co-authored-by: Jack Lin <blueskyson1401@gmail.com>
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* stylua: add page
* stylua: adopt suggestions
- Grammar fix in description
- Different way to get input file to stdin
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
---------
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
* CI/codespell: remove changed-files action
Superseeds #10704
This change would make the CI run only on English pages by directly passing the path to Codespell to prevent false detections like https://github.com/tldr-pages/tldr/pull/10702/files for other languages, There still would be annotations made for other English pages not in PR similar to now, but it won't prevent us from merging the PR as we have the only_warn parameter set to 1.
* CI/codespell: use point release instead of master
Using the development branch isn't ideal for production as it is prone to breakage with a faulty bug or PR. So in this commit, I am updating the codespell action to use the point release instead for more stability and versatility.
* iptables: adding `--line-numbers` to list example
* iptables: use long options, add backticks
---------
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
This document contains the official specification for tldr-pages clients. It is _not_ a specification of the format of the pages themselves - only a specification of how a user should be able to interface with an official client. For a list of previous versions of the specification, see the [changelog section](#Changelog) below.
This document contains the official specification for tldr-pages clients. It is _not_ a specification of the format of the pages themselves - only a specification of how a user should be able to interface with an official client. For a list of previous versions of the specification, see the [changelog section](#changelog) below.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
## Terminology
This section defines key terms that are relevant for understanding this specification document.
@ -24,7 +23,6 @@ If a page is common across multiple platforms, but slightly different on a given
For example, if the command `foo` is common to `mac`, `windows`, and `linux` but functions differently on `windows`, then the main page will be stored in `common`, and a copy will be placed in `windows` that's altered to match the different functionality.
## Command-line interface
This section describes the standardised command-line interface (CLI) for clients implementing one. Clients that do not provide a CLI can ignore this section.
@ -78,12 +76,12 @@ This section documents the directory structure that contains the pages themselve
The main version of every page is stored inside (but not directly) the `pages` directory. Inside this directory, there is a folder for each platform - for example `windows`, `linux`, and the special `common` platform:
- `pages/`
- `common/`
- `linux/`
- `windows/`
- `osx/`
- ...etc.
- `pages/`
- `common/`
- `linux/`
- `windows/`
- `osx/`
- ...etc.
It is RECOMMENDED that clients support `macos` as an alias for `osx`.
@ -97,27 +95,30 @@ Command name | Mapped name | Filename
Other directories sit alongside the main `pages` directory, and contain translations of the main versions of every page - though pages MAY NOT have a translation available for a given language yet. Furthermore, a given language MAY NOT have a folder yet either. The format of these directories is `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>_<country>`, where:
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
Some examples:
- Chinese (Taiwan): `pages.zh_TW`.
- Portuguese (Brazil): `pages.pt_BR`.
- Italian: `pages.it`.
- Chinese (Taiwan): `pages.zh_TW`.
- Portuguese (Brazil): `pages.pt_BR`.
- Italian: `pages.it`.
The structure inside these translation folders is identical to that of the main `pages` folder.
## Page structure
Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), which the exception of the non-standard `{{` and `}}` syntax, which surrounds values in an example that users may edit. Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), with the exception of the non-standard `{{` and `}}`placeholder syntax, which surrounds values in an example that users may edit. Clients MAY highlight the placeholders and MUST remove the surrounding curly braces. Clients MUST NOT treat them as the placeholder syntax if they are escaped using `\` (i.e. `\{\{` and `\}\}`) and MUST instead display literal braces, without backslashes. Placeholder escaping applies only when both braces are escaped (e.g. in `\{` or `\{{`, backslashes MUST be displayed). Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
### Examples
- `ping {{example.com}}` MUST be rendered as "ping example.com"
- `docker inspect --format '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' {{container}}` MUST be rendered as "docker inspect --format '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container"
- `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\\\computer_name\share_name Z:"
## Page resolution
@ -125,12 +126,13 @@ This section defines the algorithm by which a client can decide which page a use
After transparently replacing spaces (` `) with dashes (`-`) and lowercasing the name, clients have several decisions to make:
- The language of a page to display to a client
- The platform to display a page from
- The language of a page to display to a client
- The platform to display a page from
### Platform
Clients MUST default to displaying the page associated with the platform on which the client is running.
For example, a client running on _Windows 11_ will default to displaying pages from the `windows` platform.
Clients MAY provide a user-configurable option to override this behaviour, however.
@ -149,6 +151,8 @@ Steps #3 and #4 may be done in either order.
It is possible that due to this page resolution logic, the client may show a page which does not belong to the host platform because a page can reside in `common`, and not be present on the host platform. Clients must not assume that a given command is always executable on the host platform.
It is RECOMMENDED that clients detect new platforms added to the relevant `pages` directory automatically.
#### If a page is not found
If a page cannot be found in _any_ platform, then it is RECOMMENDED that clients display an error message with a link to create a new issue against the `tldr-pages/tldr` GitHub repository. Said link might take the following form:
@ -163,7 +167,6 @@ where `{command_name}` is the name of the command that was not found. Clients th
If multiple versions of a page were found for different platforms, then a client MAY choose to display a notice to the user notifying them of this.
## Language
Pages can be written in multiple languages. If a client has access to environment variables, it MUST use them to derive the preferred user language as described in the next paragraphs. If not, then clients MUST make reasonable assumptions based on the information provided by the environment in which they operate (e.g. consulting `navigator.languages` in a browser, etc.).
@ -194,16 +197,19 @@ It is also RECOMMENDED to make the language configurable, to not only rely on th
The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value to determine the language in which interface text is shown (separately from the language used for pages). In the absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead.
**Note that** for page lookup it is highly RECOMMENDED to give precedence to the platform over the language. In other words, look for a platform under each language, before checking the next preferred language. This ensures a meaningful and correct page resolution.
> [!IMPORTANT]
> For page lookup it is highly RECOMMENDED to give precedence to the platform over the language. In other words, look for a platform under each language, before checking the next preferred language. This ensures a meaningful and correct page resolution.
Here's an example of how the lookup should be done on `linux` having set `LANG=it` and `LANGUAGE="it:fr:en"`:
@ -211,7 +217,6 @@ If appropriate, it is RECOMMENDED that clients implement a cache of pages. If im
Caching SHOULD be done according to the user's language configuration (if any), to not waste unneeded space for unused languages. Additionally, clients MAY automatically update the cache regularly.
## Changelog
<!--
@ -225,35 +230,40 @@ including the changes. NOTE: tagging of the commit with a new version tag (in
the form `vX.Y`) should be done immediately AFTER merging the version bump, as
the commit hash changes when merging with squash or rebase.
-->
- Unreleased
- [v2.0, September 10th 2023](https://github.com/tldr-pages/tldr/blob/v2.0/CLIENT-SPECIFICATION.md) ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
- Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514))
- Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561))
- Drop the `master` branch from the assets link. ([#9668](https://github.com/tldr-pages/tldr/pull/9668))
- Require support for long options ([#9651](https://github.com/tldr-pages/tldr/pull/9651))
- Add recommendation to support caching individual translation archives ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
- Unreleased
- [v1.5, March 17th 2021](https://github.com/tldr-pages/tldr/blob/v1.5/CLIENT-SPECIFICATION.md) ([#5428](https://github.com/tldr-pages/tldr/pull/5428))
- Add requirement for converting command names to lowercase before running the page resolution algorithm.
- Use HTTPS for archive links.
- [v2.1, November 30th 2023](https://github.com/tldr-pages/tldr/blob/v2.1/CLIENT-SPECIFICATION.md) ([#11523](https://github.com/tldr-pages/tldr/pull/11523))
- Add requirement to support escaping the placeholder syntax in certain pages ([#10730](https://github.com/tldr-pages/tldr/pull/10730))
- Add suggestion to detect new platforms added to the relevant `pages` directory automatically ([#11523](https://github.com/tldr-pages/tldr/pull/11523))
- [v1.4, August 13th 2020](https://github.com/tldr-pages/tldr/blob/v1.4/CLIENT-SPECIFICATION.md) ([#4246](https://github.com/tldr-pages/tldr/pull/4246))
- Add requirement for CLI clients to use non-zero exit code on failing to find a page.
- [v2.0, September 10th 2023](https://github.com/tldr-pages/tldr/blob/v2.0/CLIENT-SPECIFICATION.md) ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
- Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514))
- Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561))
- Drop the `master` branch from the assets link. ([#9668](https://github.com/tldr-pages/tldr/pull/9668))
- Require support for long options ([#9651](https://github.com/tldr-pages/tldr/pull/9651))
- Add recommendation to support caching individual translation archives ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
- [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/v1.3/CLIENT-SPECIFICATION.md) ([#4101](https://github.com/tldr-pages/tldr/pull/4101))
- Clarified fallback to English in the language resolution algorithm.
- Update the `LANG` and `LANGUAGE` environment variables to conform to the GNU spec.
- [v1.5, March 17th 2021](https://github.com/tldr-pages/tldr/blob/v1.5/CLIENT-SPECIFICATION.md) ([#5428](https://github.com/tldr-pages/tldr/pull/5428))
- Add requirement for converting command names to lowercase before running the page resolution algorithm.
- Use HTTPS for archive links.
- [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/v1.2/CLIENT-SPECIFICATION.md) ([#3168](https://github.com/tldr-pages/tldr/pull/3168))
- Addition of a new `-L, --language` recommended command-line option.
- Rewording of the language section, also encouraging the use of configuration files for language.
- Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**.
- Clearer clarification about the recommended caching functionality.
- Correction of the usage of the term "arguments" in the homonym section.
- [v1.4, August 13th 2020](https://github.com/tldr-pages/tldr/blob/v1.4/CLIENT-SPECIFICATION.md) ([#4246](https://github.com/tldr-pages/tldr/pull/4246))
- Add requirement for CLI clients to use non-zero exit code on failing to find a page.
- [v1.1, April 1st 2019](https://github.com/tldr-pages/tldr/blob/v1.1/CLIENT-SPECIFICATION.md) (deprecated) ([#2859](https://github.com/tldr-pages/tldr/pull/2859))
- Clarified platform section.
- [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/v1.3/CLIENT-SPECIFICATION.md) ([#4101](https://github.com/tldr-pages/tldr/pull/4101))
- Clarified fallback to English in the language resolution algorithm.
- Update the `LANG` and `LANGUAGE` environment variables to conform to the GNU spec.
- [v1.0, January 23rd 2019](https://github.com/tldr-pages/tldr/blob/v1.0/CLIENT-SPECIFICATION.md) (deprecated) ([#2706](https://github.com/tldr-pages/tldr/pull/2706))
- Initial release.
- [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/v1.2/CLIENT-SPECIFICATION.md) ([#3168](https://github.com/tldr-pages/tldr/pull/3168))
- Addition of a new `-L, --language` recommended command-line option.
- Rewording of the language section, also encouraging the use of configuration files for language.
- Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**.
- Clearer clarification about the recommended caching functionality.
- Correction of the usage of the term "arguments" in the homonym section.
- [v1.1, April 1st 2019](https://github.com/tldr-pages/tldr/blob/v1.1/CLIENT-SPECIFICATION.md) (deprecated) ([#2859](https://github.com/tldr-pages/tldr/pull/2859))
- Clarified platform section.
- [v1.0, January 23rd 2019](https://github.com/tldr-pages/tldr/blob/v1.0/CLIENT-SPECIFICATION.md) (deprecated) ([#2706](https://github.com/tldr-pages/tldr/pull/2706))
@ -46,8 +46,9 @@ exceptions can always be considered, via open community discussion.)
This means they will be able to
push commits to all of the organization's repositories,
merge PRs, label and close issues, among other things.
_Note_: All members of the tldr-pages organization
must make their membership public.
> [!NOTE]
> All members of the tldr-pages organization
> must make their membership public.
- **Organization members who remain active for a while should become organization owners.**
Specifically: members of the tldr-pages organization
@ -78,8 +79,9 @@ exceptions can always be considered, via open community discussion.)
## How to change roles
*Note: This section is aimed at owners in the tldr-pages organization
(i.e. the group of people who are able to perform these changes).*
> [!NOTE]
> This section is aimed at owners in the tldr-pages organization
> (i.e. the group of people who are able to perform these changes).
If you notice a contributor being particularly active,
review their recent contributions to check whether a role transition is due,
@ -129,7 +131,7 @@ using one of the template messages below as a base.
If you accept the invitation, we ask you to make your membership public, and (in case you don't already) start hanging out in our [Matrix chat room](https://matrix.to/#/#tldr-pages:matrix.org).
Additionally, consider subscribing to the notifications from the various repositories under the [tldr-pages organization](https://github.com/tldr-pages).
As one of the public faces of the tldr-pages project, it's also especially important that you follow and encourage the [project
@ -201,3 +203,17 @@ Any member of the community can (and is encouraged to) propose role changes
by following the process outlined [above](#how-to-change-roles).
[Owners of the tldr-pages organization](MAINTAINERS.md#organization-owners)
can then perform the actual role changes.
## CODEOWNERS
The [`.github/CODEOWNERS` file](https://github.com/tldr-pages/tldr/blob/main/.github/CODEOWNERS) allows contributors with write access to the [tldr-pages/tldr repository](https://github.com/tldr-pages/tldr) to get automatic review request notifications for given files and directories.
If they wish to, contributors can open a pull request to add themselves to this file as desired.
Example uses include (but are not limited to):
- Contributors who speak a specific language and want to assist with reviewing translations in those specific languages.
- Contributors with specific expertise who wish to review pull requests for specific platforms.
- Contributors interested in reviewing [client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) updates.
> [!NOTE]
> This mechanism is purely for automatic review requests for PRs and doesn't grant collaborators additional copyright over the code-owned files. View the [LICENSE](https://github.com/tldr-pages/tldr/blob/main/LICENSE.md) file for more information.
*Note*: when submitting a new command, please base your PR against the `main` branch, and check if there's already a pull request in progress for it.
> [!NOTE]
> When submitting a new command, please base your PR against the `main` branch and check if there's already a pull request in progress for it.
## Guidelines
The basic format of a `tldr` page is a set of concrete usage examples.
Here are a few guidelines to get started:
1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate, but don't exceed 8 examples.
1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate, but don't exceed the maximum of eight examples.
Remember, it's OK if the page doesn't cover everything; that's what `man` is for.
2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
For example, commands that require `sudo` should include it directly in the examples.
3. Try to incorporate the spelled-out version of single-letter options in the example's description.
The goal is to allow people to *understand* the syntax of the commands, not just *memorize* it.
4. Introduce options gradually, starting with the simplest command invocations,
and using more complex examples progressively.
5. Focus on details specific to the command, and avoid explaining general UNIX concepts that could apply to any command
(ex: relative/absolute paths, glob patterns/wildcards, special character escaping...).
4. Introduce options gradually, starting with the simplest command invocations and using more complex examples progressively.
5. Focus on details specific to the command and avoid explaining general UNIX concepts that could apply to any command
(i.e. relative/absolute paths, glob patterns/wildcards, special character escaping, ...).
These are all guidelines, not strict rules.
Use proper judgement, keeping simplicity and user-friendliness as the top priorities.
@ -50,7 +52,7 @@ When in doubt, have a look at a few existing pages :).
As a quick reference, the format of each page should match the following template:
```
```md
# command-name
> Short, snappy description.
@ -66,12 +68,18 @@ As a quick reference, the format of each page should match the following templat
`command --option1 --option2 {{arg_value}}`
```
For page descriptions, you can additionally use ``See also: `command`.`` and [subcommand reference](#subcommands).
> [!NOTE]
> While we suggest only two lines for the page description, it is acceptable to have more than two lines if it necessary to add additional information (i.e. [`pacman`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/pacman.md)).
To see some examples of preexisting pages, you can look at:
- [pwd](https://github.com/tldr-pages/tldr/blob/main/pages/common/pwd.md) - one of the simplest command examples
- [tar](https://github.com/tldr-pages/tldr/blob/main/pages/common/tar.md) - page with placeholders
- [tar](https://github.com/tldr-pages/tldr/blob/main/pages/common/tar.md) - page with placeholders
In our pages, we use placeholders defined as being tokens within curly brackets. For example, in `sleep {{5}}`, the user can change 5 to any number.
In our pages, we use placeholders which are defined as being tokens within curly brackets, for example `sleep {{5}}`, in this case the user can change 5 to any number.
Other examples but not limited to of our placeholder syntax are:
- `{{path/to/directory}}`
@ -83,84 +91,129 @@ refer to the [style guide](contributing-guides/style-guide.md).
## Subcommands
Many programs use subcommands for separating functionality, which may require their own separate pages.
For instance, `git commit` has its own page, as well as `git push` and many others.
To create a page for a subcommand, the program and subcommand need to be separated with a dash (`-`), so `git-commit.md` is shown when calling `tldr git commit`.
You should always add a base page (e.g. `git`) that describes the program and basic switches like `--version` or `--help`.
To let users know about the subcommand, add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the base page.
To let others know about the subcommand, add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the base page.
See these examples for reference:
* [git](pages/common/git.md)
* [git-commit](pages/common/git-commit.md)
* [aws](pages/common/aws.md)
* [aws-s3](pages/common/aws-s3.md)
- [git](pages/common/git.md)
- [git-commit](pages/common/git-commit.md)
- [aws](pages/common/aws.md)
- [aws-s3](pages/common/aws-s3.md)
## Translations
Translation of pages can be done by simply creating the corresponding page within the appropriate language-specific directory, creating that as well if it does not already exist.
> [!IMPORTANT]
> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages doesn't exist for the command, it should be added first in a PR before creating a translation.
Language specific directories must follow the pattern `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>[_<country>]`, where:
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
The `<country>` code is optional and should only be added when it is needed. In other words, only when there is a valid reason to distinguish between a language (`ll`) and its regional dialects (`ll_CC1`, `ll_CC2`, etc.). As an example, both `fr_FR` and `fr_BE` should fall under the same `pages.fr` directory, since there virtually is no difference in writing between standard French and Belgian French.
The `<country>` code is optional and should only be added when it is needed. In other words, only when there is a valid reason to distinguish between a language (`ll`) and its regional dialects (`ll_CC1`, `ll_CC2`, etc.). For example, both `fr_FR` and `fr_BE` should fall under the same `pages.fr` directory since there virtually is no difference in writing between standard French and Belgian French.
> [!IMPORTANT]
> When adding a new language to `tldr`, it is suggested to add it to the [translation templates](contributing-guides/translation-templates) along with any page additions.
To see the current progress of all translations, you can visit <https://lukwebsforge.github.io/tldri18n/>, which provides a dynamically updated table of all pages and their translations.
Some examples of valid locale tags:
- French: `fr`.
- Chinese: `zh`.
- Chinese (Singapore): `zh_SG`.
- Portuguese (Brazil): `pt_BR`.
- French: `fr`.
- Chinese: `zh`.
- Chinese (Singapore): `zh_SG`.
- Portuguese (Brazil): `pt_BR`.
A list of translated templates for alias pages can be found in [here](contributing-guides/translation-templates/alias-pages.md).
A list of translated templates for alias pages can be found [here](contributing-guides/translation-templates/alias-pages.md).
Pull requests that introduce translations are the exception to the single file change per Pull Request rule. It is
acceptable for several pages to be translated in one pull request.
It is acceptable for several pages to get translated in one pull request.
### Default language for newly added pages
The default language used for pages is English (US). Pages written in English are stored in the default `pages` directory (notice the absence of a specific language tag). Although not strictly required, if you'd like to add a new page in a different language, please consider creating the English page too.
For more information about language specific rules, refer to the [style guide](contributing-guides/style-guide.md#language-specific-rules).
## Inclusive language
Where possible, use inclusive language in the content of pages. For example, prefer terms like "denylist"/"allowlist" instead of "blacklist"/"whitelist", "primary"/"secondary" instead of "master"/"slave", "they" instead of "him"/"her", etc.
Of course, this shouldn't sacrifice content clarity, such as when documenting tools where this terminology has specific technical meanings, and its usage is central to explaining the involved concepts.
Of course, this shouldn't sacrifice content clarity, such as when documenting tools where this terminology has specific technical meanings and its usage is central to explaining the involved concepts.
## Submitting a pull request
The easiest way to submit a change is to just edit the page directly on the GitHub interface.
### Testing pages locally
Once you have written a `tldr` page, you can test its syntax locally using [`tldr-lint`](https://github.com/tldr-pages/tldr-lint).
The latest version of [NodeJS](https://nodejs.org) is required to install `tldr-lint` with the following command:
```sh
npm install --global tldr-lint
```
Once its installed, you can test your page by running the following command:
```sh
tldr-lint {{path/to/page.md}}
```
Now, you are ready to submit a pull request!
> [!TIP]
> Additionally, inside the `tldr` directory you can install the dependencies using `npm install` command and now when you commit your changes, the tests will run automatically via the pre-commit hook.
### Submitting changes
The easiest way to submit a change is to edit the page directly on the GitHub interface.
Check out the step-by-step instructions (with screenshots) on
[using Git on the command-line](contributing-guides/git-terminal.md).
> [!TIP]
> After creating a pull request, it is suggested to enable the "Allow edits by maintainers" option (This only needs to be done once the first time you create a PR). It allows maintainers to make changes to your pull request and assist you in getting it merged.
### Accepting suggestions within a pull request
The easiest way to apply suggested changes is to accept the suggestion made on your pull request. Refer to the [GitHub docs](https://docs.github.com/en/enterprise-server@3.2/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) for more details.
The easiest way to apply suggested changes is to accept the suggestion made on your pull request. Refer to the [GitHub docs](https://docs.github.com/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) for more details.
To commit a suggestion to your pull request, simply click on `Commit suggestion`:
To commit a suggestion to your pull request, click on `Commit suggestion`:
If you want to commit multiple suggestions, go to the "Files changed" tab and batch all suggestions. Now, click `Commit suggestions` button and enter a commit message to create a single commit.
### Commit message
For the commit message, use the following format:
For the commit message of page changes, use the following format:
<command>: type of change
`{{command}}: type of change`
Examples:
- For a new page addition: `ls: add page`
- For a page edit: `cat: fix typo`, `git-push: add --force example`
- For a new translation of an existing page: `cp: add Tamil translation`
- For related changes to several pages: `grep, find, locate: synchronize format of wildcards`
Where `{{command}}` is the name of the command being modified, and `type of change` can be (but not limited to) one of the following examples:
- For a new page addition: `ls: add page`, `docker-container-rm: add alias page`
- For a page edit: `cat: fix typo`, `git-push: add --force example`
- For a new translation of an existing page: `cp: add Tamil translation`
- For a modification to the translation of an existing page: `cp: fix typo in Tamil translation`
- For related changes to several pages: `grep, find, locate: synchronize format of wildcards`
[11 April 2019](https://github.com/tldr-pages/tldr/issues/2898) — [17 January 2020](https://github.com/tldr-pages/tldr/issues/3764), [7 February 2023](https://github.com/tldr-pages/tldr/issues/10674) — present
[9 January 2021](https://github.com/tldr-pages/tldr/issues/5122) — [18 March 2021](https://github.com/tldr-pages/tldr/issues/5473), [15 November 2023](https://github.com/tldr-pages/tldr/issues/11509) — present
- **Marcher Simon ([@marchersimon](https://github.com/marchersimon))**:
[9 March 2021](https://github.com/tldr-pages/tldr/issues/5390) — [9 April 2021](https://github.com/tldr-pages/tldr/issues/5722), [20 November 2023](https://github.com/tldr-pages/tldr/issues/11381) — present
[27 Aug 2021](https://github.com/tldr-pages/tldr/issues/6415) — [16 October 2022](https://github.com/tldr-pages/tldr/pull/9072#issuecomment-1279847932)
[27 August 2021](https://github.com/tldr-pages/tldr/issues/6415) — [16 October 2022](https://github.com/tldr-pages/tldr/pull/9072#issuecomment-1279847932)
[19 January 2022](https://github.com/tldr-pages/tldr/issues/1209#issuecomment-285924778) — [24 April 2022](https://github.com/tldr-pages/tldr/issues/8053)
@ -27,19 +27,23 @@ to traditional [man pages](https://en.wikipedia.org/wiki/Man_page).
Maybe you're new to the command-line world? Perhaps you're just a little rusty or can't always recall the arguments for commands like `lsof`, or `tar`?
It certainly doesn't help that the first option explained in `man tar` is:
It certainly doesn't help that, in the past, the first option explained in `man tar` was:
```
```console
$ man tar
...
-b blocksize
Specify the block size, in 512-byte records, for tape drive I/O.
As a rule, this argument is only needed when reading from or writing to tape drives,
and usually not even then as the default block size of 20 records (10240 bytes) is very common.
...
```
There seems to be room for simpler help pages, focused on practical examples.
How about:
This repository is just that: an ever-growing collection of examples
for the most common UNIX, Linux, macOS, SunOS, Android and Windows command-line tools.
@ -54,16 +58,16 @@ which is supported by the tldr-pages project maintainers:
npm install -g tldr
```
Alternatively, you can also use the [Python client](https://github.com/tldr-pages/tldr-python-client), which can be installed via `pip3`.
Alternatively, you can also use the official [Python client](https://github.com/tldr-pages/tldr-python-client), which can be installed via [pip3](https://pypi.org/project/tldr/).
```sh
```shell
pip3 install tldr
```
Or Mac users can also install our [C Client](https://github.com/tldr-pages/tldr-c-client) using Homebrew.
Or Linux and Mac users can also install the official [Rust Client](https://github.com/tldr-pages/tlrc) using [Homebrew](https://formulae.brew.sh/formula/tlrc):
```sh
brew install tldr
```shell
brew install tlrc
```
Then you have direct access to simplified, easy-to-read help for commands, such as `tar`,
@ -14,7 +14,8 @@ The overall process should look somewhat like this:
3. Create a feature branch, e.g. named after the command you plan to edit:
`git checkout -b {{branch_name}}`
> :warning: It is bad practice to submit a PR from the `main` branch of your forked repository. Please create pull requests from a well named feature branch.
> [!WARNING]
> It is bad practice to submit a PR from the `main` branch of your forked repository. Please create pull requests from a well named feature branch.
4. Make your changes (edit existing files or create new ones)
@ -24,7 +25,8 @@ The overall process should look somewhat like this:
6. Push the commit(s) to your fork:
`git push origin {{branch_name}}`
> :warning: Please avoid force-pushing since it makes the review process harder.
> [!WARNING]
> Please avoid force-pushing since it makes the review process harder.
7. Go to the GitHub page for your fork and click the green "Compare & pull request" button.
on a regular basis as well, or at least show up every now and then.
regularly as well, or at least show up every now and then.
- **Know when and how to say no**.
Sometimes requests or contributions need to be declined,
@ -39,7 +40,7 @@ as a guideline for current and future maintainers.
- Always remember to **thank every contribution**,
even when it can't be accepted (in fact, especially then).
Keep in mind that
[every form of contribution](https://github.com/kentcdodds/all-contributors)
[every form of contribution](https://github.com/all-contributors/all-contributors)
(pull request, feature request, bug report, etc.)
is a voluntary gift of time offered to the tldr-pages project
by someone who cares about it,
@ -57,21 +58,20 @@ as a guideline for current and future maintainers.
- PRs should be merged once they
(1) **pass the automated tests** (GitHub Actions, CLA signing, etc.),
(2) have the **review comments addressed**,
(3) get **approved reviews by two maintainers**, (the second maintainer can merge immediately after approving) and
(4) have been open for at least **24 hours** unless the changes are trivial
(3) get **approved reviews by two maintainers** (the second maintainer can merge immediately after approving).
- If a PR fails to get a review from a second maintainer after a few days,
the first maintainer should ping others for review. If it still lingers around
for **over a week without a second maintainer’s approval**,
the first maintainer can go ahead and merge it.
the first maintainer (if Owner) can go ahead and merge it. Otherwise, a message
can be sent in the chatroom asking other maintainers to review the PR.
- If the only issues holding up a merge are **trivial fixes**
(typos, syntax errors, etc.), and the author doesn't respond in a day or two,
**maintainers can make the necessary changes themselves**,
and proceed with the merge process.
- If a PR **stops getting feedback from the submitter** and is marked as stale
by [probot-stale](../.github/workflows/stale.yml),
- If a PR **stops getting feedback from the submitter** for more than a month,
any maintainer can choose to take over the PR
and make the necessary changes to get the content ready for merging.
@ -85,7 +85,7 @@ as a guideline for current and future maintainers.
or if the multiple commits are not semantically independent changes,
use the `Squash and merge` method.
(Don't forget to clean up the body of the squashed commit message.)
If instead the PR author took the time to craft
If instead, the PR author took the time to craft
individual, informative messages for each commit,
then use the `Rebase and merge` method,
to honor that work and preserve the history of the changes.
@ -93,10 +93,19 @@ as a guideline for current and future maintainers.
is that if there are more "dirty" commits than "clean" commits,
then prefer squash, else do a rebase.
- Although having push access allows committing directly to the repository,
please **create pull requests for all of your changes**,
except the simplest ones (e.g. typo fixes).
- Although having push access allows committing directly to the repository to all branches (except main),
please **create pull requests for all of your changes**.
This ensures that the entire process that regular contributors go through
is also exposed to maintainers,
who can then identify and address bottlenecks or inconveniences.
Similarly, **avoid merging your own PRs** unless approved by other maintainers.
- At the last week of October, all applicable PRs that wouldn't get merged
in time can be labeled as `hacktoberfest-accepted`.
## III. Transparency
- All non-confidential requests/mail made/sent on behalf of the project
should be documented as an issue with the [archive](https://github.com/tldr-pages/tldr/issues?q=label%3Aarchive) label
and must be communicated with other maintainers.
- All repository/organization settings changes must be documented as an issue with the [archive](https://github.com/tldr-pages/tldr/issues?q=label%3Aarchive) label.
> Krita is a sketching and painting program designed for digital artists.
> A sketching and painting program designed for digital artists.
> See also: `gimp`.
> More information: <https://docs.krita.org/en/reference_manual/linux_command_line.html>.
@ -54,7 +54,8 @@ Example:
`krita --fullscreen`
```
> :bulb: The help page can be any documentation/project/tutorial page, not just a man page,
> [!NOTE]
> The help page can be any documentation/project/tutorial page, not just a man page,
> but documentation pages are preferred.
There is a linter that enforces the format above.
@ -75,7 +76,25 @@ Your client may be able to preview a page locally using the `--render` flag:
tldr --render path/to/tldr_page.md
```
### Aliases
### PowerShell-Specific Rules
When documenting PowerShell commands, please take note of the following naming conventions.
- The name of the file name must be written in lowercase, such as `invoke-webrequest.md` instead of `Invoke-WebRequest.md`.
- The page title/heading must be written as-is (matching the spelling intended by Microsoft or the PowerShell module author), such as `Invoke-WebRequest` instead of `invoke-webrequest`.
- The command name and options in the examples should also be written as-is, such as `Command-Name {{input}} -CommandParameter {{value}}` instead of `command-name {{input}} -commandparameter {{value}}`.
Due to [various compatibility differences](https://learn.microsoft.com/powershell/scripting/whats-new/differences-from-windows-powershell) and removed Windows-specific commands in PowerShell 6.x, Ensure that the command works on between **PowerShell 5.1** (aka. the "Legacy Windows PowerShell" as installed in Windows 10 and 11), and the **latest version of the Cross-Platform PowerShell** (formerly known as PowerShell Core). If the command or its options is unavailable or contains different behavior between each version, please kindly note them in the descriptions. For example,
```md
# Clear-RecycleBin
> Clear items from the Recycle Bin.
> This command can only be used through PowerShell versions 5.1 and below, or 7.1 and above.
> More information: <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/clear-recyclebin>.
```
## Aliases
If a command can be called with alternative names (like `vim` can be called by `vi`), alias pages can be created to point the user to the original command name.
@ -105,10 +124,96 @@ Example:
- Pre-translated alias page templates can be found [here](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md).
### PowerShell-Specific Aliases
Some PowerShell commands may introduce aliases which fall into one of these three categories:
**1. Substituting an existing Windows Command Prompt (`cmd`) command**, such as `cd` aliasing to `Set-Location` with different command options. In this case, add the following alias note into the second line of the original Command Prompt command's tldr description, for example:
```md
# cd
> Display the current working directory or move to a different directory.
> In PowerShell, this command is an alias of `Set-Location`. This documentation is based on the Command Prompt (`cmd`) version of `cd`.
> More information: <https://learn.microsoft.com/windows-server/administration/windows-commands/cd>.
- View documentation of the equivalent PowerShell command:
`tldr set-location`
```
> [!TIP]
> The "View documentation of the equivalent PowerShell command" example is optional and may be excluded if the page already has the maximum number (8) of examples.
**2. Provides a new alias but only executable in PowerShell**, such as `ni` for `New-Item`. In this case, use the [standard alias template](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md), but add the word "In Powershell," (or equivalent) to indicate that the command is exclusive to PowerShell. For example,
```md
# ni
> In PowerShell, this command is an alias of `New-Item`.
> More information: <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/new-item>.
- View documentation for the original command:
`tldr new-item`
```
**3. Provides a new alias that conflicts with other programs**, most notoriously the inclusion of `curl` and `wget` as aliases of `Invoke-WebRequest` (with a non-compatible set of command options). Note that PowerShell system aliases that fall into this category are commonly exclusive to Windows.
In this case, provide a note and method to determine whether the command currently refers to a PowerShell command (by alias) or others. For example,
```md
# curl
> In PowerShell, this command may be an alias of `Invoke-WebRequest` when the original `curl` program (<https://curl.se>) is not properly installed.
> More information: <https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest>.
- Check whether `curl` is properly installed by printing its version number. If this command evaluates into an error, PowerShell may have substituted this command with `Invoke-WebRequest`:
`curl --version`
- View documentation for the original `curl` command:
`tldr curl -p common`
- View documentation for PowerShell's `Invoke-WebRequest` command:
`tldr invoke-webrequest`
```
## Option syntax
- Use GNU-style **long options** (like `--help` rather than `-h`) when they are cross-platform compatible (intended to work the same across multiple platforms).
- In other cases, use short options (like `-h`).
- Use **GNU-style long options** (like `--help` rather than `-h`) when they are cross-platform compatible (intended to work the same across multiple platforms).
- When documenting PowerShell commands, use **PowerShell-style long options** (like `-Help` instead of `-H`).
- When long options aren't available for a command, use **short options** instead.
- While we prefer long options, we allow special cases in commands like `pacman` where short options are widely used and preferred over the long options (for cases like these decisions will be made by the maintainers on a case-by-case basis).
- We prefer using a space instead of the equals sign (`=`) to separate options from their arguments (i.e. use `--opt arg` instead of `--opt=arg`) unless the program does not support it.
> [!NOTE]
> The goal of using long options is to make the commands easier to read and understand for non-techincal users. While it is ideal for most users, some users prefer short option for better ease of use. If the command supports both the options, we can highlight the short options using mnemonics instead.
### Short option mnemonics
Short option mnemonics are optional hints which can be added to help users understand the meaning of these short options. The assigned mnemonics should match with the ones in the command's official documentation (e.g. from `man` or `Get-Help`). For example:
```md
- [d]isplay the ins[t]allation [i]D for the current device. Useful for offline license activation:
`slmgr.vbs /dti`
- Display the current license's e[xp]i[r]ation date and time:
`slmgr.vbs /xpr`
```
Note that, in the first example, the `[d]`, `[t]`, and `[i]` characters are enclosed with square brackets to indicate that the `/dti` option of the command is a combination of "display", "installation", and "ID", respectively. Consecutive mnemonic characters can be grouped under the same square brackets, such as `e[xp]i[r]ation` instead of `e[x][p]i[r]ation`.
**Mnemonic characters must be written in a case-sensitive manner**, even when it is placed as the first character of the sentence (i.e. use `[d]isplay` instead of `[D]isplay`). This is to avoid conflicts with GNU-style command options which may interpret uppercase options differently than the lowercase ones, such as `-v` for displaying the command's `[v]ersion` number and `-V` to run the command in `[V]erbose` mode.
Option mnemonics may also be used in translations as long as the highlighted word contains similar meanings to the language (commonly English) which the command is written for. For example, `[d]ownload` in English may be translated into `[d]escargar` in Spanish, `[i]nstall` in English may be translated to `[i]nstallieren` in German, and `[a]pp` in English may be translated into `[a]plikasi` in Indonesian and Malay.
> [!NOTE]
> In cases where the character isn't present in the translated word, you can highlight the option before/next to the equivalent word or you can add the English work beside the translation inside a bracket. For example, `E[x]tract` in English maybe translated into `[x] ekstrak` or `ekstrak [x]` or `ekstrak (E[x]tract)` in Indonesian.
## Placeholder syntax
@ -141,6 +246,9 @@ Keep the following guidelines in mind when choosing placeholders:
- In case of a possible reference both to a file or a directory,
use `{{path/to/file_or_directory}}`.
> [!NOTE]
> If the command is specific to Windows, use backslashes (`\`) instead, such as `{{path\to\file_or_directory}}`. Drive letters such as `C:` are optional unless if the command input requires an absolute path or specific drive letter range, such as `cd /d {{C}}:{{path\to\directory}}`.
### Extensions
- If a particular extension is expected for the file, append it.
@ -155,7 +263,7 @@ Keep the following guidelines in mind when choosing placeholders:
- If a command can take 0 or more arguments of the same kind, use an ellipsis: `{{placeholder1 placeholder2 ...}}`.
For instance, if multiple paths are expected `{{path/to/directory1 path/to/directory2 ...}}` can be used.
- If a command can take 0 or more arguments of different kinds, use an ellipsis: `{{placeholder1|placeholder2|...}}`.
If there are more than 5 possible values use `|...` after the last item.
If there are more than 5 possible values, you can use `|...` after the last item.
- It's impossible to restrict the minimum or (and) maximum placeholder count via `ellipsis`.
It's up to the program to decide how to handle duplicating values, provided syntax
@ -175,15 +283,50 @@ to figure out how to use the command and fill it in with values.
Technical wording on description lines should use the `backtick` syntax.
Use backticks on the following:
- Paths, ex. `package.json`, `/etc/package.json`.
- Extensions, ex. `.dll`.
- Commands, ex. `ls`.
- Paths, e.g. `package.json`, `/etc/package.json`.
- Extensions, e.g. `.dll`.
- Commands, e.g. `ls`.
- Standard streams: `stdout`, `stdin`, `stderr`. **Do not** use the full names (e.g. standard output).
## Imperative Mood
## Descriptions
- Example descriptions have to be phrased in imperative mood.
- For example, use `List all files` instead of `Listing all files` or `File listing`.
- Avoid using the page title in the description (e.g. use `A sketching and painting program designed for digital artists` instead of `Krita is a sketching and painting program designed for digital artists`) unless the program name differs from the executable name (e.g. `rg` and Ripgrep).
- Avoid mentioning that the program is used on the command-line (e.g. use `Ripgrep is a recursive line-oriented search tool` instead of `Ripgrep is a recursive line-oriented CLI search tool`).
### Imperative Mood
- **All descriptions must be concise and phrased in the imperative mood.**
- This also applies to all translations by default unless otherwise specified in the language-specific section below.
- For example, when writing documentation for `cd`, a tool to check out and work on a specific directory in the Terminal or Command Prompt, **do not** write a lengthy description such as:
```md
> `cd` is a system tool, available in Windows, macOS, and Linux, to check out a specific directory to get things done in the Command Prompt, Terminal, and PowerShell.
```
It should instead be simplified to make it easier for everyone to read:
```md
> Change the current working directory.
```
If you are afraid the commands may differ between platforms or operating systems (e.g. Windows vs macOS), most [tldr pages clients](https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients) will choose the most suitable version of the command.
In this case, the information of the Windows version of `cd` (stored in `pages/windows/cd.md`) will be displayed by default to Windows users, and a generic/common version (stored in `pages/common/cd.md`) will be displayed for Linux, macOS, and other platforms.
When writing descriptions for command examples, **check for any grammatical errors**. `Go to the specified directory` is preferred instead of:
- `Going to the specified directory` (should not be in present participle form)
- `This command will go to the specified directory` (it is clear that this example works for *this* comment)
- `Let's go to the specified directory!`
- `Directory change` (use the active form instead of passive, if possible)
For instance, instead of `Listing all files:`, `List all files:` can be be used as the example's description below:
```md
- Listing all files:
`ls`
```
## Serial Comma
@ -205,9 +348,30 @@ This can be resolved by inserting a comma before the "and" or "or" in the final
## More information links
On the `More information` line, prefer linking to the author's provided documentation.
On the `More information` link line, we prefer linking to the author's provided documentation of the command line reference or man page. When not available, use <https://manned.org> as the default fallback for all platforms (except `osx` and some BSD platforms).
When not available, use <https://manned.org> as the default fallback.
**All links must be enclosed inside angular brackets (`<` and `>`) for proper rendering in clients.**
We prefer translations to use the more information link of the English page by default.
### Versioned links
When a utility or distribution has versioned links for the packages, we prefer linking to the most recent version of documentation (i.e. `latest`) or none if the website automatically redirects to the latest version of the documentation.
For example, use:
- <https://manpages.debian.org/latest/apt/apt.8.html> instead of <https://manpages.debian.org/bookworm/apt/apt.8.en.html>.
- <https://docs.aws.amazon.com/cdk/latest/guide/cli.html> instead of <https://docs.aws.amazon.com/cdk/v2/guide/cli.html>.
### Microsoft Learn links
When linking pages to the Microsoft Learn links, remove the locale from the address as the website will automatically redirect to the reader's preferred locale setting. For example, Use <https://learn.microsoft.com/windows-server/administration/windows-commands/cd> instead of
Additionally, if the link is related to PowerShell command documentation, remove the **documentation version indicator** (in which the version of PowerShell/module that the documentation is derived from), aka. the part of the address that starts with `?view=`.
- Use <https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-string> instead of <https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/select-string?view=powershell-7.4>.
- Use <https://learn.microsoft.com/powershell/module/powershellget/install-module> instead of <https://learn.microsoft.com/en-us/powershell/module/powershellget/install-module?view=powershellget-1.x>.
## Language-Specific Rules
@ -219,35 +383,111 @@ The following guidelines are applied to Chinese (`zh`) and traditional Chinese (
1. Place one space before/after English words and numbers.
- For example, use `列出所有 docker 容器` rather than `列出所有docker容器`.
- For example, use `宽度为 50 个字` rather than `宽度为50个字`.
- For example, use `列出所有 docker 容器` rather than `列出所有docker容器`.
- For example, use `宽度为 50 个字` rather than `宽度为50个字`.
2. Place one space between numbers and units **except** degrees and percentages.
- For example, use `容量 50 MB` rather than `容量 50MB`.
- For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`.
- For example, use `容量 50 MB` rather than `容量 50MB`.
- For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`.
3. No additional spaces before/after full-width punctuations.
- For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式`
- For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式`
4. Use full-width punctuations except for long Latin clauses.
- For example, use `嗨，你好。` rather than `嗨, 你好.`
- For example, use `嗨，你好。` rather than `嗨, 你好.`
5. Use a half-width punctuation to end a sentence when the last character is half-width.
- For example, use `将代码转化为 Python 3.` rather than `将代码转化为 Python 3。`
- For example, use `将代码转化为 Python 3.` rather than `将代码转化为 Python 3。`
6. Use precise form for technical terms, and do not use unofficial Chinese abbreviations.
- For example, use `Facebook` rather than `facebook`, `fb` or `脸书`.
- For example, use `Facebook` rather than `facebook`, `fb` or `脸书`.
In order to maintain readability and normalization, please comply with the 6 rules above as much as possible when translating pages into Chinese.
For more information and examples of Chinese-specific rules, check out [*Chinese Copywriting Guidelines*](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.en.md).
### Indonesian-Specific Rules
When translating pages to Indonesian, please keep in mind that we expect `tldr` pages to be easy to read for **both types of Indonesian audiences**, which are:
1. People who prefer to use standard Indonesian technical terms as possible, such as `unduh` for `download`, `awakutu` for `debugging`, and `muat ulang` for `reboot`.
- One of the most comprehensive lists of technical terms can be found under the [BlankOn Linux project](https://dev.blankonlinux.or.id/TimPengembang/Dokumentasi/Panduan/PanduanWiki/KamusBlankOn/).
2. People who prefer to use English words as-is to describe technical terms: `download` for `download`, `debugging` for `debugging`, and `reboot` for `reboot`.
The segmentation of these audiences is clearly noted on [Firefox Public Data Report](https://data.firefox.com/dashboard/usage-behavior):
> For most countries in the top 10, the majority (>90%) of users have their language set to the local language, **with a notable exception in Indonesia, which has about 80% English (US) and 20% Indonesian.**
First, command and example descriptions on pages in Indonesian must be written **without using active verb forms (i.e. those with `ber-` and `me-` prefixes)**. This means that sentences such as:
> **Mengunduh** sebuah file ke dalam suatu direktori
> (i.e. Downloading a file into a directory)
is considered incorrect. The correct form of the sentence should be:
> **Unduh** sebuah file ke dalam suatu direktori
Second, we recommend using the following forms of technical terms to make translated pages easier to read for both types of Indonesian audiences. Some of them may be used as-is, but others must be rewritten using Indonesian standard terms.
| English | Indonesian | Consideration(s) |
|---|---|---|
| App / Application | Aplikasi | The abbreviated word `apl.` is not common to some readers. |
| Boot, Reboot | Muat, Muat ulang | These words are the same for `load` and `reload`. See notes on the bottom section. |
| Client | Klien | |
| Command-line | Command-line | Using the word as-is is preferred over `baris perintah` or `alat berbasis mekanisme baris perintah` (`command-line tool`). |
| Commit (Git) | Commit | |
| Compile, Compiler | Kompilasikan, Pengompilasi | [`kompilasi`](https://kbbi.kemdikbud.go.id/entri/kompilasi) is officially considered as noun. Requires a `-kan` suffix to convert into a verb. |
| Debugger | Debugger | Preferred over `pengawakutu` (`peng`-[`awakutu`](https://kbbi.kemdikbud.go.id/entri/awakutu)) which is unfamiliar to some readers. |
| Device | Perangkat | Preferred over [`peranti`](https://kbbi.kemdikbud.go.id/entri/peranti). |
| Disc | Disc | Preferred over [`cakram`](https://kbbi.kemdikbud.go.id/entri/cakram) which is unfamiliar by some readers. Use specific words if possible (e.g. CD or DVD). |
| Execute / Run (a program...) | Jalankan | Preferred over [`eksekusikan`](https://kbbi.kemdikbud.go.id/entri/eksekusikan) which is longer to read and write. |
| File | File | Preferred over [`berkas`](https://kbbi.kemdikbud.go.id/entri/berkas) which may be unfamiliar by some readers. |
| Generate | Buat | Preferred over [`hasilkan`](https://kbbi.kemdikbud.go.id/entri/hasilkan). Example context: `Buat laporan baru`. |
| Hardware | Perangkat Keras | Preferred over [`peranti`](https://kbbi.kemdikbud.go.id/entri/peranti). |
| Image (as picture or visual image) | Gambar | Do not confuse with `image` as means of storage. |
| Image (as means of storage, such as CD, ISO, and Docker) | Image | Another recommended word, [`citra`](https://kbbi.kemdikbud.go.id/entri/citra), is not officially recognized for computing. |
| Initialize, Reinitialize | Inisialisasikan, Inisialisasikan Ulang | The word [`inisialisasi`](https://kbbi.kemdikbud.go.id/entri/inisialisasi) is officially considered as noun. Requires a `-kan` suffix to convert into a verb. |
| Interpreter | Interpreter | Preferred over [`penerjemah`](https://kbbi.kemdikbud.go.id/entri/penerjemah) which is also commonly used to describe `translator`. |
| Install, Reinstall | Pasang, Pasang Ulang | Preferred over `instal` [which is not considered a standard word](https://kbbi.kemdikbud.go.id/entri/instal). |
| Load, Reload | Muat, Muat ulang | These words are the same for `boot` and `reboot`. See notes in the bottom section. |
| Server | Server | Preferred over [`peladen`](https://kbbi.kemdikbud.go.id/entri/peladen) or [`pelayan`](https://kbbi.kemdikbud.go.id/entri/pelayan), which are less common when used in computing contexts. |
| Service | Layanan | The Indonesian standard word is acceptable here. |
| Shell (command-line interface) | Syel | The Indonesian standard word is acceptable here. |
| Software | Perangkat Lunak | Preferred over [`peranti`](https://kbbi.kemdikbud.go.id/entri/peranti). |
| Start, Restart | Mulai, Mulai Ulang / Nyalakan, Nyalakan Ulang | See notes on the bottom section. |
| Update | Perbarui | Do not confuse with `upgrade`. |
| Upgrade | Tingkatkan | Do not confuse with `update`. |
When translating sentences that contain the word `boot` and `load` together, please add the context of the item that is being booted and/or loaded, so the use of the `muat` word may not be ambiguous. For example, when translating:
> Load configuration from a specific file after reboot
Instead of translating the sentence into:
> Muat konfigurasi dari file yang ditentukan setelah muat ulang
Add detailed contexts to remove ambiguity (notice the highlighted word):
> Muat konfigurasi dari file yang ditentukan setelah **pengguna** memuat ulang **sistem operasi**
Similarly, for the word `start` / `mulai`
> Mulai proses server web
> (Start the web server process)
To ensure that the sentence may not be confused with `start processing the web server`, you can use other words such as `nyalakan`:
> Nyalakan proses server web
### French-Specific Rules
Example descriptions on pages in French must use the third person singular present indicative tense (présent de l'indicatif à la troisième personne du singulier).
Command and example descriptions on pages in French must use the third person singular present indicative tense (présent de l'indicatif à la troisième personne du singulier).
For example, use `Extrait une archive` rather than `Extraire une archive` or `Extrais une archive`.
> আরও তথ্য পাবেন: <https://www.gnu.org/software/bash/manual/bash.html#index-test>।
- পরীক্ষা করুন যদি দেওয়া ভেরিয়েবল নির্দিষ্ট স্ট্রিং এর সমান/সমান না হয়:
`[ "${{ভেরিয়েবল}}" {{=|!=}} "{{স্ট্রিং}}" ]`
- পরীক্ষা করুন যদি দেওয়া ভেরিয়েবল [ই]কুয়াল/[ন]ট [ই]কুয়াল/[জি]টে [ল]েস [ট]হ্যান/[জি]টে [ই]কুয়াল/[ল]েস ট্রু থেকে/[ল]েস থেকে বা সমান নির্দিষ্ট সংখ্যায়:
> আরও তথ্য পাবেন: <https://www.gnu.org/software/bash/manual/bash.html#index-_005b_005b>।
- পরীক্ষা করুন যদি দেওয়া ভেরিয়েবল নির্দিষ্ট স্ট্রিং এর সমান/সমান না হয়:
`[[ ${{ভেরিয়েবল}} {{==|!=}} "{{স্ট্রিং}}" ]]`
- পরীক্ষা করুন যদি দেওয়া স্ট্রিং নির্দিষ্ট glob/regex এর সাথে মেলে:
`[[ ${{ভেরিয়েবল}} {{==|=~}} {{প্যাটার্ন}} ]]`
- পরীক্ষা করুন যদি দেওয়া ভেরিয়েবল [ই]কুয়াল/[ন]ট [ই]কুয়াল/[জি]টে [ল]েস [ট]হ্যান/[জি]টে [ই]কুয়াল/[ল]েস ট্রু থেকে/[ল]েস থেকে বা সমান নির্দিষ্ট সংখ্যায়:
- DNS রেকর্ড যোগ করার পর স্বয়ংক্রিয় Cloudflare/Google DNS পোলিং বন্ধ করে একটি সার্টিফিকেট ইস্যু করুন, সেকেন্ডে নির্দিষ্ট কাস্টম প্রতীক্ষার সময় স্পেসিফাই করে:
> পাওয়ারশেলে, এই কমান্ডটি অরিজিনাল `curl` প্রোগ্রাম (<https://curl.se>) সঠিকভাবে ইনস্টল না থাকলে এটি `Invoke-WebRequest` এর এলিয়াস হতে পারে।
> আরও তথ্য পাবেন: <https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest>।
- চেষ্টা করুন যে কি `curl` সঠিকভাবে ইনস্টল করা হয়েছে কিনা, এর সংস্করণ নম্বর প্রিন্ট করে। যদি এই কমান্ডটি একটি ত্রুটির মধ্যে মূল `Invoke-WebRequest` দিয়ে বদলে যায়, তবে:
`curl --version`
- মৌলিক `curl` কমান্ডের জন্য নথি:
`tldr curl -p common`
- পাওয়ারশেলের `Invoke-WebRequest` কমান্ডের জন্য নথি:
Alejandro Cervera
Juri Dispan
HoJeong Im
Sebastiaan Speck
Darío Hereñú
Starbeamrainbowlabs
Reinhart Previano Koentjoro
Gilad Alboher
K.B.Dharun Krishna
Gabe Livengood
Ren Ma
Isaac-Carrascal
Hahaha
Lena
danielsagie
Weihang Zheng
Valentin
Jonas
Hetav Pandya
dependabot[bot]
Zhiyuan Pan
Sharun
Jacques Hogge
ovigeek
Ana Aguilar
Sanjinso
Muralikrishnan
marcel
Rolv Apneseth
Snowflake
leoTlr
Valentin Vetter
Sourav-Kumar-Panda
Luka Markušić
mbsmith
Guillaume Bernard
Sergej Frank
t-mangoe
Paul Azema
nazdridoy
John Vouvakis Manousakis
Ivan Dimitrov
AndrewJop
Shashank Hebbar
Qwerty-Space
Leon
Managor
Eclipzze
Siriusmart
Nataliiaaa
Sascha Hahne
Owen Lin
Sebastiaan Speck
Harry Han
Rodrigo Stuchi
Jacobus Burger
Konstanty Dąbrowski
Abhishek M J
cyqsimon
HCAHOI
The Galaxy
grafst
WU Zhenglong
Jai Vignesh J
Riyaz Siddiqui
Magrid
Harshavardhan Bajoria
debghs
ShamimShahraeini
TornaxO7
rozie
Dmytro Voytko
Bohdan Karashchuk
Dev7g
Vedant Yadav
Jeremy Aza
Janek
Ayush Varshney
Anurag Dey
Priyanshu Paritosh
Pranjali Rathi
KangManJoo
Robson Cruz
Arman Rahimi
KangManJoo
Renan Nakazawa
Seppel3210
Farzad Hayat
subas kandel
Sayuri Kamble
WangLinSongss
Sam Waite
Samuele Facenda
Poy Chang
Suren Lockwood
Alexander
Mansoor Barri
Jeongwook Park
Wertzui123
Nadim Khemir
Anton Karmanov
Eric Lehmann
Anurag Kumar
Jan
Farzad Hayat
xuzhangheng
Felipe Furquim
Aniket Purohit
Pranav Kale
Raynaldo Sutisna
mrusme
Aditya Shrivastav
RedDeliciousApples
AbhiAk45
Pranav Upadhyay
RAJ RAUT
Nathaniel Joselson
Onkar Raghunath Shelke
Kavita Dhar
Gaurav Padam
MariaPaula Trujillo
Prerna Singh
David Zabala
Jack Lin
Joseph Sebastian
Sadeed
Pedro Mariano
fadharpra
Quentin Klein
Cristian Bastidas
Pranav Nedungadi
Constantine
Aditya Jha
Vishnu Das Puthukudi
theBulaDev
Daniel
Reinhart Previano Koentjoro
caduvieira
Kicka5h
Rui Alves
Binaya Sharma
Michael D
Rockerz
Nicolas Kosinski
Sagar Verma
Ludev
Aarya Zunjarrao
Alexandre ZANNI
Narfinger
Muhammad Hanif Amrullah
Sambuddha Chatterjee
Justin Garrison
Fyodor Dostoevsky
tellmeY18
Alois Sečkár
Jithin Sethumadhavan
Jack Lin
Aditi Kharel
Omnath Mandal
Arthur Oliveira
Daniel Kaczmarczyk
DEBADRIBASAK
Sunil
leenate
hms5232
Mighty
Karl Dangerfield
Tylerastro
Alejandro Armenta
Tristan Jahnke
parthzz
hsicilia
dyegoaurelio
pixel
CleanMachine1
Tristan Jahnke
RoepLuke
iagor molino
Caio Fuzatto
Ein Verne
ECMs
Seth Falco
MCK
Andreas Björn
Jimmy
Mehrad Mahmoudian
Austin Nazworth
Ulysse Buonomo
Florian Wilhelm
shellheim
07416
CouldBeThis
mag4no10
Osman F Bayram
Stephen Ball
Bárbara Perdigão
Isaac Vicente
Matthieu LAURENT
aoi-hiraeth
Isaac Vicente
Nethum Lamahewage
John
marc
mortalpuppet
wangme88
Reed
Miroslav Shubernetskiy
Johan Degn
879hun675tgfoO098
