| 1 |
<?xml version='1.0' encoding='UTF-8'?>
|
| 2 |
|
| 3 |
<!-- $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 |
|
| 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 |
<author title="Editor">
|
| 15 |
<mail link="neysx@gentoo.org">Xavier Neys</mail>
|
| 16 |
</author>
|
| 17 |
|
| 18 |
<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 |
<version>2</version>
|
| 29 |
<date>2011-08-23</date>
|
| 30 |
|
| 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 |
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 |
</p>
|
| 42 |
|
| 43 |
<p>
|
| 44 |
Thanks to MetadocXML, we can now
|
| 45 |
</p>
|
| 46 |
|
| 47 |
<ul>
|
| 48 |
<li>
|
| 49 |
track documents that are located inside project webspaces
|
| 50 |
(<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 |
track unofficial documentation team members (such as translators)
|
| 60 |
</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 |
primitively check if a translated file is in sync with its English
|
| 71 |
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 |
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 |
</p>
|
| 82 |
|
| 83 |
<p>
|
| 84 |
Translation teams that do not use MetadocXML yet don't need to worry - they will
|
| 85 |
not lose any current functionality as it only builds upon the existing
|
| 86 |
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 |
Next to <path>metadoc.xml</path>, one also can have a dynamically generated index
|
| 117 |
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 |
<?xml version='1.0' encoding="UTF-8"?>
|
| 139 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.25 2004/12/23 09:51:30 swift Exp $ -->
|
| 140 |
<!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">
|
| 141 |
</pre>
|
| 142 |
|
| 143 |
<p>
|
| 144 |
Then, one starts with the MetadocXML declaration.
|
| 145 |
</p>
|
| 146 |
|
| 147 |
<pre caption="English MetadocXML declaration">
|
| 148 |
<metadoc lang="<comment>en</comment>">
|
| 149 |
</pre>
|
| 150 |
|
| 151 |
<p>
|
| 152 |
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 |
<metadoc lang="<comment>language code</comment>" parent="/doc/en/metadoc.xml">
|
| 159 |
</pre>
|
| 160 |
|
| 161 |
<p>
|
| 162 |
Beneath the <c>metadoc</c> entity, the following entities should be declared (in
|
| 163 |
the given order):
|
| 164 |
</p>
|
| 165 |
|
| 166 |
<ul>
|
| 167 |
<li>
|
| 168 |
<c>version</c> to help keep track of changes
|
| 169 |
</li>
|
| 170 |
<li>
|
| 171 |
<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 |
<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 |
<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 |
<members>
|
| 218 |
<lead>swift</lead>
|
| 219 |
<lead>neysx</lead>
|
| 220 |
<member>dertobi123</member>
|
| 221 |
<member mail="gentoo_contributor@gmail.com" fullname="John Doe">jdoe</member>
|
| 222 |
</members>
|
| 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 |
<categories>
|
| 245 |
<cat id="faq">Frequently Asked Questions</cat>
|
| 246 |
<cat id="install">Installation Related Resources</cat>
|
| 247 |
<cat id="install_guides">Installation Guides</cat>
|
| 248 |
</categories>
|
| 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 |
<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 |
</p>
|
| 269 |
|
| 270 |
<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 |
<files>
|
| 276 |
<file id="metadoc">/doc/en/metadoc.xml</file>
|
| 277 |
<file id="ati-faq">/doc/en/ati-faq.xml</file>
|
| 278 |
</files>
|
| 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 |
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 |
</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 |
<docs>
|
| 330 |
<doc id="handbook_x86">
|
| 331 |
<memberof>install_guides</memberof>
|
| 332 |
<fileid>handbook-x86</fileid>
|
| 333 |
<bugs>
|
| 334 |
<bug>70753</bug>
|
| 335 |
</bugs>
|
| 336 |
</doc>
|
| 337 |
<doc id="portage-intro">
|
| 338 |
<memberof>gentoo_portage</memberof>
|
| 339 |
<fileid vpart="2" vchap="1">handbook-x86</fileid>
|
| 340 |
</doc>
|
| 341 |
<doc id="uml">
|
| 342 |
<memberof>sysadmin_general</memberof>
|
| 343 |
<fileid>uml</fileid>
|
| 344 |
</doc>
|
| 345 |
</docs>
|
| 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 |
<?xml version='1.0' encoding='UTF-8'?>
|
| 365 |
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
|
| 366 |
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
|
| 367 |
|
| 368 |
<!-- $Header$ -->
|
| 369 |
|
| 370 |
<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">
|
| 371 |
|
| 372 |
<comment><!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --></comment>
|
| 373 |
<dynamic metadoc="<i>/doc/en/metadoc.xml</i>">
|
| 374 |
<title><i>Gentoo Documentation Resources</i></title>
|
| 375 |
<intro>
|
| 376 |
|
| 377 |
<comment>(...)</comment>
|
| 378 |
|
| 379 |
</intro>
|
| 380 |
|
| 381 |
<catid><i>faq</i></catid>
|
| 382 |
<catid><i>install</i></catid>
|
| 383 |
|
| 384 |
</dynamic>
|
| 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 |
metadoc file. <e>Do not list</e> categories that are children of another
|
| 403 |
category.
|
| 404 |
</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 |
<?xml version='1.0' encoding='UTF-8'?>
|
| 419 |
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
|
| 420 |
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
|
| 421 |
|
| 422 |
<!-- $Header$ -->
|
| 423 |
|
| 424 |
<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">
|
| 425 |
|
| 426 |
<comment><!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --></comment>
|
| 427 |
<dynamic metadoc="<i>/doc/en/metadoc.xml</i>">
|
| 428 |
<title><i>Gentoo Documentation Listing</i></title>
|
| 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 |
<listing>
|
| 440 |
<list>faq</list>
|
| 441 |
<list>install</list>
|
| 442 |
</listing>
|
| 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 |
<?xml version='1.0' encoding='UTF-8'?>
|
| 457 |
<?xml-stylesheet href="/xsl/metadoc.xsl" type="text/xsl"?>
|
| 458 |
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
|
| 459 |
|
| 460 |
<!-- $Header$ -->
|
| 461 |
|
| 462 |
<!DOCTYPE dynamic SYSTEM "/dtd/metadoc.dtd">
|
| 463 |
|
| 464 |
<comment><!-- Substitute "/doc/en/metadoc.xml" with the location of your metadoc file --></comment>
|
| 465 |
<dynamic metadoc="<i>/doc/en/metadoc.xml</i>">
|
| 466 |
<title><i>Documentation Development Overview</i></title>
|
| 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><overview/></c> is sufficient.
|
| 473 |
</p>
|
| 474 |
|
| 475 |
<pre caption="Intro and overview tags">
|
| 476 |
<intro>
|
| 477 |
<comment>(...)</comment>
|
| 478 |
</intro>
|
| 479 |
|
| 480 |
<overview/>
|
| 481 |
</pre>
|
| 482 |
|
| 483 |
</body>
|
| 484 |
</section>
|
| 485 |
</chapter>
|
| 486 |
|
| 487 |
</guide>
|
Parent Directory
| 
Revision Log