Abstract
Following is a review of the
configuration files' format and the required elements on
master.top.xml
for the revision system to
work. All the necessary elements to create your documents for your
projects, from global entities to documents compilation, are
detailed in this section also.
Following is an in-depth review of Borges' configuration files and their format.
This file holds information related to the author (writer, translator, etc.) who will use that copy of the repository. A Borges project is meant to be stored in a CVS repository, and used by many people. Each author must customize this file in its own copy of the repository in order to use the revision system and to be able to compile documents.
<?xml version='1.0' encoding='ISO-8859-1'?> <author> <initials>pp</initials> <lang>en</lang> </author>
<initials>
holds the author's identifier. This has been defined in
conf/authors.xml
. If not, it must be
done: see Section 1.1.2, “conf/authors.xml”.
<lang>
holds the author's preferred language. Note that we use
the word “preferred” because the language can
be overridden with the LANG=
parameter
when doing compilations.
Each “contributor” (writer, translator,
proofreader, etc.) must be known from the
system. Borges uses this information version management
and author credits among other things. Contributors are listed
in conf/authors.xml
and is filled with
default values initially. So just edit
authors.xml
with your favorite text
editor to enter your staff. Below is a sample profile:
<?xml version="1.0" encoding="UTF-8"?> <authorgroup> <editor id="cb"> <firstname>Camille</firstname><surname>Bégnis</surname> <affiliation> <address><email>camille@some_company.com</email></address> </affiliation> </editor> <author id="pp"> <firstname>Peter</firstname><surname>Pingus</surname> <affiliation> <address><email>peter@pingus.com</email></address> </affiliation> </author> </authorgroup>
That file should strictly follow the default structure and:
The <editor>
contributor type
is used to store the project manager profile. There must be
one and only one. This person will notably receive tasks not
assigned to anybody else so that he can assign pending
tasks.
The <author>
contributor type
is used for all other people working on the project. There
can be as many as needed.
Each contributor must have a unique and meaningfull
id
used to identify him in the
system. It should be composed of letters only.
The email address will be used to send tasks the contributor is currently meant to perform (see Section 3, “Sending Mails to Authors”).
This file will be used as a template to generate document specific configuration files (Section 1.1.4, “manuals/My_Book/conf.xml”). It holds the configuration parameters of the style-sheets to use by default when producing PDF and HTML output. Please refer to Section 3, “Output Style Customizations” for details on how to customize the default style-sheets to fit your particular needs.
<?xml version='1.0' encoding='ISO-8859-1'?> <configuration omf.seriesid=""> <makefile>$DISTDIR/backend/Makefile.DB</makefile> <style format="pdf" toolchain="jade">../../drivers/docbook-jadetex.dsssl</style> <style format="flat.html" toolchain="xsl">../../drivers/docbook-xhtml.xsl</style> <style format="html" toolchain="xsl">../../drivers/docbook-xhtml-chunk.xsl</style> <document id=""> <style format="pdf"/> <style format="html"/> <language lang="en"> <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style> </language> <language lang="fr"/> <language lang="es"/> <exclude>multilingual</exclude> </document> </configuration>
<makefile>
designates the
Makefile
holding the rules specific to a
particular document type. The default one is for DocBook
documents. $DISTDIR
references to the
location where Borges is installed
(/usr/share/Borges/
by default. That
allows you to redefine a complete new set of targets and use
them easily on a per document basis.
<style>
:
in this example, the first three
<style>
elements hold the style-sheet
used for the three output formats provided by default with
Borges. Under the <document>
element, <style>
tells which formats
should be generated when making all the documents. Finally, it
is possible to define a specific stylesheet for a specific
language and a specific document in the way done with the last
<style>
element of the above
example.
<document>
holds the configuration for the first sub document. The
id
attribute must be left empty and
will be automatically filled at document insertion
time.
<language>
tells in which languages that sub document is meant to be
translated. That information will be used for tasks
dispatching and documents generation.
<exclude>
see Section 1.1.4, “manuals/My_Book/conf.xml” for
explanation. The multilingual
flag is
excluded by default. It can be used in modules to mark
data to be included only in multilingual documents (see
Section 1.2.5, “Miltilingual Documents”).
Remember that this file just holds the default configuration for the documents that will be inserted in the project. You will most probably need to adjust that configuration after document insertion (Section 1.1.4, “manuals/My_Book/conf.xml”).
This
file holds the configuration of a specific documnent, and
notably style-sheets to use when producing PDF or HTML
output, as well as “aliases” and exclusion
information for deriving various documents from a single
super-document. File is based on the
conf/manual-default.xml
file
(Section 1.1.3, “conf/manual-default.xml”).
<?xml version='1.0' encoding='ISO-8859-1'?> <configuration omf.seriesid="7a5f2ef8-3239-11d8-8574-a94a75e630dd"> <makefile>$DISTDIR/backend/Makefile.DB</makefile> <style format="pdf" toolchain="jade">../../drivers/docbook-jadetex.dsssl</style> <style format="flat.html" toolchain="xsl">../../drivers/docbook-xhtml.xsl</style> <style format="html" toolchain="xsl">../../drivers/docbook-xhtml-chunk.xsl</style> <document id="My_Book"> <style format="pdf"/> <style format="html"/> <language lang="en"> <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style> </language> <language lang="fr"/> <language lang="es"/> <exclude>Mac</exclude> <exclude>multilingual</exclude> </document> <document id="My_Book_Mac"> <style format="pdf"/> <style format="html"/> <language lang="en"> <style format="pdf" toolchain="jade">../../drivers/db-jadetex-letter-en.dsssl</style> </language> <language lang="fr"/> <language lang="es"/> <exclude>PC</exclude> <exclude>multilingual</exclude> </document> <document id="ML-Doc" multilang="//part"> <style format="pdf"/> <language lang="en"/> <language lang="fr"/> <language lang="es"/> <exclude>unilingual</exclude> </document> </configuration>
We have already seen (Section 1.1.3, “conf/manual-default.xml”) the meaning
of the elements of that file. We will now detail the use the
the <exclude>
element and see how
this document has been configured.
<exclude>
holds the name of the “flags” to exclude in
conditional-compilation of the document. See Section 1.2.4, “Specialized Books for
Different Needs” for
detailed explanation.
With the sample
manuals/My_Book/conf.xml
above, issuing
make -C manuals/My_Book My_Book.pdf
will compile a PDF file named
manuals/My_Book/My_Book.pdf
excluding
from all modules all elements marked with
condition="Mac"
; issuing
make -C manuals/My_Book My_Book_Mac.pdf
will compile a PDF file named
manuals/My_Book/My_Book_Mac.pdf
excluding
all elements marked with
condition="PC"
.
Finally, there is a third document available in PDF
only, and the multilang
attribute tells us
it's in fact a document containing various parts in various
languages in the same book. In this case, the document
ML-Doc.pdf
will have its body
(<part> here) repeated in English, French and Spanish.
Please refer to Section 1.2.5, “Miltilingual Documents” for
more information.
This file is the most important configuration file because it's the top configuration file for the whole Borges project. We will detail here a sample configuration file and see what one can modify by hand.
<?xml version='1.0' encoding='iso-8859-1'?> <configuration> <repository> <title>Documentation Project</title> <borges>0.11.2</borges> <paths> <modules>modules</modules> <manuals>manuals</manuals> </paths> <doctype>-//OASIS//DTD DocBook XML V4.2//EN</doctype> <dtd>http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</dtd> <outputs> <makefile>$DISTDIR/backend/Makefile.DB</makefile> </outputs> <manuals> <manual>Book</manual> <manual status="inactive">Took</manual> </manuals> <pool id="Printer"> <document id="Book/Book"> <language lang="en"> <style format="pdf"/> </language> <language lang="fr"> <style format="pdf"/> </language> </document> </pool> <languages> <lang>en</lang> <lang>fr</lang> <lang>es</lang> </languages> <revisions> <original> <type role="1time"> <name>write</name><author>tbn</author><weight>10</weight> </type> <type role="2time"> <name>update</name><author>tbn</author><weight role="proportional">8</weight> </type> <type> <name>tproof</name><author>tbn</author><weight>4</weight> </type> <type role="2translate"> <name>pproof</name><author>tbn</author><weight>2</weight> </type> <type> <name>ispell</name><author>tbn</author><weight>1</weight> </type> <type> <name>lproof</name><author>tbn</author><weight>4</weight> </type> </original> <translation> <type role="1time"> <name>translate</name><author>tbn</author><weight>8</weight> </type> <type> <name>synch</name><author>tbn</author><weight role="proportional">6</weight> </type> <type> <name>ispell</name><author>tbn</author><weight>1</weight> </type> <type> <name>lproof</name><author>tbn</author><weight>4</weight> </type> </translation> <cost>0.01</cost> </revisions> </repository> </configuration>
We will review now, section by section, what you can change and what far.
<title>
holds the qproject's name. This is used as the title in
the reports generated by Borges report
facilities. Mandatory.
<doctype>
holds the symbolic
DOCTYPE
of the DTD used for all the
documents and modules in this project. There can be only
one DTD per project. Make sure you use the same DTD in
your documents master files. If you change that you'll
need to update accordingly all of your master
files. Mandatory.
<dtd>
holds the URI of the DTD specified by
the <doctype>
parameter
above. Mandatory.
<outputs>
holds the location of the template output
Makefile
files. Template output make
files are used for the different DTDs Borges
supports. At the moment of this writing, only the DocBook
DTD was supported (hence, the .DB
file name extension). You can put as many
<makefile>
entries as you like
provided the rules in it do not conflict.
Mandatory.
you can also
specify the Makefile
to be used on a
super-document basis (see Section 1.1.4, “manuals/My_Book/conf.xml”).
<manuals>
holds the directory name of the different documents, with
one <manual>
entry per
document. This is automatically managed by the
adddoc
target (Section 3.2.4, “Insert the New
Document”). .
It is highly recommended not to add here any manual by hand. Use the make adddoc command instead. See Section 3.2.4, “Insert the New Document”.
Even if
GNU/Linux supports the space character in path names,
it is recommended not to use them
here. You can use the hyphen (-
) or
the underscore (_
) as word separators
for path names.
In our example, the document Took
is marked with attribute
status="inactive"
. That means this
manual won't ba taken into account when generating reports
or outputs.
<pool>
: this element that can
be repeated as much as needed is used to define document
subsets for a specific publication media. See Section 2.2.2, “For a Documents Subset”.
<languages>
holds the languages supported by all documents, one
<lang>
entry per language
containing the two letter ISO code (in lowercase) for
that language.
It is highly recommended not to add here any language by hand but the first one. Use the make addlang command instead. See Section 1.4, “Adding new languages to the system”.
There are two things you can do here:
Change the order of the languages: the first one is the default one, and will be used in some rare places when the system needs a default language. The order then determines the order of the languages in reports.
As seen above for documents, a
status="inactive"
attribute can be
added to a <lang>
element to
temporarily deactivate it..
<revisions>
holds the revision types managed by the revision
system. The order in which they appear defines the
work-flow of the document's modules. The workflow
presented here is the default one provided by
Borges. It is possible to change steps name and
number, removing or adding new steps. We will analyse
first how the default workflow (Figure 3.1, “Borges' Default Module Life Cycle”) is coded and then
see how it is possible to customize it. The workflow is
devided in two sections:
This is
the workflow followed by original modules. There
are two special states in that workflow. The one
marked with role="1time"
is
only required one time (typically the first
writing) and won't be required for module
updates. Passing the state marked as
role="2translate"
will trigger
the translation for all other languages, so that
translators can begin their work. Finally, the
task marked with role="2time"
will be available for future releases only after
the module is written.
This is
the workflow to be followed by translated
modules. The state marked with
role="1time"
is only required
one time (typically the initial translation) and
won't be required again for module updates.
See Figure 3.1, “Borges' Default Module Life Cycle” to see how those tasks articulate with each others. Each workflow is made of tasks with the following information:
<name>
holds the name of the revision for the system. This
is the meaning we give them for the default
workflow: write
, for module's
initial writing; translate
for
module's initial translation;
tproof
for module's technical
proofreading; pproof
for module's
pedagogical proofreading, ispell
for module's spell-checking and
lproof
for module's idiomatic
proofreading. After that comes
update
for original modules
updates in future releases, and
synch
for synchronization of the
translations with the original.
<author>
holds the “default” author initials or
identifier for a revision type. If no author is
assigned to a revision type yet,
tbn
(To Be Named)
must be used.
<weight>
is used to estimate the relative cost of a task
with respect to writing task. For example the
pedagogic proofreading (pproof
)
task has a relative weight of 2 with respect to
write
(10), meaning that we
estimate it costs 5 times less to do pedagogic
proofreading than writing a text (see Section 4, “Accounting Reports”). Of course you can
use whatever values you wish here.
You
may have noted that some weights are added the
attribute role="proportional"
.
That means that the cost of this task will be
weighted by the actual changes done on this
module. See Section 4, “Accounting Reports” to
get details on the way this is calculated.
The <revisions>
element is
repeated for each language defined in the system. This is to
allow defining specific authors for every language. See
Section 1.4, “Adding new languages to
the system” to learn how to define
those authors at language addition time.
<cost>
is the estimated cost per written character for the
writing task (see Section 4, “Accounting Reports”). All other costs will be
derived from this one according to respectives weights.
Adjust to your own value.
The
<revhistory>
part of the
master.top.xml
file plays an important role
in the revision system of Borges.
Below you have a sample
<revhistory>
part:
<revhistory> <revision lang="en"> <revnumber>1</revnumber> <date>2002-06-04</date> <authorinitials>pp</authorinitials> <revremark>First Draft</revremark> </revision> <revision lang="fr"> <revnumber>1</revnumber> <date>2002-06-14</date> <authorinitials>pt</authorinitials> <revremark>Begin French Translation</revremark> </revision> <revision lang="es"> <revnumber>1</revnumber> <date>2002-06-10</date> <authorinitials>rp</authorinitials> <revremark>Begin Spanish Translation</revremark> </revision> </revhistory>
Each
<revision>
entry contains data related to
one of the translations of the document. It has a
lang
attribute with the two letter ISO code
(in lowercase) of the language. The first entry has been
automatically created at document creation time (see Section 3.2.4, “Insert the New
Document”) following ones
are added by translators to record the date at which they began
translating a document:
<revnumber>
contains the
revision number (or edition number) of the document. It is the
one corresponding to the current document release (see Section 4.3, “Project Major Release”). Mandatory.
<date>
contains the date at which work on the corresponding language
started. This is used by the report facility of Borges
to estimate finishing dates for the revisions; in the sample
above, work has begun on the French revision on June, the
10th, 2002. The format is
YYYY-MM-DD
. Mandatory.
<authorinitials>
contains the initials (unique identifier) of the author
responsible for that revision. Optional.
<revremark>
contains remarks on the revision itself. This remark is
not rendered with the default DSSSL
style-sheet provided by Borges for printed documents, so
you'll need to customize the style-sheet if you want the
remarks to be printed. Optional.
In the following sections the document creation features of Borges will be detailed. The sections are not presented in any particular order.
Global entities are those
entities that you intend to use without any change at
all among all versions of a project and/or among all
your projects. They reside in the
entities/
directory and are XML files with
file names ending in .ent
Put all entities which
neither change from one language to another
nor from one document to another under
entities/
.
Put all entities which
do change from one language to another,
but do not change from one document to
another in entities/ll/
, where
ll
is the ISO two letter code (in lowercase)
for the language in question.
Good candidates for global entities are:
Most acronyms[1].
Including images in your
work is as easy as inserting a <figure>
element in your modules. For example:
<figure> <title>An Amazing Figure</title> <mediaobject> <imageobject> <imagedata align="center" fileref="images/image_file_name.png" format="PNG"/> </imageobject> </mediaobject> </figure>
will insert a PNG image contained in the file named
image_file_name.png
, aligned in the center of
the page with “An Amazing Figure” (without the
quotes) as its title.
Needless to say,
Borges will take care of finding the image for you in the
corresponding images/ll/
directory, where
ll
is the two letter ISO code (in lowercase)
of the language the module will be compiled into.
You can also put
language-neutral images under the images/
directory and Borges will get them from there.
Images
formats available for your documents are PNG
(format="PNG"
), PDF
(format="PDF"
) and EPS
(format="EPS"
). Borges will
automatically make them available at the right place for you. If
the required format is not available Borges will take care
of converting the image to the needed format
automatically. Supported formats as input image files are:
In case that you insert
an image in a module and you forget to make the image itself,
the system will replace it by a default image, so that the
compilation is not broken. The image used by default is
images/missing.jpg
and you can replace it
with whatever you want.
![]() |
Additionally, whenever
Borges finds a missing image, it will report it in the
<manual>.missing.xx.img
text file. So
if you have just compiled a document (say
UserGuide
) in French and you note some images
are missing (showing the default missing image) you can get the
list of missing images by printing
manuals/UserGuide/UserGuide.missing.fr.img
. You
can also generate that file directly to check that no other images are
missing by simply running make -C manuals/UserGuide/
UserGuide.missing.fr.img
DocBook
is able to
generate an automatic index by collecting all index terms found
in the source document. Borges will automatically
generate such an index provided you request it in the master
document. If you want an index to be added at the end of your
book, simply end your master.top.xml
in:
<index id="index"> <title>Index </title> <para>Automatic Index Here.</para> </index> </book>
Often you need to make small variations on your book to fit different audiences, for example a technical manual for a family of products with only small differences between them.
So, instead of writing different books for the different audiences, it would be desirable to have the possibility to write one set of modules for all audiences and have different parts excluded from the different documentation books for each audience.
Borges makes this possible thanks to “conditional compilation”. Conditional compilation allows you to “mark” some parts of your modules or entire modules in order to exclude them in certain compilations, but not in others.
Let's take an
example. You are writing a user manual for the
Tortoise
operating system running on both
Intel
and Sparc
architectures. There are only minor differences between both
guides.
You only need to add the
condition="i386"
attribute to mark an element
(section, paragraph, phrase, note, warning, tip, etc.) as being
only valid for the Intel
version. Likewise mark
elements specific to the Sparc
version with
condition="sparc"
. If the element appears to be
an entire module, add the attribute in the
master
file:
<sect1 condition="i386"> <title>Some Title</title> <para role="module">some_sect-sect1</para> <para>Introduce here the Tortoise OS, highlighting Intel specifications.</para> </sect1>
You then need to tell Borges how to derive both user guides
from the Tortoise-UserGuide
super-document. This is done in the super document configuration
file Section 1.1.4, “manuals/My_Book/conf.xml”. For our
example, this file could be:
<?xml version='1.0' encoding='ISO-8859-1'?> <configuration> <stylesheet> <dssslprint>../drivers/docbook-jadetex.dsssl</dssslprint> <xslxhtmlchunk>../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk> <xslxhtmlflat>../drivers/docbook-xhtml.xsl</xslxhtmlflat> </stylesheet> <manuals> <manual> <lang>en</lang> <format>html</format> <exclude>sparc</exclude> </manual> <manual id="Tortoise-Sparc"> <lang>en</lang> <format>html</format> <exclude>i386</exclude> </manual> </manuals> </configuration>
make -C manuals/My_Book Tortoise-i386.pdf
will compile the whole book into PDF discarding the elements
with condition="sparc"
.
From time to time, it is recommended you check that your modules are valid XML. Issue
make -C manuals/My_Book master.validate
to validate your whole super-document for your preferred (working) language.
Use the
LANG=ll
parameter to validate in a language
other than your preferred language. ll
is the
ISO two letter code (in lowercase) for the language you want to
validate the super-document into.
Validation
of plain master
document does not mean that
all your sub-documents will be actually valid. To ensure that the
Tortoise-i386
document is actually valid
(taking into account exclusions and indexes), issue:
make -C manuals/My_Book Tortoise-i386.flat.validate
Finally, if you wish to validate against one single module, run:
make -C modules/en tortoise-install-sect1.validate
When translating a module into a another language it often happens that the translator wants to add a footnote with translator notes or a few clarification words in a separate paragraph. Also, some licenses (for example the GPL and the GFDL) require that you include some portion of it in the original language.
Borges' automated revision management system will report differences between the translated module and the original module only because of those added footnotes/paragraphs, even if they are correct or necessary in some cases; so, how can you make those paragraphs “invisible” to the revision system?
Borges solves this
“problem” in an elegant way which does not break
DocBook compatibility by using the
revision="-1"
attribute. For example:
<para revision="-1">En otro idioma</para>
will exclude that paragraph (in Spanish, in the example) when comparing against the original looking for differences in revisions.
This way, you can have those “extra” paragraphs in your translation without worrying about the revisions report being wrong every the time just because of them.
Whenever you modify the structure of a super-document it is necessary to inform the system of such modifications. That will particularly build the module templates for the added modules.
Simply run the make alltemplates command.
If your project is CVS enabled, the new module templates will automatically be added to the CVS repository. See Section 2.1, “Commands with Modified Behavior”.
When one of your documents needs to be translated, or simply when you decide that one of the documents will need to be translated, it is time to make the system aware of this new language. This is done in one single command:
make addlang NEWLANG=ll
will declare the new ll
[2] language document for the
whole project. It will actually perform the following
tasks:
create all language specific directories for modules, images, entities, etc.;
copy entities files from the default one (first in the list of languages in the main configuration file) to the new language directories;
Make all module templates for this new language for all defined documents;
Add all new files to the CVS repository, if available. Note that you'll still need to commit those files by hand;
Once this is done translators will have to