/[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 - (hide annotations) (download) (as text)
Tue Aug 23 14:35:58 2011 UTC (2 years, 10 months 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 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2    
3 swift 1.6 <!-- $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 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 swift 1.6 <version>2</version>
29     <date>2011-08-23</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 swift 1.6 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 swift 1.1 </p>
82    
83     <p>
84     Translation teams that do not use MetadocXML yet don't need to worry - they will
85 neysx 1.2 not lose any current functionality as it only builds upon the existing
86 swift 1.1 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 neysx 1.2 Next to <path>metadoc.xml</path>, one also can have a dynamically generated index
117 swift 1.1 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 neysx 1.2 <pre caption="English MetadocXML declaration">
148 swift 1.1 &lt;metadoc lang="<comment>en</comment>"&gt;
149     </pre>
150    
151     <p>
152 neysx 1.2 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 swift 1.1 the given order):
164     </p>
165    
166     <ul>
167     <li>
168 neysx 1.3 <c>version</c> to help keep track of changes
169     </li>
170     <li>
171 swift 1.1 <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 neysx 1.3 <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 swift 1.1 <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 neysx 1.3 &lt;member mail="gentoo_contributor@gmail.com" fullname="John Doe"&gt;jdoe&lt;/member&gt;
222 swift 1.1 &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 neysx 1.2 <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 swift 1.1 </p>
269    
270 neysx 1.3 <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 swift 1.1 &lt;files&gt;
276 neysx 1.3 &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 swift 1.1 &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 nightmorph 1.5 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 swift 1.1 </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 nightmorph 1.5 metadoc file. <e>Do not list</e> categories that are children of another
403     category.
404 swift 1.1 </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