Mailing List Archive

Sven Vermeulen wrote:
> Okay, I'm feeling productive again and have a lot of ideas for the GDP.
> Some of them have been brought up earlier but dismissed due to insufficient
> resources, others are ideas I've stolen from people that didn't dare to tell
> it out loud, the rest is fairly new and due to a huge cafe�ne concentration
> in my body.

The blood level of my cafeïne is rather low ;-)

> My first observation is that we have an abstract tag in each of our
> documents (mandatory) that's only used for the upper right corner. It seems
> to me that this abstract can very well be used as a description of the
> document for our index page.

Indeed. BTW, allowing both "file.xml" and "/path/to/doc/LANG/file.xml" might
be a problem, but more about that later...

> What I was thinking about is to write an XML format (to be chained to
> GuideXML) that includes each document and automatically uses the abstract as
> a description. This format would make it possible to have two documentation
> index'es:
> - index.xml, desktop.xml and additional index'es that look the same as
> they are now (but with the abstract information)
> - list.xml which contains links to every single document we have without
> additional information
>
> This latter is something cam also requested (one document that lists them
> all) and I proposed something along the lines of
>
> <ul>
> <li>
> Category 1
> <ul>
> <li><uri link="${DOCUMENT}">${DOCUMENT_TITLE}</uri></li>
> ...
> </ul>
> </li>
> <li>
> Category 2
> ...
> </li>
> ...
> </ul>
>
> Writing such an XML (well, actually DTD+XSL+XML) is fairly simple, *but*
> since I'm always trying to get Xavier on my neck with my proposals, I'd like
> to go even further and have his TradsXML format that he uses for the translation
> summary incorporated. I believe (although I haven't written a POC yet) that
> we can have such a translation summary incorporated so that this is
> available on the official website.

I also think it's about time we had a list.xml of our docs. It might even be
the first step to an index generator (I mean an index like at the end of
books, not like the current index.xml).
We'd need to list documents and also files for multi-file docs like a
handbook, categories (one doc can appear in several categories), some meta
information like whether the doc is required to be translated, whether it is
translatable. Originals' revision number would be best stored in each file
because CVS can ensure it is up-to-date ($Revision$). Anything else?
It needs to allow listing docs outside of /doc/en/ as well BTW.
Another thing: list active languages and known languages. Active ones could be
used to generate the list of languages at the beginning of our indexes, the
known ones would be used when processing document paths. i.e. if anything from
known languages appears between //, i.e. .../fr/..., we know the document is
a translation of .../en/... I'm not too keen on having an attribute like
translation_of="/doc/en/original.xml" in the <guide> element.

> And, to make things even worse, I'm thinking about extending the book.dtd
> definition to have a <version> and <date> entity within the <sections>
> entity (mandatory) so that each hb-* file has it's own version/date
> information.

YeaHa!
It's a real PITA to update those in all handbook-ARCH.xml whenever anything
has been changed in a common part. It's a double-PITA when you update
translations at the same time.
We need to be able to display "updated #{max(hb*xml.date)}" on handbook pages BTW.

> I was (but have dropped the idea) thinking about adding an optional
> attribute to the "version" tag that had information about the English
> revision, so that translated documents could have:
> <version english="1.32">2.1</version>
> in which the "english" attribute referenced the CVS Revision of the English
> document to which the document was translated, but I dropped the idea
> because it's confusing and the above proposal (Xavier's TradXML format)
> includes the necessary information already.

I'm happy you dropped that idea ;-)
I quite dislike mentioning the original's revision in a translation because it
means whenever a new revision of an original is committed purely for language
reasons (i.e. typos, rephrasing...), you need to commit a new revision of the
translation as well just to say "nothing has changed".

> So, short summary:
> - Write an XML to be chained to GuideXML that incorporates Xavier's
> TradXML format
> - Have index.xml and others automatically generated from the abstract
> information
> - Have a single document that links to all existing documents
>
> Thoughts? Ideas? I won't do anything about this for at least 5 days so that
> everything can be thought of and discussed properly (I know I have the bad
> habit of pushing things which is why I force myself upon this 5 days "lag").

My TradsXML cannot be used a such because it holds information like the path
to the local CVS copy on the translator's disk, contributors' email, bla bla
bla. I'll update my TMS --Translation Management System :-) -- to use whatever
solution we decide to implement.
The one thing it holds that we could use is the revision number of the English
revision that has been translated. I definitely want to keep that out of the
translated docs themselves and a common format used for all languages would be
an improvement IMO.

