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.