1 |
Hi all |
2 |
|
3 |
Xavier kindly pointed me to a problem I'm now facing with the documentation |
4 |
metadata that allows us to dynamically generate a documentation index. |
5 |
|
6 |
Let me first restate why a dynamical documentation index is preferred imho: |
7 |
- Ease of maintenance |
8 |
- Hierarchical separation |
9 |
- Removing duplicate documentation summary |
10 |
|
11 |
A draft on the dynamical index can be found online at |
12 |
http://www.gentoo.org/doc/en/index-dyn.xml |
13 |
|
14 |
Using the metadoc, we can easily create a page that lists all Gentoo |
15 |
documentation on a single page, without the additional summaries. |
16 |
|
17 |
A draft on this can be found online at |
18 |
http://www.gentoo.org/doc/en/list-dyn.xml |
19 |
|
20 |
A final feature is creating an overview for translations in which they can |
21 |
see the translated files, their version, and the version of the master |
22 |
English file. |
23 |
|
24 |
A draft on this can be found online at |
25 |
http://wren.gentoo.org/doc/nl/overview-dyn.xml |
26 |
|
27 |
Regarding the "Members" and "Bugs" chapters, a better example is the English |
28 |
overview page, http://www.gentoo.org/doc/en/overview-dyn.xml |
29 |
|
30 |
Now on to the issue: the XSLT code we use sources the linked documents to |
31 |
get their version, summary, title, etc. As long as all documents exist, this |
32 |
isn't a problem. However, when a document is removed from CVS, sourcing the |
33 |
inexisting document yields a "Internal Server 500" error which just doesn't |
34 |
look nice. |
35 |
|
36 |
When dealing with /doc/${LANG} documents, this isn't such a major issue |
37 |
because we control our repository ourselves. Iow, when I would remove |
38 |
alsa-guide.xml from the repository I should know that I have to remove the |
39 |
file from the metadoc as well. |
40 |
|
41 |
However, when dealing with project-specific documentation (such as the |
42 |
Hardened Docs), the responsibility of the document itself is in hands of the |
43 |
project documentation developer, not ours. This also means that "they" will |
44 |
undoubtedly (re)move their documents without prior notice to the |
45 |
documentation team. Each such action will lead to a "Internal Server 500" |
46 |
error. |
47 |
|
48 |
Their are a few solutions to this: |
49 |
|
50 |
We can ignore the issue and "wait" for the projects to (re)move their |
51 |
documents and hearing from our users that the index page doesn't work |
52 |
anymore. This sounds like a no-go, yet not all indexes would fail, only |
53 |
those that explicitly would list the document (index-dyn.xml originally |
54 |
doesn't list any documents, you need to select a category). Imho, it's still |
55 |
a no-go though. |
56 |
|
57 |
We can ask the projects that we would like to list their docs on our |
58 |
documentation index page as well, but that this would mean that they can't |
59 |
(shouldn't) (re)move those documents without atomically updating the |
60 |
metadoc.xml file. This might work, but requires continuous awareness. |
61 |
|
62 |
We can implement any QA-tool on client-side ("repodoc") and keep asking all |
63 |
developers to use repodoc to operate on xml files. Since they're usually |
64 |
used to working with repoman, I don't think too much objections will be |
65 |
stated. |
66 |
|
67 |
We can implement a QA-tool on server-side (extend the current XML-Checker) |
68 |
that verifies if the removal of a file can happen (see if the file is listed |
69 |
in the English metadoc.xml) and, if not, issue an error. |
70 |
|
71 |
We can request the used xml parsers on our webnodes to return an empty |
72 |
node-set instead of generating an error and update our XSLT to verify if the |
73 |
returned node-set is empty. If it is, ignore the document. We can then |
74 |
create a new chapter in the overview-dyn.xml document that lists all |
75 |
non-existing documents. |
76 |
|
77 |
This latter solution is possible with Xavier's gorg application but has the |
78 |
drawback that any other issues with missing xml files (for instance, |
79 |
checking a handbook that lacks some files) will need to be covered in the |
80 |
XSLT as well. The advantage is however that a nicer error can be shown to |
81 |
the user that has a bit more information. |
82 |
|
83 |
Thoughts, ideas? |
84 |
|
85 |
Wkr, |
86 |
Sven Vermeulen |
87 |
|
88 |
|
89 |
-- |
90 |
Documentation & PR project leader |
91 |
|
92 |
The Gentoo Project <<< http://www.gentoo.org >>> |