> A second thing I am thinking about is to add a warning to all outdated
> documentation. Outdated would mean that it's not accurate to the definition
> in the Translators Howto [1].
>
> The warning would constitute something like this:
>
> <warn>
> This translation is not up to date with the latest <uri
> link="path/to/english.xml">English document</uri> conform the documentation
> project's <uri link="path/to/accuracy.xml">Translation Accuracy
> Guidelines</uri>. If you want to help us update this document, please
> contact <mail link="lead@translator">Franky Oobar</mail>, the Bleh Lead
> Translator, or file a <uri link="http://bugs.gentoo.org">bugreport</uri> and
> attach an updated version.
> </warn>

I'm 100% behind this.

> This would be translated first (we might want to store this translation
> somewhere) and can easily be filled in. The warning would be put before the
> first sentence (<p> entity) although I don't think we need to add a specific
> <chapter><title>...</title><section><body> construct just for this.
>
> This not only informs users about the not-so-updated documentation (which
> reduces the number of mails sent to www@gentoo.org) but might also result in
> more contributions (who knows).
>
> We _can_ (but it's hackish) include the translation (which is two-fold) in
> the inserts-${LANG}.xml file

Not at the moment. IIRC, our gettext will only work with a single string, not
a node-set. No big deal but you need to know.
Maybe /doc/{LANG}/outdated.xml is a neater way even though it's yet another file.

> and add an attribute to the GuideXML format so we
> can just include
> <version outdated="yes">...</version>
> which will automatically add in this warning (although the location may be
> different here).

Hmmm.
The lead translator simply removes this attribute when updating the
translation but what or who sets this attribute, when and how?

+++++++++++++++++++++++++++++++++++++++++++++

Hey, wait a minute!
Can't it all be simpler?
Let's say we have a list.xml with a list of documents and some metadata.
We can use it to generate indexes, lists of documents...

Let's say we can rely on the <version> and <link> elements.
When a <guide|book> document is processed, use the following pseudo-code:

If no /en/ in link attribute or lang attribute not 'en',
# Doc is a translation
Find original (replace /{LANG}/ with /en/)
compare <version> elements of both docs
if versions differ,
issue warning
# We may even display version numbers or
# add "('very' | '' | 'slightly') outdated"
# depending on (en.version - {LANG}.version)

If we rely on <version>, lead translators do not need to commit anything to
say "my translation is still up-to-date" because <version>'s match as long as
there is no content change.


It looks like Sven has started a very interesting thread!

BTW, any reason we have 2.x and 3.x versions of our handbook?
$ grep '<version>' h*-*xml
handbook-alpha.xml:<version>2.94</version>
handbook-amd64.xml:<version>3.2</version>
handbook-arm.xml:<version>2.97</version>
handbook-hppa.xml:<version>2.94</version>
handbook-mips.xml:<version>2.84</version>
handbook-ppc64.xml:<version>2.63</version>
handbook-ppc.xml:<version>3.4</version>
handbook-sparc.xml:<version>2.95</version>
handbook-x86.xml:<version>2.118</version>



Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\

On Mon, Oct 11, 2004 at 06:55:02PM +0200, Xavier Neys wrote:
> Sven Vermeulen wrote:
> >My first observation is that we have an abstract tag in each of our
> >documents (mandatory) that's only used for the upper right corner. It seems
> >to me that this abstract can very well be used as a description of the
> >document for our index page.

My idea of list.xml was to use a shorter description for each document
than the abstract.

Some time ago, I had started such a list manually,
http://dev.gentoo.org/~cam/cam_index.html (the layout is unintentionnaly
broken) where I wanted to re-organize documents and shorten their
description to consume less bandwidth. IMO, documents title are
sometimes just enough.

I agree with you on the easy-to-generate-with-abstract point.

> >And, to make things even worse, I'm thinking about extending the book.dtd
> >definition to have a <version> and <date> entity within the <sections>
> >entity (mandatory) so that each hb-* file has it's own version/date
> >information.

Good idea :p

> We need to be able to display "updated #{max(hb*xml.date)}" on handbook
> pages BTW.

We also can remove the date on pages that do not contain content? Or
should we have a "handbook version"? If yes, why?

> Let's say we have a list.xml with a list of documents and some metadata.
> We can use it to generate indexes, lists of documents...

