Skip to content

Commit

Permalink
docs: (LaTex) adapted documenation to be better convertible
Browse files Browse the repository at this point in the history
and also fix the generation of Latex based documentaion.
The top level Makefile will only build the Latex documentation.
Also disable the test, if all configuration directives are defined.
As the documentation will be switched to RST/Sphinx,
the new configuration directives will not be documented in Latex.
  • Loading branch information
joergsteffens committed Mar 9, 2019
1 parent 8b48304 commit 920fe2b
Show file tree
Hide file tree
Showing 6 changed files with 21 additions and 166 deletions.
2 changes: 1 addition & 1 deletion docs/Makefile
@@ -1,5 +1,5 @@

SUBDIRS = manuals/en/new_main_reference/ manuals/en/main/
SUBDIRS = manuals/en/main/
.PHONY: $(SUBDIRS)

all: TARGET=
Expand Down
5 changes: 3 additions & 2 deletions docs/manuals/en/main/Makefile
Expand Up @@ -12,7 +12,7 @@ BAREOS_SD=/usr/sbin/bareos-sd
BAREOS_FD=/usr/sbin/bareos-fd
BCONSOLE=/usr/bin/bconsole
BAREOS_TRAY_MONITOR=/usr/bin/bareos-tray-monitor
GENERATED_RESOURCE_DESCRIPTIONS=../../scripts/generate-resoure-descriptions.py
GENERATED_RESOURCE_DESCRIPTIONS=../../scripts/generate-resoure-descriptions.py --latex
GENERATED_PACKAGE_INFO=../../scripts/generate-bareos-package-info.py

INDEXES = bareos-manual-main-reference.console.ind \
Expand Down Expand Up @@ -146,7 +146,8 @@ check: bareos-manual-main-reference.pdf
@# hyperlink: multiline: pdfTeX warning .* has been reference$d but does not exist
@# defDirective multiline: Warning: defDirective{Dir}{Director}{PluginNames} has no matching resourceDirective and will be ignored.
@# pdfTeX warning (dest): name{directiveDirJobMigration\040Time} has been referenced but does not exist, replaced by a fixed one
@if ! grep "LaTeX Warning: Hyper reference .* undefined on input\|LaTeX Warning: There were undefined references.\|pdfTeX warning .* has been reference\|Warning: defDirective\|pdfTeX warning (dest): name" $(LOG); then echo "CHECK: OK"; true; else echo "CHECK: FAILED: undefined references"; false; fi
@# Warning: defDirective\|
@if ! grep "LaTeX Warning: Hyper reference .* undefined on input\|LaTeX Warning: There were undefined references.\|pdfTeX warning .* has been reference\|pdfTeX warning (dest): name" $(LOG); then echo "CHECK: OK"; true; else echo "CHECK: FAILED: undefined references"; false; fi

