From 8d1fa2f6bee76fdbc3bffc3e703caabd5f3ed8ed Mon Sep 17 00:00:00 2001 From: Tobias Killer Date: Sun, 2 Dec 2018 15:49:51 +0100 Subject: [PATCH 1/3] Add Markdown conventions for files and shell sessions Concerns issue #4179. --- basics_user/doc-guidelines.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 4c8f6035..8d246bab 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -254,6 +254,22 @@ When making contributions, please try to observe the following style conventions where appropriate. * Use underline headings (`=====` and `-----`) if possible. 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: + * State in the text above the commands that the user shall open a terminal and run those commands. E.g. + ~~~markdown + Open a terminal in your AppVM and run + ```shell_session + $ cd test + $ echo Hello + Hello + ``` + ~~~ + * Precede each command with a non-empty prompt that fits the needs. 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. + * Put the expected output below the command as usual or use a separate code block for that. You should write `[...]` for omitted parts of the output. + * Use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). + * When quoting (script) files: + * 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). + * You should write `[...]` for omitted parts. * Use `[reference-style][ref]` links. `[ref]: https://daringfireball.net/projects/markdown/syntax#link` From 3f25b1c8c999f9660a0f6a1978901a78ab87e1c2 Mon Sep 17 00:00:00 2001 From: Tobias Killer Date: Sun, 2 Dec 2018 15:58:47 +0100 Subject: [PATCH 2/3] Fix format --- basics_user/doc-guidelines.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index 8d246bab..a1d5af97 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -255,17 +255,20 @@ When making contributions, please try to observe the following style conventions * Use underline headings (`=====` and `-----`) if possible. 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: - * State in the text above the commands that the user shall open a terminal and run those commands. E.g. - ~~~markdown - Open a terminal in your AppVM and run - ```shell_session - $ cd test - $ echo Hello - Hello - ``` - ~~~ - * Precede each command with a non-empty prompt that fits the needs. 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. - * Put the expected output below the command as usual or use a separate code block for that. You should write `[...]` for omitted parts of the output. + * State in the text above the commands that the user shall open a terminal and run those commands. + E.g. + ~~~markdown + Open a terminal in your AppVM and run + ```shell_session + $ cd test + $ echo Hello + Hello + ``` + ~~~ + * Precede each command with a non-empty prompt that fits the needs. + 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. + * Put the expected output below the command as usual or use a separate code block for that. + You should write `[...]` for omitted parts of the output. * Use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). * When quoting (script) files: * 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). From 2bfd51e7233fcb79c3a03ef60b8ae8141c0df252 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 2 Dec 2018 17:16:59 -0600 Subject: [PATCH 3/3] Improve code block Markdown guidelines (#749) --- basics_user/doc-guidelines.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/basics_user/doc-guidelines.md b/basics_user/doc-guidelines.md index a1d5af97..4aef9550 100644 --- a/basics_user/doc-guidelines.md +++ b/basics_user/doc-guidelines.md @@ -254,25 +254,33 @@ When making contributions, please try to observe the following style conventions where appropriate. * Use underline headings (`=====` and `-----`) if possible. 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: - * State in the text above the commands that the user shall open a terminal and run those commands. - E.g. + * 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. + * When providing command line examples: + * 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 - Open a terminal in your AppVM and run + Open a terminal in dom0 and run: ```shell_session $ cd test $ echo Hello Hello ``` ~~~ - * Precede each command with a non-empty prompt that fits the needs. - 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. - * Put the expected output below the command as usual or use a separate code block for that. - You should write `[...]` for omitted parts of the output. - * Use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). - * When quoting (script) files: - * 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). - * You should write `[...]` for omitted parts. + * Precede each command with the appropriate command prompt: + 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. + * Don't try to add comments inside the code block. + For example, *don't* do this: + ~~~markdown + Open a terminal in dom0 and run: + ```shell_session + # 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. `[ref]: https://daringfireball.net/projects/markdown/syntax#link`