/[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.8 - (hide annotations) (download) (as text)
Sun Oct 28 15:21:05 2012 UTC (23 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.7: +2 -2 lines
File MIME type: application/xml
Removing link attribute from guides

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

  ViewVC Help
Powered by ViewVC 1.1.20