docs: fix some formatting

docs/manuals/source/Appendix/BareosPrograms.rst

@@ -285,7 +285,7 @@ For example:
 
 .. code-block:: shell-session
 
-   <command>bls</command> <parameter>FileStorage -V Full1</parameter>
+   root@host:~# bls FileStorage -V Full1
    bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
    12-Sep 18:30 bls JobId 0: Ready to read from volume "Full1" on device "FileStorage" (/var/lib/bareos/storage).
    bls JobId 1: -rwxr-xr-x   1 root     root            4614 2013-01-22 22:24:11  /usr/sbin/service
@@ -308,7 +308,7 @@ To retrieve information, about how a file is stored on the volume, you can use :
 
 .. code-block:: shell-session
 
-   <command>bls</command> <parameter>FileStorage -V TestVolume001 -v</parameter>
+   root@host:~# bls FileStorage -V TestVolume001 -v
    bls: butil.c:273-0 Using device: "FileStorage" for reading.
    22-Jun 19:34 bls JobId 0: Ready to read from volume "TestVolume001" on device "Storage1" (/var/lib/bareos/storage).
    Volume Label Record: VolSessionId=1 VolSessionTime=1498152622 JobId=0 DataLen=168
@@ -339,7 +339,7 @@ Using the :strong:`-L` the label information of a Volume is shown:
 .. code-block:: shell-session
    :caption: bls: show volume label
 
-   <command>bls</command> <parameter>-L /var/lib/bareos/storage/testvol</parameter>
+   root@host:~# bls -L /var/lib/bareos/storage/testvol
    bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
    12-Sep 18:41 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage).
 
@@ -367,7 +367,7 @@ If you are listing a Volume to determine what Jobs to restore, normally the :str
 .. code-block:: shell-session
    :caption: bls: list jobs
 
-   <command>bls</command> <parameter>/var/lib/bareos/storage/testvol -j</parameter>
+   root@host:~# bls /var/lib/bareos/storage/testvol -j
    bls: butil.c:282-0 Using device: "/var/lib/bareos/storage" for reading.
    12-Sep 18:33 bls JobId 0: Ready to read from volume "testvol" on device "FileStorage" (/var/lib/bareos/storage).
    Volume Record: File:blk=0:193 SessId=1 SessTime=1362582744 JobId=0 DataLen=158
@@ -402,7 +402,7 @@ Normally, except for debugging purposes, you will not need to list Bareos blocks
 
 .. code-block:: shell-session
 
-   <command>bls</command> <parameter>-k /tmp/File002</parameter>
+   root@host:~# bls -k /tmp/File002
    bls: butil.c:148 Using device: /tmp
    Block: 1 size=64512
    Block: 2 size=64512
@@ -416,7 +416,7 @@ By adding the :strong:`-v` option, you can get more information, which can be us
 
 .. code-block:: shell-session
 
-   <command>bls</command> <parameter>-k -v /tmp/File002</parameter>
+   root@host:~# bls -k -v /tmp/File002
    Date label written: 2002-10-19 at 21:16
    Block: 1 blen=64512 First rec FI=VOL_LABEL SessId=1 SessTim=1035062102 Strm=0 rlen=147
    Block: 2 blen=64512 First rec FI=6 SessId=1 SessTim=1035062102 Strm=DATA rlen=4087
@@ -434,7 +434,7 @@ If you want to know even more, add a second :strong:`-v` to the command line to
 
 .. code-block:: shell-session
 
-   <command>bls</command> <parameter>-k -vv /tmp/File002</parameter>
+   root@host:~# bls -k -vv /tmp/File002
    bls: block.c:79 Dump block  80f8ad0: size=64512 BlkNum=1
                   Hdrcksum=b1bdfd6d cksum=b1bdfd6d
    bls: block.c:92    Rec: VId=1 VT=1035062102 FI=VOL_LABEL Strm=0 len=147 p=80f8b40
@@ -559,20 +559,19 @@ Extracting Under Windows
 
 :index:`\ <single: Windows; bextract>`\ 
 
