Abstract
Revision management is the most interesting feature of Borges. It tracks documents on two axes:
Module status (Section 4.1, “Module Life Cycle”). Each independent piece of a document called a “module” has its own life cycle in Borges. Granular module management ensures quality standards while allowing you to generate accurate project tracking information.
Translation Freshness (Section 4.2, “Inter-Language Module Synchronization”). Translating a document is something common. Updating translations for an ever-changing original is often a nightmare. Thanks to the innovative system brought by Borges, it is possible to know whenever a translation needs to be updated, and where exactly the changes are located. This system also ensures that the structure of the document is respected throughout its various translations, while allowing translators to explicitly make additions with respect to the original structure.
Thanks to these tools, hierarchical reports can be generated giving relevant project tracking information for everyone: project managers as well as module authors, translators, contributors, etc.
In addition to module revisions it is necessary to handle whole document revisions (when a new version of the documented product is released for example).
A module is born when it is referenced for the first time in a master document. It reaches its maturity when it passes final language proofreading. Between those two steps it is necessary to bring a module to each one of these steps[3]:
Written. When the redactor has finished writing an original module.
Translated. When a translator has finished the translation of an original module to his language.
Technical proofreading. When a technical expert has read a module, and his remarks have been incorporated.
Pedagogical proofreading. When an education specialist has read a module, and his remarks have been incorporated.
Spell checking. When the module has successfully passed a spell checker.
Language proofreading. When a skilled native speaker has read a module, and his remarks have been incorporated.
After a module has reached this last step, it is regarded as mature and ready for publication. Below is a diagram that better explains the process for an original module and one of its translations.
This figure is the illustration of the information contained in Section 1.1.5, “conf/repository.xml”, and requires a few comments:
Just after the original module passes the presentational proofreading status, all automatic IDs in it are (re)assigned, as well for all its translations. This resets the automatic IDs numbering from one to the other release.
After a major release change is decided the writing and translation states are not required anymore, simply because this only needs to bo done once. Instead they are replaced by the “Update” and “Synchronise” steps.
The “Synchronise” step can be reactivated even after the original has passed the “Presentational Proofreading” status. This is to allow the translations to be updated with respect to the original if this one is to be altered afterwards. This is represented by dotted arrows in the diagram. See Section 4.2, “Inter-Language Module Synchronization”. Note that the subsequent steps for the translation (spell and language proof) are not reactivated if they had been done already.
Note
This is the description of the default workflow as proposed by Borges by default. It is possible to define a customized workflow by defining it in Section 1.1.5, “conf/repository.xml”.
The module history is stored in a hidden file, and must not be edited by hand. For this purpose there are make targets that will take care of all the tasks associated with a module's status.
This is the synopsis of the command that will perform the work associated to a task:
make <module-name>.revision TYPE=<type>
where <type> is one of the following, corresponding to the steps we described just above:
Let's imagine you just modified the module intro-section.xml according to the remarks made by the pedagogical proofreader. The command to issue in the directory containing the file will be:
make intro-section.revision TYPE=pproof
In order to get full advantage of Borges features, it is recommended that you assign all tasks in all languages for all modules. That will ensure that no task is left orphaned, improving project efficiency.
This operation is achieved with the following command:
make <module-name>.revision TYPE=<type>.todo AUTHOR=<ai>
where <ai> are the initials of the author responsible for that operation. For example if author pp is responsible for performing language proofreading on module intro-section in Spanish, you would issue:
make -C modules/es/ intro-section.revision TYPE=pproof.todo AUTHOR=pp
To ensure a translation remains up to date with respect to its original, it is necessary to track changes in the original. To track changes in a text, there is basically only one method: generate the differences between two versions. However this has a big drawback: when the changes are not relevant for the translator (spell and syntactic changes in opposition to semantic changes), one has to extract pertinent bits in a sea of irrelevant information.
To make sure relevant changes are explicitly marked as such, human action is needed. Therefore the redactor changing the meaning of a paragraph will have to explicitly mark that paragraph as modified by incrementing its associated revision attribute. Then the system will be able to spot atoms through a translated module that are not up to date and warn the translator.
The whole system relies on authors good will. If they are conscientious at adding revisions all will be fine. Experience has proved that it's easy to make authors aware of the problem, and then all works perfectly.
When a module passes the pproof step, it becomes ready for translation. The system then automatically adds IDs to any possible atom[4] in that module. Let's follow a specific paragraph of the passwords module:
After the module has passed the pproof step, our paragraph got an automatic ID:
<para> <screen> root# head -c 6 /dev/urandom | mimencode</screen> This will print five random characters on the console, suitable for password generation. You can find <command>mimencode</command> in the <filename>metamailer</filename> package.</para>
Despite technical proofreading a reader has spotted an error: it should read six and not five random characters. You then correct the error and add a revision ID:
<para revision="1"> <screen> root# head -c 6 /dev/urandom | mimencode</screen> This will print six random characters on the console, suitable for password generation. You can find <command>mimencode</command> in the <filename>metamailer</filename> package.</para>
Later on, you realize there is a mistake in the package name, it is not metamailer but metamail. Even though the filename element is not a default atom, you can assign it an ID and a revision attribute:
<para revision="1"> <screen> root# head -c 6 /dev/urandom | mimencode</screen> This will print six random characters on the console, suitable for password generation. You can find <command>mimencode</command> in the <filename id="metamail-pack" revision="1">metamail</filename> package.</para>
This is better than increasing the paragraph revision to 2, as the translator will directly spot the change in the filename element without having to search through the whole paragraph.
Tip
If you wish to help translators spot a little change in a big chunk of text, it is better to enclose the modified sentence in the phrase element, adding the ID and revision to that reduced element...
Warning
It often happens that an author is forced to modify the structure of a module, even after it has gone to translation. In that case, it may become necessary to assign IDs to possible new elements. The author can choose to assign them manually (ensuring there are no risks of duplicate IDs) or to let the system reassign all IDs throughout the module if there have been many changes. This is made thanks to the following command:
make <module-name>.id
Obviously, this command will also have to be run on translated modules...
Abstract
We won't talk about report generation here, but rather about how to read the reports and what to do according to the information contained in the reports.
Whenever a translated module becomes obsolete with respect to the original, the corresponding cell in the super-document report table becomes red (Figure 3.2, “An extract of a super-document report”). If you click in the cell, you then get to the module's detailed report (Figure 3.3, “A Sample Modules' report”).
In that report, after the revision history table, two links appear:
Figure 3.4, “Changes in IDs/revisions”: spots the atoms that differ between the translation and its original;
Figure 3.5, “Side by side not synched elements”: presents the original and translated atoms that are out of synch side by side.
In this table, the atoms that have been modified in the original clearly show. The author knows that the element with ID passwords-pa2 has been modified, while a new element metamail-pack has been added.
Through this page the translator can open the modules/fr/passwords.xml file, search the element passwords-pa2 and synchronize its content according to the text in the HTML report. Of course the new ID and revision attributes will have to be copied too, so that the system will know the atom has been updated.
When a new version of a software or product is released, its accompanying documentation generally also needs big changes. That's in this case that Borges offers a documents major release feature, allowing you to restart the production cycle on existing modules.
When you have created your documents you have assigned them an initial release number (see Section 3.2.4, “Insert the New Document”). Then all tasks that have been performed on associated modules since then are linked to this precise release number. Increasing the release number of a project will create a new set of tasks for every single module of the project with the new release number.
All this is performed in one single command:
make release REL=2.0
Note
This process can take a fair amount of time if there are a lot of modules and languages.
It is recommended to change the release number of all documents of a same project at once. Indeed, if two documents with two different release numbers use a same module, it will result in conflicts when generating reports. Though if you prefer to manage document release numbers separately you can with the following command:
make -C manuals/My_Manual/ release REL=2.0
Here is a diagram showing the different HTMLreports generated by Borges, and the navigation through them.
We will now see how to generate each one of those reports and how to read them.
Warning
It is necessary that all the sources in all languages are valid so that the reports get generated correctly.
Generating this report will in fact generate all other reports so that it is possible to consult them starting from the global project report page. You simply need to issue the following command (in the reports/ directory of your project):
make all
This will generate the index.html file and you just have to point your browser to that file. For an example of such a report, consult the Overall report for Borges Manuals.
The resulting page is self-documented so we won't detail it here. You will however note that, during the compilation process, all rough super-documents have also been generated (see the “Links to the compiled versions of the manuals”). If you wish to only generate the reports without the documents, run
make index.html
If you wish to generate only the report for a super document (and all dependent reports), run:
make master-report.html
in the directory of the super-document (e.g. manuals/My_Doc/). You can then open master-report.html with your favorite browser. For an example of such a report, consult the Detailed report status for Borges-doc.
The table in that report has one line per module of the corresponding super-document. There are at least three columns:
The name of the module, followed by the name of the original author of that module;
Three possibilities for the content of that cell:
If a cell appears with a red background, it means this translation is outdated with respect to the original module. See Section 4.2.3, “How Translators Synchronize Modules”.
A click on the text of that cell will lead to the corresponding Section 4.4.3, “Module report”.
There is no need to generate one specific module report, all module reports related to a specific super-document are generated while making the super-document report. This page simply contains the revision history for the module, plus possible links to detailed diff reports if that module happens to be out of synch (see Section 4.2.3, “How Translators Synchronize Modules”).
When a translator is in the process of updating a module, it may be interesting to quickly regenerate the IDs report to check everything is fine. The command to issue is:
make <module-name>.ids.html LANG=<xx> manual=<super-document>
for example to get the IDs report of the passwords module in French as part of the Borges-doc super-document, you will need to go into modules/fr/ and run:
make passwords.ids.html LANG=fr manual=Borges-doc
You then just need to open passwords.ids.html with your browser.