Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve code block Markdown guidelines (#749)

Browse Source
This commit is contained in:
Andrew David Wong 2018-12-02 17:16:59 -06:00
parent 3f25b1c8c9
commit 2bfd51e723
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 20 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
basics_user/doc-guidelines.md
View File

@ -254,25 +254,33 @@ When making contributions, please try to observe the following style conventions
where appropriate. where appropriate.
* Use underline headings (`=====` and `-----`) if possible. * Use underline headings (`=====` and `-----`) if possible.
If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`). If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`).
* When writing commands to be entered into a terminal: * When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* State in the text above the commands that the user shall open a terminal and run those commands. * When providing command line examples:
E.g. * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown ~~~markdown
Open a terminal in your AppVM and run Open a terminal in dom0 and run:
```shell_session ```shell_session
$ cd test $ cd test
$ echo Hello $ echo Hello
Hello Hello
``` ```
~~~ ~~~
* Precede each command with a non-empty prompt that fits the needs. * Precede each command with the appropriate command prompt:
As a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively. At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Put the expected output below the command as usual or use a separate code block for that. * Don't try to add comments inside the code block.
You should write `[...]` for omitted parts of the output. For example, *don't* do this:
* Use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). ~~~markdown
* When quoting (script) files: Open a terminal in dom0 and run:
* Use code blocks with [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). ```shell_session
* You should write `[...]` for omitted parts. # Navigate to the new directory
$ cd test
# Generate a greeting
$ echo Hello
Hello
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
* Use `[reference-style][ref]` links. * Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link` `[ref]: https://daringfireball.net/projects/markdown/syntax#link`