From 463bce0470e82b38677136e46bb36cf01a2e87a4 Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Tue, 1 Apr 2014 12:13:38 +0200 Subject: [PATCH] Add more documentation --- docs/README.pct | 212 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/README.pct diff --git a/docs/README.pct b/docs/README.pct new file mode 100644 index 00000000..0351d782 --- /dev/null +++ b/docs/README.pct @@ -0,0 +1,212 @@ + +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. -- 2.39.5