RE: GNOME FAQ FUBAR'd; need advice

[barreiro arrakis es]

On 21-Nov-98 Todd Graham Lewis wrote:
>Ok, I completely screwed up the transition of the GNOME FAQ from
>v1.0 to v1.0.1.  This was supposed to be a simple little release,
>but, as I mentioned, it is F'dUBAR.  This is, I think, an opportunity
>to examine how to deal with a complex and fluid document like this
>in the presence of multiple translations, and I would like to hear
>people's ideas.
>

Hi Todd,

Could you send me a copy of the new release ?
Have you used the docbook format ?



>1) HOW THE FAQ IS SCREWED UP
>
>When I released v1.0 of the FAQ, I hand-edited the SGML to make it
>as pretty as possible.  If you look at the source code for the v1.0
>SGML version of the FAQ, you will see that the paragraphs are nicely
>justified, etc.  The problem is that I then went on my merry way
>editing the LyX version for the v1.0.1 release.  When I spit out
>the SGML for v1.0.1, although it had the exact same words as v1.0,
>it bore no structural resemblence to it, and a diff between the two
>is full of meaningless differences in formatting.
>
>This makes it very hard to catalogue the changes which I made and
>send them out to the translators for them to integrate.
>
>This was colosally boneheaded on my part.
>

I'm lived similar problems with the JDK Faq. This kind of structural
change discourage translator efforts.

>2) HOW DO I WANT FOR THE FAQ TO WORK
>
>       A) I would like for each individual change to the FAQ to be
>       catalogued.
>
>       B) I would like for these changes to be easily accessible to
>       the translators so that they can apply them to the various
>       non-English versions of the FAQ.

You may use the cvs mail facilities to notify changes to the 
translators.

>
>       C) I would like to track the changes which the translators make
>       to their respective versions of the FAQ, so that I can understand
>       how close they are to the English version.
>
>       D) I would like _not_ to do a release of the FAQ until my
>       version and _all_ of the translations are in sync, so that
>       non-English-speakers are not given worse information than English
>       speakers.  Of course, this is dependent on the availability
>       of translators.

I agree with this dream !

>
>       E) I would rather feed the translators a steady stream of small
>       changes rather than a big group of changes, so that they can
>       better schedule the time out of their lives that they spend
>       on the FAQ and not have to rush all of the changes into their
>       translations at the last minute to allow me to do a release.
>
>3) WHAT DO I PROPOSE WE DO WITH THE FAQ?
>
>I propose to build a small computing system to accomplish these goals.
>What I envision is similar to CVS.  I would use CVS, except that I
>know of no way in CVS to document whether one file has been brought
>into accord with another file.  (E.g., has 4.1.6.es been updated
>to reflect the changes that happened two weeks ago to 4.1.6.en?)
>Fortunately, this is a very simple project, and I am confident that
>I can build it.
>
>What the translator would see is a utility.  This utility would list for
>the translators a list of questions which have changed.  The translator
>selects one of these questions.  The utility fetches the old and new
>versions of that question and presents them, as well as a diff between
>the two, to the translator.  The translator then updates his translation's
>version of that question.  The system then takes that question off of
>the translator's TODO list.
>
>The way that I propose storing the FAQ is in a two-pronged directory,
>FAQROOT.  The first prong is $FAQROOT/questions.  Under this directory
>are 'n' directories, where 'n' is some number.  Each of these directories
>stores a single question/answer pair.  It stores one version of the Q/A
>in a file per language.  Thus, e.g., a single question's directory
>would look like this:
>
>$FAQROOT/
>   questions/
>      43/
>         en
>         it
>         es
>         fr
>
>'en' stores the english-language version of the Q/A, 'it' stores the
>italian version, etc.
>
>The second portion would be the structure portion.  This would have
>all of the sections, subsections, etc., of the FAQ, with symlinks
>to the actual questions in the $FAQROOT/questions portion.  This
>would look, e.g., something like this:
>
>$FAQROOT/
>   structure/
>      3/
>         TITLE.en
>         TITLE.it(...)
>         INTRODUCTION.en
>         INTRODUCTION.it(...)
>         2 -> ../../../questions/412/
>
>This way, I can change around the organization of the FAQ without
>the translators having to care about it.  Any changes to a section's
>title or introduction would be tracked the same way as the questions.
>Perhaps I should store these in the 'questions' tree, which might
>be better titled the 'content' tree.
>
>I would track all actual files using RCS/CVS, enabling one to see
>the history of changes thereto.
>
>IMPORTANT: The content files themselves would be SGML fragments.
>They would have tags like "<ITEMIZE>", but not like "<SUBSECTION>".
>Translators should be able to keep the tags like they are in the
>English version and just translate the actual content.  It is
>important, esp., that cross-references be left alone, in order
>for the document to remain integral.
>
>What do people, translators in particular, think of this approach?
>I would like to start work on it, but I don't want to do it if 
>someone has a better way, or if someone has a big objection to this
>approach.  Please let me know what you think!
>

I think it's a good approach, with this system it's easy for translator
make the work step by step, and work together with other volunteer.
I can't help you to test the system, if you want. I'm system admin and
perl programer.

Regards



Manuel de Vega Barreiro. barreiro@arrakis.es   En un lugar de la red
Madrid. Espaņa.                                de cuyo nombre no quiero
http://www.croftj.net/~barreiro Linux Landia   acordarme..........

P.D. Vota por el proyecto DLD en el concurso de PC-internet
http://www.pc-internet.com/pcinternet/concurso.asp