2. Generating Final Documents

Abstract

Beyond the simple document generation, many advanced features are available to allow the user easily customizing the output formats or generate a set of manuals in a single command. We will detail all that here.

2.1. Single Manual Generation

A final manual (in a user readable format) is simply identified by its name followed by a format extension. Four formats with four extensions are available for DocBook document sin Borges:

Table 3.1. Borges Output Formats

FormatExtensionDescription
PDF.pdf

The famous Adobe PDF format for printable documents with readers available for all platforms.

HTML.htmlStandard HTML format for online publishing, with chunked output: the document is chunked in many different HTML files. In this case My_Book.html designates a directory, not a file, holding all the HTML files composing the document. The entry page is My_Book.html/index.html
Flat HTML.flat.htmlOne single HTML file for the whole document. Can result very big.
PostScript.psfor printable documents.

Knowing that all you need to do is to make the desired output. For example if you want to get the document Install-guide-RPM from the super-document Install-guide in English in PDF format, just run:

make -C manuals/Install-guide/ Install-guide-RPM.pdf LANG=en

2.2. Generating Multiple Documents at Once

When one needs to publish all the manuals available in all language for his project, compiling them one after the other in all formats can result harassing. For this reason Borges provides a target to automatically compile any combination of manual-language-format.

The synopsis of this command is:

make all SUBDOCS="<docs list>" LANGS=""<languages list>" FORMATS=""<formats list>"

where:

docs list

is the list of super-document/document pairs you wish to generate. If you wish to get the manuals Install-guide-RPM and Install-guide-tar from super-document Install-guide, you'll have to use SUBDOCS="Install-guide/Install-guide-RPM Install-guide/Install-guide-tar"

languages list

the list of languages to get the manuals in. use LANGS="en fr es" to get all manuals in English, French and Spanish.

formats list

the list of extensions to compiles the manuals in. If you are interested in PDF and flat HTML output, use FORMATS="pdf flat.html"

With this example we would end up with the following command line:

make all SUBDOCS="Install-guide/Install-guide-RPM Install-guide/Install-guide-tar" \
LANGS="en fr es" FORMATS="pdf flat.html"

Which will result in 2*3*2=12 manuals in Outputs/.

2.3. Generating a Single Module

When you are working on writing and/or translating a module, you often want to have a look at it in one of the supported output formats. Borges' single module compilation feature allows you to do so without the need to compile the whole document containing the module in question, thus leaving you more time to do your work instead of waiting long book compilation times.

The command synopsis for compiling a single module is:

    make -C manuals/module <module_name>.<output_format> [LANG=ll]
   

Note that the directory for single module compilation is always manuals/module regardless of which document the module belongs to. This directory is automatically created when Borges is initialized. All single module compilation output goes into it.

The LANG=ll parameter is optional and it is used to force compilation to occur in a language other than the default one. ll is the two letter lowercase ISO code of the language.

For example, after issuing:

    make -C manuals/module borges-compile-features-sect1.pdf LANG=es
   

you will end up with the PDF file manuals/module/borges-compile-features-sect1.pdf with the contents of the borges-compile-features-sect1 module in Spanish.