Specific Formatting¶

Configuration¶

Configuration File¶

Configuration file (snippets) should be formatted as

.. code-block:: cfg
    :caption: /etc/my.cnf.d/server.cnf

    ...
    [mysqld]
    innodb_lock_wait_timeout = 300
    ...

This will be displayed as:

/etc/my.cnf.d/server.cnf¶

...
[mysqld]
innodb_lock_wait_timeout = 300
...

The code-block highlighting scheme should be suitable for all kind of configuration files, especially ini files. However, Bareos configuration resources, we use our own scheme, see Bareos Configuration Resource.

Configuration Directive¶

If you want to display a refer to a single configuration option, the following formatting should be used:

``host = s3.amazonaws.com``

The output should look like this:

host = s3.amazonaws.com

However, for a Bareos configuration directive with value use Resource Directive With Value.

System Command¶

If only a single command should be shown, or you just want to refer to a system command from the text use:

:command:`bareos-dbcheck`

The output will look like this:

bareos-dbcheck

Unix Command Session¶

If you want to display a unix command, then it needs to be put in a code block.

Example:

.. code-block:: shell-session
   :caption: Access the local PostgreSQL database
    
   root@host:~# cd /etc/bareos
   root@host:/etc/bareos# ls -1
   bareos-fd.d
   bconsole.conf
   tray-monitor.d
   root@host:/etc/bareos# cd
   root@host:~# ssh root@bareos-dir.example.com
   root@bareos-dir:~# su - postgres
   postgres@bareos-dir:~> psql bareos
   Welcome to psql 8.3.23, the PostgreSQL interactive terminal.
   ...

This will be displayed as:

Access the local PostgreSQL database¶

root@host:~# cd /etc/bareos
root@host:/etc/bareos# ls -1
bareos-fd.d
bconsole.conf
tray-monitor.d
root@host:/etc/bareos# cd
root@host:~# ssh root@bareos-dir.example.com
root@bareos-dir:~# su - postgres
postgres@bareos-dir:~> psql bareos
Welcome to psql 8.3.23, the PostgreSQL interactive terminal.
...

Unix Commmand Prompt¶

Unix command prompts should look identical thoughout the documentation. Normally, we assume a root console on Linux: root@host:~#. Mind a space after the #.

The hostname host is used, if it is a generic host. If the command runs on a specific Bareos server, the specific host name from Bareos Host Names should be used.

Windows¶

Windows Registry Key¶

If you want to display a path where registry key is defined, this formatting should be used:

``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\BackupRestore\FilesNotToBackup``

The output should look like this:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\BackupRestore\FilesNotToBackup

Environment Variable¶

If you want to display an (Unix) environment variable name, the following formating should be followed:

``$HOSTNAME``

``VERSION="18.2.5"``

The output should look like this:

$HOSTNAME

VERSION="18.2.5"

SQL¶

Example:

.. code-block:: sql
    :caption: Optimize the performance of the SQL queries used by :bcommand:`.bvfs_lsdirs`

    CREATE INDEX PathId_JobId_FileIndex_FileNameId ON File(PathId,JobId,FileIndex,FilenameId);

This will be displayed as:

Optimize the performance of the SQL queries used by .bvfs_lsdirs¶

CREATE INDEX PathId_JobId_FileIndex_FileNameId ON File(PathId,JobId,FileIndex,FilenameId);

Logging¶

Currently, only Bareos logs (Bareos Logging) are part of the documentation. General logs are currently not used.

If they should be used in the future, use

.. code-block:: none
   :caption: /var/log/syslog

   Mar 20 11:19:27 ting avahi-daemon[1218]: Interface wlp59s0.IPv6 no longer relevant for mDNS.
   Mar 20 11:19:27 ting systemd[1]: Starting Network Manager Script Dispatcher Service...
   Mar 20 11:19:27 ting dbus-daemon[1263]: [system] Successfully activated service 'org.freedesktop.nm_dispatcher'
   Mar 20 11:19:27 ting systemd[1]: Started Network Manager Script Dispatcher Service.

The output will look like this:

/var/log/syslog¶