When list.xml will be generated by Who?

> Let's say we can rely on the <version> and <link> elements.
> When a <guide|book> document is processed, use the following pseudo-code:
>
> If no /en/ in link attribute or lang attribute not 'en',
> # Doc is a translation
> Find original (replace /{LANG}/ with /en/)
> compare <version> elements of both docs
> if versions differ,
> issue warning
> # We may even display version numbers or
> # add "('very' | '' | 'slightly') outdated"
> # depending on (en.version - {LANG}.version)
>
> If we rely on <version>, lead translators do not need to commit anything to
> say "my translation is still up-to-date" because <version>'s match as long
> as there is no content change.

That sounds nice.
Why did you introduce this idea with list.xml?

> BTW, any reason we have 2.x and 3.x versions of our handbook?
> $ grep '<version>' h*-*xml
> handbook-alpha.xml:<version>2.94</version>
> handbook-amd64.xml:<version>3.2</version>
> handbook-arm.xml:<version>2.97</version>
> handbook-hppa.xml:<version>2.94</version>
> handbook-mips.xml:<version>2.84</version>
> handbook-ppc64.xml:<version>2.63</version>
> handbook-ppc.xml:<version>3.4</version>
> handbook-sparc.xml:<version>2.95</version>
> handbook-x86.xml:<version>2.118</version>

I guess some documents went to 3.00 after 2.99...
Now the 3.x version is started, I suggest to progressively switch every
2.x document to 3.0 to keep the consistency.

--
Camille Huot cam(@)gentoo.org
Gentoo Documentation Project http://dev.gentoo.org/~cam/

On Mon, Oct 11, 2004 at 06:55:02PM +0200, Xavier Neys wrote:
> BTW, any reason we have 2.x and 3.x versions of our handbook?
> $ grep '<version>' h*-*xml
> handbook-alpha.xml:<version>2.94</version>
> handbook-amd64.xml:<version>3.2</version>
> handbook-arm.xml:<version>2.97</version>
> handbook-hppa.xml:<version>2.94</version>
> handbook-mips.xml:<version>2.84</version>
> handbook-ppc64.xml:<version>2.63</version>
> handbook-ppc.xml:<version>3.4</version>
> handbook-sparc.xml:<version>2.95</version>
> handbook-x86.xml:<version>2.118</version>

Looks like SeJo found bug #65999 interesting enough to bump the document's
major version number. Or he probably found 2.99 -> 3.00 more logical than
2.99 -> 2.100 =)

Wkr,
Sven Vermeulen

--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>

Camille Huot wrote:
>>>And, to make things even worse, I'm thinking about extending the book.dtd
>>>definition to have a <version> and <date> entity within the <sections>
>>>entity (mandatory) so that each hb-* file has it's own version/date
>>>information.
>
> Good idea :p
>
>>We need to be able to display "updated #{max(hb*xml.date)}" on handbook
>>pages BTW.
>
> We also can remove the date on pages that do not contain content? Or
> should we have a "handbook version"? If yes, why?

Pages with no content?

Dates / Versions:

Glad you talk about handbook version.
<version>'s are not displayed and are meaningless to users. They should be
used only by us, docsdevs and translators. Having one <version> per file makes
sense to me and would be useful to keep track of translations and display the
outdated warning automatically.

We should display the version on the handbook in the title and the version
should be the release number like 2004.2. I still see users wondering why they
can't install 2004.0/1 even though they followed the docs. They could not know
about that.
I'll go one step further and suggest we save a copy of the 2004.2 handbook
just before we release 2004.3 so that users can find the right docs.
FYI, the latest (or the one before) issue of LinuxFormat has a Gentoo 2004.2
CD with it. We should expect users to try it for a few more weeks.
Please remember that a lambda users trying Gentoo will boot the CD and follow
the doc, if it does not work, *Gentoo* is bugged and binned, and we lose a user.

The date on the other hand is useful to users. Displaying different dates
across the handbook will be very confusing. We should display the latest.

>>Let's say we have a list.xml with a list of documents and some metadata.
>>We can use it to generate indexes, lists of documents...
>
> When list.xml will be generated by Who?

ASASC(*).
By docdevs, who else?

