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.
In the following pages it is assumed that Borges is already configured properly as explained in Section 2 at least up to the point of creating your personal profile.
First, you should clean the files and directories related to the sample document provided with the project template. Issue the following
rm -rf manuals/Sample rm -rf modules/en rm -rf manuals/images rm -rf images/en rm -rf entities/en
to do so. You should also clean the main configuration file (see Section 3.2.1). You should also define in this file the title for your whole project.
Next, you have to perform the following steps (see Section 3.2 below for details):
Prepare the master file. The master file outlining your project's structure needs to be created and edited.
Initialize the repository. This is mandatory for the system to work properly.
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.4 and in Section 1.2.1.
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.
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.
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).
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.
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.
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.
All examples of command lines to issue assume that the current directory is ~/My_Project/ (you can use pwd to check that).
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.
The conf/repository.xml file for your starting project should look like this:
<?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> </manuals> <languages> <lang>en</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>
The file is pretty self-explanatory, 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).
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.
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.
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.
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/template/manuals/Sample/master.top.xml to ~/My_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="⟨"> <title>&book-title;</title> <bookinfo> <title>&book-title;</title> <subtitle>&book-sub-title;</subtitle> <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> <abstract><para></para></abstract> <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> <authorblurb> <para>&e-mail; doc@co.net</para> <para>&web; www.co.net</para> </authorblurb> <pubdate>2002-06-20</pubdate> <copyright> <year>2002</year> <holder>Your_Company</holder> </copyright> </bookinfo> <preface id="legal-notice"> <para role="module">legal-notice-legalnotice </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:
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 direction for 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.
There are many entities notably 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 in (here our sections titles for example).
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_Project master=master.top.xml
that will create the new My_Doc document based on the master file master.top.xml. It will actually perform the following tasks:
Project and documents entities need to be defined. Project entities are those entities common to all documents, for example: computer program names. Documents entities are those entities used only in a particular document. All entities files are XML files which 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.
Global entities are covered more thoroughly in Section 1.2.1.
There are two predefined documents entities files, and they are:
titles.ent where entities for titles are defined. Below you have a sample titles.ent file:
<?xml version='1.0' encoding='ISO-8859-1'?> <!ENTITY book-title "My First Book"> <!ENTITY book-subtitle "First Book Using Borges"> <!ENTITY chapter1-title "First Chapter"> <!ENTITY chapter2-title "Second Chapter">
strings.ent where other entities used in master.top.xml are defined. Below you have a sample strings.ent file:
<?xml version='1.0' encoding='ISO-8859-1'?> <!ENTITY e-mail "E-mail:"> <!ENTITY web "Web:">
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.
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.
By default tasks are assigned to the people declared in the main configuration file (Section 1.1.4). You may need to reassign tasks, notably those assigned to tbn. Consult Section 4.1.3 to learn how to do that. However this step is optional.
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, also 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 contents. We won't tell you how to use DocBook here, there is excellent material about that all other the Internet. Start consulting The DocBook Wiki.
If you use entities in your modules, make sure to create a new entities file to hold the modules' entities (manuals/My_Book/en/acronym-list.ent for a file having entities for acronyms in English, for example). Consult Section 1.2.1 for more information about entities.
Borges also supports images and drawings. At the time of this writing, PNG and JPEG (for raster images), EPS (for vector graphics), DIA drawings (.dia files) and XFig drawings were supported. Consult Section 1.2.2 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.
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 ~/My_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 ~/My_Project/manuals/My_Book/master.flat.html to check the results.
Needless to say, the last two sections of Section 3.2 should be done “in a loop”. There is no need to write all the modules for your book to check how it is looking 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 also needed to compile documents in another language than the one declared in your preferences conf file.