1 |
Jan Kundrát wrote: |
2 |
> Hi GDP-related entities, |
3 |
> as promised on IRC, here are my ideas about $SUBJECT. |
4 |
> |
5 |
> Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained" |
6 |
> documents for one of these reasons: |
7 |
> |
8 |
> a) Third party article |
9 |
> b) Older Handbook |
10 |
> c) Translation in language which is not officially supported |
11 |
> d) Outdated translation |
12 |
|
13 |
Outdated translations are something different, but more about that later. |
14 |
|
15 |
Adding a disclaimer at the beginning of a doc is a good idea IMO. |
16 |
|
17 |
To clear a few points: |
18 |
Adding a disclaimer is not about about making a doc unofficial. |
19 |
Everything that we publish is official, or has been so at least. |
20 |
If we want to make a doc officially unofficial, we remove it. |
21 |
|
22 |
Of course, users reading a 2004.3 handbook should realise it's old, but they |
23 |
could at least be told it's not maintained anymore so that 1) they can read it |
24 |
with a grain of salt 2) they should not bother submitting bugs. |
25 |
|
26 |
Dumping the text in the doc itself is not a great idea as it will lead to |
27 |
cut'n'paste errors and lose consistency. Besides, scripts could not distinguish |
28 |
normal content from such disclaimers. |
29 |
|
30 |
Another way would have been to list the outdated/unmaintained docs in an |
31 |
external file, or add attributes to metadoc. IMO, this adds some unnecessary |
32 |
complexity. |
33 |
|
34 |
I much prefer something along Flammie's idea, a new tag. This way, we just need |
35 |
to add the tag to the relevant doc and forget about it. |
36 |
|
37 |
As we already see the need for different disclaimers, I suggest using a |
38 |
<disclaimer> tag with a type attribute. The relevant text is fished from our |
39 |
inserts.xml files and I suggest displaying it right at the top of the content |
40 |
area. It needs to be either before, after or on the side, but I'd rather not |
41 |
insert it randomly in the text. |
42 |
|
43 |
I have implemented a proposal with the following disclaimers: |
44 |
"articles" for republished articles |
45 |
"oldbook" self-explanatory |
46 |
"obsolete" idem |
47 |
Disclaimers can also auto-redirect users, very useful for obsolete docs. |
48 |
|
49 |
Samples: |
50 |
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml |
51 |
http://gentoo.neysx.org/mystuff/l-sed2.xml |
52 |
http://gentoo.neysx.org/mystuff/l-sed1.xml |
53 |
http://gentoo.neysx.org/mystuff/oldbook.xml |
54 |
|
55 |
|
56 |
Now about outdated translations: |
57 |
It's possible to use metadoc to check the corresponding original and display a |
58 |
note about a more recent original. |
59 |
I've implemented the following: |
60 |
If a translation is not listed in its local metadoc, warn users translation is |
61 |
not maintained. |
62 |
If a translation is listed in its local metadoc, but not in the parent one (ie. |
63 |
the English one), warn users original doc is not maintained anymore. |
64 |
If file appears both in local and English metadocs, compare their dates and warn |
65 |
users that a more recent original exists with a link to it. |
66 |
|
67 |
Notes: |
68 |
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will do |
69 |
for currently unsupported languages. |
70 |
1) We have to use metadoc and *may not* test the corresponding file (ie. |
71 |
s:/pl/:/en/:) as that would force us to keep files we want to remove in /doc/en/ |
72 |
until all translated versions have disappeared. |
73 |
2) We need to use the dates and not the versions because using the versions |
74 |
would force us to compare handbooks file by file. |
75 |
3) Reminder: the date of a handbook is the max_date(master, all parts) |
76 |
4) Some of you need to stop bumping dates needlessly |
77 |
5) link attributes must contain the full path, no more <book |
78 |
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o) |
79 |
|
80 |
At the moment, it is limited to /doc as dates are not reliable outside of /doc |
81 |
anyway (not yyyy-mm-dd formatted or not bumped properly). |
82 |
|
83 |
Samples: |
84 |
http://gentoo.neysx.org/doc/fr/handbook/2005.1/ |
85 |
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml |
86 |
|
87 |
FYI, an inserts would like like |
88 |
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1 |
89 |
|
90 |
Please comment. |
91 |
|
92 |
|
93 |
Cheers, |
94 |
-- |
95 |
/ Xavier Neys |
96 |
\_ Gentoo Documentation Project |
97 |
/ French & Internationalisation Lead |
98 |
\ http://www.gentoo.org/doc/en |
99 |
/\ |
100 |
|
101 |
|
102 |
-- |
103 |
gentoo-doc@g.o mailing list |