>>Let's say we can rely on the <version> and <link> elements.
>>When a <guide|book> document is processed, use the following pseudo-code:
>>
>>If no /en/ in link attribute or lang attribute not 'en',
>> # Doc is a translation
>> Find original (replace /{LANG}/ with /en/)
>> compare <version> elements of both docs
>> if versions differ,
>> issue warning
>> # We may even display version numbers or
>> # add "('very' | '' | 'slightly') outdated"
>> # depending on (en.version - {LANG}.version)
>>
>>If we rely on <version>, lead translators do not need to commit anything to
>>say "my translation is still up-to-date" because <version>'s match as long
>>as there is no content change.
>
> That sounds nice.
> Why did you introduce this idea with list.xml?

Because I was replying to Sven's mails. We can implement both ideas separately.
Without any language list, we can only rely on the lang attribute.
Maybe we need some kind of repodoc to check a few things automatically before
any doc is committed, e.g. have the link and lang attributes been properly
set, have the <date> and <version> elements been updated. It is not much but
it could help.

>>BTW, any reason we have 2.x and 3.x versions of our handbook?
>>$ grep '<version>' h*-*xml
>>handbook-alpha.xml:<version>2.94</version>
>>handbook-amd64.xml:<version>3.2</version>
>>handbook-arm.xml:<version>2.97</version>
>>handbook-hppa.xml:<version>2.94</version>
>>handbook-mips.xml:<version>2.84</version>
>>handbook-ppc64.xml:<version>2.63</version>
>>handbook-ppc.xml:<version>3.4</version>
>>handbook-sparc.xml:<version>2.95</version>
>>handbook-x86.xml:<version>2.118</version>
>
> I guess some documents went to 3.00 after 2.99...
> Now the 3.x version is started, I suggest to progressively switch every
> 2.x document to 3.0 to keep the consistency.

Then let's slap sejo with a fish and set things straight.
I can't find any reason to jump to 3.x, not now.
Maybe when Sven commits his draft. That is major enough IMHO.


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\

On Tue, Oct 12, 2004 at 04:25:56PM +0000, Camille Huot wrote:
> On Mon, Oct 11, 2004 at 06:55:02PM +0200, Xavier Neys wrote:
> > Sven Vermeulen wrote:
> > >My first observation is that we have an abstract tag in each of our
> > >documents (mandatory) that's only used for the upper right corner. It seems
> > >to me that this abstract can very well be used as a description of the
> > >document for our index page.
>
> My idea of list.xml was to use a shorter description for each document
> than the abstract.

Nono, you misread what I meant to say (*cough*). The index itself is one
with the (elaborate) abstraction for each document for those documents that
aren't put in a different overview document (such as the desktop
documentation currently within desktop.xml).

The list.xml won't contain the abstract information, only the title's of the
documents.

> We also can remove the date on pages that do not contain content? Or
> should we have a "handbook version"? If yes, why?

Yes, for when more chapters are added, information about the chapters is
changed or the sequence of chapters is altered.

> When list.xml will be generated by Who?

Automatically (XSL).

> Now the 3.x version is started, I suggest to progressively switch every
> 2.x document to 3.0 to keep the consistency.

The version isn't used publicly, so I wouldn't mind this, although it would
seem more logical to wait until f.i. my changed (currently in draft/) are
entered (unless ppl oppose the documents).

Wkr,
Sven Vermeulen


--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>

On Wed, Oct 13, 2004 at 11:04:25PM +0200, Xavier Neys wrote:
> We should display the version on the handbook in the title and the version
> should be the release number like 2004.2. I still see users wondering why
> they can't install 2004.0/1 even though they followed the docs. They could
> not know about that.
> I'll go one step further and suggest we save a copy of the 2004.2 handbook
> just before we release 2004.3 so that users can find the right docs.

Agreed 100%. The installation instructions are tightly coupled to the
installation media, so having point documentation releases for each release
releng makes is a normal occurrence.

If I may suggest something:

handbook/handbook-${ARCH}.xml is the source for the current handbook [1]
handbook/handbook-${ARCH}-${RELEASE}.xml is the source for the releases. It
also contains one for the current handbook (plain copy).

The files themselves can be stored everywhere (since they're referenced from the
file anyway). I would say

handbook/2004.2 - contains all the hb-install-* files for 2004.2
handbook/2004.3 - contains all the hb-install-* files for 2004.3 (when
2004.4 or 2005.0 is released)

[1] Or would we deprecate this one and inform ppl about the new location?

> The date on the other hand is useful to users. Displaying different dates
> across the handbook will be very confusing. We should display the latest.

