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_Project
You 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="ISO-8859-1"?> <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="ISO-8859-1"?> <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.