neysx 07/10/04 19:37:23 Modified: xml-guide.xml Log: Documented recent and much less recent features: . shortcut for Gentoo devs in <mail> . @link is not compulsory . handbook values & conditionals . <faqindex> Used GuideXML more consistently
Revision Changes Path 1.67 xml/htdocs/doc/en/xml-guide.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?rev=1.67&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?rev=1.67&content-type=text/plain diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/xml-guide.xml?r1=1.66&r2=1.67 Index: xml-guide.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v retrieving revision 1.66 retrieving revision 1.67 diff -u -r1.66 -r1.67 --- xml-guide.xml 29 Nov 2006 15:48:57 -0000 1.66 +++ xml-guide.xml 4 Oct 2007 19:37:23 -0000 1.67 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.66 2006/11/29 15:48:57 nightmorph Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.67 2007/10/04 19:37:23 neysx Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> -<guide link="/doc/en/xml-guide.xml"> -<title>Gentoo XML Guide</title> +<guide> +<title>Gentoo GuideXML Guide</title> <author title="Author"> - <mail link="[EMAIL PROTECTED]">Xavier Neys</mail> + <mail link="neysx"/> </author> <author title="Author"> <mail link="[EMAIL PROTECTED]">Daniel Robbins</mail> @@ -32,17 +32,17 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>7</version> -<date>2006-05-11</date> +<version>8</version> +<date>2007-10-04</date> <chapter> -<title>Guide basics</title> +<title>GuideXML basics</title> <section> -<title>Guide XML design goals</title> +<title>GuideXML design goals</title> <body> <p> -The guide XML syntax is lightweight yet expressive, so that it is easy to +The guideXML syntax is lightweight yet expressive, so that it is easy to learn yet also provides all the features we need for the creation of web documentation. The number of tags is kept to a minimum -- just those we need. This makes it easy to transform guide into other formats, such as DocBook @@ -50,7 +50,7 @@ </p> <p> -The goal is to make it easy to <e>create</e> and <e>transform</e> guide XML +The goal is to make it easy to <e>create</e> and <e>transform</e> guideXML documents. </p> @@ -77,7 +77,7 @@ </chapter> <chapter> -<title>Guide XML</title> +<title>GuideXML</title> <section> <title>Basic structure</title> <body> @@ -119,17 +119,19 @@ document and specifies its DTD. The <c><!-- $Header$ --></c> line will be automatically modified by the CVS server and helps to track revisions. Next, there's a <c><guide></c> tag -- the entire guide document is -enclosed within a <c><guide> </guide></c> pair. The <c>link</c> -attribute is compulsory and should preferably contain the absolute path to the -document relatively to the document root even though the file name alone will -work. It is mainly used to generate a link to a printer-friendly version of -your document. If you use a wrong value, the link to the printable version will -either not work or point to a wrong document. Translated documents <e>must</e> -specify the full path because it is also used to check whether a more recent -original document exists. The <c>lang</c> attribute should be used to specify -the language code of your document. It is used to format the date and insert -strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language. -The default is English. +enclosed within a <c><guide> </guide></c> pair. +<br/> +The <c>link</c> attribute is optional and should preferably contain the +absolute path to the document relatively to the document root even though the +file name alone will work. It is only used to generate a link to a +printer-friendly version of your document and check whether a translation is +up-to-date. Our XSL back-engine passes the actual path to our XSL stylesheet. +The link attribute is only used as a fall-back value in case the XML is +processed by other means. +<br/> +The <c>lang</c> attribute should be used to specify the language code of your +document. It is used to format the date and insert strings like "<e>Note</e>", +"<e>Content</e>", etc. in the specified language. The default is English. </p> <p> @@ -144,8 +146,8 @@ relationship to the document (author, co-author, editor, etc.). In this particular example, the authors' names are enclosed in another tag -- a <c><mail></c> tag, used to specify an email address for this particular -person. The <c><mail></c> tag is optional and can be omitted, and no -more than one <c><author></c> element is required per guide document. +person. The <c><mail></c> tag is optional and can be omitted, and at +least one <c><author></c> element is required per guide document. </p> <p> @@ -157,9 +159,9 @@ </p> <p> -This rounds out the tags that should appear at the beginning of a guide -document. Besides the <c><title></c> and <c><mail></c> tags, these -tags shouldn't appear anywhere else except immediately inside the +This sums up the tags that should appear at the beginning of a guide document. +Besides the <c><title></c> and <c><mail></c> tags, these tags +shouldn't appear anywhere else except immediately inside the <c><guide></c> tag, and for consistency it's recommended (but not required) that these tags appear before the content of the document. </p> @@ -216,10 +218,10 @@ </p> <note> -A <c><guide></c> element can contain multiple <c><chapter></c> -elements, and a <c><chapter></c> can contain multiple -<c><section></c> elements. However, a <c><section></c> -element can only contain one <c><body></c> element. +A <c><guide></c> element must contain at least one <c><chapter></c> +elements, a <c><chapter></c> must contain at least one +<c><section></c> elements and a <c><section></c> element must +contain at least one <c><body></c> element. </note> </body> @@ -480,26 +482,51 @@ <p> We've taken a look at the <c><mail></c> tag earlier; it's used to link some text with a particular email address, and takes the form <c><mail -link="[EMAIL PROTECTED]">Mr. Foo Bar</mail></c>. If you want to display the -email address, you can use <c><mail>[EMAIL PROTECTED]</mail></c>, this -would be displayed as <mail>[EMAIL PROTECTED]</mail>. +link="[EMAIL PROTECTED]">Mr. Foo Bar</mail></c>. If you want to display the +email address, you can use <c><mail>[EMAIL PROTECTED]</mail></c>, this +would be displayed as <mail>[EMAIL PROTECTED]</mail>. +</p> + +<p> +Shorter forms make it easier to use names and emails of Gentoo developers. Both +<c><mail>neysx</mail></c> and <c><mail link="neysx"/></c> +would appear as <mail>neysx</mail>. If you want to use a Gentoo dev's email +with a different content than his full name, use the second form with some +content. For instance, use a dev's first name: <c><mail +link="neysx">Xavier</mail></c> appears as <mail +link="neysx">Xavier</mail>. +<br/> +This is particularly useful when you want to name a developer whose name +contains "funny" characters that you can't type. </p> <p> The <c><uri></c> tag is used to point to files/locations on the Internet. It has two forms -- the first can be used when you want to have the actual URI displayed in the body text, such as this link to -<uri>http://forums.gentoo.org</uri>. To create this link, I typed -<c><uri>http://forums.gentoo.org</uri></c>. The alternate form is +<uri>http://forums.gentoo.org/</uri>. To create this link, I typed +<c><uri>http://forums.gentoo.org/</uri></c>. The alternate form is when you want to associate a URI with some other text -- for example, <uri -link="http://forums.gentoo.org";>the Gentoo Forums</uri>. To create <e>this</e> -link, I typed <c><uri link="http://forums.gentoo.org">the Gentoo -Forums</uri></c>. You don't need to write <c>http://www.gentoo.org/</c> -to link to other parts of the Gentoo web site. For instance, a link to the <uri -link="/doc/en/">documentation main index</uri> should be simply <c><uri -link="/doc/en/index.xml">documentation main index</uri></c>. You can -even omit <c>index.xml</c> when you link to a directory index, e.g. <c><uri -link="/doc/en/">documentation main index</uri></c>. +link="http://forums.gentoo.org/";>the Gentoo Forums</uri>. To create +<e>this</e> link, I typed <c><uri link="http://forums.gentoo.org/">the +Gentoo Forums</uri></c>. You don't need to write +<c>http://www.gentoo.org/</c> to link to other parts of the Gentoo web site. +For instance, a link to the <uri link="/doc/en/">documentation main index</uri> +should be simply <c><uri link="/doc/en/index.xml">documentation main +index</uri></c>. You can even omit <c>index.xml</c> when you link to a +directory index, e.g. <c><uri link="/doc/en/">documentation main +index</uri></c>. Leaving the trailing slash saves an extra HTTP request. +</p> + +<p> +You should not use a <c><uri></c> tag with a <c>link</c> attribute that +starts with <c>mailto:</c>. In this case, use a <c><mail></c> tag. +</p> + +<p> +Please avoid the <uri link="http://en.wikipedia.org/wiki/Click_here";>click here +syndrome</uri> as recommended by the <uri +link="http://www.w3.org/QA/Tips/noClickHere";>W3C</uri>. </p> </body> @@ -525,10 +552,10 @@ <body> <p> -Guide supports a simplified table syntax similar to that of HTML. To start a +GuideXML supports a simplified table syntax similar to that of HTML. To start a table, use a <c><table></c> tag. Start a row with a <c><tr></c> -tag. However, for inserting actual table data, we <e>don't</e> support the -HTML <td> tag; instead, use the <c><th></c> if you are inserting a +tag. However, for inserting actual table data, we <e>don't</e> support the HTML +<td> tag; instead, use the <c><th></c> if you are inserting a header, and <c><ti></c> if you are inserting a normal informational block. You can use a <c><th></c> anywhere you can use a <c><ti></c> -- there's no requirement that <c><th></c> elements appear only in the @@ -644,15 +671,15 @@ <body> <p> -Guide makes it really easy to reference other parts of the document using +GuideXML makes it really easy to reference other parts of the document using hyperlinks. You can create a link pointing to <uri link="#doc_chap1">Chapter One</uri> by typing <c><uri link="#doc_chap1">Chapter One</uri></c>. To point to <uri link="#doc_chap1_sect2">section two of Chapter One</uri>, type <c><uri link="#doc_chap1_sect2">section two of -Chapter One</uri></c>. To refer to figure 3 in chapter 1, type <c><uri -link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer to <uri -link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type <c><uri -link="#doc_chap2_pre2">code listing 2.2</uri></c>. +Chapter One</uri></c>. To refer to figure 3 in chapter 1, type +<c><uri link="#doc_chap1_fig3">figure 1.3</uri></c>. Or, to refer +to <uri link="#doc_chap2_pre2">code listing 2 in chapter 2</uri>, type +<c><uri link="#doc_chap2_pre2">code listing 2.2</uri></c>. </p> <p> @@ -711,7 +738,7 @@ <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header$ --> -<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> +<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> <title>Gentoo x86 Installation Guide</title> <author title="Author"> @@ -720,9 +747,312 @@ </body> </section> +<section> +<title>FAQs</title> +<body> + +<p> +FAQ documents need to start with a list of questions with links to their +answers. Creating such a list is both time-consuming and error-prone. The list +can be created automatically if you use a <c>faqindex</c> element as the first +chapter of your document. This element has the same structure as a +<c>chapter</c> to allow some introductory text. The structure of the document +is expected to be split into chapters (at least one chapter) containing +sections, each section containing one question specified in its <c>title</c> +element with the answer in its <c>body</c>. The FAQ index will appear as one +section per chapter and one link per question. +</p> + +<p> +A quick look at a <uri link="/doc/en/faq.xml">FAQ</uri> and <uri +link="/doc/en/faq.xml?passthru=1">its source</uri> should make the above +obvious. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Handbook Format</title> +<section> +<title>Guide vs Book</title> +<body> + +<p> +For high-volume documentation, such as the <uri +link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a +broader format was needed. We designed a GuideXML-compatible enhancement that +allows us to write modular and multi-page documentation. +</p> + +</body> +</section> +<section> +<title>Main File</title> +<body> + +<p> +The first change is the need for a "master" document. This document contains no +real content, but links to the individual documentation modules. The syntax +doesn't differ much from GuideXML: +</p> + +<pre caption="Example book usage"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<<i>book</i>> +<title>Example Book Usage</title> + +<author...> + ... +</author> + +<abstract> + ... +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>...</version> +<date>...</date> +</pre> + +<p> +So far no real differences (except for the <c><book></c> instead of +<c><guide></c> tag). Instead of starting with the individual +<c><chapter></c>s, you define a <c><part></c>, which is the +equivalent of a separate part in a book: +</p> + +<pre caption="Defining a part"> +<part> +<title>Part One</title> +<abstract> + ... +</abstract> + +<comment>(Defining the several chapters)</comment> +</part> +</pre> + +<p> +Each part is accompanied by a <c><title></c> and an +<c><abstract></c> which gives a small introduction to the part. +</p> + +<p> +Inside each part, you define the individual <c><chapter></c>s. Each +chapter <e>must</e> be a separate document. As a result it is no surprise that +a special tag (<c><include></c>) is added to allow including the separate +document. +</p> + +<pre caption="Defining a chapter"> +<chapter> +<title>Chapter One</title> + + <include href="path/to/chapter-one.xml"/> + +</chapter> +</pre> + +</body> +</section> +<section> +<title>Designing the Individual Chapters</title> +<body> + +<p> +The content of an individual chapter is structured as follows: +</p> + +<pre caption="Chapter Syntax"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> + +<sections> + +<abstract> + This is a small explanation on chapter one. +</abstract> + +<version>...</version> +<date>...</date> + +<comment>(Define the several <section> and <subsection>)</comment> + +</sections> +</pre> + +<p> +Inside each chapter you can define <c><section></c>s (equivalent of +<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent +of <c><section></c> in a Guide). +</p> + +<p> +Each individual chapter should have its own date and version elements. The +latest date of all chapters and master document will be displayed when a user +browses through all parts of the book. +</p> + +</body> +</section> </chapter> <chapter> +<title>Advanced Handbook Features</title> +<section> +<title>Global Values</title> +<body> + +<p> +Sometimes, the same values are repeated many times in several parts of a +handbook. Global search and replace operations tend to forget some or introduce +unwanted changes. Besides, it can be useful to define different values to be +used in shared chapters depending on which handbook includes the chapter. +</p> + +<p> +Global values can be defined in a handbook master file and used in all included +chapters. +</p> + +<p> +To define global values, add a <c><values></c> element to the handbook +master file. Each value is then defined in a <c><key></c> element whose +<c>id</c> attribute identifies the value, i.e. it is the name of your variable. +The content of the <c><key></c> is its value. +</p> + +<p> +The following example defines three values in a handbook master file: +</p> + +<pre caption="Define values in a handbook"> +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book SYSTEM "/dtd/book.dtd"> +<!-- $Header$ --> + +<book> +<title>Example Book Usage</title> + +<i><values> + <key id="arch">x86</key> + <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key> + <key id="min-cd-size">57</key> +</values></i> + +<author...> + ... +</author> + +... +</pre> + +<p> +The defined values can then be used throughout the handbook with the in-line +<c><keyval id="key_id"/></c> element. Specify the name of the key in its +<c>id</c> attribute, e.g. <keyval id="min-cd-name"/> would be replaced by +"install-x86-minimal-2007.0-r1.iso" in our example. +</p> + +<pre caption="Using defined values"> +<p> +The Minimal Installation CD is called <c><i><keyval id="min-cd-name"/></i></c> +and takes up only <i><keyval id="min-cd-size"/></i> MB of diskspace. You can use this +Installation CD to install Gentoo, but <e>only</e> with a working Internet +connection. +</p> +</pre> + +<p> +To make life easier on our translators, only use actual values, i.e. content +that does not need to be translated. For instance, we defined the +<c>min-cd-size</c> value to <c>57</c> and not <c>57 MB</c>. +</p> + +</body> +</section> +<section> +<title>Conditional Elements</title> +<body> + +<p> +Chapters that are shared by several handbooks such as our <uri +link="/doc/en/handbook/">Installation Handbooks</uri> often have small +differences depending on which handbook includes them. Instead of adding +content that is irrelevant to some handbooks, authors can add a condition to +the following elements: <c><section></c>, <c><subsection></c>, +<c><body></c>, <c><note></c>, <c><impo></c>, +<c><warn></c>, <c><pre></c>, <c><p></c>, +<c><table></c>, <c><tr></c>, <c><ul></c>, <c><ol></c> +and <c><li></c>. +</p> + +<p> +The condition must be an <uri +link="http://en.wikipedia.org/wiki/XPath";>XPATH</uri> expression that will be +evaluated when transforming the XML. If it evaluates to <c>true</c>, the +element is processed, if not, it is ignored. The condition is specified in a +<c>test</c> attribute. +</p> + +<p> +The following example uses the <c>arch</c> value that is defined in each +handbook master file to condition some content: +</p> + +<pre caption="Using conditional elements"> +<body test="contains('AMD64 x86',func:keyval('arch'))"> + +<p> +This paragraph applies to both x86 and AMD64 architectures. +</p> + +<p test="func:keyval('arch')='x86'"> +This paragraph only applies to the x86 architecture. +</p> + +<p test="func:keyval('arch')='AMD64'"> +This paragraph only applies to the AMD64 architecture. +</p> + +<p test="func:keyval('arch')='PPC'"> +This paragraph will never be seen! +The whole body is skipped because of the first condition. +</p> + +</body> + +<body test="contains('AMD64 PPC64',func:keyval('arch'))"> + +<p> +This paragraph applies to the AMD64, PPC64 <comment>and PPC</comment> architectures because +the 'AMD64 PPC64' string does contain 'PPC'. +</p> + +<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'"> +This note only applies to the AMD64 and PPC64 architectures. +</note> + +</body> +</pre> + +</body> +</section> +</chapter> + +<chapter id="codingstyle"> <title>Coding Style</title> <section> <title>Introduction</title> @@ -877,156 +1207,21 @@ </chapter> <chapter> -<title>Handbook Format</title> -<section> -<title>Guide vs Book</title> -<body> - -<p> -For high-volume documentation, such as the <uri -link="/doc/en/handbook/handbook-x86.xml?part=1">Installation Instructions</uri>, a -broader format was needed. We designed a GuideXML-compatible enhancement that -allows us to write modular and multi-page documentation. -</p> - -</body> -</section> -<section> -<title>Main File</title> -<body> - -<p> -The first change is the need for a "master" document. This document contains no -real content, but links to the individual documentation modules. The syntax -doesn't differ much from GuideXML: -</p> - -<pre caption="Example book usage"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE book SYSTEM "/dtd/book.dtd"> -<!-- $Header$ --> - -<<i>book</i> link="example.xml"> -<title>Example Book Usage</title> - -<author...> - ... -</author> - -<abstract> - ... -</abstract> - -<!-- The content of this document is licensed under the CC-BY-SA license --> -<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> -<license/> - -<version>...</version> -<date>...</date> -</pre> - -<p> -So far no real differences (except for the <c><book></c> instead of -<c><guide></c> tag). Instead of starting with the individual -<c><chapter></c>s, you define a <c><part></c>, which is the -equivalent of a separate part in a book: -</p> - -<pre caption="Defining a part"> -<part> -<title>Part One</title> -<abstract> - ... -</abstract> - -<comment>(Defining the several chapters)</comment> -</part> -</pre> - -<p> -Each part is accompanied by a <c><title></c> and an -<c><abstract></c> which gives a small introduction to the part. -</p> - -<p> -Inside each part, you define the individual <c><chapter></c>s. Each -chapter <e>must</e> be a separate document. As a result it is no surprise that -a special tag (<c><include></c>) is added to allow including the separate -document. -</p> - -<pre caption="Defining a chapter"> -<chapter> -<title>Chapter One</title> -<abstract> - This is a small explanation on chapter one. -</abstract> - - <include href="path/to/chapter-one.xml"/> - -</chapter> -</pre> - -</body> -</section> -<section> -<title>Designing the Individual Chapters</title> -<body> - -<p> -The content of an individual chapter is structured as follows: -</p> - -<pre caption="Chapter Syntax"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> -<!-- $Header$ --> - -<!-- The content of this document is licensed under the CC-BY-SA license --> -<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> - -<sections> - -<version>...</version> -<date>...</date> - -<comment>(Define the several <section> and <subsection>)</comment> - -</sections> -</pre> - -<p> -Inside each chapter you can define <c><section></c>s (equivalent of -<c><chapter></c> in a Guide) and <c><subsection></c>s (equivalent -of <c><section></c> in a Guide). -</p> - -<p> -Each individual chapter should have its own date and version elements. The -latest date of all chapters and master document will be displayed when a user -browses through all parts of the book. -</p> - -</body> -</section> -</chapter> - -<chapter> <title>Resources</title> <section> <title>Start writing</title> <body> <p> -Guide has been specially designed to be "lean and mean" so that developers can -spend more time writing documentation and less time learning the actual XML +GuideXML has been specially designed to be "lean and mean" so that developers +can spend more time writing documentation and less time learning the actual XML syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" -to start writing quality Gentoo documentation. You might be interested -in our <uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation -Development Tips & Tricks</uri>. If you'd like to help (or have any -questions about guide), please post a message to the <uri -link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd -like to tackle. Have fun! +to start writing quality Gentoo documentation. You might be interested in our +<uri link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Development Tips +& Tricks</uri>. If you'd like to help (or have any questions about +GuideXML), please post a message to the <uri +link="/main/en/lists.xml">gentoo-doc mailing list</uri> stating what you'd like +to tackle. Have fun! </p> </body> -- [EMAIL PROTECTED] mailing list
