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 the system. Each author must define it 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> <firstname>Peter</firstname> <lastname>Pingus</lastname> <mail>peter.pingus@mandrakesoft.com</mail> <lang>en</lang> </author>
<initials> holds the author's initials. Most likely two lowercase letters, the initials are used as a unique identifier to distinguish among different authors. Mandatory.
<firstname> holds the author's name and <lastname> holds the author's lastname. Optional.
<mail> holds the author's e-mail address. Optional, but necessary for email alerts
<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. However, for revision control the language cannot be forced with the LANG= parameter and the one defined in <lang> is used. Mandatory.
This file holds the configuration parameters of the style-sheets to use by default when producing PDF and HTML output.
<?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> </configuration>
<dssslprint> holds the DSSSL style-sheet used for TeX transformation of the document to prepare it for printing. Mandatory.
<xslxhtmlchunk> holds the XSL style-sheet used for (X)HTML transformation of the document into different (X)HTML files for online publication. Mandatory.
<xslxhtmlflat> holds the XSL style-sheet used for (X)HTML transformation of the document into a single (X)HTML file for online publication. Mandatory.
This file holds the configuration parameters of the style-sheets to use when producing PDF and HTML output, as well as “aliases” and exclusion information for deriving various documents from a single super-document. By default this file is the copy of the conf/manual-default.xml file above.
<?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 id="Some_Book"> <lang>en</lang> <format>pdf</format> <exclude>VPN</exclude> </manual> <manual id="Another_Book"> <lang>en</lang> <format>pdf</format> <exclude>VPN</exclude> <exclude>booklet</exclude> </manual> </manuals> </configuration>
<stylesheet> contains the same parameters as before. Please, refer to Section 1.1.2 for more information on it.
With the sample manuals/My_Book/conf.xml above, issuing
make -C manuals/My_Book Some_Book.pdf
will compile a PDF file named manuals/My_Book/Some_Book.pdf excluding all elements marked with condition="VPN"; issuing
make -C manuals/My_Book Another_Book.pdf
will compile a PDF file named manuals/My_Book/Another_Book.pdf excluding all elements marked with condition="VPN" and also all elements marked with condition="booklet".
Please refer to Section 1.2.4 for more information on conditional-compilation.
This file is the most important configuration files because it's the top configuration file for the whole Borges project.
<?xml version='1.0' encoding='iso-8859-1'?> <configuration> <repository> <title>My Book Project</title> <paths> <modules>modules</modules> <manuals>manuals</manuals> </paths> <outputs> <makefile>/usr/share/Borges/backend/Makefile.DB</makefile> </outputs> <manuals> <manual>My_Book</manual> </manuals> <languages> <lang>en</lang> <lang>fr</lang> <lang>es</lang> </languages> <revisions> <type> <name>lproof</name> <author>tbn</author> </type> <type> <name>ispell</name> <author>tbn</author> </type> <type> <name>pproof</name> <author>tbn</author> </type> <type> <name>tproof</name> <author>tbn</author> </type> <type> <name>translate</name> <author>tbn</author> </type> <type> <name>write</name> <author>tbn</author> </type> </revisions> </repository> </configuration>
<title> holds the project's name. This is used as the title in the reports generated by Borges report facilities. Mandatory.
<paths> holds the paths where the different documents and their modules are located. The defaults are a safe bet, so it is recommended not to change them. 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. Mandatory.
<manuals> holds the directory name of the different documents, with one <manual> entry per document. There must be at least one entry. Mandatory.
It is highly recommended not to add here any manual by hand. Use the make adddoc command instead. See Section 3.2.3.
<languages> holds the languages supported by all documents, one <lang> entry per language containing the two letter ISO code (in lowercase) for that language. At least one language must be defined. Mandatory.
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.
<revisions> holds the revision types managed by the revision system. The order in which they appear define the work-flow of the document's modules. At the moment of this writing, neither the names of the revision types nor their order can be changed, however the initials of the “default” author responsible for a specific revision can be set. Mandatory.
<name> holds the name of the revision: write, for module's writing; translate for module's 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. Mandatory.
<author> holds the “default” author initials for a revision type. If no author is assigned to a revision type yet, tbn (To Be Named) must be used. Mandatory.
<server> holds the parameters related to remote compilation and/or validation of XML files. This is not yet implemented in Borges.
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. There must be at least one such entry which also has the following:
<revnumber> contains the revision number (or edition number) of the document. Generally, it is an integer value starting at 1 and incrementing for each major revision (or edition) of the document. Optional[2].
<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 under 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 under 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[3].
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_file_name.png file 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 in 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.
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 by 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 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 directly that file to check no more 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 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 among each other.
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 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 just 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 userguides from the Tortoise-UserGuide super-document. This is done in the super document configuration file Section 1.1.3. 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> <exclude>sparc</exclude> </manual> <manual id="Tortoise-Sparc"> <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 to check 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 document into.
At the moment of this writing the validation process is a parsing of the whole XML code of the document, there are no other validation constraints checked yet.
When translating a module into a foreign 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 revisions management system will report differences among 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 all 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.
When this is done, to not forget to add the generated templates to your CVS repository, if any.
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 LANG=ll
that will declare the new ll[4] 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