| 1 |
neysx 05/10/09 11:00:20 |
| 2 |
|
| 3 |
Modified: xml/htdocs/doc/en xml-guide.xml |
| 4 |
Log: |
| 5 |
Documented disclaimers and some extra fixes |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.51 +85 -29 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.51&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.51&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.50&r2=1.51&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.50 |
| 18 |
retrieving revision 1.51 |
| 19 |
diff -u -r1.50 -r1.51 |
| 20 |
--- xml-guide.xml 9 Oct 2005 06:07:09 -0000 1.50 |
| 21 |
+++ xml-guide.xml 9 Oct 2005 11:00:20 -0000 1.51 |
| 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.50 2005/10/09 06:07:09 vapier Exp $ --> |
| 25 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ --> |
| 26 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 27 |
|
| 28 |
<guide link="/doc/en/xml-guide.xml"> |
| 29 |
@@ -113,16 +113,18 @@ |
| 30 |
On the first lines, we see the requisite tag that identifies this as an XML |
| 31 |
document and specifies its DTD. The <c><!-- $Header$ --></c> line |
| 32 |
will be automatically modified by the CVS server and helps to track revisions. |
| 33 |
-Next, there's a <c><guide></c> tag -- the entire guide document is |
| 34 |
-enclosed within a <c><guide> </guide></c> pair. The <c>link</c> |
| 35 |
+Next, there's a <c><guide></c> tag -- the entire guide document is |
| 36 |
+enclosed within a <c><guide> </guide></c> pair. The <c>link</c> |
| 37 |
attribute is compulsory and should preferably contain the absolute path to the |
| 38 |
document relatively to the document root even though the file name alone will |
| 39 |
work. It is mainly used to generate a link to a printer-friendly version of |
| 40 |
-your document. If you use a wrong value, the link to the printable version |
| 41 |
-will either not work or point to a wrong document. The <c>lang</c> attribute |
| 42 |
-can be used to specify the language code of your document. It is used to format |
| 43 |
-the date and insert strings like "<e>Note</e>", "<e>Content</e>", etc. in the |
| 44 |
-specified language. The default is English. |
| 45 |
+your document. If you use a wrong value, the link to the printable version will |
| 46 |
+either not work or point to a wrong document. Translated documents <e>must</e> |
| 47 |
+specify the full path because it is also used to check whether a more recent |
| 48 |
+original document exists. The <c>lang</c> attribute should be used to specify |
| 49 |
+the language code of your document. It is used to format the date and insert |
| 50 |
+strings like "<e>Note</e>", "<e>Content</e>", etc. in the specified language. |
| 51 |
+The default is English. |
| 52 |
</p> |
| 53 |
|
| 54 |
<p> |
| 55 |
@@ -305,11 +307,11 @@ |
| 56 |
stacked -- in other words, don't put a <c><note></c> element inside a |
| 57 |
<c><p></c> element. As you might guess, the <c><pre></c> element |
| 58 |
preserves its whitespace exactly, making it well-suited for code excerpts. |
| 59 |
-You can also name the <c><pre></c> tag: |
| 60 |
+You must name the <c><pre></c> tag with a caption attribute: |
| 61 |
</p> |
| 62 |
|
| 63 |
<pre caption="Named <pre>"> |
| 64 |
-<pre caption = "Output of uptime"> |
| 65 |
+<pre caption="Output of uptime"> |
| 66 |
# <i>uptime</i> |
| 67 |
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 |
| 68 |
</pre> |
| 69 |
@@ -318,11 +320,11 @@ |
| 70 |
</body> |
| 71 |
</section> |
| 72 |
<section> |
| 73 |
-<title><path>, <c>, <i> and <e></title> |
| 74 |
+<title><path>, <c>, <i>, <b> and <e></title> |
| 75 |
<body> |
| 76 |
|
| 77 |
<p> |
| 78 |
-The <c><path></c>, <c><c></c> and <c><e></c> elements can |
| 79 |
+The <c><path></c>, <c><c></c>, <c><b></c> and <c><e></c> elements can |
| 80 |
be used inside any child <c><body></c> tag, except for |
| 81 |
<c><pre></c>. The <c><i></c> element can only be used inside |
| 82 |
<c><pre></c>. |
| 83 |
@@ -356,6 +358,11 @@ |
| 84 |
</p> |
| 85 |
|
| 86 |
<p> |
| 87 |
+As you might have guessed, <c><b></c> is used to <b>boldface</b> some |
| 88 |
+text. |
| 89 |
+</p> |
| 90 |
+ |
| 91 |
+<p> |
| 92 |
<c><e></c> is used to apply emphasis to a word or phrase; for example: |
| 93 |
I <e>really</e> should use semicolons more often. As you can see, this text is |
| 94 |
offset from the regular paragraph type for emphasis. This helps to give your |
| 95 |
@@ -369,9 +376,11 @@ |
| 96 |
<body> |
| 97 |
|
| 98 |
<p> |
| 99 |
-We've taken a look at the <c><mail></c> tag earlier; it's used to link |
| 100 |
-some text with a particular email address, and takes the form <c><mail |
| 101 |
-link="foo@×××.com">Mr. Foo Bar</mail></c>. |
| 102 |
+We've taken a look at the <c><mail></c> tag earlier; it's used to link |
| 103 |
+some text with a particular email address, and takes the form <c><mail |
| 104 |
+link="foo@×××.com">Mr. Foo Bar</mail></c>. If you want to display the |
| 105 |
+email address, you can use <c><mail>foo@×××.com</mail></c>, this |
| 106 |
+would be displayed as <mail>foo@×××.com</mail>. |
| 107 |
</p> |
| 108 |
|
| 109 |
<p> |
| 110 |
@@ -414,15 +423,14 @@ |
| 111 |
<body> |
| 112 |
|
| 113 |
<p> |
| 114 |
-Guide supports a simplified table syntax similar to that of HTML. To start |
| 115 |
-a table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
| 116 |
+Guide supports a simplified table syntax similar to that of HTML. To start a |
| 117 |
+table, use a <c><table></c> tag. Start a row with a <c><tr></c> |
| 118 |
tag. However, for inserting actual table data, we <e>don't</e> support the |
| 119 |
HTML <td> tag; instead, use the <c><th></c> if you are inserting a |
| 120 |
header, and <c><ti></c> if you are inserting a normal informational |
| 121 |
-block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
| 122 |
--- there's no requirement that <c><th></c> elements appear only in the |
| 123 |
-first row. Currently, these tags don't support any attributes, but some might |
| 124 |
-be added (such as a <c>caption=</c> attribute for <c><table></c>) later. |
| 125 |
+block. You can use a <c><th></c> anywhere you can use a <c><ti></c> |
| 126 |
+-- there's no requirement that <c><th></c> elements appear only in the |
| 127 |
+first row. |
| 128 |
</p> |
| 129 |
|
| 130 |
<p> |
| 131 |
@@ -470,6 +478,51 @@ |
| 132 |
|
| 133 |
</body> |
| 134 |
</section> |
| 135 |
+<section> |
| 136 |
+<title>Disclaimers and obsolete documents</title> |
| 137 |
+<body> |
| 138 |
+ |
| 139 |
+<p> |
| 140 |
+A disclaimer attribute can be applied to guides and handbooks to display a predefined disclaimer at the top of the document. The available disclaimers are: |
| 141 |
+</p> |
| 142 |
+ |
| 143 |
+<ul> |
| 144 |
+ <li> |
| 145 |
+ <b>articles</b> is used for <uri link="/doc/en/articles/">republished |
| 146 |
+ articles</uri> |
| 147 |
+ </li> |
| 148 |
+ <li> |
| 149 |
+ <b>draft</b> is used to indicate a document is still being worked on and |
| 150 |
+ should not be considered official |
| 151 |
+ </li> |
| 152 |
+ <li> |
| 153 |
+ <b>oldbook</b> is used on old handbooks to indicate they are not maintained |
| 154 |
+ anymore |
| 155 |
+ </li> |
| 156 |
+ <li><b>obsolete</b> is used to mark a document as obsolete.</li> |
| 157 |
+</ul> |
| 158 |
+ |
| 159 |
+<p> |
| 160 |
+When marking a document as obsolete, you might want to add a link to a new |
| 161 |
+version. The <c>redirect</c> attribute does just that. The user might be |
| 162 |
+automatically redirected to the new page but you should not rely on that |
| 163 |
+behaviour. |
| 164 |
+</p> |
| 165 |
+ |
| 166 |
+<pre caption="Disclaimer sample"> |
| 167 |
+<?xml version="1.0" encoding="UTF-8"?> |
| 168 |
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 169 |
+<!-- $Header$ --> |
| 170 |
+ |
| 171 |
+<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> |
| 172 |
+<title>Gentoo x86 Installation Guide</title> |
| 173 |
+ |
| 174 |
+<author title="Author"> |
| 175 |
+... |
| 176 |
+</pre> |
| 177 |
+ |
| 178 |
+</body> |
| 179 |
+</section> |
| 180 |
</chapter> |
| 181 |
|
| 182 |
<chapter> |
| 183 |
@@ -517,17 +570,20 @@ |
| 184 |
|
| 185 |
<p> |
| 186 |
<b>Word-wrapping</b> must be applied at 80 characters except inside |
| 187 |
-<c><pre></c>. Only when there is no other choice can be deviated from |
| 188 |
-this rule (for instance when a URL exceeds the maximum amount of characters). |
| 189 |
-The editor must then wrap whenever the first whitespace occurs. |
| 190 |
+<c><pre></c>. You may only deviate from this rule when there is no other |
| 191 |
+choice (for instance when a URL exceeds the maximum amount of characters). The |
| 192 |
+editor must then wrap whenever the first whitespace occurs. You should try to |
| 193 |
+keep the <e>rendered</e> content of <c><pre></c> elements within 80 |
| 194 |
+columns to help console users. |
| 195 |
</p> |
| 196 |
|
| 197 |
<p> |
| 198 |
-<b>Indentation</b> may not be used, except with the XML-constructs of which |
| 199 |
-the parent XML-tags are <c><tr></c> (from <c><table></c>), |
| 200 |
-<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation |
| 201 |
-is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e> |
| 202 |
-tabs and <e>not</e> more spaces. |
| 203 |
+<b>Indentation</b> may not be used, except with the XML-constructs of which the |
| 204 |
+parent XML-tags are <c><tr></c> (from <c><table></c>), |
| 205 |
+<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation |
| 206 |
+is used, it <e>must</e> be two spaces for each indentation. That means <e>no |
| 207 |
+tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML |
| 208 |
+documents. |
| 209 |
</p> |
| 210 |
|
| 211 |
<p> |
| 212 |
|
| 213 |
|
| 214 |
|
| 215 |
-- |
| 216 |
gentoo-doc-cvs@g.o mailing list |
Archives