
Note: this document is used for the Bacula Enterprise version and some
things are different in the community version, for example, the directory
bsysmanual is only used in the Bacula Enterprise version.  That said,
this document might be useful.

Philippe Chauvat
18-octobre-2013 First edition
---
21-octobre-2013 - Adding: tree example; what's changed; special needs;
                          images management; coverpage process; images
                          management*
---
24-octobre-2013: Known bug: Currently, the perl 5.18.1 version has a bug which
                           have a big impact on latex2html
---
25-octobre-2013: HTML external references added.

What has changed?
=================
Some important thigs has changed with this new manual design:
- initial Makefile.in in ./docs to include thde two steps process: PDF and WEB
- Makefile.in into docs/manuals/en/{the-manual-name}
- new web.Makefile in each docs/manuals/en/{the-manual-name} directory
- tables management
- images management

What do you need to produce the documentation?
==============================================
- a complete latex distribution
- a working inkscape
- a working latex2html
- the atxy.sty package (currently provided into the docs/bsysmanual/ directory)

On Debian stable version, the following are sufficient to produce the manuals:
aptitude install make
aptitude install inkscape
aptitude install texlive-full
aptitude install latex2html
aptitude install gawk

It could be necessary to define an "EXPORT TEXMFLOCAL=~/texmf".



General layout of the manual building process
=============================================
Directories and files
---------------------
- The LaTeX sources are still in the same directories. In the TYPICAL
  BACULA MANUALS TREE below not all files are displayed and some directories
  are empty to save some space.

Additions
---------
- two tools, located into the docs/tools directory: htmls.sh and
  translatedoc.pl. See the docs/tools/README for more information.
- external references management. See the REFERENCES MANAGEMENT part
  below.

Alerts
------
- The DVI documentation is no longer generated.
- Because of the references, building only one specific manual is more
  or less useless. Re-builiding everything would probably be faster
  and more secure.

Process
-------
The overall process is the following
a) References building management
b) PDF files generation
c) HTML documentation generation

The process to build one PDF manual is the following:
a) Linking the coverpage to the class directory
b) Building PDF images from svg files using inkscape
c) Managing common files like Gnu GPL licence and other files shared
   over manuals.
d) Compiling the tex files with pdflatex command

The process to build an HTML manual is the following:
a) Building the PNG images from svg files using inkscape
b) Convert the high-level LaTeX code into LaTeX that may be interpreted
   by latex2html
c) Run the latex2html command on the code produce in step b)
d) Run the htmls.sh script to convert the latex2html code into something
   useful for current HTML / CSS technology.

REFERENCES MANAGEMENT
=====================
Since the Bacula manual was split into several parts, external references
were broken. The should be OK now using the LaTeX xr and xr-hyper packages.
Because those references are using LaTeX compiling process to generate the
appropriate files and because references are used over several manuals,
this process must be ran over all the manuals, whatever the actual manual
on which the modification(s) is (are) made.

External references are now managed.

How it works?
-------------
The main Makefile (docs/Makefile) find all .tex files containing a "\label{}"
LaTeX command and create a line for each. The line follows this templace
\externaldocument[{the-manual-name}-]{../{the-manual-name}/a_file_name}
Where:
- the-manual-name is one of console, developers, main, etc.
- a_file_name is the file name on which the Makefile found the \label
  command.
e.g:
\externaldocument[main-]{../main/quickstart}

With HTML, the process is defined by:
- finding into the original LaTeX code the \bsysxrling{$1}{$2}{$3}{$4} macro
- replacing them by __XRANCHOR_$1_$2_$3_$4__ 
- modifications made into the translatedoc.pl script (see. docs/tools/README)
- calling the handle-xr-references.pl script at the end of htmls.sh script
  (see docs/tools/README)

COVERPAGE MANAGEMENT
====================
The source coverpage file for a manual is located into the docs/covers/svg
(aka: COVERSDIR in the Makefiles) directory. Each manual has its own cover
named coverpage-{the-manual-name}.svg where {the-manual-name} is the name of the manual. The coverpage
sourcefile is name SVGCOVERSDIR. To build to PDF manuals, LaTeX will search
for a file into the PDF coverpage directory name PDFCOVERSDIR into the
Makefiles. Finally the coverpage filename (without any extension) is named
COVERNAME.
Because the LaTeX class is supposed to compile each and every manuals,
the coverpage filename inclusion is made against BSYSMANNAME. Therefore
the process will link the real coverpage to the BSYSMANNAME file
(bsysmanual-coverpagebackground).
docs/
|-- bsysmanual
|   |-- bsysmanual.cls
|   |-- bsysmanual-coverpagebackground.pdf -> /home/pchauvat/BaculaSystems/git/docs-bee/docs/manuals/en/utility/../../../covers/pdf/coverpage-utility.pdf
|   |-- console.lang.tex
|   `-- external-references.tex
|-- covers
|   |-- pdf
|   |   |-- coverpage-console.pdf
|   |   |-- coverpage-developers.pdf
|   |   |-- coverpage-main.pdf
|   |   |-- coverpage-misc.pdf
|   |   |-- coverpage-problems.pdf
|   |   |-- coverpage-utility.pdf
|   `-- svg
|       |-- coverpage-console.svg
|       |-- coverpage-developers.svg
|       |-- coverpage-main.svg
|       |-- coverpage-misc.svg
|       |-- coverpage-problems.svg
|       |-- coverpage-utility.svg
|       |-- Makefile
|       `-- Makefile.in


IMAGES MANAGEMENT
=================
There are a lot of images into the Bacula manuals, into several format:
svg, png, pdf, eps, jpg, ...
To be able to prioritize them, we need to use some LaTeX directives
like the following:
\graphicspath{{../../../images/pdf/}{../../../images/png/} \
{../../../images/}{../../../images/hires/}{../../../images/eps/}}
\DeclareGraphicsExtensions{.pdf,.png,.jpg,.jpeg,.eps}

The images may be included from the directories specified on the
\graphicspath{} directive.
Depending on the output format, we want to prioritize differently. E.g.
the definitions above are PDF output oriented for what we definitely
prefer PDF, then PNG, then JPG, etc.

Since the new version, I choose to preferably designed images with
inkscape / svg format. Why: two main reasons. Vertorized images are much
more nice than bitmap (IMHO) and inkscape is able to automatically
produce PNG or PDF on the fly (e.g. into Makefile process).


TABLES MANAGEMENT
=================
As tables are always a bit difficult to manage, since the new design,
tables are progressively moved into specific files. Why?
- it let us to use the longtable package and then be able to have a
  better control on how tables are displayed.
- it let us not to have data tables, which don't change frenquently
  and, IMHO, don't give a change to have an overall perspective on
  the text being written.

HTML VERSION
============
The source document is written in LaTeX. The HTML version uses latex2html
converter. Because of the LaTeX possibility to define some "macros", we 
use a three step process:
- convert 'high level' LaTeX to 'low level' LaTeX during the make process
- convert 'low level' LaTeX to 'raw' HTML using latex2html
- convert 'raw' HTML to 'recent' HTML using  dedicated script
  (docs/tools/htmls.sh)

During the HTML compilation process, some temporary directories are created.
They are named www-{the-manual-name} where {the-manual-name} is the name of the manual. Therefore
you will find:
- www-console
- www-developers
- www-main
- www-misc
- www-problems
- www-utility
in the bacula manuals tree.

Please notice that the process described for IMAGES MANAGEMENT is used also
with different values.
