From: Xavier Neys <neysx@gentoo.org>
To: gentoo-doc@lists.gentoo.org
Subject: [gentoo-doc] Re: [RFC] Marking unmaintained documents
Date: Thu, 15 Sep 2005 11:55:58 +0000 (UTC) [thread overview]
Message-ID: <loom.20050915T135454-193@post.gmane.org> (raw)
In-Reply-To: 43206D3A.5030406@gentoo.org
Jan Kundrát wrote:
> Hi GDP-related entities,
> as promised on IRC, here are my ideas about $SUBJECT.
>
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
> documents for one of these reasons:
>
> a) Third party article
> b) Older Handbook
> c) Translation in language which is not officially supported
> d) Outdated translation
Outdated translations are something different, but more about that later.
Adding a disclaimer at the beginning of a doc is a good idea IMO.
To clear a few points:
Adding a disclaimer is not about about making a doc unofficial.
Everything that we publish is official, or has been so at least.
If we want to make a doc officially unofficial, we remove it.
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.
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.
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.
I have implemented a proposal with the following disclaimers:
"articles" for republished articles
"oldbook" self-explanatory
"obsolete" idem
Disclaimers can also auto-redirect users, very useful for obsolete docs.
Samples:
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
http://gentoo.neysx.org/mystuff/l-sed2.xml
http://gentoo.neysx.org/mystuff/l-sed1.xml
http://gentoo.neysx.org/mystuff/oldbook.xml
Now about outdated translations:
It's possible to use metadoc to check the corresponding original and display a
note about a more recent original.
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.
Notes:
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will do
for currently unsupported languages.
1) We have to use metadoc and *may not* test the corresponding file (ie.
s:/pl/:/en/:) as that would force us to keep files we want to remove in /doc/en/
until all translated versions have disappeared.
2) We need to use the dates and not the versions because using the versions
would force us to compare handbooks file by file.
3) Reminder: the date of a handbook is the max_date(master, all parts)
4) Some of you need to stop bumping dates needlessly
5) link attributes must contain the full path, no more <book
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)
At the moment, it is limited to /doc as dates are not reliable outside of /doc
anyway (not yyyy-mm-dd formatted or not bumped properly).
Samples:
http://gentoo.neysx.org/doc/fr/handbook/2005.1/
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml
FYI, an inserts would like like
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1
Please comment.
Cheers,
--
/ Xavier Neys
\_ Gentoo Documentation Project
/ French & Internationalisation Lead
\ http://www.gentoo.org/doc/en
/\
--
gentoo-doc@gentoo.org mailing list
next prev parent reply other threads:[~2005-09-15 12:12 UTC|newest]
Thread overview: 43+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-09-08 16:56 [gentoo-doc] [RFC] Marking unmaintained documents Jan Kundrát
2005-09-08 17:07 ` Xavier Neys
2005-09-08 17:36 ` Jan Kundrát
2005-09-08 17:54 ` Xavier Neys
2005-09-08 18:12 ` Jan Kundrát
2005-09-08 19:04 ` Shyam Mani
2005-09-09 17:00 ` Sven Vermeulen
2005-09-09 16:57 ` Sven Vermeulen
2005-09-10 13:10 ` Jan Kundrát
2005-09-10 18:22 ` Sven Vermeulen
2005-09-10 20:26 ` Jan Kundrát
2005-09-14 16:55 ` Sven Vermeulen
2005-09-14 18:20 ` Jan Kundrát
2005-09-08 21:00 ` Alexey Chumakov
2005-09-08 21:10 ` Jan Kundrát
2005-09-08 21:11 ` Łukasz Damentko
2005-09-09 1:13 ` Flammie Pirinen
2005-09-09 6:50 ` Alexey Chumakov
2005-09-09 13:10 ` Jan Kundrát
2005-09-09 13:08 ` Jan Kundrát
2005-09-09 15:49 ` Flammie Pirinen
2005-09-09 16:26 ` Łukasz Damentko
2005-09-10 13:11 ` Jan Kundrát
2005-09-09 16:50 ` Sven Vermeulen
2005-09-10 12:35 ` Jan Kundrát
2005-09-15 11:51 ` Xavier Neys
2005-09-15 11:55 ` Xavier Neys [this message]
2005-09-16 13:01 ` [gentoo-doc] " Jan Kundrát
2005-09-17 12:06 ` Sven Vermeulen
2005-09-19 7:51 ` Alexey Chumakov
2005-09-16 9:01 ` [gentoo-doc] " Xavier Neys
2005-09-16 13:07 ` Jan Kundrát
2005-09-16 15:24 ` Xavier Neys
2005-09-16 18:51 ` Jan Kundrát
2005-09-29 15:41 ` Xavier Neys
1980-01-03 20:09 ` Alexey Chumakov
2005-09-29 16:49 ` Jose Luis Rivero
2005-09-29 22:57 ` Łukasz Damentko
2005-09-30 7:20 ` Shyam Mani
2005-09-30 8:59 ` Flammie Pirinen
2005-09-30 16:29 ` Sven Vermeulen
2005-10-02 13:11 ` Jan Kundrát
2005-10-09 10:21 ` Xavier Neys
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=loom.20050915T135454-193@post.gmane.org \
--to=neysx@gentoo.org \
--cc=gentoo-doc@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox