/[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.5 - (hide annotations) (download) (as text)
Sun Jun 10 19:33:13 2007 UTC (7 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.4: +9 -8 lines
File MIME type: application/xml
fixed english, grammar, and punctuation. no content changes.

1 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2    
3 nightmorph 1.5 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml,v 1.4 2006/05/23 13:26:41 nightmorph Exp $ -->
4 swift 1.1
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 neysx 1.2 <author title="Editor">
15     <mail link="neysx@gentoo.org">Xavier Neys</mail>
16     </author>
17    
18 swift 1.1 <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 neysx 1.3 <version>1.2</version>
29     <date>2005-04-04</date>
30 swift 1.1
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 neysx 1.2 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 swift 1.1 </p>
42    
43     <p>
44     Thanks to MetadocXML, we can now
45     </p>
46    
47     <ul>
48     <li>
49 nightmorph 1.5 track documents that are located inside project webspaces
50 swift 1.1 (<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 nightmorph 1.5 track unofficial documentation team members (such as translators)
60 swift 1.1 </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 nightmorph 1.5 primitively check if a translated file is in sync with its English
71 swift 1.1 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 nightmorph 1.4 that have many more features than this.
80 swift 1.1 </p>
81    
82     <p>
83     Translation teams that do not use MetadocXML yet don't need to worry - they will
84 neysx 1.2 not lose any current functionality as it only builds upon the existing
85 swift 1.1 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 neysx 1.2 Next to <path>metadoc.xml</path>, one also can have a dynamically generated index
116 swift 1.1 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 neysx 1.2 <pre caption="English MetadocXML declaration">
147 swift 1.1 &lt;metadoc lang="<comment>en</comment>"&gt;
148     </pre>
149    
150     <p>
151 neysx 1.2 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 swift 1.1 the given order):
163     </p>
164    
165     <ul>
166     <li>
167 neysx 1.3 <c>version</c> to help keep track of changes
168     </li>
169     <li>
170 swift 1.1 <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 neysx 1.3 <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 swift 1.1 <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 neysx 1.3 &lt;member mail="gentoo_contributor@gmail.com" fullname="John Doe"&gt;jdoe&lt;/member&gt;
221 swift 1.1 &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 neysx 1.2 <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 swift 1.1 </p>
268    
269 neysx 1.3 <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 swift 1.1 &lt;files&gt;
275 neysx 1.3 &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 swift 1.1 &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 nightmorph 1.5 One or more <c>memberof</c> entities, referring to the category or
315     categories in which the document is located (note that a document can be in
316     several categories at once)
317 swift 1.1 </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 nightmorph 1.5 metadoc file. <e>Do not list</e> categories that are children of another
402     category.
403 swift 1.1 </p>
404    
405     </body>
406     </section>
407     <section>
408     <title>Dynamically Generated List Document</title>
409     <body>
410    
411     <p>
412     A dynamically generated list document starts identically to a dynamically
413     generated index file:
414     </p>
415    
416     <pre caption="Dynamically generated list document">
417     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
418     &lt;?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?&gt;
419     &lt;?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?&gt;
420    
421     &lt;!-- &#36;Header&#36; --&gt;
422    
423     &lt;!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd"&gt;
424    
425     <comment>&lt;!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --&gt;</comment>
426     &lt;dynamic metadoc="<i>/doc/en/metadoc.xml</i>"&gt;
427     &lt;title&gt;<i>Gentoo Documentation Listing</i>&lt;/title&gt;
428     </pre>
429    
430     <p>
431     However, there is no <c>intro</c> tag. What needs to be added are all the top
432     categories used by the listing. To differentiate this from the index (which will
433     also display the abstract information on each document) this happens between
434     <c>list</c> tags inside <c>listing</c>:
435     </p>
436    
437     <pre caption="Listing of categories">
438     &lt;listing&gt;
439     &lt;list&gt;faq&lt;/list&gt;
440     &lt;list&gt;install&lt;/list&gt;
441     &lt;/listing&gt;
442     </pre>
443    
444     </body>
445     </section>
446     <section>
447     <title>Dynamically Generated Overview Document</title>
448     <body>
449    
450     <p>
451     The overview document is started similarly as the two documents decribed above:
452     </p>
453    
454     <pre caption="Dynamically generated overview document">
455     &lt;?xml version='1.0' encoding='UTF-8'?&gt;
456     &lt;?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?&gt;
457     &lt;?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?&gt;
458    
459     &lt;!-- &#36;Header&#36; --&gt;
460    
461     &lt;!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd"&gt;
462    
463     <comment>&lt;!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --&gt;</comment>
464     &lt;dynamic metadoc="<i>/doc/en/metadoc.xml</i>"&gt;
465     &lt;title&gt;<i>Documentation Development Overview</i>&lt;/title&gt;
466     </pre>
467    
468     <p>
469     You can again write up a small introduction in GuideXML between the <c>intro</c>
470     XML tags, starting from a <c>section</c> up. Once that is finished, a single tag
471     <c>&lt;overview/&gt;</c> is sufficient.
472     </p>
473    
474     <pre caption="Intro and overview tags">
475     &lt;intro&gt;
476     <comment>(...)</comment>
477     &lt;/intro&gt;
478    
479     &lt;overview/&gt;
480     </pre>
481    
482     </body>
483     </section>
484     </chapter>
485    
486     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20