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.
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 2.1
$ cd ~/New_ProjectYou should replace en by the language code you wish to use by default on your system, if it's not English. Likewise 2.1 is the first release number of the documentation you are about to start working on. 1.0 will be used if nothing is provided.
Next, you have to perform the following steps (see Section 3.2, “Step by Step Example” below for details):
Declare the languages expected to be used in this project besides the default one.
Prepare the master file. The master file outlining your project's structure needs to be created and edited.
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.6, “Define Entities” and in Section 1.2.1, “Global Entities”.
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 should be read with an appropriate tool (Xpdf or Acrobat Reader, for example) to check its validity.
Assign tasks to every contributor. 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 one appendix 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. You can consult Section 1.1, “Configuration Files” for details about configuration files.
All examples of command lines to issue assume that the current directory is ~/New_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.
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="UTF-8"?>
<configuration>
<repository>
<title>Documentation Project</title>
<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>
</manuals>
<languages>
<lang>en</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>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).
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 <manuals> and <languages> list is handled by Borges and you must not modify it by hand. Same goes for the <borges> element which is used to record the Borges version used by the repository.
The <revisions> section defines the document's workflow, which represents the “life cycle” of modules or the “stages” through which each modules part of a document must pass. See Section 1.1.5, “conf/repository.xml” for more information.
This is done in one single command. As we want to add both French and Spanish besides English, we will have to run:
make addlang NEWLANG=fr make addlang NEWLANG=es
The addlang target will actually perform the following tasks:
Update conf/repository.xml;
Create all directories meant to hold language specific files (in modules/ entities/ and images/) and populate them with all default files;
Make all module templates for this new languge for all defined documents;
Add all new files to the CVS repository, if available.
The addlang target has more options, consult Section 1.4, “Adding new languages to the system” for more information.
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.2/docbookx.dtd"[
<!ENTITY % entities SYSTEM "entities">
%entities;
]>
<book id="My_Book" lang="⟨">
<title>&book-title;</title>
<preface role="module" id="legal-notice">
<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 role="module" id="chap1-sect1-section">
<title>First Section Title</title>
<para>Write the chapter 1, section 1 contents</para>
</sect1>
<sect1 role="module" id="chap1-sect2-section">
<title>Second Section Title</title>
<para>Write in here the chapter 1, section 2 contents</para>
</sect1>
</chapter>
<chapter>
<title>&chapter-2-title;</title>
<sect1 role="module" id="chap2-sect1-section">
<title>Second Chapter First Section Title</title>
<para>Write in here the chapter 2, section 1 contents</para>
</sect1>
<sect1 role="module" id=""chap2-sect2-section>
<title>Second Chapter Second Section Title</title>
<para>Write in here the chapter 2, section 2 contents</para>
</sect1>
<sect1 role="module" id="chap2-sect3-section">
<title>Second Chapter Third Section Title</title>
<para>Write in here the chapter 2, section 3 contents</para>
</sect1>
</chapter>
<appendix role="module" id="app1-appendix">
<title>First Appendix Title</title>
<para>Write in here interesting appendix informations</para>
</appendix>
</book>
Thinking in a more or less “modular” way we can say that, generally speaking, a book has: a title, a preface, chapters and appendices. So, that is exactly what is represented in the sample master.top.xml above, no more, no less.
Finally, our master document looks like a standard DocBook document. However, there is something essential to be noted: The role="module" attribute. The elements (usually, sectX, chapter, appendix) having this attribute, denotes the modules handled by Borges.
For example, the whole sect1 element
<sect1 role="module" id="chap1-sect1-section">
<title>First Section Title</title>
<para>Write the chapter 1, section 1 contents</para>
</sect1>
will be used to generate the module's template. It will show as is in the document's guidelines but will be replaced by the module's content as written by its author in the module chap1-sect1-section.xml. Note that the module's name is taken from the structuring element ID.
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.
You might need to change the XML SYSTEM declaration of the DocBook DTD ("/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd") to suit your system. Note that if you use another version of the DTD, you will need to update the doctype and dtd elements of the main configuration file to fit the version number.
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=~/New_Project/master.top.xml
this will create the new My_Book document based on the master file ~/New_Project/master.top.xml (the file path must be absolute). It will actually perform the following tasks:
Each “contributor” (writer, translator, proofreader, etc.) must now 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>peter@pingus.com</email></address>
</affiliation>
</author>
</authorgroup>
Replace existing data with your own, possibly removing the <author> element if you are currently alone working on that project. Make sure to use unique IDs.
see Section 1.1.2, “conf/authors.xml” for more information about the structure of this file.
If you did not do it already it is time to tell to the system who you are in conf/author.xml (see Section 1.1.1, “conf/author.xml”).
This step is optional and can be performed in a loop during documents writing.
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.
Global entities are covered more thoroughly in Section 1.2.1, “Global Entities”.
When you add a new super-document to the repository, strings needed to be translated found in the master file are automatically transformed into entities that are 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:">
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.5, “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.
All that is left now is to fill your book with content: write the modules and create the images and/or drawings your book will contain. 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.
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.
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.