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