Mar 20 11:19:27 ting avahi-daemon[1218]: Interface wlp59s0.IPv6 no longer relevant for mDNS.
Mar 20 11:19:27 ting systemd[1]: Starting Network Manager Script Dispatcher Service...
Mar 20 11:19:27 ting dbus-daemon[1263]: [system] Successfully activated service 'org.freedesktop.nm_dispatcher'
Mar 20 11:19:27 ting systemd[1]: Started Network Manager Script Dispatcher Service.

If logfiles should be shown more often, an own language marker can be implemented for it.

Name¶

In general, specific named items should be written as:

**name**

The output should look like this:

name

Especially it should be used for:

Argument, used synonym with parameter (has been \argument{<name>} in Latex)
Database Table (has been \dbtable{<name>} in Latex)
Database Table Column (has been \dbcolumn{<name>} in Latex)
Parameter, like command line parameter or settings for Bareos configuration directives (has been \parameter{<name>} in Latex)
Plugin Events (has been \pluginevent{<name>} in Latex)
Storage Daemon Backend (has been \sdBackend{type}{subtype} in Latex. Did create indices in the past.)
Software Package (e.g. package bareos-common, has been \package{<name>} in Latex. Did create indices in the past.)
System User (e.g. user root, has been \user{<name>} in Latex))
System Group (e.g. group bareos, has been \group{<name>} in Latex))
Volume Name (has been \volume{<name>} in Latex)
Volume Status (UPPPERCASE) (has been \volumestatus{<name>} in Latex)

Unless a specific rule for this kind of item exists.

Specific rules exist for:

Volume Parameter¶

If you want to display a volume parameter, the following formatting should be used:

Without value:

**Volume Retention**

With value:

**Recycle = yes**

The output should look like this:

Volume Retention

or

Recycle = yes

Operating System¶

If you want to display an operating system name, the following formatting should be used:

  * :os:`AIX 7.1.0.0`
  * :os:`Debian 8`
  * :os:`Fedora 21`
  * :os:`RHEL 7`
  * :os:`SLES 12sp3`
  * :os:`Solaris`
  * :os:`Ubuntu 18.04`
  * ...

The output will look like this:

AIX 7.1.0.0

Debian 8

Fedora 21

RHEL 7

SLES 12sp3

Solaris

Ubuntu 18.04

…

As an index is generated from the operation systems, the naming should be identical in all occurances. The first space seperates the platform from the version.

Email Address¶

An email address can be written as plain text. Sphinx will format it automatically.

Example:

Emails will be send to root@localhost\ .

Output:

Emails will be send to root@localhost.

Backus–Naur form¶

To display Backus–Naur form (BNF) definitions, use following formatting:

.. code-block:: bnf
   :caption: Example BNF

    <syntax>         ::= <rule> | <rule> <syntax>
    <rule>           ::= <opt-whitespace> "<" <rule-name> ">" <opt-whitespace> "::=" <opt-whitespace> <expression> <line-end>
    <opt-whitespace> ::= " " <opt-whitespace> | ""
    <expression>     ::= <list> | <list> <opt-whitespace> "|" <opt-whitespace> <expression>
    <line-end>       ::= <opt-whitespace> <EOL> | <line-end> <line-end>
    <list>           ::= <term> | <term> <opt-whitespace> <list>
    <term>           ::= <literal> | "<" <rule-name> ">"
    <literal>        ::= '"' <text1> '"' | "'" <text2> "'"
    <text1>          ::= "" | <character1> <text1>
    <text2>          ::= "" | <character2> <text2>
    <character>      ::= <letter> | <digit> | "-" | "!" | "#" | "$" | "%" | "&" | "(" | ")" | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | "=" | ">" | "?" | "@" | "[" | "\" | "]" | "^" | "_" | "`" | "{" | "|" | "}" | "~"
    <letter>         ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
    <digit>          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
    <character1>     ::= <character> | "'"
    <character2>     ::= <character> | '"'
    <rule-name>      ::= <letter> | <rule-name> <rule-char>
    <rule-char>      ::= <letter> | <digit> | "-"

The output will look like this:

Example BNF¶

 <syntax>         ::= <rule> | <rule> <syntax>
 <rule>           ::= <opt-whitespace> "<" <rule-name> ">" <opt-whitespace> "::=" <opt-whitespace> <expression> <line-end>
 <opt-whitespace> ::= " " <opt-whitespace> | ""
 <expression>     ::= <list> | <list> <opt-whitespace> "|" <opt-whitespace> <expression>
 <line-end>       ::= <opt-whitespace> <EOL> | <line-end> <line-end>
 <list>           ::= <term> | <term> <opt-whitespace> <list>
 <term>           ::= <literal> | "<" <rule-name> ">"
 <literal>        ::= '"' <text1> '"' | "'" <text2> "'"
 <text1>          ::= "" | <character1> <text1>
 <text2>          ::= "" | <character2> <text2>
 <character>      ::= <letter> | <digit> | "-" | "!" | "#" | "$" | "%" | "&" | "(" | ")" | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | "=" | ">" | "?" | "@" | "[" | "\" | "]" | "^" | "_" | "`" | "{" | "|" | "}" | "~"
 <letter>         ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
 <digit>          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
 <character1>     ::= <character> | "'"
 <character2>     ::= <character> | '"'
 <rule-name>      ::= <letter> | <rule-name> <rule-char>
 <rule-char>      ::= <letter> | <digit> | "-"

