Extract STYLEGUIDE.md from CONTRIBUTING.md

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/<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
 

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/<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.