/[gentoo]/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml
Gentoo

Contents of /xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (show annotations) (download) (as text)
Sun Sep 4 14:58:00 2011 UTC (3 years ago) by swift
Branch: MAIN
Changes since 1.6: +39 -34 lines
File MIME type: application/xml
Bug #380403 - Update metadoc information with correct entity/attribute information. Thanks to Chema "nimiux" Alonso for patch.

1 <?xml version='1.0' encoding='UTF-8'?>
2
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml,v 1.6 2011/08/23 14:35:58 swift Exp $ -->
4
5 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6
7 <guide link="metadoc-guide.xml">
8 <title>Gentoo Metadoc XML Guide</title>
9
10 <author title="Author">
11 <mail link="swift"/>
12 </author>
13 <author title="Editor">
14 <mail link="neysx@gentoo.org">Xavier Neys</mail>
15 </author>
16 <author title="Editor">
17 <mail link="nimiux"/>
18 </author>
19
20 <abstract>
21 This guide informs developers how to use the Metadoc XML format that allows the
22 Gentoo Documentation Project to keep its documentation in a hierarchical manner
23 and allow more information to be stored about each document.
24 </abstract>
25
26 <!-- The content of this document is licensed under the CC-BY-SA license -->
27 <!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
28 <license/>
29
30 <version>3</version>
31 <date>2011-09-04</date>
32
33 <chapter>
34 <title>Introduction</title>
35 <section>
36 <title>Why is MetadocXML Needed?</title>
37 <body>
38
39 <p>
40 MetadocXML is not needed, it's an additional resource for the Gentoo
41 Documentation Project to keep track of documents, even if they are located
42 outside of the normal <path>[gentoo]/xml/htdocs/doc</path> scope.
43 </p>
44
45 <p>
46 Thanks to MetadocXML, we can now
47 </p>
48
49 <ul>
50 <li>
51 track documents that are located inside project webspaces
52 (<path>/proj</path>) instead of the usual documentation repository
53 (<path>/doc</path>)
54 </li>
55 <li>
56 categorize documentation into various categories (or subcategories) with the
57 additional benefit that we can now automatically generate the documentation
58 index (and more)
59 </li>
60 <li>
61 track unofficial documentation team members (such as translators)
62 </li>
63 <li>
64 use parts of big documents (Handbooks) as individual guides on certain
65 topics
66 </li>
67 <li>
68 assign bugs to particular documents for quick reference and with the
69 possibility of masking out a document in case of a major showstopping bug
70 </li>
71 <li>
72 primitively check if a translated file is in sync with its English
73 counterpart or not
74 </li>
75 </ul>
76
77 <p>
78 Note that the last advantage is primitive and will probably not be extended.
79 Some translation teams use scripts based on <c>trads-doc</c> to manage
80 translations, others use online translation management tools. If you are
81 starting up translations for Gentoo, pop by on <c>#gentoo-doc</c> or ask the
82 <c>gentoo-doc@gentoo.org</c> mailinglist for help.
83 </p>
84
85 <p>
86 Translation teams that do not use MetadocXML yet don't need to worry - they will
87 not lose any current functionality as it only builds upon the existing
88 infrastructure - there are no changes to the GuideXML format that need
89 MetadocXML.
90 </p>
91
92 </body>
93 </section>
94 <section>
95 <title>How does MetadocXML Work?</title>
96 <body>
97
98 <p>
99 There is one central file in which all meta information on the documentation is
100 maintained. We call this file <path>metadoc.xml</path>. This file should be
101 located inside your main repository (<path>/doc/${LANGUAGE}</path>) although
102 this is not hard-coded.
103 </p>
104
105 <p>
106 Inside this file, all meta information is stored:
107 </p>
108
109 <ul>
110 <li>Members of the team</li>
111 <li>Categories in which documents participate</li>
112 <li>Files that are covered</li>
113 <li>Documents that are covered</li>
114 <li>Bugs that are part of a document</li>
115 </ul>
116
117 <p>
118 Next to <path>metadoc.xml</path>, one also can have a dynamically generated index
119 file (usually called <path>index.xml</path>), an overview listing of all
120 documentation (usually called <path>list.xml</path>) and an overview listing of
121 all members, files and bugs (usually called <path>overview.xml</path>).
122 </p>
123
124 </body>
125 </section>
126 </chapter>
127
128 <chapter>
129 <title>The metadoc.xml File</title>
130 <section>
131 <title>XML Structure</title>
132 <body>
133
134 <p>
135 The <path>metadoc.xml</path> file is started with the usual XML initialisation
136 code and Gentoo CVS header information:
137 </p>
138
139 <pre caption="XML Initialisation">
140 &lt;?xml version='1.0' encoding="UTF-8"?&gt;
141 &lt;!-- &#36;Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.25 2004/12/23 09:51:30 swift Exp &#36; --&gt;
142 &lt;!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd"&gt;
143 </pre>
144
145 <p>
146 Then, one starts with the MetadocXML declaration.
147 </p>
148
149 <pre caption="English MetadocXML declaration">
150 &lt;metadoc lang="<comment>en</comment>"&gt;
151 </pre>
152
153 <p>
154 Translators should reference the main <path>/doc/en/metadoc.xml</path> in the
155 <c>parent</c> attribute. This lets metadoc identify untranslated files and find
156 out whether versions of translated versions and originals still match.
157 </p>
158
159 <pre caption="Translated MetadocXML declaration">
160 &lt;metadoc lang="<comment>language code</comment>" parent="/doc/en/metadoc.xml"&gt;
161 </pre>
162
163 <p>
164 Beneath the <c>metadoc</c> entity, the following entities should be declared (in
165 the given order):
166 </p>
167
168 <ul>
169 <li>
170 <c>version</c> to help keep track of changes
171 </li>
172 <li>
173 <c>members</c> which declares all members of the given language team
174 </li>
175 <li>
176 <c>categories</c> which declares the possible categories used
177 </li>
178 <li>
179 <c>files</c> which contains all files covered by the Metadoc file
180 </li>
181 <li>
182 <c>docs</c> which contains all documents covered by the Metadoc file
183 </li>
184 </ul>
185
186 </body>
187 </section>
188 <section>
189 <title>The Version Entity</title>
190 <body>
191
192 <p>
193 The version number should be increased when a document or a file is added or
194 removed, when a path is changed or on any update that might have an impact on
195 translated versions.
196 </p>
197
198 </body>
199 </section>
200 <section>
201 <title>The Members Entity</title>
202 <body>
203
204 <p>
205 Inside the members entity, one can declare two 'types' of members: <c>lead</c>
206 and <c>member</c>. A <c>lead</c> should be known by the Gentoo Developers
207 Relations as it takes only the nickname of the Lead developer and looks it up in
208 the Gentoo Memberlist. A <c>member</c> can either be a Gentoo Developer (in
209 which case only a nickname is given) or a contributor.
210 </p>
211
212 <p>
213 In case of a contributor, a <c>member</c> tag is given two attributes,
214 <c>mail</c> and <c>fullname</c>, containing the contributor's e-mail address and
215 full name.
216 </p>
217
218 <pre caption="Example use of the members entity">
219 &lt;members&gt;
220 &lt;lead&gt;swift&lt;/lead&gt;
221 &lt;lead&gt;neysx&lt;/lead&gt;
222 &lt;member&gt;dertobi123&lt;/member&gt;
223 &lt;member mail="gentoo_contributor@gmail.com" fullname="John Doe"&gt;jdoe&lt;/member&gt;
224 &lt;/members&gt;
225 </pre>
226
227 </body>
228 </section>
229 <section>
230 <title>The Categories Entity</title>
231 <body>
232
233 <p>
234 Inside the <c>categories</c> entity one only declares <c>cat</c> entities. Each
235 <c>cat</c> entity covers one Category. It uses one mandatory parameter <c>id</c>
236 which is used to reference the category. You can also define a parameter
237 <c>parent</c> in case the category is a child of another category.
238 </p>
239
240 <p>
241 In this case, the <c>parent</c> attribute references the <c>id</c> attribute of
242 the parent category.
243 </p>
244
245 <pre caption="Example use of the categories entity">
246 &lt;categories&gt;
247 &lt;cat id="faq"&gt;Frequently Asked Questions&lt;/cat&gt;
248 &lt;cat id="install"&gt;Installation Related Resources&lt;/cat&gt;
249 &lt;cat id="install_guides"&gt;Installation Guides&lt;/cat&gt;
250 &lt;/categories&gt;
251 </pre>
252
253 </body>
254 </section>
255 <section>
256 <title>The Files Entity</title>
257 <body>
258
259 <p>
260 The <c>files</c> entity contains only <c>file</c> entities.
261 </p>
262
263 <p>
264 Each <c>file</c> entity references a single XML file. It has a mandatory
265 <c>id</c> attribute which should be seen as a primary key to lookup the file.
266 Metadoc will compare the file name defined with the same <c>id</c> attribute in
267 the metadoc's parent file (defined in the root element) to find out whether the
268 file is a translation or an untranslated file. File names would be identical in
269 the latter case.
270 </p>
271
272 <p>
273 The metadoc file itself can be listed and will appear on the overview page.
274 </p>
275
276 <pre caption="Files entity examples">
277 &lt;files&gt;
278 &lt;file id="metadoc"&gt;/doc/en/metadoc.xml&lt;/file&gt;
279 &lt;file id="ati-faq"&gt;/doc/en/ati-faq.xml&lt;/file&gt;
280 &lt;/files&gt;
281 </pre>
282
283 </body>
284 </section>
285 <section>
286 <title>The Docs Entity</title>
287 <body>
288
289 <p>
290 The <c>docs</c> entity should only contain <c>doc</c> entities.
291 </p>
292
293 <p>
294 Each <c>doc</c> entity has a mandatory <c>fileid</c> attribute, which refers to
295 the <c>id</c> attribute of a <c>file</c> entity corresponding with the main file
296 for the document.
297 </p>
298
299 <p>
300 In case of a handbook chapter, the <c>doc</c> entity must contain a
301 <c>bookref</c> entity which references the main handbook page (the top handbook
302 XML file). This entity then contains two attributes, called <c>vpart</c> and
303 <c>vchap</c> which refer to the corresponding part and chapter of the document
304 inside the handbook.
305 </p>
306
307 <p>
308 Inside the <c>doc</c> entity, two other entities are possible:
309 </p>
310
311 <ul>
312 <li>
313 One or more <c>memberof</c> entities, referring to the category or
314 categories in which the document is located (note that a document can be in
315 several categories at once)
316 </li>
317 <li>
318 One <c>bugs</c> entity containing one or more <c>bug</c> entities. A
319 <c>bug</c> entity refers to a bugnumber that covers a bug in the document.
320 In case of a major bug, one can add the attribute <c>stopper="yes"</c> to
321 the <c>bug</c> entity in order for the document not to appear on the
322 generated index page.
323 </li>
324 </ul>
325
326 <pre caption="Example Docs entity">
327 <![CDATA[<docs>
328 <doc fileid="ldap-howto">
329 <memberof>sysadmin_specific</memberof>
330 <bugs>
331 <bug>102481</bug>
332 <bug stopper="yes">1151330</bug>
333 </bugs>
334 </doc>
335 <doc fileid="uml">
336 <memberof>sysadmin_general</memberof>
337 </doc>
338 </docs>]]>
339 </pre>
340
341 </body>
342 </section>
343 <section>
344 <title>Example metadoc.xml file</title>
345 <body>
346
347 <p>
348 The Gentoo site uses a <path>metadoc.xml</path> file to aggregate information of
349 all its documentation. You can view the current version one <uri
350 link="/doc/en/metadoc.xml?passthru=1">online</uri>.
351 </p>
352
353 </body>
354 </section>
355 </chapter>
356
357 <chapter>
358 <title>The Additional MetadocXML Files</title>
359 <section>
360 <title>Automatically Generated Index</title>
361 <body>
362
363 <p>
364 When you want an automatically generated index, you should start the document
365 with the following code:
366 </p>
367
368 <pre caption="Dynamically Generated Index">
369 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
370 &lt;?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?&gt;
371 &lt;?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?&gt;
372
373 &lt;!-- &#36;Header&#36; --&gt;
374
375 &lt;!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd"&gt;
376
377 <comment>&lt;!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --&gt;</comment>
378 &lt;dynamic metadoc="<i>/doc/en/metadoc.xml</i>"&gt;
379 &lt;title&gt;<i>Gentoo Documentation Resources</i>&lt;/title&gt;
380 &lt;intro&gt;
381
382 <comment>(...)</comment>
383
384 &lt;/intro&gt;
385
386 &lt;catid&gt;<i>faq</i>&lt;/catid&gt;
387 &lt;catid&gt;<i>install</i>&lt;/catid&gt;
388
389 &lt;/dynamic&gt;
390 </pre>
391
392 <p>
393 In between the <c>intro</c> tags you should write one or more sections which
394 will always appear on the top of the page. You will probably want to write an
395 introduction and some additional information for the reader to know who to
396 contact in case of translation mishaps or other issues.
397 </p>
398
399 <p>
400 Inside the <c>intro</c> tags you can use plain GuideXML starting from
401 <c>section</c>.
402 </p>
403
404 <p>
405 The <c>catid</c> tags refer to the main categories used by the dynamical index.
406 You should list each possible non-child category that is declared in your
407 metadoc file. <e>Do not list</e> categories that are children of another
408 category.
409 </p>
410
411 </body>
412 </section>
413 <section>
414 <title>Dynamically Generated List Document</title>
415 <body>
416
417 <p>
418 A dynamically generated list document starts identically to a dynamically
419 generated index file:
420 </p>
421
422 <pre caption="Dynamically generated list document">
423 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
424 &lt;?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?&gt;
425 &lt;?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?&gt;
426
427 &lt;!-- &#36;Header&#36; --&gt;
428
429 &lt;!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd"&gt;
430
431 <comment>&lt;!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --&gt;</comment>
432 &lt;dynamic metadoc="<i>/doc/en/metadoc.xml</i>"&gt;
433 &lt;title&gt;<i>Gentoo Documentation Listing</i>&lt;/title&gt;
434 </pre>
435
436 <p>
437 However, there is no <c>intro</c> tag. What needs to be added are all the top
438 categories used by the listing. To differentiate this from the index (which will
439 also display the abstract information on each document) this happens between
440 <c>list</c> tags inside <c>listing</c>:
441 </p>
442
443 <pre caption="Listing of categories">
444 &lt;listing&gt;
445 &lt;list&gt;faq&lt;/list&gt;
446 &lt;list&gt;install&lt;/list&gt;
447 &lt;/listing&gt;
448 </pre>
449
450 </body>
451 </section>
452 <section>
453 <title>Dynamically Generated Overview Document</title>
454 <body>
455
456 <p>
457 The overview document is started similarly as the two documents decribed above:
458 </p>
459
460 <pre caption="Dynamically generated overview document">
461 &lt;?xml version='1.0' encoding='UTF-8'?&gt;
462 &lt;?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?&gt;
463 &lt;?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?&gt;
464
465 &lt;!-- &#36;Header&#36; --&gt;
466
467 &lt;!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd"&gt;
468
469 <comment>&lt;!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --&gt;</comment>
470 &lt;dynamic metadoc="<i>/doc/en/metadoc.xml</i>"&gt;
471 &lt;title&gt;<i>Documentation Development Overview</i>&lt;/title&gt;
472 </pre>
473
474 <p>
475 You can again write up a small introduction in GuideXML between the <c>intro</c>
476 XML tags, starting from a <c>section</c> up. Once that is finished, a single tag
477 <c>&lt;overview/&gt;</c> is sufficient.
478 </p>
479
480 <pre caption="Intro and overview tags">
481 &lt;intro&gt;
482 <comment>(...)</comment>
483 &lt;/intro&gt;
484
485 &lt;overview/&gt;
486 </pre>
487
488 </body>
489 </section>
490 </chapter>
491
492 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20