Chapter 3. User's Reference manual

1. Documents Writing
1.1. Configuration Files
1.2. Document Creation Features
1.3. Document modification features
1.4. Adding new languages to the system
2. Generating Final Documents
2.1. Single Manual Generation
2.2. Generating Multiple Documents at One Time
2.3. Generating a Single Module
2.4. OMF Support
3. Output Style Customizations
3.1. Customizing Existing Formats
3.2. Creating a New Customization Layer
4. Revision Management
4.1. Module Life Cycle
4.2. Inter-Language Module Synchronization
4.3. Project Major Release
4.4. Generating Reports

1. Documents Writing

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.

1.1. Configuration Files

Following is an in-depth review of Borges' configuration files and their format.

1.1.1. conf/author.xml

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.

1.1.2. conf/manual-default.xml

This file 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> 	 
       <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.

1.1.3. manuals/My_Book/conf.xml

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. File is based on the conf/manual-default.xml file above.

 	 
     <?xml version='1.0' encoding='ISO-8859-1'?> 	 
     <configuration> 	 
      <makefile>/usr/share/Borges/backend/Makefile.DB</makefile> 	 
      <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, “conf/manual-default.xml” for more information on it.

<makefile> is optional and overwrites the overall project setting (Section 1.1.4, “conf/repository.xml”). It points to the Makefile you wish to use to transform the sources into output formats.

<manual> defines the one to many documents associated to that super-document. The id attribute must be unique among all projects, it defines the name of the document that will have to be used to generate it.

lang

Add one <lang> element per language this document is to meant published in;

format

Add here all <format> extensions this document is to meant published in (see Section 2.1, “Single Manual Generation”);

exclude

<exclude> holds the name of the “flags” to exclude in conditional-compilation of the document.

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, “Specialized Books for Different Needs” for more information on conditional-compilation.

1.1.4. conf/repository.xml

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> 	 
   <dtd>http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</dtd> 	 
   <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> 	 
       <original>
        <type role="1time">
          <name>write</name>
          <author>tbn</author>
          <weight>10</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>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>
  • <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.

    • <modules> holds the modules' “top” directory. Mandatory.

    • <manuals> holds the documents' “top” directory. Mandatory.

  • <dtd> holds the DTD URI of the DTD you plan to use in your project.

  • <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.

    Note

    you can also specify the Makefile to be used on a super-document basis (see Section 1.1.3, “manuals/My_Book/conf.xml”).

  • <manuals> holds the directory name of the different documents, with one <manual> entry per document. There must be at least one entry. Mandatory.

    Caution

    It is highly recommended not to add here any manual by hand. Use the make adddoc command instead. See Section 3.2.3, “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.

  • <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.

    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”.

  • <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. 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.

    translation

    This is the workflow to be followed by original 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 to see how those tasks articulates with each others. Each workflow is made of tasks with the following information:

    • <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.

      Note

      Translations of the modules will only have translate, ispell and lproof revision types.

    • <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.

    • <weight> is used to estimate the relative cost of a task with respect to writing task. For example the pedagogic proofreading (pproof) task as 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.

  • <cost> is the estimated cost to per written character for the writing task (see Section 4, “Accounting Reports”). Adjust to your own value.

1.1.5. master.top.xml and the Revision System

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.3, “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.

1.2. Document Creation Features

In the following sections the document creation features of Borges will be detailed. The sections are not presented in any particular order.

1.2.1. Global Entities

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:

  • Company names;

  • Program (software) names;

  • Operating Systems names.

  • Most acronyms[3].

1.2.2. Images

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:

.png

Portable Network Graphic (bitmap);

.jpg

Compressed bitmap usable for photos;

.eps

Encapsulated PostScript (Vector);

.pdf

Encapsulated Portable Document Format (Vector);

.fig

native output format of the xfig diagram application.

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

1.2.3. Index Support

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>
  

1.2.4. Specialized Books for Different Needs

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.3, “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>
   

That done, issuing

     make -C manuals/My_Book Tortoise-i386.pdf
    

will compile the whole book into PDF discarding the elements with condition="sparc".

1.2.5. Document Validation

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

Caution

At the moment, module validation does not check cross references (<xref>) validity.

1.2.6. Making Translated Paragraphs Transparent to the Revision System

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.

1.3. Document modification features

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”.

1.4. Adding new languages to the system

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

will declare the new ll[4] language document for the whole project. It will actually perform the following tasks:

  • Update conf/repository.xml;

  • 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

  1. Translate entities in manuals/My_Doc/ll/*.ent;

  2. Translate entities in entities/ll/*.ent;

  3. Translate modules in modules/ll/*.xml;

  4. Take snapshots and translate diagrams from images/xx/ to images/ll/, xx being another language for which images have already been created.



[3] Acronyms are used “almost” without change between all languages/projects. One that does change, for example, is ISDN which is RDSI in Spanish.

[4] ll being the two letters ISO code for that language. See ISO 639.