From f3c002d32f98d0644c2729bae77096ad351d0910 Mon Sep 17 00:00:00 2001 From: Amy Martin Date: Sat, 28 Oct 2017 23:24:15 +1300 Subject: [PATCH] Extract STYLEGUIDE.md from CONTRIBUTING.md --- CONTRIBUTING.md | 53 ++++++------------------------------------ STYLEGUIDE.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 46 deletions(-) create mode 100644 STYLEGUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9e7035fe7..fbc4494b05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/}}`. - 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/}}` 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 diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md new file mode 100644 index 0000000000..7989d3bfeb --- /dev/null +++ b/STYLEGUIDE.md @@ -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/}}`. + 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/}}` 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. \ No newline at end of file