+.. warning::
 
+   If you use :command:`bextract` under Windows, the ordering of the parameters is essential.
 
-   .. warning::
-
-      If you use :command:`bextract` under Windows, the ordering of the parameters is essential.
 
 To use :command:`bextract`, the Bareos Storage Daemon must be installed. As bextract works on tapes or disk volumes, these must be configured in the Storage Daemon configuration file, normally found at :file:`C:\\ProgrammData\\Bareos\\bareos-sd.conf`. However, it is not required to start the Bareos Storage Daemon. Normally, if the Storage Daemon would be able to run, :command:`bextract` would not be required.
 
 After installing, :command:`bextract` can be called via command line:
 
-.. code-block:: shell-session
+.. code-block:: doscon
    :caption: Call of bextract
 
-   C:\Program Files\Bareos .\bextract.exe -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V <Volume> <YourStorage> <YourDestination>
+   C:\Program Files\Bareos> .\bextract.exe -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V <Volume> <YourStorage> <YourDestination>
 
 If you want to use exclude or include files you need to write them like you do on Linux. That means each path begins with a "/" and not with "yourdrive:/". You need to specify the parameter -e exclude.list as first parameter. For example:
 
@@ -582,10 +581,10 @@ If you want to use exclude or include files you need to write them like you do o
    /Program Files/Bareos/bareos-dir.exe
    /ProgramData/
 
-.. code-block:: shell-session
+.. code-block:: doscon
    :caption: Call bextract with exclude list
 
-   C:\Program Files\Bareos .\bextract.exe -e exclude.list -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V <Volume> <YourStorage> <YourDestination>
+   C:\Program Files\Bareos> .\bextract.exe -e exclude.list -c "C:\ProgrammData\Bareos\bareos-sd.conf" -V <Volume> <YourStorage> <YourDestination>
 
 
 .. _bscan:

docs/manuals/source/Appendix/Debugging.rst

@@ -30,7 +30,7 @@ For this to work, you need to ensure that a few things are setup correctly on yo
    .. code-block:: shell-session
       :caption: disable ptrace protection to enable debugging (required on Ubuntu Linux)
 
-      <command> </command><parameter>test -e /proc/sys/kernel/yama/ptrace_scope && echo 0 > /proc/sys/kernel/yama/ptrace_scope</parameter>
+      root@host:~# test -e /proc/sys/kernel/yama/ptrace_scope && echo 0 > /proc/sys/kernel/yama/ptrace_scope
 
 If all the above conditions are met, the daemon that crashes will produce a traceback report and email it. If the above conditions are not true, you can run the debugger by hand as described below.
 
@@ -44,22 +44,23 @@ To "manually" test the traceback feature, you simply start Bareos then obtain th
 .. code-block:: shell-session
    :caption: get the process ID of a running Bareos daemon
 
-   <command> </command><parameter>ps fax | grep bareos-dir</parameter>
+   root@host:~# ps fax | grep bareos-dir
     2103 ?        S      0:00 /usr/sbin/bareos-dir
 
 which in this case is 2103. Then while Bareos is running, you call the program giving it the path to the Bareos executable and the PID. In this case, it is:
 
 .. code-block:: shell-session
    :caption: get traceback of running Bareos director daemon
 
-   <command> </command><parameter>btraceback /usr/sbin/bareos-dir 2103</parameter>
+   root@host:~# btraceback /usr/sbin/bareos-dir 2103
 
 It should produce an email showing you the current state of the daemon (in this case the Director), and then exit leaving Bareos running as if nothing happened. If this is not the case, you will need to correct the problem by modifying the :command:`btraceback` script.
 
 Getting A Traceback On Other Systems
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It should be possible to produce a similar traceback on systems other than Linux, either using :command:`gdb` or some other debugger. Solaris:index:`\ <single: Platform; Solaris; Debug>`\  with :command:`dbx` loaded works quite fine. On other systems, you will need to modify the :command:`btraceback` program to invoke the correct debugger, and possibly correct the :file:`btraceback.gdb` script to have appropriate commands for your debugger.
+It should be possible to produce a similar traceback on systems other than Linux, either using :command:`gdb` or some other debugger.
+:index:`Solaris <single: Platform; Solaris; Debug>`\  with :command:`dbx` loaded works quite fine. On other systems, you will need to modify the :command:`btraceback` program to invoke the correct debugger, and possibly correct the :file:`btraceback.gdb` script to have appropriate commands for your debugger.
 Please keep in mind that for any debugger to work, it will most likely need to run as root.
 
 Manually Running Bareos Under The Debugger
