mirror of https://github.com/CrimsonTome/tldr.git
CONTRIBUTING.md: Add token conventions (#981)
* CONTRIBUTING.md: Add token conventions * Shortening the token guidelines * Minor spacing fix * Addressing further concerns * Replacing - by :waldyrious/alt-syntax
parent
3061f6ca65
commit
beb517b6a8
|
@ -53,24 +53,32 @@ 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)
|
[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md)
|
||||||
|
|
||||||
### Token syntax
|
### Token syntax
|
||||||
User-provided values should use the `{{token}}` syntax in order to allow clients
|
User-provided values should use the `{{token}}` syntax
|
||||||
to highlight them.
|
in order to allow clients to highlight them.
|
||||||
|
Use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case)
|
||||||
|
for multi-word tokens.
|
||||||
|
|
||||||
Some examples:
|
Keep the following guidelines in mind when choosing token names:
|
||||||
- `tar cf {{file}}`
|
|
||||||
- `ln -s {{path/to/original/file}} {{path/to/link}}`
|
- 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}}`.
|
||||||
- `mysql {{database_name}}`
|
|
||||||
- `unrar x {{compressed.rar}}`
|
- 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
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.
|
||||||
|
|
||||||
|
- 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.
|
||||||
|
|
||||||
In short, make it as intuitive as possible
|
In short, make it as intuitive as possible
|
||||||
for the user to figure out how to use the command
|
for the user to figure out how to use the command
|
||||||
and fill it in with values.
|
and fill it in with values.
|
||||||
|
|
||||||
Stick to [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) where possible.
|
|
||||||
In some situations a command works with typical file extensions
|
|
||||||
(like the `unrar` example above);
|
|
||||||
you are encouraged to add these for demonstration.
|
|
||||||
|
|
||||||
## Submitting a pull request
|
## Submitting a pull request
|
||||||
|
|
||||||
For submitting changes, you can use whatever workflow you're more comfortable with.
|
For submitting changes, you can use whatever workflow you're more comfortable with.
|
||||||
|
|
Loading…
Reference in New Issue