mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-08-16 23:40:43 +03:00
Extract STYLEGUIDE.md from CONTRIBUTING.md
This commit is contained in:
parent
d681bb4cb5
commit
f3c002d32f
@ -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
61
STYLEGUIDE.md
Normal 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.
|
Loading…
Reference in New Issue
Block a user