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:
...
[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.
See also
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:
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:
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:
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 (UPPERCASE) (has been
\volumestatus{<name>}in Latex)
Unless a specific rule for this kind of item exists.
Specific rules exist for:
Substitutions form Common Names.
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 separates 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:
<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
This is an example UML diagram