git.sur5r.net Git - bacula/docs/blob - docs/README.pct

   1
   2 Note: this document is used for the Bacula Enterprise version and some
   3 things are different in the community version, for example, the directory
   4 bsysmanual is only used in the Bacula Enterprise version.  That said,
   5 this document might be useful.
   6
   7 Philippe Chauvat
   8 18-octobre-2013 First edition
   9 ---
  10 21-octobre-2013 - Adding: tree example; what's changed; special needs;
  11                           images management; coverpage process; images
  12                           management*
  13 ---
  14 24-octobre-2013: Known bug: Currently, the perl 5.18.1 version has a bug which
  15                            have a big impact on latex2html
  16 ---
  17 25-octobre-2013: HTML external references added.
  18
  19 What has changed?
  20 =================
  21 Some important thigs has changed with this new manual design:
  22 - initial Makefile.in in ./docs to include thde two steps process: PDF and WEB
  23 - Makefile.in into docs/manuals/en/{the-manual-name}
  24 - new web.Makefile in each docs/manuals/en/{the-manual-name} directory
  25 - tables management
  26 - images management
  27
  28 What do you need to produce the documentation?
  29 ==============================================
  30 - a complete latex distribution
  31 - a working inkscape
  32 - a working latex2html
  33 - the atxy.sty package (currently provided into the docs/bsysmanual/ directory)
  34
  35 On Debian stable version, the following are sufficient to produce the manuals:
  36 aptitude install make
  37 aptitude install inkscape
  38 aptitude install texlive-full
  39 aptitude install latex2html
  40 aptitude install gawk
  41
  42 It could be necessary to define an "EXPORT TEXMFLOCAL=~/texmf".
  43
  44
  45
  46 General layout of the manual building process
  47 =============================================
  48 Directories and files
  49 ---------------------
  50 - The LaTeX sources are still in the same directories. In the TYPICAL
  51   BACULA MANUALS TREE below not all files are displayed and some directories
  52   are empty to save some space.
  53
  54 Additions
  55 ---------
  56 - two tools, located into the docs/tools directory: htmls.sh and
  57   translatedoc.pl. See the docs/tools/README for more information.
  58 - external references management. See the REFERENCES MANAGEMENT part
  59   below.
  60
  61 Alerts
  62 ------
  63 - The DVI documentation is no longer generated.
  64 - Because of the references, building only one specific manual is more
  65   or less useless. Re-builiding everything would probably be faster
  66   and more secure.
  67
  68 Process
  69 -------
  70 The overall process is the following
  71 a) References building management
  72 b) PDF files generation
  73 c) HTML documentation generation
  74
  75 The process to build one PDF manual is the following:
  76 a) Linking the coverpage to the class directory
  77 b) Building PDF images from svg files using inkscape
  78 c) Managing common files like Gnu GPL licence and other files shared
  79    over manuals.
  80 d) Compiling the tex files with pdflatex command
  81
  82 The process to build an HTML manual is the following:
  83 a) Building the PNG images from svg files using inkscape
  84 b) Convert the high-level LaTeX code into LaTeX that may be interpreted
  85    by latex2html
  86 c) Run the latex2html command on the code produce in step b)
  87 d) Run the htmls.sh script to convert the latex2html code into something
  88    useful for current HTML / CSS technology.
  89
  90 REFERENCES MANAGEMENT
  91 =====================
  92 Since the Bacula manual was split into several parts, external references
  93 were broken. The should be OK now using the LaTeX xr and xr-hyper packages.
  94 Because those references are using LaTeX compiling process to generate the
  95 appropriate files and because references are used over several manuals,
  96 this process must be ran over all the manuals, whatever the actual manual
  97 on which the modification(s) is (are) made.
  98
  99 External references are now managed.
 100
 101 How it works?
 102 -------------
 103 The main Makefile (docs/Makefile) find all .tex files containing a "\label{}"
 104 LaTeX command and create a line for each. The line follows this templace
 105 \externaldocument[{the-manual-name}-]{../{the-manual-name}/a_file_name}
 106 Where:
 107 - the-manual-name is one of console, developers, main, etc.
 108 - a_file_name is the file name on which the Makefile found the \label
 109   command.
 110 e.g:
 111 \externaldocument[main-]{../main/quickstart}
 112
 113 With HTML, the process is defined by:
 114 - finding into the original LaTeX code the \bsysxrling{$1}{$2}{$3}{$4} macro
 115 - replacing them by __XRANCHOR_$1_$2_$3_$4__
 116 - modifications made into the translatedoc.pl script (see. docs/tools/README)
 117 - calling the handle-xr-references.pl script at the end of htmls.sh script
 118   (see docs/tools/README)
 119
 120 COVERPAGE MANAGEMENT
 121 ====================
 122 The source coverpage file for a manual is located into the docs/covers/svg
 123 (aka: COVERSDIR in the Makefiles) directory. Each manual has its own cover
 124 named coverpage-{the-manual-name}.svg where {the-manual-name} is the name of the manual. The coverpage
 125 sourcefile is name SVGCOVERSDIR. To build to PDF manuals, LaTeX will search
 126 for a file into the PDF coverpage directory name PDFCOVERSDIR into the
 127 Makefiles. Finally the coverpage filename (without any extension) is named
 128 COVERNAME.
 129 Because the LaTeX class is supposed to compile each and every manuals,
 130 the coverpage filename inclusion is made against BSYSMANNAME. Therefore
 131 the process will link the real coverpage to the BSYSMANNAME file
 132 (bsysmanual-coverpagebackground).
 133 docs/
 134 |-- bsysmanual
 135 |   |-- bsysmanual.cls
 136 |   |-- bsysmanual-coverpagebackground.pdf -> /home/pchauvat/BaculaSystems/git/docs-bee/docs/manuals/en/utility/../../../covers/pdf/coverpage-utility.pdf
 137 |   |-- console.lang.tex
 138 |   `-- external-references.tex
 139 |-- covers
 140 |   |-- pdf
 141 |   |   |-- coverpage-console.pdf
 142 |   |   |-- coverpage-developers.pdf
 143 |   |   |-- coverpage-main.pdf
 144 |   |   |-- coverpage-misc.pdf
 145 |   |   |-- coverpage-problems.pdf
 146 |   |   |-- coverpage-utility.pdf
 147 |   `-- svg
 148 |       |-- coverpage-console.svg
 149 |       |-- coverpage-developers.svg
 150 |       |-- coverpage-main.svg
 151 |       |-- coverpage-misc.svg
 152 |       |-- coverpage-problems.svg
 153 |       |-- coverpage-utility.svg
 154 |       |-- Makefile
 155 |       `-- Makefile.in
 156
 157
 158 IMAGES MANAGEMENT
 159 =================
 160 There are a lot of images into the Bacula manuals, into several format:
 161 svg, png, pdf, eps, jpg, ...
 162 To be able to prioritize them, we need to use some LaTeX directives
 163 like the following:
 164 \graphicspath{{../../../images/pdf/}{../../../images/png/} \
 165 {../../../images/}{../../../images/hires/}{../../../images/eps/}}
 166 \DeclareGraphicsExtensions{.pdf,.png,.jpg,.jpeg,.eps}
 167
 168 The images may be included from the directories specified on the
 169 \graphicspath{} directive.
 170 Depending on the output format, we want to prioritize differently. E.g.
 171 the definitions above are PDF output oriented for what we definitely
 172 prefer PDF, then PNG, then JPG, etc.
 173
 174 Since the new version, I choose to preferably designed images with
 175 inkscape / svg format. Why: two main reasons. Vertorized images are much
 176 more nice than bitmap (IMHO) and inkscape is able to automatically
 177 produce PNG or PDF on the fly (e.g. into Makefile process).
 178
 179
 180 TABLES MANAGEMENT
 181 =================
 182 As tables are always a bit difficult to manage, since the new design,
 183 tables are progressively moved into specific files. Why?
 184 - it let us to use the longtable package and then be able to have a
 185   better control on how tables are displayed.
 186 - it let us not to have data tables, which don't change frenquently
 187   and, IMHO, don't give a change to have an overall perspective on
 188   the text being written.
 189
 190 HTML VERSION
 191 ============
 192 The source document is written in LaTeX. The HTML version uses latex2html
 193 converter. Because of the LaTeX possibility to define some "macros", we
 194 use a three step process:
 195 - convert 'high level' LaTeX to 'low level' LaTeX during the make process
 196 - convert 'low level' LaTeX to 'raw' HTML using latex2html
 197 - convert 'raw' HTML to 'recent' HTML using  dedicated script
 198   (docs/tools/htmls.sh)
 199
 200 During the HTML compilation process, some temporary directories are created.
 201 They are named www-{the-manual-name} where {the-manual-name} is the name of the manual. Therefore
 202 you will find:
 203 - www-console
 204 - www-developers
 205 - www-main
 206 - www-misc
 207 - www-problems
 208 - www-utility
 209 in the bacula manuals tree.
 210
 211 Please notice that the process described for IMAGES MANAGEMENT is used also
 212 with different values.