I always use the following script to bump handbook-files:

---------------------------------------------------------
#!/bin/bash

source /sbin/functions.sh
TMPFILE=$(mktemp -p ~/tmp/)

for FILE in $*
do
# Change version
VERSIONLINE=$(grep '<version>' ${FILE})
VERSIONALT=$(echo $VERSIONLINE | sed -e 's/<[^<]*>//g')
VERSION=$(echo $VERSIONALT | awk -F '.' '{for (x = 1; x < NF; x++) {printf "%s.", $x} print $NF+1}')
einfo "$FILE:\tChanging from ${VERSIONALT} to ${VERSION}"
cat $FILE | grep '<version>' -B 9999 | grep -v '<version>' > $TMPFILE
echo "<version>${VERSION}</version>" >> $TMPFILE
cat $FILE | grep '<version>' -A 99999 | grep -v '<version>' >> $TMPFILE
mv $TMPFILE $FILE
# Change date
DATEL=$(grep '<date>' ${FILE} | sed -e 's/<[^<]*>//g')
NEWDAT=$(date +"%B %d, %Y")
einfo "$FILE:\tChanging from \"${DATEL}\" to \"${NEWDAT}\""
cat $FILE | grep '<date>' -B 9999 | grep -v '<date>' > $TMPFILE
echo "<date>${NEWDAT}</date>" >> $TMPFILE
cat $FILE | grep '<date>' -A 99999 | grep -v '<date>' >> $TMPFILE
mv $TMPFILE $FILE
done
---------------------------------------------------------

I call is "gtBumpVersion.sh" and use it like this:

$ gtBumpVersion handbook-*.xml

But I agree it's a bit cumbersome...

> >When list.xml will be generated by Who?
>
> ASASC(*).
> By docdevs, who else?

By apache? (XSL)... or do you mean the XML file with all the metadata in it?

> Then let's slap sejo with a fish and set things straight.

At least make it a medium-sized fish. I want to keep the ugly, big ones for
those that mess with Gentoo without informing the GDP :)

Wkr,
Sven Vermeulen

--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>

Sven Vermeulen wrote:
> On Wed, Oct 13, 2004 at 11:04:25PM +0200, Xavier Neys wrote:
>
>>We should display the version on the handbook in the title and the version
>>should be the release number like 2004.2. I still see users wondering why
>>they can't install 2004.0/1 even though they followed the docs. They could
>>not know about that.
>>I'll go one step further and suggest we save a copy of the 2004.2 handbook
>>just before we release 2004.3 so that users can find the right docs.
>
> Agreed 100%. The installation instructions are tightly coupled to the
> installation media, so having point documentation releases for each release
> releng makes is a normal occurrence.
>
> If I may suggest something:
>
> handbook/handbook-${ARCH}.xml is the source for the current handbook [1]
> handbook/handbook-${ARCH}-${RELEASE}.xml is the source for the releases. It
> also contains one for the current handbook (plain copy).
>
> The files themselves can be stored everywhere (since they're referenced from the
> file anyway). I would say
>
> handbook/2004.2 - contains all the hb-install-* files for 2004.2
> handbook/2004.3 - contains all the hb-install-* files for 2004.3 (when
> 2004.4 or 2005.0 is released)

I was thinking (for once) we could simply copy the files to handbook/200x.y/
and list previous versions in a new section of handbook/index.xml
This saves us from renaming files/links.
Translations that are up-to-date will be handled the same way.

>>The date on the other hand is useful to users. Displaying different dates
>>across the handbook will be very confusing. We should display the latest.
>
> I always use the following script to bump handbook-files:
> ---------------------------------------------------------
>>There was a script here<<
> ---------------------------------------------------------
> I call is "gtBumpVersion.sh" and use it like this:
> $ gtBumpVersion handbook-*.xml
> But I agree it's a bit cumbersome...

You'd need to be more creative to copy dates to translated versions ;-)
Of course we might use the same format like yyyy-mm-dd in all docs and format
them with some xsl magic ;-)

The more I think of it, the more I believe we're going to need a repodoc.

>>>When list.xml will be generated by Who?
>>
>>By docdevs, who else?
>
> By apache? (XSL)... or do you mean the XML file with all the metadata in it?

Indeed. There's been a misundertanding here. I thought list.xml would be the
metadata file, not the generated one.

