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)