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

1 swift 1.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