mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-09-11 12:05:35 +03:00
Edited CONTRIBUTING.md to reflect final convention.
This commit is contained in:
parent
e54f49ad60
commit
2c1a6f14d6
@ -7,16 +7,16 @@ Contribution are most welcome! All `tldr` pages are stored in Markdown right her
|
|||||||
## Guidelines
|
## Guidelines
|
||||||
|
|
||||||
Note that `tldr` is focused on concrete examples.
|
Note that `tldr` is focused on concrete examples.
|
||||||
Here's a few guidelines to get started:
|
Here are a few guidelines to get started:
|
||||||
|
|
||||||
1. Focus on the 5 or 6 most common usages. It's OK if the page doesn't cover everything; that's what `man` is for.
|
1. Focus on the 5 or 6 most common usages. 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.
|
2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
|
||||||
3. Try to incorporate the spelled-out version of single-letter options in the example's description.
|
3. Try to incorporate the spelled-out version of single-letter options in the example's description.
|
||||||
4. Introduce options gradually, starting with the simplest commands and using more complex examples progressively.
|
4. Introduce options gradually, starting with the simplest commands and using more complex examples progressively.
|
||||||
5. Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`.
|
5. Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`.
|
||||||
6. Be specific: avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, brace expansion, character escaping...)
|
6. Be specific: avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, brace expansion, character escaping...).
|
||||||
|
|
||||||
The best way to be consistent is to have a look at a few existing pages :)
|
The best way to be consistent is to have a look at a few existing pages :).
|
||||||
|
|
||||||
## Markdown format
|
## Markdown format
|
||||||
|
|
||||||
@ -25,21 +25,35 @@ The format of each page should match the following:
|
|||||||
```
|
```
|
||||||
# command-name
|
# command-name
|
||||||
|
|
||||||
> Short description
|
> Short, snappy description.
|
||||||
> Max 1 or 2 lines
|
> Preferably one line, we can work with two.
|
||||||
|
|
||||||
- example description
|
- Example description:
|
||||||
|
|
||||||
`command -opt1 -opt2 -arg1 {{arg_value}}`
|
`command -opt1 -opt2 -arg1 {{arg_value}}`
|
||||||
|
|
||||||
- example description
|
- Example description:
|
||||||
|
|
||||||
`command -opt1 -opt2`
|
`command -opt1 -opt2`
|
||||||
```
|
```
|
||||||
|
|
||||||
User-provided values should use the `{{token}}` syntax, to allow clients to highlight them. For example: `tar cf {{file}}`
|
### Token Syntax
|
||||||
|
User-provided values should use the `{{token}}` syntax in order to allow clients
|
||||||
|
to highlight them.
|
||||||
|
|
||||||
One of the reasons for this format is that it's well suited for command-line clients that need to extract a single description/example.
|
Some examples:
|
||||||
|
- `tar cf {{file}}`
|
||||||
|
- `ln -s {{path/to/original/file}} {{path/to/link}}`
|
||||||
|
- `mysql {{database_name}}`
|
||||||
|
- `unrar x {{compressed.rar}}`
|
||||||
|
|
||||||
|
In short, make it as intuitive as possible for the user to figure out how to use
|
||||||
|
the command and fill it in with values. Stick to `snake_case` where possible. In
|
||||||
|
some situations a command works with typical file extensions (like the `unrar`
|
||||||
|
example above); you are encouraged to add these for demonstration.
|
||||||
|
|
||||||
|
One of the reasons for this format is that it's well suited for command-line
|
||||||
|
clients that need to extract a single description/example.
|
||||||
|
|
||||||
## Submitting a pull request
|
## Submitting a pull request
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user