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 throughout the documentation. Normally, we assume a root console on Linux: root@host:~#. Mind a space after the #.

If no specific user is required, we use the username user. The prompt of a no-root user looks like: user@host:~$.

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