3. Beginning Your Own Project

Abstract

We will first outline the steps needed to configure Borges for a new project and then a step-by-step example will be provided.

3.1. Configuring Borges to Start a New Project

First, you should create a new project skeleton based on the provided template as described in Section 2, “First Steps”:

$ /usr/share/Borges/bin/configure ~/New_Project en	 
$ cd ~/New_Project

Note

You should replace en by the language code you wish to use by default on your system, if it's not English.

Next, you have to perform the following steps (see Section 3.2, “Step by Step Example” below for details):

  1. Prepare the master file. The master file outlining your project's structure needs to be created and edited.

    Tip

    You can think of the master file as the “skeleton” of your future document.

  2. Insert your new document into the project.

  3. Fill your personal profile information. This information is needed for tracking purposes.

  4. Define entities. Entities for titles and names (for example, application names, company names, etc.) need to be defined. The importance of entities is explained in Section 3.2.5, “Define Entities” and in Section 1.2.1, “Global Entities”.

  5. Generate the writers' guidelines. The writers' guidelines is a PDF or HTML file compiled from the master file having your project's structure as its content. Once generated the file must be read with an appropriate tool (Xpdf or Acrobat Reader, for example) to check its validity.

  6. Assign tasks to every author. Ideally you should be able now to assign a reponsible for every single task of the life cycle of every module.

  7. Write the modules and create images. Now, authors can start writing the different modules that make up your project and creating the modules' associated images (if needed).

  8. Check the result. You can check the progress of the work being done on your project (writing, translating, etc.) by compiling the project and reading the resulting PDF from time to time.

In the following section a step by step example is provided to clarify the points detailed above.

3.2. Step by Step Example

Let's say you want to start a new book named “My_Book” consisting of a preface and two chapters: the first with two sections and the last one with three sections. You also want to include two appendices and want your book to be translated into French and Spanish.

So, here is what you have to do, step-by-step.

Note

In all the following examples comments in files are excluded for simplicity reasons. Luckily, all configuration files are self-documented so you can always refer to them for an explanation of a particular configuration option. You can consult Section 1.1, “Configuration Files” for details about configuration files.

Note

All examples of command lines to issue assume that the current directory is ~/New_Project/ (you can use pwd to check that).

3.2.1. Edit the Main Configuration File

Borges is designed to handle multiple manuals and languages; to define your project details, it uses a file named repository.xml stored under the conf/ directory.

Note

It is not mandatory to modify the main configuration file at that point. You can keep default values for now and come back here when you actually need to change parameters.

The conf/repository.xml file for your starting project should look like this:

<?xml version="1.0" encoding="ISO-8859-1"?> 	 
 <configuration> 	 
   <repository> 	 
     <title>Documentation 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>$DISTDIR/backend/Makefile.DB</makefile> 	 
     </outputs> 	 
     <manuals> 	 
     </manuals> 	 
     <languages> 	 
       <lang>en</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> 	 
   <server> 	 
 </configuration>

The file is pretty self-explanatory (comments have been removed here for clarity sake), however there are some things to note. The <manuals> section contains all the documents (one <manual> entry per document) handled by Borges. The <languages> section contains all supported languages for all projects (one <lang> entry containing the two letter ISO code of the language per each language).

Note

There is no document defined yet, and no language but the default one you wish to use for your project. Other documents and languages will be added later through the command line.

Warning

The <manuals> and <languages> list is handled by Borges and you should not modify it by hand. One exception being the initial language setup (<lang>en</lang> by default) you can change to the one you wish.

The <revisions> section defines the document's workflow[1] which represents the “life cycle” of the document or the “stages” through which a document must pass. See Section 1.1.4, “conf/repository.xml” for more information.

Tip

tbn (To Be Named) must be used as the value for <author> to tell Borges that the person responsible for that revision is not defined yet. You can put here the initials of the person that will be responsible for a specific step by default. Then for all new modules in all languages, this person will be marked as responsible for this specific step.

the weight and cost elements are used for accounting purposes, see Section 4, “Accounting Reports”.

3.2.2. Define the Document Structure

We spoke about “document structure” a lot, right? Well, time has come to define it. We need to create a file named master.top.xml. You can copy /usr/share/Borges/Sample/master.top.xml to ~/New_Project/master.top.xml and edit it to fit your needs.

