Skip to content

EN_Home

Jump to bottom
ak-li edited this page Apr 25, 2022 · 13 revisions

Welcome to the sidu-manual wiki!

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.

Notes for authors

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.

File names

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.

MD code for block elements

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

MD code for inline elements

  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

Other MD code

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

Clone this wiki locally