@@ -74,10 +75,11 @@ If for some reason you cannot get the automatic traceback, or if you want to int
    .. code-block:: shell-session
       :caption: run the Bareos Storage daemon in the debugger
 
-      <command>gdb</command><parameter> --args /usr/sbin/bareos-sd -f -s -d 200</parameter>
-      (gdb) <input>run</input>
+      root@host:~# su - bareos -s /bin/bash
+      bareos@host:~# gdb --args /usr/sbin/bareos-sd -f -s -d 200
+      (gdb) run
 
-   Parameter:
+   Bareos Parameter:
 
    -f
       foreground
@@ -99,12 +101,8 @@ If for some reason you cannot get the automatic traceback, or if you want to int
 #. To get a general traceback of all threads, issue the following command:
 
    .. code-block:: shell-session
-      :caption: run the Bareos Storage daemon in the debugger
+      :caption: Bareos Storage daemon in a debugger session
 
-      (gdb) <input>thread apply all bt</input>
+      (gdb) thread apply all bt
 
    After that you can issue any debugging command.
-
-
-
-

docs/manuals/source/Appendix/DisasterRecoveryUsingBareos.rst

@@ -113,7 +113,7 @@ If you have installed and configured ReaR on your system, type
 .. code-block:: shell-session
    :caption: Create Rescue Image
 
-   <command>rear</command><parameter> -v mkrescue</parameter>
+   root@host:~# rear -v mkrescue
 
 to create the rescue image. If you used the configuration example above, you will get a bootable ISO image which can be burned onto a CD.
 
@@ -135,26 +135,21 @@ In case, you want to recover your system, boot it using the generated ReaR recov
 .. code-block:: shell-session
    :caption: Restore your system using Rear and Bareos
 
-   <command>rear</command><parameter> recover</parameter>
+   root@host:~# rear recover
 
 ReaR will now use the most recent backup from Bareos to restore your system. When the restore job has finished, ReaR will start a new shell which you can use to verify if the system has been restored correctly. The restored system can be found under the :file:`/mnt/local` directory. When you are done< with the verification, type ’exit’ to leave the shell, getting back to the recovery process. Finally, you will be asked to confirm that everything is correct. Type ’yes’ to continue. After that,
 ReaR will restore your bootloader. Recovery is complete.
 
 
 
 
-
-
+.. _section-RestoreServer:
 
 Restoring a Bareos Server
 -------------------------
 
 :index:`\ <single: Restore; Bareos Server>`\  
 
-.. _section-RestoreServer:
-
-
-
 Above, we considered how to recover a client machine where a valid Bareos server was running on another machine. However, what happens if your server goes down and you no longer have a running Director, Catalog, or Storage daemon? There are several solutions:
 
 #. Bring up static versions of your Director, Catalog, and Storage daemon on the damaged machine.
@@ -186,7 +181,3 @@ The second suggestion is probably a much simpler solution, and one I have done m
 -  Start the database, and restart Bareos. Then use the Console restore command, restore all the files on the damaged machine, where you have loaded a Bareos File daemon using the Rescue disk.
 
 For additional details of restoring your database, please see the :ref:`section-RestoreCatalog` chapter.
-
-
-
-

docs/manuals/source/Configuration/Director.rst

@@ -1572,7 +1572,7 @@ Now lets take a slight variation on the above and suppose you want to save all y
 .. code-block:: shell-session
    :caption: df
 
