mirror of https://github.com/CrimsonTome/tldr.git
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
# Contributing
|
|
|
|
- Your favourite command isn't covered?
|
|
- You can think of more examples?
|
|
|
|
Contribution are most welcome! All `tldr` pages are stored in Markdown right here on GitHub. Just open an issue or send a pull request and we'll merge it as soon as possible.
|
|
|
|
*Note: when submitting a new command, don't forget to check if there's already a pull request in progress.*
|
|
|
|
## Setup
|
|
|
|
When setting up a brand new fork, run `make setup` to install the git pre-commit hook that will check errors in your changes with Markdown linter.
|
|
|
|
## Guidelines
|
|
|
|
Note that `tldr` is focused on concrete examples.
|
|
Here's 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.
|
|
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.
|
|
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}}`.
|
|
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 :)
|
|
|
|
## Markdown format
|
|
|
|
The format of each page should match the following:
|
|
|
|
```
|
|
# command-name
|
|
|
|
> Short description
|
|
> Max 1 or 2 lines
|
|
|
|
- example description
|
|
|
|
`command -opt1 -opt2 -arg1 {{arg_value}}`
|
|
|
|
- example description
|
|
|
|
`command -opt1 -opt2`
|
|
```
|
|
|
|
User-provided values should use the `{{token}}` syntax, to allow clients to highlight them. For example: `tar cf {{file}}`
|
|
|
|
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.
|
|
|
|
---------------------------------------
|
|
|
|
**Footnote:** tldr is under MIT license.
|
|
|
|
You're free to modify or redistribute the content. That being said, but why not contribute over here? :) Say if you wanted to have `tldr` pages in `groff` format, why not have a client that uses [pandoc](http://johnmacfarlane.net/pandoc/) and periodically updates straight from this repo?
|