neysx 05/10/13 15:57:42 Modified: xml/htdocs/doc/en xml-guide.xml Log: GuideXML improvements requested on #106017
Revision Changes Path 1.52 +151 -35 xml/htdocs/doc/en/xml-guide.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml?rev=1.52&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml?rev=1.52&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/xml-guide.xml.diff?r1=1.51&r2=1.52&cvsroot=gentoo Index: xml-guide.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v retrieving revision 1.51 retrieving revision 1.52 diff -u -r1.51 -r1.52 --- xml-guide.xml 9 Oct 2005 11:00:20 -0000 1.51 +++ xml-guide.xml 13 Oct 2005 15:57:42 -0000 1.52 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.52 2005/10/13 15:57:42 neysx Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/xml-guide.xml"> @@ -32,8 +32,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>2.26</version> -<date>2005-10-09</date> +<version>2.27</version> +<date>2005-10-11</date> <chapter> <title>Guide basics</title> @@ -62,9 +62,14 @@ <p> If you are planning on contributing documentation to Gentoo, or you want to -test GuideXML, please read the <uri -link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which -contains tips and tricks for documentation development. +test GuideXML, please read our <uri +link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide +which contains tips and tricks for documentation development. +</p> + +<p> +You may want to look at the <uri link="?passthru=1">XML source</uri> of this +document while you read it. </p> </body> @@ -135,7 +140,7 @@ <p> Then, we come to the <c><author></c> tags, which contain information about the various authors of the document. Each <c><author></c> tag -allows for an optional <c>title=</c> element, used to specify the author's +allows for an optional <c>title</c> element, used to specify the author's 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 @@ -297,17 +302,18 @@ <body> <p> -We introduced a lot of new tags in the previous section -- here's what you -need to know. The <c><p></c> (paragraph), <c><pre></c> (code -block), <c><note></c>, <c><warn></c> (warning) and -<c><impo></c> (important) tags all can contain one or more lines of text. -Besides the <c><table></c> element (which we'll cover in just a bit), -these are the only tags that should appear immediately inside a -<c><body></c> element. Another thing -- these tags <e>should not</e> be -stacked -- in other words, don't put a <c><note></c> element inside a -<c><p></c> element. As you might guess, the <c><pre></c> element -preserves its whitespace exactly, making it well-suited for code excerpts. -You must name the <c><pre></c> tag with a caption attribute: +We introduced a lot of new tags in the previous section -- here's what you need +to know. The <c><p></c> (paragraph), <c><pre></c> (code block), +<c><note></c>, <c><warn></c> (warning) and <c><impo></c> +(important) tags all can contain one or more lines of text. Besides the +<c><table></c>, <c><ul></c>, <c><ol></c> and +<c><dl></c> elements (which we'll cover in just a bit), these are the +only tags that should appear immediately inside a <c><body></c> element. +Another thing -- these tags <e>should not</e> be stacked -- in other words, +don't put a <c><note></c> element inside a <c><p></c> element. As +you might guess, the <c><pre></c> element preserves its whitespace +exactly, making it well-suited for code excerpts. You must name the +<c><pre></c> tag with a caption attribute: </p> <pre caption="Named <pre>"> @@ -320,14 +326,42 @@ </body> </section> <section> -<title><path>, <c>, <i>, <b> and <e></title> +<title>Epigraphs</title> +<body> + +<p by="Anonymous student"> +Delegates from the original 13 states formed the Contented Congress. Thomas +Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration +of Independence. Franklin discovered electricity by rubbing two cats backwards +and declared, "A horse divided against itself cannot stand." Franklin died in +1790 and is still dead. +</p> + +<p> +Epigraphs are sometimes used at the beginning of chapters to illustrate what is +to follow. It is simply a paragraph with a <c>by</c> attribute that contains +the signature. +</p> + +<pre caption="Short epigraph"> +<p by="Anonymous student"> +Delegates from the original 13 states formed the... +</p> +</pre> + +</body> +</section> +<section> +<title> + <path>, <c>, <i>, <b>, <e>, <sub> and <sup> +</title> <body> <p> -The <c><path></c>, <c><c></c>, <c><b></c> and <c><e></c> elements can -be used inside any child <c><body></c> tag, except for -<c><pre></c>. The <c><i></c> element can only be used inside -<c><pre></c>. +The <c><path></c>, <c><c></c>, <c><b></c>, <c><e></c>, +<c><sub></c> and <c><sup></c> elements can be used inside any child +<c><body></c> tag, except for <c><pre></c>. The <c><i></c> +element can only be used inside <c><pre></c>. </p> <p> @@ -369,6 +403,11 @@ prose more <e>punch</e>! </p> +<p> +The <c><sub></c> and <c><sup></c> elements are used to specify +<sub>subscript</sub> and <sup>superscript</sup>. +</p> + </body> </section> <section> @@ -409,9 +448,9 @@ <p> Here's how to insert a figure into a document -- <c><figure link="mygfx.png" short="my picture" caption="my favorite picture of all -time"/></c>. The <c>link=</c> attribute points to the actual graphic image, -the <c>short=</c> attribute specifies a short description (currently used for -the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult +time"/></c>. The <c>link</c> attribute points to the actual graphic image, +the <c>short</c> attribute specifies a short description (currently used for +the image's HTML <c>alt</c> attribute), and a caption. Not too difficult :) We also support the standard HTML-style <img src="foo.gif"/> tag for adding images without captions, borders, etc. </p> @@ -419,13 +458,13 @@ </body> </section> <section> -<title>Tables and lists</title> +<title>Tables</title> <body> <p> -Guide supports a simplified table syntax similar to that of HTML. To start a +Guide 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 +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> @@ -434,13 +473,91 @@ </p> <p> +Besides, the table header tag (<c><th></c>) accepts the <c>colspan</c> +and <c>rowspan</c> attributes to span titles across rows, columns or both as +shown below: +</p> + +<table> + <tr> + <th colspan="4">This title spans 4 columns</th> + </tr> + <tr> + <th rowspan="3">This title spans 3 rows</th> + <ti>Item A1</ti> + <ti>Item A2</ti> + <ti>Item A3</ti> + </tr> + <tr> + <ti>Item B1</ti> + <th colspan="2" rowspan="2">Blocky 2x2 title</th> + </tr> + <tr> + <ti>Item C1</ti> + </tr> -- [email protected] mailing list
