We have the branch "WIP". Please work on the manual only in it.

We would be happy if you could help with the translation into a language of your choice.

An overview and the status of the MarkDown documents within the siduction manual is available on the wiki page EN_Status-of-manual-pages. If a new page is created, please create an issue and expand the status page.

To edit manual pages online simply select its file name in the status page or go to the folder https://github.com/siduction/sidu-manual/tree/WIP/data/en and select the file there.

To work on the local machine just clone the git repository of the siduction manual or do a pull request. To make the result locally comparable, we use Firefox with the Markdown Viewer Webext PlugIn. The settings used are in the file /development/css_FF_Plugin_Markdown-Viewer-Webext.
The plugin settings are:
markdown "github"
code style "default"

Regarding Markdown, we adhere to the GitHub Flavored Markdown Spec and the specifications listed below.

The file names of the new manual start with a four-digit number followed by a hyphen.
The first two digits assign the file to the main group, e.g. "03XX-" for the main group "Installation".
Digits three and four rank the file within the main group.
Gaps in the sequence of digits are harmless for the generation of the .html files and the PDF and are useful for files that may be added in the future.

Files with the same name without a preceding four-digit number are used to improve and update previously published chapters.
Other files without a preceding four-digit number are for chapters that will be added to the manual in the future.

1. Title
   Every .md file needs a title in the first line in the notation % My Title. The text of the title may be different from the first title used in the document. It is necessary for the creation of the .html files and will be displayed in the title line or tab in the web browser.

2. Headings

   • Heading classes:

     • #
       Use only for main groups and only once in the first file of the main group.
       Main groups are for example: "Installation", "System Administration" or "Network".
     • ## and ###
       Default in .md files.
     • ####
       Rare to not encountered in .md files.
       These headings are integrated by pandoc (LaTex) as bold text in the first line of the following paragraph. This leads to unexpected and undesired effects especially with following lists or tables. Most of the time a line with bold text makes more sense.

   • Special characters
     Allowed are the space, the dot and the hyphen or the minus sign.
     Prohibited are these, and many more characters, because linking to headings with these characters is not possible:

     , ; : ! ? ^ " ' ` ' " " § $ % & / \  
     ( ) { } [ ] + * ~ # | < > " " &#8482 &gth;
     

   • headings unique, concise and short
     Headings that may be linked to must be unique.
     Headings should be short.

   • Use headings sparingly.
     Please use headings sparingly.
     A headline, then a paragraph of two or three lines, then another headline is nonsense.

3. Link to headings
   If you want to link to manual internal pages, the link must always contain the file name and an anchor.

   • Correct spelling of the link
     The file name is always followed by the hash "#" and the target heading (jump address or anchor).
     Complete lower case applies and spaces are to be replaced by "-".
     The following example refers to the heading "### Copyright legal and license information" in the .md document "0000-welcome_en.md".

     [See Copyright](0000-welcome_en.md#copyright-rights--and-license-notices).
     

4. Headline lists
   The files headinglinks-en-by-file and headinglinks-en-by-text support you when linking to manual internal pages.

5. Warnings
   For particularly important notes, quote the lines: "> "
   This creates a quote (an indent with a gray vertical bar and grayed-out font) in MD, and a color-coded block element with padding in PDF and .html documents.

   • Line breaks within warnings:
     Lines must end with two spaces!
     Example:

     Attention
     All data will be lost!

     This is how the Qulltext looks like:

     > **Attention**  
     > All data will be lost!
     

6. Footer in the new files
   The last line of the .md files contains the editing note in HTML notation:

   <div id="rev">Last edited: 2021/05/04</div>        # year/month/day
   

   It is right-aligned, scaled down and grayed out in .md files (local in FF only) and .html files.

7. Code block
   No parsing by MarkDown takes place within these areas. The additional text markups *, **, ` and ~~ have no effect on the text and are represented literal, just like coded characters &gth;.

   • Start and end of the code block
     Insert a blank line before and after each block. The first and the last line consists of three tildes "~~~". Compared to indenting by four spaces, this has the great advantage that the source text remains easily readable.

   • No syntax highlighting
     We do not use syntax highlighting because the display of code blocks and inline code has been adapted to the needs of people with color vision deficiency.

   • Line breaks in code blocks
     Inside of code blocks in the PDF manual, line breaks are applied to lines with more than 60 characters and, if the code block is part of a list, to lines with more than 55 characters. Whenever possible and reasonable, the lines inside of code blocks should not be any longer to achieve a good visual display in the PDF.

   • Code blocks in lists
     Using tildes for code blocks inside of lists ensures a good readability of the md code. If indentations were used instead, the overview and thus the readability would be destroyed from the second level on.
     In the example below (with tildes), the indentations for both levels and functions are identical. Source code and screen display are the same except for the tildes which are not visible on the screen.

     • List item
       Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
       eirmod tempor invidunt ut labore et dolore magna aliquyam

       Code_Block  
       

       • Subitem
         Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
         eirmod tempor invidunt ut labore et dolore magna aliquyam

         Code_Block_2  
         

     This is what the md code looks like:

         * List item
           Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy  
           eirmod tempor invidunt ut labore et dolore magna aliquyam
     
           ~~~
           Code_Block
           ~~~
     
           * Subitem
             Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy  
             eirmod tempor invidunt ut labore et dolore magna aliquyam
     
             ~~~
             Code_Block_2
             ~~~
     

1. bold and highlighted
   Only for use in a technical context for text that can be entered directly into a terminal in this form, or is an output of the terminal.
   No parsing by MarkDown takes place within these areas. The additional text markups *, **, `, and ~~ have no effect on the text and are represented literally, just like coded characters &gth;. The display is created with double asterisk and backtick **` immediately before and in reverse order immediately after the text to be marked.

   • inline code, analogous to source code blocks for example nmcli dev wifi show
   • designation of keys
     for example ALT+CTRL+F2 or Enter

2. highlighted
   Following 1. when used in the technical context. The display is created with single backtick ` immediately before and immediately after the text to be marked.

   • all file names, program names (they are also files), and paths
     for example /home/user/filename, Inkscape
   • command options and their values
     for example dev wifi show; cf. the complete command under 1.
   • variables
     for example IFS

3. bold
   when used in a technical context:

   • user names, group names
     for example root or user1 or www-data.developer
   • file system types
     for example ext4

   when used in a textual context:

   • strong emphasis on text passages (Please use sparingly.)
   • occasionally substitute for 4th order headings (####)

4. italic and quotation marks
   All of the previously mentioned elements when they appear as a quote in the respective context.
   For example, a code block with commands is followed by text with explanations. The command quoted in the text and its options are formatted accordingly. Please note coding order: *"command"* gives "command", "*bad command*" gives "bad command". (The "d" runs into the closing quotation mark.)

5. italic
   when used in textual context:
   discreet emphasis of text passages (Please use sparingly.)

6. italic and highlighted
   currently not used

Everything else, for example tables, lists or link, is based on GitHub Flavored Markdown Spec, but with one exception.
Do not use horizontal lines.

As of 2022/03/30, Author: davydych