mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-08-16 23:40:43 +03:00
contributing.md: various tweaks (#1100)
- adjust whitespace & line breaks to make the markdown source more readable and consistent - remove "we"/"our", to avoid reinforcing the "us vs. them" paradigm - clarify a couple passages - remove obsolete license agreement notice, now covered by the CLA - remove redundant (and oddly specific) plea for contributions and the end of the document, since there's already one at the beginning - remove a redundant example of commit message format
This commit is contained in:
parent
27123e215a
commit
03f947196b
@ -11,12 +11,16 @@ To get started, sign the [Contributor License Agreement](https://cla-assistant.i
|
||||
The basic format of a `tldr` page is a set of concrete usage examples.
|
||||
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.
|
||||
2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
|
||||
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.
|
||||
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 commands and using more complex examples progressively.
|
||||
5. Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`.
|
||||
4. Introduce options gradually, starting with the simplest command invocations,
|
||||
and using more complex examples progressively.
|
||||
5. Use short but descriptive values for the tokens,
|
||||
ex. `{{source_file}}` or `{{wallet.txt}}`.
|
||||
6. 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...).
|
||||
|
||||
@ -41,7 +45,7 @@ The format of each page should match the following:
|
||||
`command -opt1 -opt2`
|
||||
```
|
||||
|
||||
We actually have a linter/formatter that enforces our format.
|
||||
There actually is a linter/formatter that enforces the format above.
|
||||
It is run automatically on every pull request,
|
||||
but you may install it to test your contributions locally before submitting them:
|
||||
|
||||
@ -54,31 +58,38 @@ For other ways to use `tldrl`, such as linting an entire directory, check out (w
|
||||
[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md)
|
||||
|
||||
### Token syntax
|
||||
User-provided values should use the `{{token}}` syntax
|
||||
in order to allow clients to highlight them.
|
||||
Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case)
|
||||
for multi-word tokens.
|
||||
|
||||
User-provided values should use the `{{token}}` syntax in order to allow `tldr` clients to highlight them.
|
||||
Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens.
|
||||
|
||||
Keep the following guidelines in mind when choosing token names:
|
||||
|
||||
- If the example is clearer with an actual value rather than a generic placeholder, use the actual value. For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`.
|
||||
- If the example is clearer with an actual value rather than a generic placeholder,
|
||||
use the actual value. For example, use `iostat {{2}}` rather than `iostat {{interval_in_secs}}`.
|
||||
|
||||
- For any reference to paths to files or folders, use `{{path/to/<placeholder>}}`. For example, `ln -s {{path/to/file}} {{path/to/symlink}}`. In case of a possible reference both to a file or a folder, use `{{path/to/file_or_folder}}`
|
||||
- For any reference to paths to files or folders, use `{{path/to/<placeholder>}}`.
|
||||
For example, `ln -s {{path/to/file}} {{path/to/symlink}}`.
|
||||
In case of a possible reference both to a file or a folder, use `{{path/to/file_or_folder}}`
|
||||
|
||||
- If a command expects the file to have a particular extension, use it. For example, `unrar x {{compressed.rar}}`. In case needs a generic extension, use `{{.ext}}`, but **only** if it helps to clarify the command. For example, here:
|
||||
- If a command expects the file to have a particular extension, use it.
|
||||
For example, `unrar x {{compressed.rar}}`.
|
||||
In case needs a generic extension, use `{{.ext}}`, but **only** if it helps to clarify the command.
|
||||
For example, here:
|
||||
|
||||
```
|
||||
Open all the files of a given extension in the current directory with the associated application:
|
||||
open {{*.ext}}
|
||||
```
|
||||
|
||||
... using `{{.ext}}` helps to clarify the command. But in a command like `wc -l {{file}}`, using `{{file}}` is sufficiently clear.
|
||||
... using `{{.ext}}` helps to clarify the command.
|
||||
But in a command like `wc -l {{file}}`, using `{{file}}` is sufficiently clear.
|
||||
|
||||
- Lastly, follow the `{{path/to/<placeholder>}}` convention when there is a path-related command. Not when the file location is implicit. But of course, use proper judgement, keeping simplicity and user friendliness as the top priority.
|
||||
- Lastly, follow the `{{path/to/<placeholder>}}` convention when there is a path-related command,
|
||||
except when the file location is implicit.
|
||||
But of course, use proper judgement, keeping simplicity and user friendliness as the top priority.
|
||||
|
||||
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.
|
||||
In short, choose tokens that make it as intuitive as possible
|
||||
for the user to figure out how to use the command and fill it in with values.
|
||||
|
||||
## Submitting a pull request
|
||||
|
||||
@ -125,17 +136,10 @@ Examples:
|
||||
- `ls: add page`
|
||||
- `cat: fix typo`
|
||||
- `git-push: add --force example`
|
||||
- `uname: fix -a example`
|
||||
|
||||
## Licensing
|
||||
|
||||
`tldr` is licensed under the [MIT license](https://github.com/tldr-pages/tldr/blob/master/LICENSE.md).
|
||||
|
||||
**IMPORTANT**: By submitting a patch, you agree to license your work
|
||||
under the same license as that used by the project.
|
||||
|
||||
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?
|
||||
Any contributions to this project are governed by the
|
||||
[Contributor License Agreement](https://cla-assistant.io/tldr-pages/tldr).
|
||||
|
Loading…
Reference in New Issue
Block a user