3. Some Vocabulary


We will explain all terms used in Borges' documentation: project, author, author initials, document, sub-document, module, module status, atom, atom revision, etc.


The terms are not presented in any particular order.


An author can be the redactor, the translator or the reviewer of a module. Generally speaking, the “author” concept is bound to the creator (in this case, writer) of something, but Borges treats translators and reviewers as authors.

See Also Author Initials, Module.

Author Initials

Borges identifies the different authors that participate in a project by their initials. This limits the initials used by different authors of the same project to be unique.

If your project has a small group of authors, two-letter initials should be enough, but more letters may be used as long as they are unique.

See Also Author, Project.


A project is a document or a set of documents you are managing with Borges. Usually, a project contains lots of documents.

See Also Document.


Designates a set of modules, structured together to form a book, an article, a user manual; any exhaustive information block about a particular subject.

The super-document is the “master” from which different documents can be generated. The super-document structure is defined in the master.top.xml file.

A super-document can contain mutually exclusive informations that will be sorted out by specializing the super-documents into various documents.

See Also Document.


A document is a compilation of a super-document resulting in a PDF file or (X)HTML file(s). You may choose to compile all your super-document, or parts of it. Documents can be whole books, articles, reference sheets, letters, manuals, etc.

See Also Compilation, Super-document.


Compilation is the process by which a set of source XML files is “transformed” into a PDF or (X)HTML document.

Structuring element

In a super-document, a structuring element is a DocBook element that contains module elements. Typical structuring elements are part or chapter.

See Also Super-document, Module element.

Module element

In a super-document, a module element is a DocBook element which contains the special

<para role="module">

child element. A module element will be replaced in the final document by the module content itself. Typical module elements are chapter or sect1.

See Also Super-document, Module element.


Modules are the parts that compose documents. Usually, a super-document is divided into small chunks called modules to simplify writing, translating, management and content re-use. Chapters, sections, appendices and glossaries are good candidates to become modules.

In fact, Borges requires that any structuring element be placed in a module to be able to be translated and to take advantage of the revision management features.

Modules can have some parts flagged, by means of the condition= attribute, in order to be excluded from certain compilations. This gives you the ability to create more than one kind of document from a single set of modules, improving the content re-use features of Borges.

See Also Document, Super-document, Project.

Original Module

This is used to specify a module which has been written by the module redactor. Translators will use this original module as the base for all translations.

See Also Module, Translated Module.

Translated Module

Designates a module which is not the original one, but a translation of the original module.

See Also Module, Original Module.

Module Status

Modules go through different states during their life cycle. Each “state” determines the module's status.

In order to go from one state to another, some operation needs to be performed on the module, for example: writing, translating, spell checking, proofreading, etc.

See Also Life Cycle.


Atoms are the XML elements used for checking modifications inside a module. They are the smallest possible elements that contain text. Typical DocBook atoms are <title> and <para>.

See Also Atom Revision.

Atom Revision

Atom's have a revision number used by the Borges revision management system in order to track changes made into modules at an “atom scale”.

See Also Atom.

Life Cycle

The life cycle of a module is composed of several stages (or states) that a module must go through in order to be considered ready to be released. Currently, Borges only supports a fixed life cycle, which is detailed in Section 4.1, “Module Life Cycle”.

See Also Module, Module Status.