--- /dev/null
+
+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.
projects / bacula / docs / commitdiff