Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-doc
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-doc@g.o
From: Jan Kundrát <jkt@g.o>
Subject: Re: Re: [RFC] Marking unmaintained documents
Date: Fri, 16 Sep 2005 15:01:04 +0200
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.

Yep.

> 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
Attachment:
signature.asc (OpenPGP digital signature)
Replies:
Re: Re: [RFC] Marking unmaintained documents
-- Sven Vermeulen
References:
[RFC] Marking unmaintained documents
-- Jan Kundrát
Re: [RFC] Marking unmaintained documents
-- Xavier Neys
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: [RFC] Marking unmaintained documents
Next by thread:
Re: Re: [RFC] Marking unmaintained documents
Previous by date:
Re: [RFC] Marking unmaintained documents
Next by date:
Re: [RFC] Marking unmaintained documents


Updated Jun 17, 2009

Summary: Archive of the gentoo-doc mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.