-   <command>df</command>
+   user@host:~$ df
    Filesystem      1k-blocks      Used Available Use% Mounted on
    /dev/hda5         5044156    439232   4348692  10% /
    /dev/hda1           62193      4935     54047   9% /boot

docs/manuals/source/DocumentationStyleGuide/SpecificFormatting.rst

@@ -82,6 +82,9 @@ 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 ``#``.
 
+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 :ref:`DocumentationStyleGuide/BareosSpecificFormatting/BareosHostNames:Bareos Host Names` should be used.

docs/manuals/source/DocumentationStyleGuide/example/code-block-shell-session.rst.inc

@@ -9,6 +9,6 @@
    root@host:/etc/bareos# cd
    root@host:~# ssh root@bareos-dir.example.com
    root@bareos-dir:~# su - postgres
-   postgres@bareos-dir:~> psql bareos
+   postgres@bareos-dir:~$ psql bareos
    Welcome to psql 8.3.23, the PostgreSQL interactive terminal.
    ...

docs/manuals/source/IntroductionAndTutorial/Tutorial.rst

@@ -65,7 +65,7 @@ The :command:`bconsole` runs the Bareos Console program, which connects to the |
 .. code-block:: shell-session
    :caption: bconsole
 
-   <command>bconsole</command>
+   root@host:~# bconsole
    Connecting to Director bareos:9101
    Enter a period to cancel a command.
    *
