Gentoo Archives: gentoo-doc

From: "Jan Kundrát" <jkt@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Re: [RFC] Marking unmaintained documents
Date: Fri, 16 Sep 2005 13:01:50
In Reply to: [gentoo-doc] Re: [RFC] Marking unmaintained documents by Xavier Neys
Xavier Neys wrote:
> Of course, users reading a 2004.3 handbook should realise it's old, but they > could at least be told it's not maintained anymore so that 1) they can read it > with a grain of salt 2) they should not bother submitting bugs.
IMHO that's against what SwifT said about fixing?
> Dumping the text in the doc itself is not a great idea as it will lead to > cut'n'paste errors and lose consistency. Besides, scripts could not distinguish > normal content from such disclaimers.
> Another way would have been to list the outdated/unmaintained docs in an > external file, or add attributes to metadoc. IMO, this adds some unnecessary > complexity.
External file would look mroe elegant to me, but that's just me.
> I much prefer something along Flammie's idea, a new tag. This way, we just need > to add the tag to the relevant doc and forget about it. > > As we already see the need for different disclaimers, I suggest using a > <disclaimer> tag with a type attribute. The relevant text is fished from our > inserts.xml files and I suggest displaying it right at the top of the content > area. It needs to be either before, after or on the side, but I'd rather not > insert it randomly in the text.
Seems great.
> Now about outdated translations: > It's possible to use metadoc to check the corresponding original and display a > note about a more recent original.
That would be great.
> I've implemented the following: > If a translation is not listed in its local metadoc, warn users translation is > not maintained. > If a translation is listed in its local metadoc, but not in the parent one (ie. > the English one), warn users original doc is not maintained anymore. > If file appears both in local and English metadocs, compare their dates and warn > users that a more recent original exists with a link to it.
Well, as I said on IRC, I'd prefer checking <version>, but <date> is also better than nothing, yep (code which would check <version>s of HB files is not available). Cheers, -jkt -- cd /local/pub && more beer > /dev/mouth


File name MIME type
signature.asc application/pgp-signature


Subject Author
Re: [gentoo-doc] Re: [RFC] Marking unmaintained documents Sven Vermeulen <swift@g.o>