Abstract
Beyond the simple document generation, many advanced features are available to allow the user to easily customize the output formats or to generate a set of manuals in a single command. We will detail all that here.
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 documents in Borges:
Table 3.1. Borges Output Formats
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
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 be 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>"]
Without the SUBDOCS option, this command will generate all sub documents as defined in the conf.xml files (Section 1.1.4, “manuals/My_Book/conf.xml”) of all the documents defined for the whole project (Section 3.2.4, “Insert the New Document”).
If you supply a SUBDOCS list, only the specified super-document/document pairs will be generated. If you wish to get only 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"
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"
Which will result in all manuals in Outputs/, sorted by language and document.
Documents from a single project are often published separately for different purposes or publishing medias. This feature allows to define pools of documents in specific formats and languages, that can be used to generate in a single commands all the output documents associated, or an archive containing the sources for just those deocuments.
We have seen at Section 1.1.5, “conf/repository.xml” that we can define elements like this:
<pool id="Printer">
<document id="Book/Book">
<language lang="en">
<style format="pdf"/>
</language>
<language lang="fr">
<style format="pdf"/>
</language>
</document>
</pool>The <style> element must always specify the format attribute. It must be enclosed in a <language> element (with a mandatory lang attribute) which must be enclosed in a <document> element (with an id attribute). The id attribute identifies the document/subdocument pair concerned. Each of these elements can be repeated as much as needed to reach the exact combination of document, language and format needed.
Once a pool is defined in conf/repository.xml with appropriate id, one can start the generation of the documents defined in it in a single command:
make all POOL=Printer
That will generate and place in Outputs/Printer all the documents defined in the pool with ID Printer.
Likewise, the following command:
make archive POOL=Printer
Will create an archive called Printer-9.2.tar.bz2 (9.2 being replaced by the current project release) containing a striped down version of the project repository allowing only to generate the documents defined in the Printer pool with make all.
A feature also allows you to generate all documents (in all formats and languages defined in the conf.xml file) associated to a specific super-document.
make -C manuals/Install-guide/ all
does the job for the Install-guide super-document for example. The resulting files will be stored in the manuals/Install-guide/Outputs/ directory.
Finally you may want to generate all formats and languages outputs associated to a single document as defined in the conf.xml file. Simply run
make -C manuals/Install-guide/ Install-guide-RPM.all
The resulting files will be stored in the manuals/Install-guide/Outputs/ directory.
When you are working on writing and/or translating a module, you will 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 out the long book compilation times.
The command synopsis for compiling a single module is:
make -C manuals/module module MOD=<module_name> FORMAT=<output_format> [LANG=ll] [exclude=foo]
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, and all single module compilation outputs go 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.
The exclude= parameter is optional and it is used to exclude elements from input XML files. See Section 1.1.4, “manuals/My_Book/conf.xml”.
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.
Abstract
The Open Metadata Framework is an initiative of ibiblio to provide an open cataloging system for documentation. It allows various documentation projects to present their documents through a common catalog interface, making browsing and searching much easier. See the OMF home for more information. The ScrollKeeper project offers a common interface for managing OMF files.
To generate the OMF file for a specific sub-document, simply run, for example:
make -C manuals/Install-guide/ Install-guide-RPM.omf
This will generate in a single file all the OMF metadata necessary to catalog all the actual output files (all languages and all formats) derived from the specified document, according to the content of the conf.xml file.
The actual cataloging metadata is extracted from the master document header. The following table shows the DocBook elements (from inside the info element (bookinfo, articleinfo, etc.) of the master file) used to fill the information in the different OMF elements.
Table 3.2. Correspondence between DocBook and OMF elements
| OMF element | DocBook equivalent |
|---|---|
| creator | first author |
| title | title: subtitle |
| date | pubdate |
| description | abstract |
| type | releaseinfo |
| coverage/@architecture | @arch |
| coverage/@os | @os |
| rights/@type | legalnotice[1]/@conformance |
| rights/@license | legalnotice[1]/@role |
| rights/@holder | copyright/holder |
Consult the http://www.ibiblio.org/osrt/omf/omf_elementsOMF Specification to learn about the meanings of the OMF elements.
The OMF files are automatically generated when all the formats associated with specific documents are generated (make all)