<?xml version="1.0" encoding="ISO-8859-1"?>
<sect1 id="borges-revision-features-sect1">
<sect1info>
<!-- Please, do NOT edit the following revision history by hand. Use the
"make <module_name>.revision" target instead. -->
<revhistory><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>write</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>translate</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>tproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>pproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>ispell</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>lproof</revremark> </revision>
<revision>
<revnumber>1.en.lproof</revnumber>
<date>YYYY-MM-DD</date>
<authorinitials>tbn</authorinitials>
</revision>
<revision>
<revnumber>1.en.ispell</revnumber>
<date>YYYY-MM-DD</date>
<authorinitials>tbn</authorinitials>
</revision>
<revision>
<revnumber>1.en.pproof</revnumber>
<date>2002-07-22</date>
<authorinitials>jp</authorinitials>
</revision>
<revision>
<revnumber>1.en.tproof</revnumber>
<date>2002-07-03</date>
<authorinitials>cb</authorinitials>
</revision>
<revision>
<revnumber>1.en.write</revnumber>
<date>2002-06-28</date>
<authorinitials>cb</authorinitials>
</revision>
</revhistory></sect1info>
<title id="borges-revision-features-sect1-ti1">Revision Management</title>
<abstract>
<para id="borges-revision-features-sect1-pa1">Revision management is the most interesting feature of
&prog-borges;. It tracks documents on two axes:
<orderedlist>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti2">Modules status (<xref linkend="module-life-cycle"/>)</title> <para id="borges-revision-features-sect1-pa2">Each
independant piece of document called a
<quote>module</quote> has its own life cycle in
&prog-borges;. Granular module management ensures quality
standards while allowing to generate accurate project
tracking information.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti3">Translations Freshness (<xref linkend="module-synch"/>)</title> <para id="borges-revision-features-sect1-pa3">Translating a
document is something common. Updating translation from an
ever-changing original is often a nightmare. Thanks to the
innovative system brought by &prog-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.</para>
</formalpara>
</listitem>
</orderedlist>Thanks to these tools, hierarchical reports can be
generated giving relevant project tracking information for
everyone project managers as well as modules authors,
translators, contributors.</para>
</abstract>
<sect2 id="module-life-cycle">
<title id="borges-revision-features-sect1-ti4">Modules Life Cycle</title>
<sect3>
<title id="borges-revision-features-sect1-ti5">The underlying philosophy</title>
<para id="borges-revision-features-sect1-pa4">A module is born when it is referenced for the first time
in a master super-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:
<orderedlist>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti6">Written</title> <para id="borges-revision-features-sect1-pa5">When the redactor has
finished writing an original module.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti7">Translated</title> <para id="borges-revision-features-sect1-pa6">When a translator has
finished the translation of an original module in his
language.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti8">Technical proofreading</title> <para id="borges-revision-features-sect1-pa7">When a
technical expert has read a module, and his remarks have
been incorporated.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti9">Pedagogical proofreading</title> <para id="borges-revision-features-sect1-pa8">When an
education specialist has read a module, and his remarks
have been incorporated.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti10">Spell checking</title> <para id="borges-revision-features-sect1-pa9">When the module has
successfully passed a spell checker.</para>
</formalpara>
</listitem>
<listitem>
<formalpara>
<title id="borges-revision-features-sect1-ti11">Language proofreading</title> <para id="borges-revision-features-sect1-pa10">When a skilled
native speaker has read a module, and his remarks have been
incorporated.</para>
</formalpara>
</listitem>
</orderedlist>After a module has reached this last step, he 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.</para>
<figure>
<title id="borges-revision-features-sect1-ti12">Borges' Modules Life Cycle</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/borges-modules-workflow.pdf" format="EPS" id="borges-revision-features-sect1-im1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/borges-modules-workflow.png" format="PNG" id="borges-revision-features-sect1-im2"/>
</imageobject>
</mediaobject>
</figure>
</sect3>
<sect3>
<title id="borges-revision-features-sect1-ti13">Modules status in practice</title> <para id="borges-revision-features-sect1-pa11">The module
history is stored directly in the revision history of the
module's root element. However it <emphasis>must not</emphasis>
be edited by hand. For this purpose there are &prog-make;
targets that will take care of all the tasks associated with a
module's status.</para> <para id="borges-revision-features-sect1-pa12">This is the synopsis of the
command that will perform the work associated to a task:
<synopsis id="borges-revision-features-sect1-sy1">make <module-name>.revision TYPE=<type></synopsis>
where <type> is one of the following, corresponding to the steps we described just above:<orderedlist>
<listitem>
<para id="borges-revision-features-sect1-pa13"><literal>write</literal></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa14"><literal>translate</literal></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa15"><literal>tproof</literal></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa16"><literal>pproof</literal></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa17"><literal>ispell</literal></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa18"><literal>lproof</literal></para>
</listitem>
</orderedlist>Let's imagine you just modified the module
<filename>intro-section.xml</filename> according to the
remarks the pedagogical proofreader gave you. The command to
issue in the directory owning the file will be:
<programlisting id="borges-revision-features-sect1-pl1">make intro-section.revision TYPE=pproof</programlisting></para>
</sect3>
<sect3 id="assign-tasks">
<title id="borges-revision-features-sect1-ti14">Assigning tasks</title>
<para id="borges-revision-features-sect1-pa19">In order to get full advantage of &prog-borges; features,
it is recommended to assign all tasks in all languages for all
modules. That will ensure no task is left orphan, improving
project efficiency.</para>
<para id="borges-revision-features-sect1-pa20">This operation is achieve with the following command:
<synopsis id="borges-revision-features-sect1-sy2">make <module-name>.revision TYPE=<type>.todo AUTHOR=<ai></synopsis>
where <literal><ai></literal> are the initials of the author
responsible for that operation. For example if author
<literal>pp</literal> is responsible for performing language
proofreading on module <filename>intro-section</filename> in spanish, you would issue:
<programlisting id="borges-revision-features-sect1-pl2">make -C modules/es/ intro-section.revision TYPE=pproof.todo AUTHOR=pp</programlisting></para>
</sect3>
</sect2>
<sect2 id="module-synch">
<title id="borges-revision-features-sect1-ti15">Inter-Languages Modules Synchronization</title>
<sect3>
<title id="borges-revision-features-sect1-ti16">The Idea Behind Atom Revisions</title>
<para id="borges-revision-features-sect1-pa21">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 one and
only 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 by
opposition to semantic changes), one has to extract pertinent
bits in a sea of irrelevant information.</para>
<para id="borges-revision-features-sect1-pa22">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.</para>
</sect3>
<sect3>
<title id="borges-revision-features-sect1-ti17">Authors Duties</title>
<para id="borges-revision-features-sect1-pa23">The whole system relies on authors good will. If they are
contentious 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.</para>
<para id="borges-revision-features-sect1-pa24">When a module passes the <literal>pproof</literal> step,
it gets ready for translation. The system then automatically
adds IDs to any possible atom<footnote>
<para id="borges-revision-features-sect1-pa25">To get the list of elements that become an atom,
consult
<filename>/usr/share/Borges/bin/scatter_ids.pl</filename></para></footnote>
in that module. Let's follow a specific paragraph of the
<filename>passwords</filename> module:<orderedlist>
<listitem>
<para id="borges-revision-features-sect1-pa26">After the module has passed the
<literal>pproof</literal> step, our paragraph got an
automatic ID:
<programlisting id="borges-revision-features-sect1-pl3">
<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>
</programlisting></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa27">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:
<programlisting id="borges-revision-features-sect1-pl4">
<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>
</programlisting></para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa28">Later on, you realize there is a mistake in the
package name, it is not <filename>metamailer</filename>
but <filename>metamail</filename>. Even though the
<literal>filename</literal> element is not a default atom,
you can assign it an ID and a revision attribute:
<programlisting id="borges-revision-features-sect1-pl5">
<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>
</programlisting>
This is better than increasing the paragraph revision to
<literal>2</literal>, as the translator will directly spot the change
in the <literal>filename</literal> element without having to search
through the whole paragraph.</para>
</listitem>
</orderedlist></para>
<tip>
<para id="borges-revision-features-sect1-pa29">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 <literal>phrase</literal> element, adding the
ID and revision to that reduced element...</para>
</tip>
<warning>
<para id="borges-revision-features-sect1-pa30">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 risk of duplicate IDs) or
to let the system reassign all IDs throughout the module if
there has been many changes. This is made thanks to the
following command:
<programlisting id="borges-revision-features-sect1-pl6">make <module-name>.id</programlisting>
Obviously, this command will also have to be run on translated
modules...</para>
</warning>
</sect3>
<sect3 id="translation-outdated">
<title id="borges-revision-features-sect1-ti18">How Translators Synchronize Modules</title>
<abstract>
<para id="borges-revision-features-sect1-pa31">We won't speak about reports generation here, but rather
how to read reports and what to do according to the
information contained in the reports.</para></abstract>
<figure id="doc-report-sample">
<title id="borges-revision-features-sect1-ti19">An extract of a super-document report</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/doc-report-sample.pdf" format="EPS" id="borges-revision-features-sect1-im3" scale="60" scalefit="1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/doc-report-sample.png" format="PNG" id="borges-revision-features-sect1-im4"/>
</imageobject>
</mediaobject>
</figure>
<para id="borges-revision-features-sect1-pa32">Whenever a translated module becomes obsolete with
respect to the original, the corresponding cell in the
super-document report table becomes red (<xref linkend="doc-report-sample"/>). If you click in the cell, you
then get to the module's detailed report (<xref linkend="module-report-sample"/>).</para>
<figure id="module-report-sample">
<title id="borges-revision-features-sect1-ti20">A Sample Modules' report</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/module-report-sample.pdf" format="EPS" id="borges-revision-features-sect1-im5" scale="70" scalefit="1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/module-report-sample.png" format="PNG" id="borges-revision-features-sect1-im6"/>
</imageobject>
</mediaobject>
</figure>
<para id="borges-revision-features-sect1-pa33">In that report, after the revision history table, two links appear:<itemizedlist>
<listitem>
<para id="borges-revision-features-sect1-pa34"><xref linkend="IdChange-report-sample"/>: spots the
atoms that differs between the translation and its
original;</para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa35"><xref linkend="TextChange-report-sample"/>: presents
the original and translated atoms that are out of synch
side by side.</para>
</listitem>
</itemizedlist></para>
<figure id="IdChange-report-sample">
<title id="borges-revision-features-sect1-ti21">Changes in IDs/revisions</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/IdChange-report-sample.pdf" format="EPS" id="borges-revision-features-sect1-im7" scale="50" scalefit="1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/IdChange-report-sample.png" format="PNG" id="borges-revision-features-sect1-im8"/>
</imageobject>
</mediaobject>
</figure>
<para id="borges-revision-features-sect1-pa36">In this table, the atoms that have been modified in the
original clearly appear. The author knows that the element with
ID <literal>passwords-pa2</literal> has been modified, while a
new element <literal>metamail-pack</literal> has been
added.</para>
<figure id="TextChange-report-sample">
<title id="borges-revision-features-sect1-ti22">Side by side not synched elements</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/TextChange-report-sample.pdf" format="EPS" id="borges-revision-features-sect1-im9" scale="45" scalefit="1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/TextChange-report-sample.png" format="PNG" id="borges-revision-features-sect1-im10"/>
</imageobject>
</mediaobject>
</figure>
<para id="borges-revision-features-sect1-pa37">Through this page the translator can open the
<filename>modules/fr/passwords.xml</filename> file, search the
element <literal>passwords-pa2</literal> and synchronize its
content according to the text in the <acronym>HTML</acronym>
report. Of course the new ID and revision attributes will have
to be copied too, so that the system can know the atom has been
updated.</para>
</sect3>
</sect2>
<sect2 id="generate-global-reports">
<title id="borges-revision-features-sect1-ti23">Generating Reports</title>
<para id="borges-revision-features-sect1-pa38">Here is a diagram showing the different
<acronym>HTML</acronym>reports generated by &prog-borges;, and the
navigation through them.</para>
<figure id="borges-reports-diagram">
<title id="borges-revision-features-sect1-ti24">The reports generated by Borges</title>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/borges-reports-diagram.pdf" format="EPS" id="borges-revision-features-sect1-im11" scale="80" scalefit="1"/>
</imageobject>
<imageobject>
<imagedata align="center" fileref="images/borges-reports-diagram.png" format="PNG" id="borges-revision-features-sect1-im12"/>
</imageobject>
</mediaobject>
</figure>
<para id="borges-revision-features-sect1-pa39">We will now see how to generate each one of those reports
and how to read them.</para>
<warning>
<para id="borges-revision-features-sect1-pa40">It is necessary that all the sources in all languages are
valid so that the reports get generated correctly.</para>
</warning>
<sect3 id="borges-global-report">
<title id="borges-revision-features-sect1-ti25">Global Project Report</title>
<para id="borges-revision-features-sect1-pa41">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
<filename>reports/</filename> directory of your project):
<programlisting id="borges-revision-features-sect1-pl7">make all</programlisting>
That will generate the <filename>index.html</filename> file and you
will just have to point your browser to that file. For an
example of such a report, consult the <ulink url="http://www.linux-mandrake.com/en/doc/project/Borges/reports/">Overall
report for Borges Manuals</ulink>.</para>
<para id="borges-revision-features-sect1-pa42" revision="1">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 <quote>Links to the compiled versions of the
manuals</quote>). If you wish to only generate the reports
without the documents, run
<programlisting id="borges-revision-features-sect1-pl8">make index.html</programlisting></para>
<note>
<para id="borges-revision-features-sect1-pa43">This feature is
particularly useful for project managers willing to regularly
(through cron jobs) publish on a website the current project
status. It is enough to upload the content of the
<filename>reports/</filename> directory on a website and point
people to it.</para>
</note>
</sect3>
<sect3>
<title id="borges-revision-features-sect1-ti26">Super-Document Report</title>
<para id="borges-revision-features-sect1-pa44">If you wish to generate only the report for a super
document (and all dependent reports), run:
<programlisting id="borges-revision-features-sect1-pl9">make master-report.html</programlisting>
in the directory of the super-document
(e.g. <filename>manuals/My_Doc/</filename>). You can then open
<filename>master-report.html</filename> with your favorite
browser. For an example of such a report, consult the <ulink url="http://www.linux-mandrake.com/en/doc/project/Borges/reports/Borges-doc/master-report.html">Detailed
report status for Borges-doc</ulink>.</para>
<para id="borges-revision-features-sect1-pa45">The table in that report has one line per module of the
corresponding super-document. There are at least three
columns:<orderedlist>
<listitem>
<para id="borges-revision-features-sect1-pa46">The name of the module, followed by the name of the
original author of that module;</para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa47">The title of the module;</para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa48">Three possibilities for the content of that
cell:<itemizedlist>
<listitem>
<para id="borges-revision-features-sect1-pa49">The task in progress for that module in the
language corresponding to that column. If known the person
responsible for that task is shown in parenthesis.</para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa50">If no task is available for now the text
<quote>Pending</quote> is shown.</para>
</listitem>
<listitem>
<para id="borges-revision-features-sect1-pa51"><quote>OK</quote> means that all tasks
required on that module have been passed.</para>
</listitem>
</itemizedlist>If the cell appear on a red background,
that means this translation is outdated with respect to
the original module. See <xref linkend="translation-outdated"/>.</para>
<para id="borges-revision-features-sect1-pa52">A click on the text of that cell will lead to the
corresponding <xref linkend="module-report"/>.</para>
</listitem>
</orderedlist>
</para>
</sect3>
<sect3 id="module-report">
<title id="borges-revision-features-sect1-ti27">Module report</title>
<para id="borges-revision-features-sect1-pa53">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 holds the revision history for the module, plus possible
links to detailed diff reports if that module happens to be out
of synch (see <xref linkend="translation-outdated"/>).</para>
</sect3>
<sect3>
<title id="borges-revision-features-sect1-ti28">ID Changes Report</title>
<para id="borges-revision-features-sect1-pa54">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:
<programlisting id="borges-revision-features-sect1-pl10">make <module-name>.ids.html LANG=<xx> manual=<super-document></programlisting>
for example to get the IDs report of the
<literal>passwords</literal> module in French as part of the
<literal>Borges-doc</literal> super-document, you will need to go
into <filename>modules/fr/</filename> and run:
<programlisting id="borges-revision-features-sect1-pl11">make passwords.ids.html LANG=fr manual=Borges-doc</programlisting>
You then just need to open <filename>passwords.ids.html</filename>
with your browser.</para>
</sect3>
<sect3>
<title id="borges-revision-features-sect1-ti29">Content Changes Report</title>
<para id="borges-revision-features-sect1-pa55">Same as above, but then the command becomes:
<programlisting id="borges-revision-features-sect1-pl12">make <module-name>.changes.html LANG=<xx> manual=<super-document></programlisting></para>
</sect3>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-parent-document: ("../../manuals/Borges-doc/master.top.xml" "sect1")
End:
-->
distrib
>
Mandriva
>
9.1
>
ppc
>
media
>
main
>
by-pkgid
>
6c1629ca18f6adf273e73d0f5069fa8c
>
files
>
338