The master.top.xml file for your project should look like this:

 	 
      <?xml version='1.0' encoding='iso-8859-1'?> 	 
      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 	 
      "/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd"[ 	 
      <!ENTITY % entities SYSTEM "entities"> 	 
      %entities; 	 
      ]> 	 
  	 
      <book id="My_Book" lang="&lang;"> 	 
       <title>&book-title;</title> 	 
       <bookinfo> 	 
        <title>&book-title;</title> 	 
        <subtitle>&book-sub-title;</subtitle> 	 
        <revhistory> 	 
          <revision>
            <revnumber>0</revnumber>
            <date>2003</date>
      	    <authorinitials>pp</authorinitials>
            <revremark>First sample draft to be used with Borges</revremark>
          </revision>
        </revhistory>
       <authorgroup>
        <editor id="pp">
         <firstname>Peter</firstname>
         <surname>Pingus</surname>
         <affiliation>
          <address><email>pp@co.net</email></address>
         </affiliation>
        </editor>
        <author id="pt">
         <firstname>Pierre</firstname>
         <surname>Tremblay</surname>
         <affiliation>
          <address><email>pt@co.net</email></address>
         </affiliation>
        </author>
        <author id="rp">
         <firstname>Reina</firstname>
         <surname>Pingüino</surname>
         <affiliation>
          <address><email>rp@co.net</email></address>
         </affiliation>
        </author>
       </authorgroup>
       <pubdate>2002-06-20</pubdate>
       <copyright>
        <year>2002</year> <holder>Your_Company</holder>
       </copyright>
      </bookinfo>
      <preface id="legal-notice">
       <para role="module">legal-notice</para>  <para>Put
       here the content of the former legal notice section. If not all
       can fit here in the physical page, ask the team. </para>
      </preface>
      <chapter>
       <title>&chapter-1-title;</title>
       <sect1 id="sect-1-1">
        <title>First Section Title</title>
        <para role="module">chap1-sect1-section</para>
        <para>Write the chapter 1, section 1 contents</para>
       </sect1>
       <sect1 id="sect-1-2">
        <title>Second Section Title</title>
        <para role="module">chap1-sect2-section</para>
       </sect1>
      </chapter>
      <chapter>
       <title>&chapter-2-title;</title>
       <sect1 id="sect-2-1">
        <title>Second Chapter First Section Title</title>
        <para role="module">chap2-sect1-section</para>
       </sect1>
       <sect1 id="sect-2-2">
        <title>Second Chapter Second Section Title</title>
        <para role="module">chap2-sect2-section</para>
       </sect1>
       <sect1 id="sect-2-3">
        <title>Second Chapter Third Section Title</title>
        <para role="module">chap2-sect3-section</para>
       </sect1>
      </chapter>
      <appendix id="appendix-1">
       <title>First Appendix Title</title>
       <para role="module">app1-appendix</para>
      </appendix>
      <appendix id="appendix-2">
       <title>Second Appendix Title</title>
       <para role="module">app2-appendix</para>
      </appendix>
     </book>

Thinking in a more or less “modular” way we can say that, generally speaking, a book has: a title, some information about the book itself (sub-title, authors, editor, revisions, publication date, etc.), a preface, chapters and appendices. So, that is exactly what is represented in the sample master.top.xml above, no more, no less.

However, there are some “special” things you might have noticed:

  1. The empty revhistory element. This revision history will contain the revision numbers of the documents (see Section 4.3, “Project Major Release” and Section 1.1.5, “master.top.xml and the Revision System”).

  2. The role="module" attribute. Whenever Borges finds a para element having this attribute, it will go up to the element's “father” (usually, a sectX, chapter, appendix element), and will replace that whole “father” with the entity named after the content of that para.

    For example, the whole sect1 element

    	<sect1>
    	 <title>Some Title</title>
    	 <para role="module">some_sect-sect1</para>
    	 <para>Introduce here the Tartempion application, tell why it rocks.</para>
    	</sect1>
           

    will be replaced by the entity &some_sect-sect1;, which in turn refers to the module some_sect-sect1.xml stored under the modules/ll/ directory, where ll is the ISO two letter code for the language you want to compile the book in.

    This way of deriving the resulting document directly from the specifications document ensures that there is no discrepancy between specs and final result. Furthermore, the system publishes those directions for the writers in the the spec file and in the module templates. They will have disappeared in the final document. Do not hesitate to make those guidelines as lengthy as necessary.

  3. There are many entities, especially for titles. As this master file will serve as a skeleton for our final document, all texts in it must be enclosed in entities so that the master is language-independent. There is a notable exception however: you remember that module elements will be entirely replaced by the modules themselves. So texts in these elements can stay here (our sections titles for example).

Note

You might need to change the XML SYSTEM declaration of the DocBook DTD ("/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd") to suit your system.

3.2.3. Insert the New Document

Now that the structure of the document is defined, the system can create the directories and files to support this new document. This is all done in one single command:

make adddoc doc=My_Book master=master.top.xml REL=2.1

