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.
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”.
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>firstname.lastname@example.org</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.
<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.
make -C manuals/My_Book My_Book.pdf
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.
<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.
<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”.
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”.
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.
<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.
<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.
<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.
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 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.
<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.
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>
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.
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".
make -C manuals/My_Book master.validate
to validate your whole super-document for your preferred (working) language.
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
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?
<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.
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 language document for the whole project. It will actually perform the following tasks:
Once this is done translators will have to