@@ -562,7 +562,7 @@ After exiting the Console program, you can examine the files in :file:`/tmp/bare
 .. code-block:: shell-session
    :caption: remove restore directory
 
-   <command>rm</command> -rf /tmp/bareos-restore
+   root@host:~# rm -rf /tmp/bareos-restore
 
 Quitting the Console Program
 ----------------------------

docs/manuals/source/IntroductionAndTutorial/UpdatingBareos.rst

@@ -26,34 +26,35 @@ Sometimes improvements in Bareos make it necessary to update the database scheme
 
 
 
-   .. warning::
+.. warning::
+
+   If the Bareos catalog database does not have the current schema, the Bareos Director refuses to start.
 
-      If the Bareos catalog database does not have the current schema, the Bareos Director refuses to start.
 
 Detailed information can then be found in the log file :file:`/var/log/bareos/bareos.log`.
 
 Take a look into the :ref:`Release Notes <releasenotes>` to see which Bareos updates do require a database scheme update.
 
 
 
-   .. warning::
+.. warning::
 
-      Especially the upgrade to Bareos >= 17.2.0 restructures the **File** database table. In larger installations this is very time consuming and temporarily doubles the amount of required database disk space.
+   Especially the upgrade to Bareos >= 17.2.0 restructures the **File** database table. In larger installations this is very time consuming and temporarily doubles the amount of required database disk space.
 
 Debian based Linux Distributions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Since Bareos :sinceVersion:`14.2.0: dbconfig-common (Debian)` the Debian (and Ubuntu) based packages support the **dbconfig-common** mechanism to create and update the Bareos database. If this is properly configured, the database schema will be automatically adapted by the Bareos packages.
 
+.. warning::
 
+   When using the PostgreSQL backend and updating to Bareos < 14.2.3, it is necessary to manually grant database permissions, normally by using
 
-   .. warning::
-
-      When using the PostgreSQL backend and updating to Bareos < 14.2.3, it is necessary to manually grant database permissions, normally by using
 
 .. code-block:: shell-session
 
-   <command> </command><parameter>su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges</parameter>
+   root@host:~# su - postgres -c /usr/lib/bareos/scripts/grant_bareos_privileges
+
 
 For details see :ref:`section-dbconfig`.
 

docs/manuals/source/TasksAndConcepts/AutochangerSupport.rst

@@ -623,12 +623,13 @@ Direct access to Volumes with with non-default block sizes
 
 To be able to read a volume written with an arbitrary block size, you need to set the :config:option:`sd/device/LabelBlockSize`\  (to be able to to read the label block) and the :config:option:`sd/device/MaximumBlockSize`\  (to be able to read the data blocks) setting in the device definition used by those tools to be able to open the medium.
 
-Example using :command:`bls` with a tape that was written with another blocksize than the ``DEFAULT_BLOCK_SIZE``\  (63k), but with the default label block size of 63k:
+Example using :command:`bls` with a tape that was written with another blocksize than the ``DEFAULT_BLOCK_SIZE``\  (63k),
+but with the default label block size of 63k:
 
 .. code-block:: shell-session
    :caption: bls with non-default block size
 
-   <command>bls</command> <parameter>FC-Drive-1 -V A00007L4</parameter>
+   root@host:~# bls FC-Drive-1 -V A00007L4
    bls: butil.c:289-0 Using device: "FC-Drive-1" for reading.
    25-Feb 12:47 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst).
    25-Feb 12:47 bls JobId 0: Cartridge change or "update slots" may be required.
@@ -643,7 +644,7 @@ As can be seen, :command:`bls` manages to read the label block as it knows what
 .. code-block:: shell-session
    :caption: dmesg
 
-   <command>dmesg</command>
+   root@host:~# dmesg
    [...]
    st2: Failed to read 131072 byte block with 64512 byte transfer.
    [...]
@@ -673,13 +674,14 @@ Now we can call bls again, and everything works as expected:
 .. code-block:: shell-session
    :caption: bls with non-default block size
 
-   <command>bls</command> <parameter>FC-Drive-1 -V A00007L4</parameter>
+   root@host:~# bls FC-Drive-1 -V A00007L4
    bls: butil.c:289-0 Using device: "FC-Drive-1" for reading.
    25-Feb 12:49 bls JobId 0: No slot defined in catalog (slot=0) for Volume "A00007L4" on "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst).
    25-Feb 12:49 bls JobId 0: Cartridge change or "update slots" may be required.
    25-Feb 12:49 bls JobId 0: Ready to read from volume "A00007L4" on device "FC-Drive-1" (/dev/tape/by-id/scsi-350011d00018a5f03-nst).
    bls JobId 203: [...]
 
+
 How to configure the block sizes in your environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/manuals/source/TasksAndConcepts/NdmpBackupsWithBareos.rst

@@ -372,10 +372,11 @@ Now restart the |sd|. If everything is correct, the |sd| starts and listens now
 
 .. code-block:: shell-session
 
-   <command>netstat</command> <parameter>-lntp | grep bareos-sd</parameter>
+   root@host:~# netstat -lntp | grep bareos-sd
    tcp        0      0 0.0.0.0:9103            0.0.0.0:*               LISTEN      10661/bareos-sd
    tcp        0      0 0.0.0.0:10000           0.0.0.0:*               LISTEN      10661/bareos-sd
 
+
 Bareos Director: Configure a Paired Storage
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/manuals/source/TasksAndConcepts/Plugins.rst

@@ -406,7 +406,7 @@ As of http://kb.vmware.com/kb/2075984 manually enabling CBT is currently not wor
 .. code-block:: shell-session
    :caption: usage of vmware\_cbt\_tool.py
 
-   # <parameter>vmware_cbt_tool.py --help</parameter>
+   user@host:~$ vmware_cbt_tool.py --help
    usage: vmware_cbt_tool.py [-h] -s HOST [-o PORT] -u USER [-p PASSWORD] -d
                              DATACENTER [-f FOLDER] [-v VMNAME]
                              [--vm-uuid VM_UUID] [--enablecbt] [--disablecbt]
@@ -444,7 +444,7 @@ For the above configuration example, the command to enable CBT would be
 .. code-block:: shell-session
    :caption: Example using vmware\_cbt\_tool.py
 
-   # <parameter>vmware_cbt_tool.py -s vcenter.example.org -u bakadm@vsphere.local -p Bak.Adm-1234 -d mydc1 -f /webservers -v websrv1 --enablecbt</parameter>
+   user@host:~$ vmware_cbt_tool.py -s vcenter.example.org -u bakadm@vsphere.local -p Bak.Adm-1234 -d mydc1 -f /webservers -v websrv1 --enablecbt
 
 Note: CBT does not work if the virtual hardware version is 6 or earlier.