ctome
/
tldr
mirror of https://github.com/CrimsonTome/tldr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CONTRIBUTING: document the directory structure (#12314) 

* CONTRIBUTING: document the directory structure

* CONTRIBUTING: rename the subtitle "Pages directory" to "Directory structure"

* CONTRIBUTING: fix casing of platforms list

* CONTRIBUTING: use plural form of "directory"

Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>

* CONTRIBUTING: remove "valid reason"

* CONTRIBUTING: change platform directory listing for a numbered list format

* CONTRIBUTING: apply suggestions from code review

Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>

---------

Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
pull/23/head
Vitor Henrique 2024-02-25 07:48:36 -03:00 committed by GitHub
parent a609b14c83
commit d77ae17016
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 25 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
CONTRIBUTING.md
View File

@ -48,6 +48,30 @@ Use proper judgement, keeping simplicity and user-friendliness as the top priori
When in doubt, have a look at a few existing pages :).
## Directory structure
The English pages directory is called `pages`, under which the platform directories are present. 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).
The `<country>` code is optional and should only be added when there is a substantial difference 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.
### Platform directories
The `pages` directory and `pages.*` language-specific directories contain the platform directories, if they have at least one page of that platform.
1. If the command is available for **two or more** platforms, put it **under the `common` directory**.
2. If the command is **only** available for **one** platform, these are the available directories followed by their right platform:
- `android`: Android
- `freebsd`: FreeBSD
- `openbsd`: OpenBSD
- `osx`: OSX/Mac OS/macOS (will be replaced by `macos`)
- `linux`: any Linux distro
- `netbsd`: NetBSD
- `sunos`: SunOS
- `windows`: Windows
## Markdown format
As a quick reference, the format of each page should match the following template:
@ -140,17 +164,10 @@ See these examples for reference:
## 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 don'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).
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.
Translation of pages can be done by simply creating the corresponding page within the appropriate [language-specific directory](#pages-directory), creating that as well if it does not already exist.
> [!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.