>>Then let's slap sejo with a fish and set things straight.
>
> At least make it a medium-sized fish. I want to keep the ugly, big ones for
> those that mess with Gentoo without informing the GDP :)

Then use a catfish, they smell, they have spikes and believe me they hurt.
They come in all sizes up to some you could not even lift off the ground ;-)


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\

On Thu, Oct 14, 2004 at 12:45:20AM +0200, Xavier Neys wrote:
> I was thinking (for once) we could simply copy the files to
> handbook/200x.y/ and list previous versions in a new section of
> handbook/index.xml
> This saves us from renaming files/links.
> Translations that are up-to-date will be handled the same way.

All files? Well, I wouldn't really mind, but this means we're copying 2
(perhaps even 3 in the near future) parts of the Gentoo Handbook because of
one (the Installation Instructions) that needs to be snapshot'ed.

Another thing: do we take this snapshot when a new release is made, or when
we're almost confident that the installation instructions for that release
are valid?

The reason why I'm asking is because the installation instructions might
change in between releases. For instance, I recently added some subsections
for the updated system profiles (slocate, dhcpcd not being part of them
anymore). Although these specific updates don't harm regular installations
(as they're only visible for users that have changed their profile to a
cascading one) the changes might influence more users in the future.

> The more I think of it, the more I believe we're going to need a repodoc.

I'd rather keep away from a repodoc tool as long as possible. Imho, repodoc
is a hack created to fill in CVS's shortcomings - apart from things like
XML-Checker it doesn't give much flexibility and control over the committed
quality.

But trust me, you don't want to force 99% of the Gentoo devs to use aegis :)

> Indeed. There's been a misundertanding here. I thought list.xml would be
> the metadata file, not the generated one.

Ah, as they say in Italian: SCSI. Well, list.xml can be the metadata file
and still be chained to a couple of XSL files to provide an overview
document :)

> Then use a catfish, they smell, they have spikes and believe me they hurt.
> They come in all sizes up to some you could not even lift off the ground ;-)

Now THAT's what I mean!

Wkr,
Sven Vermeulen

--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>

Sven Vermeulen wrote:
> On Thu, Oct 14, 2004 at 12:45:20AM +0200, Xavier Neys wrote:
>
>>I was thinking (for once) we could simply copy the files to
>>handbook/200x.y/ and list previous versions in a new section of
>>handbook/index.xml
>>This saves us from renaming files/links.
>>Translations that are up-to-date will be handled the same way.
>
> All files? Well, I wouldn't really mind, but this means we're copying 2
> (perhaps even 3 in the near future) parts of the Gentoo Handbook because of
> one (the Installation Instructions) that needs to be snapshot'ed.

All files? Yes. Of course. Unless you can promise whenever a change is made to
a file that had not been copied makes it incompatible with the previous
release, the old version will be saved and links redone.

> Another thing: do we take this snapshot when a new release is made, or when
> we're almost confident that the installation instructions for that release
> are valid?

The ideal time would be when we know for sure the doc and the released media
match perfectly.

> The reason why I'm asking is because the installation instructions might
> change in between releases. For instance, I recently added some subsections
> for the updated system profiles (slocate, dhcpcd not being part of them
> anymore). Although these specific updates don't harm regular installations
> (as they're only visible for users that have changed their profile to a
> cascading one) the changes might influence more users in the future.

Good point. I find it annoying to see important changes between releases that
make the released media unusable with the current doc.
I suppose the best thing to do would be to create the snapshot as soon as the
doc becomes incompatible with the iso files.

>>The more I think of it, the more I believe we're going to need a repodoc.
>
> I'd rather keep away from a repodoc tool as long as possible. Imho, repodoc
> is a hack created to fill in CVS's shortcomings - apart from things like
> XML-Checker it doesn't give much flexibility and control over the committed
> quality.

Maybe I should not have used a name that sounds like repoman.
repodoc would not just fill in the shortcomings of CVS.
There are a few simple checks that can be done locally before hitting CVS:
* <version> and <date> have not been changed, are you sure you haven't forgotten?
* lang attribute does not match dir name or is missing from translation
* link attribute does not match dir/filename
* <version> in your translation is < original, are you sure?
* same with date if we can match English dates with translated ones
* <date> of handbook-ARCH.xml is not max(<date> from hb*(ARCH)*xml)

Some are warnings but should not be blocking. CVS precommit could not help.
What's wrong with a simple script that would check for simple mistakes we 've
all made once or twice?


Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\