/[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.1 - (show annotations) (download) (as text)
Mon Dec 27 22:11:16 2004 UTC (9 years, 9 months ago) by swift
Branch: MAIN
File MIME type: application/xml
Metadoc file as promised

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

  ViewVC Help
Powered by ViewVC 1.1.20