lilith/tldr
1
0
Fork 0
mirror of https://github.com/tldr-pages/tldr.git synced 2025-03-28 21:16:20 +01:00
Code Activity

contributing.md: various tweaks (#1100)

Browse source 
- 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:
Waldir Pimenta 2016-10-02 11:03:37 +01:00 • committed by GitHub
parent 27123e215a
commit 03f947196b
1 changed files with 30 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
CONTRIBUTING.md
View file

@ -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).