/[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.3 - (show annotations) (download) (as text)
Mon Apr 4 10:19:34 2005 UTC (9 years, 6 months ago) by neysx
Branch: MAIN
Changes since 1.2: +26 -6 lines
File MIME type: application/xml
Metadoc now has a version element

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

  ViewVC Help
Powered by ViewVC 1.1.20