this will create the new My_Book document based on the master file master.top.xml with initial master release 2.1[2] (see Section 4.3, “Project Major Release”). It will actually perform the following tasks:

  • Update conf/repository.xml;

  • create manuals/My_Book/ directory and populate it with all needed file and language directories;

  • Make all module templates for this new document in all defined languages;

  • Add all new files to the CVS repository, if available. Note that you'll still need to commit those files by hand.

3.2.4. Create Your Personal Profile

Each “author” (writer, translator, proofreader, etc.) needs to define his personal profile. Borges uses the information in the profile for version management and author credits among other things. The profile is stored in conf/author.xml and is filled with default values initially. So just edit author.xml with your favorite text editor to suit your personal data. Below is a sample profile:

 
       <?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>
      

Tip

Take a look at the comments in author.xml for hints about the meanings of the parameters (In the above sample, the comments are excluded for simplicity reasons).

3.2.5. Define Entities

Project and document entities need to be defined. Project entities are those entities common to all documents, for example: computer program names. Document entities are those entities used only in a particular document. All entities files are XML files. Entities file names must end in .ent.

Project entities files go into the entities/ directory.

Master entities files go into the manuals/My_Book/ll/ directory where ll is the two letter ISO code for the language. All entities defined in master.top.xml will have to be defined here.

Note

Global entities are covered more thoroughly in Section 1.2.1, “Global Entities”.

When you add a new super-document to the repository, undefined entities found in it are automatically created in ll/strings.ent. You then just need to open that file and write your own content in it. By default Borges sets entities content to FILL ME: entity-name.

Below you have a sample strings.ent file:

<?xml version='1.0' encoding='ISO-8859-1'?>
<!ENTITY e-mail "E-mail:">
<!ENTITY web "Web:">

3.2.6. Generate the Writers' Guidelines

Now that all entities are defined, you can generate the writers' guidelines. Issue

     make -C manuals/My_Book master.top.pdf LANG=en
    

to do so, and check the resulting PDF with your favorite PDF viewer.

Tip

You can also issue

make -C manuals/My_Book master.top.flat.html LANG=en

to build the writers' guidelines in HTML.

If all went fine, you should see the book with the table of contents, all chapters and sections with the guidelines you wrote in it.

3.2.7. Assign Tasks to Contributors

By default tasks are assigned to the people declared in the main configuration file (Section 1.1.4, “conf/repository.xml”). You may need to reassign tasks, notably those assigned to tbn. Consult Section 4.1.3, “Assigning tasks” to learn how to do that. However this step is optional.

3.2.8. Write the Modules and Create Images

All that is left is to fill your book with content: write the modules and create the images and/or drawings your book will have. If needed, new entities file(s) have to be created and filled properly.

So, open the modules' XML files (modules/en/chap2-sect1-section.xml for the first section of the second chapter of the English book, for example) with your favorite text editor and start filling it with content. We won't tell you how to use DocBook here, there is excellent material about that all over the Internet. Start consulting The DocBook Wiki.

If you use entities in your modules, make sure you create a new entities file to hold the modules' entities (entities/en/acronym-list.ent for a file having entities for acronyms in English, for example). Consult Section 1.2.1, “Global Entities” for more information about entities.

Borges also supports images and drawings. At the time of writing, PNG and JPEG (for raster images), EPS (for vector graphics), and XFig drawings were supported. Consult Section 1.2.2, “Images” for more information about images.

Images and drawings common to all languages should be put in the images/ directory and images and drawings particular to each language must be put in the images/ll/ directory, where ll is the two letter ISO code for the language.

3.2.9. Check the Result

Finally, you have to check the results. Issue

     make -C manuals/My_Book master.pdf LANG=en
    

to compile the document into PDF and open it with your favorite PDF reader.

You can also compile the document into HTML both as a single (flat) HTML file or as several (chunked) HTML files. Issuing

     make -C manuals/My_Book master.html LANG=en
    

will compile the document into chunked HTML files. Point your web browser to ~/New_Project/manuals/My_Book/html/index.html to check the results. Issuing

     make -C manuals/My_Book master.flat.html LANG=en
    

will compile into a single HTML file. Point your web browser to ~/New_Project/manuals/My_Book/master.flat.html to check the results.

3.3. Final Notes

A few things to note:

  • Needless to say, the last two sections of Section 3.2, “Step by Step Example” should be done “in a loop”. There is no need to write all the modules for your book to check how it looks so far.

  • The LANG=en parameter passed to the make commands in the above sections is only needed if your preferred language is other than English. This is needed to compile documents in another language than the one declared in your author.xml profile conf file.



[1] At the moment of this writing the workflow is fixed and cannot be changed.

[2] If the REL option is not provided, it is assumed to be 1.0by default.