/[gentoo]/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml
Gentoo

Diff of /xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.2
1<?xml version='1.0' encoding='UTF-8'?> 1<?xml version='1.0' encoding='UTF-8'?>
2 2
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml,v 1.1 2004/12/27 22:11:16 swift Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/metadoc-guide.xml,v 1.2 2005/01/06 17:18:12 neysx Exp $ -->
4 4
5<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 5<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
6 6
7<guide link="metadoc-guide.xml"> 7<guide link="metadoc-guide.xml">
8<title>Gentoo Metadoc XML Guide</title> 8<title>Gentoo Metadoc XML Guide</title>
9 9
10<author title="Author"> 10<author title="Author">
11 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 11 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
12</author>
13
14<author title="Editor">
15 <mail link="neysx@gentoo.org">Xavier Neys</mail>
12</author> 16</author>
13 17
14<abstract> 18<abstract>
15This guide informs developers how to use the Metadoc XML format that allows the 19This guide informs developers how to use the Metadoc XML format that allows the
16Gentoo Documentation Project to keep its documentation in a hierarchical manner 20Gentoo Documentation Project to keep its documentation in a hierarchical manner
19 23
20<!-- The content of this document is licensed under the CC-BY-SA license --> 24<!-- The content of this document is licensed under the CC-BY-SA license -->
21<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> 25<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
22<license/> 26<license/>
23 27
24<version>1.0</version> 28<version>1.1</version>
25<date>2004-12-27</date> 29<date>2005-01-06</date>
26 30
27<chapter> 31<chapter>
28<title>Introduction</title> 32<title>Introduction</title>
29<section> 33<section>
30<title>Why is MetadocXML Needed?</title> 34<title>Why is MetadocXML Needed?</title>
31<body> 35<body>
32 36
33<p> 37<p>
34MetadocXML is not needed, it's an additional resource for the Gentoo 38MetadocXML is not needed, it's an additional resource for the Gentoo
35Documentatoin Project to keep track of documents, even if they are located 39Documentation Project to keep track of documents, even if they are located
36outside the normal <path>[gentoo]/xml/htdocs/doc</path> scope. 40outside of the normal <path>[gentoo]/xml/htdocs/doc</path> scope.
37</p> 41</p>
38 42
39<p> 43<p>
40Thanks to MetadocXML, we can now 44Thanks to MetadocXML, we can now
41</p> 45</p>
75that has many more features than this. 79that has many more features than this.
76</p> 80</p>
77 81
78<p> 82<p>
79Translation teams that do not use MetadocXML yet don't need to worry - they will 83Translation teams that do not use MetadocXML yet don't need to worry - they will
80not loose any current functionality as it only builds upon the existing 84not lose any current functionality as it only builds upon the existing
81infrastructure - there are no changes to the GuideXML format that need 85infrastructure - there are no changes to the GuideXML format that need
82MetadocXML. 86MetadocXML.
83</p> 87</p>
84 88
85</body> 89</body>
106 <li>Documents that are covered</li> 110 <li>Documents that are covered</li>
107 <li>Bugs that are part of a document</li> 111 <li>Bugs that are part of a document</li>
108</ul> 112</ul>
109 113
110<p> 114<p>
111Next to <path>metadoc.xml</path> one also can have a dynamically generated index 115Next to <path>metadoc.xml</path>, one also can have a dynamically generated index
112file (usually called <path>index.xml</path>), an overview listing of all 116file (usually called <path>index.xml</path>), an overview listing of all
113documentation (usually called <path>list.xml</path>) and an overview listing of 117documentation (usually called <path>list.xml</path>) and an overview listing of
114all members, files and bugs (usually called <path>overview.xml</path>). 118all members, files and bugs (usually called <path>overview.xml</path>).
115</p> 119</p>
116 120
137 141
138<p> 142<p>
139Then, one starts with the MetadocXML declaration. 143Then, one starts with the MetadocXML declaration.
140</p> 144</p>
141 145
142<pre caption="MetadocXML declaration"> 146<pre caption="English MetadocXML declaration">
143&lt;metadoc lang="<comment>en</comment>"&gt; 147&lt;metadoc lang="<comment>en</comment>"&gt;
144</pre> 148</pre>
145 149
146<p> 150<p>
151Translators 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
153out 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>
147Beneith the <c>metadoc</c> entity, the following entities should be declared (in 161Beneath the <c>metadoc</c> entity, the following entities should be declared (in
148the given order): 162the given order):
149</p> 163</p>
150 164
151<ul> 165<ul>
152 <li> 166 <li>
228The <c>files</c> entity contains only <c>file</c> entities. 242The <c>files</c> entity contains only <c>file</c> entities.
229</p> 243</p>
230 244
231<p> 245<p>
232Each <c>file</c> entity references a single XML file. It has a mandatory 246Each <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 247<c>id</c> attribute which should be seen as a primary key to lookup the file.
234the file is a translation of another file, the <c>parent</c> attribute must 248Metadoc will compare the file name defined with the same <c>id</c> attribute in
235reference the <e>other language metadoc file</e> and the <c>id</c> attribute 249the metadoc's parent file (defined in the root element) to find out whether the
236must be the same. 250file is a translation or an untranslated file. File names would be identical in
251the latter case.
237</p> 252</p>
238 253
239<pre caption="Files entity example"> 254<pre caption="Files entity example">
240&lt;files&gt; 255&lt;files&gt;
241 &lt;file id="ati-faq" parent="/doc/en/metadoc.xml"&gt;/doc/nl/ati-faq.xml&lt;/file&gt; 256 &lt;file id="ati-faq"&gt;/doc/nl/ati-faq.xml&lt;/file&gt;
242&lt;/files&gt; 257&lt;/files&gt;
243</pre> 258</pre>
244 259
245</body> 260</body>
246</section> 261</section>

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.20