/[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.6 - (show annotations) (download) (as text)
Tue Aug 23 14:35:58 2011 UTC (3 years ago) by swift
Branch: MAIN
Changes since 1.5: +7 -6 lines
File MIME type: application/xml
Fix bug #379735 - Remove reference to trads script (not available anymore). Thanks to Chema "nimiux" Alonso for reporting

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

  ViewVC Help
Powered by ViewVC 1.1.20