Gentoo Archives: gentoo-doc

From: Xavier Neys <neysx@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] [RFC] Marking unmaintained documents
Date: Sun, 09 Oct 2005 10:21:52
In Reply to: Re: [gentoo-doc] [RFC] Marking unmaintained documents by Sven Vermeulen
Sven Vermeulen wrote:
> On Thu, Sep 29, 2005 at 05:41:06PM +0200, Xavier Neys wrote: > >>Disclaimer & redirect >> (*) Yea () Nay >> >>Note about more recent English version >> (*) Yea () Nay > > I do have ears for flammie's points, but I think "timed redirects" are well > supported and used often enough. And they're part of the standard as well :)
A/ redirect My ears heard Flammie as well :) Delayed redirects are supported and do not even break the back button anymore in recent browsers. Anyway, the redirect attribute is a structured way of saying 'This is doc has been replaced by that doc'. It is *not* a way of turning docs into a slide show or make the handbook jump from one chapter to the next. Now, if users complain about those delayed redirects, we can do several things: 1) if the doc still receives many hits, we can ask infra to add rewrite/redirect in the web server config 2) if we had to keep some content in the doc, it's trivial to add a test and omit the delayed redirect on docs that contain more than an arbitrary number of elements, e.g. more than 1 <section> and 1 <p> 3) we can drop the delayed redirect if it proves really troublesome to our users I do not expect many hits on those outdated files and the delayed redirect is probably the best we can do on www.g.o, but it is not the only way: The redirect attribute is only available in <guide> and should contain the new uri. B/ Disclaimer A disclaimer attribute can be used on <book> and <guide> tags. Its value can be one of (articles|oldbook|draft|obsolete). Inserted text comes from inserts-en.xml and is displayed at the top of the content area. Sample at C/ Note about outdated translations A note will be displayed under the date when a translation is either not maintained or outdated. This works only if 1) the link attribute has the full path to the doc, not just the file name 2) it starts with /doc/XX/, XX != en The original to compare to is found using /doc/XX/metadoc.xml which is why metadoc has become a requirement for translations. Sample: D/ Note about the date and inserts-XX.xml It has been tricky for some languages to translate 'Updated' to make it work by just appending the date. As translating 'The original version of this document was last updated '+$DATE might prove even more difficult, I have added the <docdate/> placeholder in inserts. /me needs to update xml-guide.xml Cheers, -- / Xavier Neys \_ Gentoo Documentation Project / French & Internationalisation Lead \ /\ -- gentoo-doc@g.o mailing list