Gentoo Archives: gentoo-doc-cvs

From: Xavier Neys <neysx@×××××××××××.org>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] cvs commit: xml-guide.xml
Date: Thu, 13 Oct 2005 15:57:51
Message-Id: 200510131548.j9DFm4pG001568@robin.gentoo.org
1 neysx 05/10/13 15:57:42
2
3 Modified: xml/htdocs/doc/en xml-guide.xml
4 Log:
5 GuideXML improvements requested on #106017
6
7 Revision Changes Path
8 1.52 +151 -35 xml/htdocs/doc/en/xml-guide.xml
9
10 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
11 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
12 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
13
14 Index: xml-guide.xml
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v
17 retrieving revision 1.51
18 retrieving revision 1.52
19 diff -u -r1.51 -r1.52
20 --- xml-guide.xml 9 Oct 2005 11:00:20 -0000 1.51
21 +++ xml-guide.xml 13 Oct 2005 15:57:42 -0000 1.52
22 @@ -1,5 +1,5 @@
23 <?xml version="1.0" encoding="UTF-8"?>
24 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ -->
25 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.52 2005/10/13 15:57:42 neysx Exp $ -->
26 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
27
28 <guide link="/doc/en/xml-guide.xml">
29 @@ -32,8 +32,8 @@
30 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
31 <license/>
32
33 -<version>2.26</version>
34 -<date>2005-10-09</date>
35 +<version>2.27</version>
36 +<date>2005-10-11</date>
37
38 <chapter>
39 <title>Guide basics</title>
40 @@ -62,9 +62,14 @@
41
42 <p>
43 If you are planning on contributing documentation to Gentoo, or you want to
44 -test GuideXML, please read the <uri
45 -link="/proj/en/gdp/doc/doc-tipsntricks.xml">Tips and Tricks</uri> which
46 -contains tips and tricks for documentation development.
47 +test GuideXML, please read our <uri
48 +link="/proj/en/gdp/doc/doc-tipsntricks.xml">Doc Tips 'n' Tricks</uri> guide
49 +which contains tips and tricks for documentation development.
50 +</p>
51 +
52 +<p>
53 +You may want to look at the <uri link="?passthru=1">XML source</uri> of this
54 +document while you read it.
55 </p>
56
57 </body>
58 @@ -135,7 +140,7 @@
59 <p>
60 Then, we come to the <c>&lt;author&gt;</c> tags, which contain information
61 about the various authors of the document. Each <c>&lt;author&gt;</c> tag
62 -allows for an optional <c>title=</c> element, used to specify the author's
63 +allows for an optional <c>title</c> element, used to specify the author's
64 relationship to the document (author, co-author, editor, etc.). In this
65 particular example, the authors' names are enclosed in another tag -- a
66 <c>&lt;mail&gt;</c> tag, used to specify an email address for this particular
67 @@ -297,17 +302,18 @@
68 <body>
69
70 <p>
71 -We introduced a lot of new tags in the previous section -- here's what you
72 -need to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code
73 -block), <c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and
74 -<c>&lt;impo&gt;</c> (important) tags all can contain one or more lines of text.
75 -Besides the <c>&lt;table&gt;</c> element (which we'll cover in just a bit),
76 -these are the only tags that should appear immediately inside a
77 -<c>&lt;body&gt;</c> element. Another thing -- these tags <e>should not</e> be
78 -stacked -- in other words, don't put a <c>&lt;note&gt;</c> element inside a
79 -<c>&lt;p&gt;</c> element. As you might guess, the <c>&lt;pre&gt;</c> element
80 -preserves its whitespace exactly, making it well-suited for code excerpts.
81 -You must name the <c>&lt;pre&gt;</c> tag with a caption attribute:
82 +We introduced a lot of new tags in the previous section -- here's what you need
83 +to know. The <c>&lt;p&gt;</c> (paragraph), <c>&lt;pre&gt;</c> (code block),
84 +<c>&lt;note&gt;</c>, <c>&lt;warn&gt;</c> (warning) and <c>&lt;impo&gt;</c>
85 +(important) tags all can contain one or more lines of text. Besides the
86 +<c>&lt;table&gt;</c>, <c>&lt;ul&gt;</c>, <c>&lt;ol&gt;</c> and
87 +<c>&lt;dl&gt;</c> elements (which we'll cover in just a bit), these are the
88 +only tags that should appear immediately inside a <c>&lt;body&gt;</c> element.
89 +Another thing -- these tags <e>should not</e> be stacked -- in other words,
90 +don't put a <c>&lt;note&gt;</c> element inside a <c>&lt;p&gt;</c> element. As
91 +you might guess, the <c>&lt;pre&gt;</c> element preserves its whitespace
92 +exactly, making it well-suited for code excerpts. You must name the
93 +<c>&lt;pre&gt;</c> tag with a caption attribute:
94 </p>
95
96 <pre caption="Named &lt;pre&gt;">
97 @@ -320,14 +326,42 @@
98 </body>
99 </section>
100 <section>
101 -<title>&lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt; and &lt;e&gt;</title>
102 +<title>Epigraphs</title>
103 +<body>
104 +
105 +<p by="Anonymous student">
106 +Delegates from the original 13 states formed the Contented Congress. Thomas
107 +Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration
108 +of Independence. Franklin discovered electricity by rubbing two cats backwards
109 +and declared, "A horse divided against itself cannot stand." Franklin died in
110 +1790 and is still dead.
111 +</p>
112 +
113 +<p>
114 +Epigraphs are sometimes used at the beginning of chapters to illustrate what is
115 +to follow. It is simply a paragraph with a <c>by</c> attribute that contains
116 +the signature.
117 +</p>
118 +
119 +<pre caption="Short epigraph">
120 +&lt;p by="Anonymous student"&gt;
121 +Delegates from the original 13 states formed the...
122 +&lt;/p&gt;
123 +</pre>
124 +
125 +</body>
126 +</section>
127 +<section>
128 +<title>
129 + &lt;path&gt;, &lt;c&gt;, &lt;i&gt;, &lt;b&gt;, &lt;e&gt;, &lt;sub&gt; and &lt;sup&gt;
130 +</title>
131 <body>
132
133 <p>
134 -The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c> and <c>&lt;e&gt;</c> elements can
135 -be used inside any child <c>&lt;body&gt;</c> tag, except for
136 -<c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c> element can only be used inside
137 -<c>&lt;pre&gt;</c>.
138 +The <c>&lt;path&gt;</c>, <c>&lt;c&gt;</c>, <c>&lt;b&gt;</c>, <c>&lt;e&gt;</c>,
139 +<c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements can be used inside any child
140 +<c>&lt;body&gt;</c> tag, except for <c>&lt;pre&gt;</c>. The <c>&lt;i&gt;</c>
141 +element can only be used inside <c>&lt;pre&gt;</c>.
142 </p>
143
144 <p>
145 @@ -369,6 +403,11 @@
146 prose more <e>punch</e>!
147 </p>
148
149 +<p>
150 +The <c>&lt;sub&gt;</c> and <c>&lt;sup&gt;</c> elements are used to specify
151 +<sub>subscript</sub> and <sup>superscript</sup>.
152 +</p>
153 +
154 </body>
155 </section>
156 <section>
157 @@ -409,9 +448,9 @@
158 <p>
159 Here's how to insert a figure into a document -- <c>&lt;figure
160 link="mygfx.png" short="my picture" caption="my favorite picture of all
161 -time"/&gt;</c>. The <c>link=</c> attribute points to the actual graphic image,
162 -the <c>short=</c> attribute specifies a short description (currently used for
163 -the image's HTML <c>alt=</c> attribute), and a caption. Not too difficult
164 +time"/&gt;</c>. The <c>link</c> attribute points to the actual graphic image,
165 +the <c>short</c> attribute specifies a short description (currently used for
166 +the image's HTML <c>alt</c> attribute), and a caption. Not too difficult
167 :) We also support the standard HTML-style &lt;img src="foo.gif"/&gt; tag
168 for adding images without captions, borders, etc.
169 </p>
170 @@ -419,13 +458,13 @@
171 </body>
172 </section>
173 <section>
174 -<title>Tables and lists</title>
175 +<title>Tables</title>
176 <body>
177
178 <p>
179 -Guide supports a simplified table syntax similar to that of HTML. To start a
180 +Guide supports a simplified table syntax similar to that of HTML. To start a
181 table, use a <c>&lt;table&gt;</c> tag. Start a row with a <c>&lt;tr&gt;</c>
182 -tag. However, for inserting actual table data, we <e>don't</e> support the
183 +tag. However, for inserting actual table data, we <e>don't</e> support the
184 HTML &lt;td&gt; tag; instead, use the <c>&lt;th&gt;</c> if you are inserting a
185 header, and <c>&lt;ti&gt;</c> if you are inserting a normal informational
186 block. You can use a <c>&lt;th&gt;</c> anywhere you can use a <c>&lt;ti&gt;</c>
187 @@ -434,13 +473,91 @@
188 </p>
189
190 <p>
191 +Besides, the table header tag (<c>&lt;th&gt;</c>) accepts the <c>colspan</c>
192 +and <c>rowspan</c> attributes to span titles across rows, columns or both as
193 +shown below:
194 +</p>
195 +
196 +<table>
197 + <tr>
198 + <th colspan="4">This title spans 4 columns</th>
199 + </tr>
200 + <tr>
201 + <th rowspan="3">This title spans 3 rows</th>
202 + <ti>Item A1</ti>
203 + <ti>Item A2</ti>
204 + <ti>Item A3</ti>
205 + </tr>
206 + <tr>
207 + <ti>Item B1</ti>
208 + <th colspan="2" rowspan="2">Blocky 2x2 title</th>
209 + </tr>
210 + <tr>
211 + <ti>Item C1</ti>
212 + </tr>
213
214
215
216 --
217 gentoo-doc-cvs@g.o mailing list