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.
Note
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”). .
Caution
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”.
Tip
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.
Caution
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:
- original
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.
- translation
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:
Missing Images
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.
Tip
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