clean:
if [ -e html/images/ ]; then rm -f html/images/* && rmdir html/images; fi
Expand Down
18 changes: 0 additions & 18 deletions docs/manuals/en/main/bareos.sty
Expand Up @@ -376,24 +376,6 @@ Version $>=$ #3%
\newcommand{\deprecatedSince}[3]{This option is deprecated since version #3}
\newcommand{\removedSince}[3]{This option is removed since version #3}

% deprecated. use xdirective instead.
\newcommand{\directive}[6]{
% 1: config file (dir | sd | fd)
% 2: directive name
% 3: directive type/value
% 4: "required" | ""
% 5: default value
% 6: since version
\item [#2 = {\textless}#3{\textgreater}]
\hfill
\ifthenelse{\isempty{#5}}{}{(default: #5)}
\ifthenelse{\isempty{#4}}{}{(#4)}
\ifthenelse{\isempty{#6}}{}{\sinceVersion{#1}{#2}{#6}}
\hfill \\
\index[#1]{#2}
\index[#1]{Directive!#2}
}

\newcommand{\xdirective}[8]{
% 1: config file (Dir | Sd | Fd | Console)
% 2: Resource
Expand Down
24 changes: 8 additions & 16 deletions docs/manuals/en/main/dirdconf-fileset.tex
Expand Up @@ -30,7 +30,7 @@ \subsection{FileSet Include Ressource}
\end{enumerate}

\begin{description}
\directive{dir}{File}{ filename \textbar\ dirname \textbar\ \textbar command \textbar\ \textbackslash\textless includefile-client \textbar\ \textless includefile-server }{}{}{}
\item [File = filename \textbar\ dirname \textbar\ \textbar command \textbar\ \textbackslash\textless includefile-client \textbar\ \textless includefile-server] \hfill \\
The file list
consists of one file or directory name per line. Directory names should be
specified without a trailing slash with Unix path notation.
Expand Down Expand Up @@ -289,7 +289,7 @@ \subsection{FileSet Include Ressource}
\directive{dir}{Exclude Dir Containing}{filename}{}{}{}
\item [Exclude Dir Containing = filename]
This directive can be added to the Include section of the FileSet resource. If the specified
filename ({\bf filename-string}) is found on the Client in any directory to be
backed up, the whole directory will be ignored (not backed up).
Expand Down Expand Up @@ -335,7 +335,7 @@ \subsection{FileSet Include Ressource}
files, directories, etc).
\directive{dir}{Plugin}{plugin-name:plugin-parameter1:plugin-parameter2:$\ldots$}{}{}{}
\item [Plugin = plugin-name:plugin-parameter1:plugin-parameter2:$\ldots$]
\label{directive-fileset-plugin}
Instead of only specifying files, a file set can also use plugins.
Plugins are additional libraries that handle specific requirements.
Expand All @@ -354,7 +354,7 @@ \subsection{FileSet Include Ressource}
Note: It is also possible to define more than one plugin directive in a FileSet to do several database dumps at once.
\directive{dir}{Options}{$\ldots$}{}{}{}
\item [Options = $\ldots$]
See the \nameref{fileset-options} section.
\end{description}
Expand Down Expand Up @@ -412,10 +412,10 @@ \subsubsection{FileSet Options Ressource}
The directives within an Options resource may be one of the following:
\begin{description}
\xdirective{Dir}{}{AutoExclude}{\dtYesNo}{}{yes}{14.2.2}{%
\item[Auto Exclude = \dtYesNo] (default: yes) \hfill \\
Automatically exclude files not intended for backup.
Currently only used for Windows, to exclude files defined in the registry key \registrykey{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\BackupRestore\FilesNotToBackup}, see section \nameref{FilesNotToBackup}.
}
Since \sinceVersion{Dir}{Auto Exclude}{14.2.2}.
\item [compression={\textless}GZIP{\textbar}GZIP1{\textbar}...{\textbar}GZIP9{\textbar}LZO{\textbar}LZFAST{\textbar}LZ4{\textbar}LZ4HC{\textgreater}] \hfill \\
\index[dir]{compression}
Expand Down Expand Up @@ -1044,10 +1044,9 @@ \subsubsection{FileSet Options Ressource}
so you may want to test your expressions prior to running your
backup by using the \nameref{bregex} program.
\xdirective{dir}{}{Exclude}{\dtYesNo}{}{no}{}{%
\item[Exclude = \dtYesNo]%
When enabled, any files matched within the
Options will be excluded from the backup.
}
\item [aclsupport=yes{\textbar}no] \hfill \\
\index[dir]{aclsupport}
Expand Down Expand Up @@ -1264,15 +1263,8 @@ \subsection{FileSet Exclude Ressource}
\begin{description}
% file | directoy | |command | \<includefile-client | <includefile-server
\xdirective{dir}{}{File}{
filename \textbar\
directory \textbar\
\textbar command \textbar\
\textbackslash\textless includefile-client \textbar\
\textless includefile-server
}{}{}{}{%
\item [File = filename \textbar\ dirname \textbar\ \textbar command \textbar\ \textbackslash\textless includefile-client \textbar\ \textless includefile-server] \hfill \\
Files to exclude are descripted in the same way as at the \nameref{fileset-include}.
}
\end{description}
For example:
Expand Down
18 changes: 9 additions & 9 deletions docs/manuals/en/main/tls.tex
Expand Up @@ -42,12 +42,12 @@ \section{TLS Configuration Directives}
These directives are defined as follows:

\begin{description}
\directive{dir}{TLS Enable}{yes{\textbar}no}{}{no}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Enable}]%
Enable TLS support. Without setting \configdirective{TLS Require}=yes,
the connection can fall back to unencrypted connection,
if the other side does not support TLS.

\directive{dir}{TLS Require}{yes{\textbar}no}{}{no}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Require}]%
Require TLS connections.
If TLS is not required,
then Bareos will connect with other daemons either with or without TLS depending
Expand All @@ -56,18 +56,18 @@ \section{TLS Configuration Directives}
then Bareos will refuse any connection that does not use TLS.
\configdirective{TLS Require}=yes implicitly sets \configdirective{TLS Enable}=yes.

\directive{dir}{TLS Certificate}{filename}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Certificate}]%
The full path and filename of a PEM encoded TLS certificate. It can be
used as either a client or server certificate.
It is used because PEM files are base64 encoded and hence ASCII
text based rather than binary.
They may also contain encrypted information.

\directive{dir}{TLS Key}{filename}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Key}]%
The full path and filename of a PEM encoded TLS private key. It must
correspond to the certificate specified in the \configdirective{TLS Certificate} configuration directive.

\directive{dir}{TLS Verify Peer}{yes{\textbar}no}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Verify Peer}]%
Request and verify the peers certificate.

In server context, unless the \configdirective{TLS Allowed CN} configuration directive is specified,
Expand All @@ -77,15 +77,15 @@ \section{TLS Configuration Directives}
the \configdirective{Address} and \configdirective{TLS Allowed CN} configuration directives.


\directive{dir}{TLS Allowed CN}{stringlist}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS Allowed CN}]%
Common name attribute of allowed peer certificates.
If \configdirective{TLS Verify Peer}=yes, all connection request certificates
will be checked against this list.

This directive may be specified more than once.


\directive{dir}{TLS CA Certificate File}{filename}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS CA Certificate File}]%
The full path and filename specifying a
PEM encoded TLS CA certificate(s). Multiple certificates are
permitted in the file.
Expand All @@ -96,7 +96,7 @@ \section{TLS Configuration Directives}

In a server context, it is only required if \configdirective{TLS Verify Peer} is used.

\directive{dir}{TLS CA Certificate Dir}{directory}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS CA Certificate Dir}]%
Full path to TLS CA certificate directory. In the current implementation,
certificates must be stored PEM encoded with OpenSSL-compatible hashes,
which is the subject name's hash and an extension of {\bf .0}.
Expand All @@ -108,7 +108,7 @@ \section{TLS Configuration Directives}
In a server context, it is only required if \configdirective{TLS Verify Peer} is used.


\directive{dir}{TLS DH File}{filename}{}{}{}%
\item [\linkResourceDirective{Dir}{Director}{TLS DH File}]%
Path to PEM encoded Diffie-Hellman parameter file. If this directive is
specified, DH key exchange will be used for the ephemeral keying, allowing
for forward secrecy of communications. DH key exchange adds an additional
Expand Down

This file was deleted.

0 comments on commit 920fe2b

Please sign in to comment.