Diagrams¶

There are several diagram formats available for you to use.

A block diagram¶

.. blockdiag::

   blockdiag {
     // standard node shapes
     box [shape = box];
     square [shape = square];
     roundedbox [shape = roundedbox];
     dots [shape = dots];

     circle [shape = circle];
     ellipse [shape = ellipse];
     diamond [shape = diamond];
     minidiamond [shape = minidiamond];

     note [shape = note];
     mail [shape = mail];
     cloud [shape = cloud];
     actor [shape = actor];

     beginpoint [shape = beginpoint];
     endpoint [shape = endpoint];

     box -> square -> roundedbox -> dots;
     circle -> ellipse -> diamond -> minidiamond;
     note -> mail -> cloud -> actor;
     beginpoint -> endpoint;

     // node shapes for flowcharts
     condition [shape = flowchart.condition];
     database [shape = flowchart.database];
     terminator [shape = flowchart.terminator];
     input [shape = flowchart.input];

     loopin [shape = flowchart.loopin];
     loopout [shape = flowchart.loopout];

     condition -> database -> terminator -> input;
     loopin -> loopout;
   }

An activity diagram¶

.. actdiag::

   actdiag {
     write -> convert -> image

     lane user {
        label = "User"
        write [label = "Writing reST"];
        image [label = "Get diagram IMAGE"];
     }
     lane actdiag {
        convert [label = "Convert reST to Image"];
     }
   }

A sequence diagram¶

.. seqdiag::
   :desctable:

   seqdiag {
      A -> B -> C;
      A [description = "browsers in each client"];
      B [description = "web server"];
      C [description = "database server"];
   }

.. seqdiag::

   seqdiag {
     # define order of elements
     # seqdiag sorts elements by order they appear
     browser; database; webserver;

     browser  -> webserver [label = "GET /index.html"];
     browser <-- webserver;
     browser  -> webserver [label = "POST /blog/comment"];
                 webserver  -> database [label = "INSERT comment"];
                 webserver <-- database;
     browser <-- webserver;
   }

Name	Description
A	browsers in each client
B	web server
C	database server

A network diagram¶

.. nwdiag::

   {
     network dmz {
         address = "210.x.x.x/24"

         web01 [address = "210.x.x.1"];
         web02 [address = "210.x.x.2"];
     }
     network internal {
         address = "172.x.x.x/24";

         web01 [address = "172.x.x.1"];
         db01;
         app01;
     }
   }

Any PlantUML diagram¶

.. uml::
  :caption: This is an example UML diagram

  Dir -> Fd: Hello Fd
  Dir <- Fd: Hello Dir

Dir -> Fd: Hello Fd
Dir <- Fd: Hello Dir

This is an example UML diagram¶