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

Extract STYLEGUIDE.md from CONTRIBUTING.md

Browse source
This commit is contained in:
Amy Martin 2017-10-28 23:24:15 +13:00 • committed by Agniva De Sarker
parent d681bb4cb5
commit f3c002d32f
2 changed files with 68 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
CONTRIBUTING.md
View file

@ -43,11 +43,14 @@ Here are a few guidelines to get started:
5. 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...).
The best way to be consistent is to have a look at a few existing pages :).
These are all guidelines, not strict rules.
Use proper judgement, keeping simplicity and user-friendliness as the top priority.
When in doubt, have a look at a few existing pages :).
## Markdown format
The format of each page should match the following:
As a quick reference, the format of each page should match the following template:
```
# command-name
@ -64,50 +67,8 @@ The format of each page should match the following:
`command -opt1 -opt2`
```
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:
```
npm install tldr-lint
tldrl -f {{page.md}}
```
For other ways to use `tldrl`, such as linting an entire directory, check out (what else!)
[`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 `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:
1. Use short but descriptive values for the tokens,
ex. `{{source_file}}` or `{{wallet.txt}}`.
2. 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}}`.
3. For any reference to paths to files or folders, use the format `{{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}}`
4. Follow the `{{path/to/<placeholder>}}` convention when there is a path-related command,
except when the file location is implicit.
5. If a command expects the file to have a particular extension, use it.
For example, `unrar x {{compressed.rar}}`.
In case a generic extension is needed, use `{{.ext}}`, but **only** if an extension is required.
For instance, in find.md's example "Find files by extension" (`find {{root_path}} -name '{{*.ext}}'`)
using `{{*.ext}}` explains the command without being unnecessarily specific;
But in a command like `wc -l {{file}}`, using `{{file}}` (without extension) is sufficient.
These are all guidelines, not strict rules.
In general, tokens should make it as intuitive as possible
to figure out how to use the command and fill it in with values.
Use proper judgement, keeping simplicity and user-friendliness as the top priority.
For more detailed page formatting guidelines,
refer to the [style guide](./STYLEGUIDE.md).
## Submitting a pull request

61
STYLEGUIDE.md Normal file
View file

@ -0,0 +1,61 @@
# Style Guide
This page lists specific formatting instructions for tldr pages.
## Layout
The basic format of each page should match the following template:
```
# command-name
> Short, snappy description.
> Preferably one line; two are acceptable if necessary.
- Example description:
`command -opt1 -opt2 -arg1 {{arg_value}}`
- Example description:
`command -opt1 -opt2`
```
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:
```
npm install tldr-lint
tldrl -f {{page.md}}
```
For other ways to use `tldrl`, such as linting an entire directory, check out (what else!)
[`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 `tldr` clients to highlight them.
Keep the following guidelines in mind when choosing tokens:
1. Use short but descriptive tokens,
ex. `{{source_file}}` or `{{wallet.txt}}`.
2. Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for multi-word tokens.
3. For any reference to paths to files or folders, use the format `{{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}}`
4. Follow the `{{path/to/<placeholder>}}` convention for all path-related commands, except when the
file location is implicit.
5. If a command expects the file to have a particular extension, use it.
For example, `unrar x {{compressed.rar}}`.
In case a generic extension is needed, use `{{.ext}}`, but **only** if an extension is required.
For instance, in find.md's example "Find files by extension" (`find {{root_path}} -name '{{*.ext}}'`)
using `{{*.ext}}` explains the command without being unnecessarily specific;
But in a command like `wc -l {{file}}`, using `{{file}}` (without extension) is sufficient.
6. 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}}`.
In general, tokens should make it as intuitive as possible
to figure out how to use the command and fill it in with values.