neysx 05/10/09 11:00:20 Modified: xml/htdocs/doc/en xml-guide.xml Log: Documented disclaimers and some extra fixes
Revision Changes Path 1.51 +85 -29 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.51&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.51&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.50&r2=1.51&cvsroot=gentoo Index: xml-guide.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v retrieving revision 1.50 retrieving revision 1.51 diff -u -r1.50 -r1.51 --- xml-guide.xml 9 Oct 2005 06:07:09 -0000 1.50 +++ xml-guide.xml 9 Oct 2005 11:00:20 -0000 1.51 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.50 2005/10/09 06:07:09 vapier Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xml-guide.xml,v 1.51 2005/10/09 11:00:20 neysx Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/xml-guide.xml"> @@ -113,16 +113,18 @@ On the first lines, we see the requisite tag that identifies this as an XML 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> +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. The <c>lang</c> attribute -can 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. +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. </p> <p> @@ -305,11 +307,11 @@ 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 can also name the <c><pre></c> tag: +You must name the <c><pre></c> tag with a caption attribute: </p> <pre caption="Named <pre>"> -<pre caption = "Output of uptime"> +<pre caption="Output of uptime"> # <i>uptime</i> 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 </pre> @@ -318,11 +320,11 @@ </body> </section> <section> -<title><path>, <c>, <i> and <e></title> +<title><path>, <c>, <i>, <b> and <e></title> <body> <p> -The <c><path></c>, <c><c></c> and <c><e></c> elements can +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>. @@ -356,6 +358,11 @@ </p> <p> +As you might have guessed, <c><b></c> is used to <b>boldface</b> some +text. +</p> + +<p> <c><e></c> is used to apply emphasis to a word or phrase; for example: I <e>really</e> should use semicolons more often. As you can see, this text is offset from the regular paragraph type for emphasis. This helps to give your @@ -369,9 +376,11 @@ <body> <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>. +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>. </p> <p> @@ -414,15 +423,14 @@ <body> <p> -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> +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 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 -first row. Currently, these tags don't support any attributes, but some might -be added (such as a <c>caption=</c> attribute for <c><table></c>) later. +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 +first row. </p> <p> @@ -470,6 +478,51 @@ </body> </section> +<section> +<title>Disclaimers and obsolete documents</title> +<body> + +<p> +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: +</p> + +<ul> + <li> + <b>articles</b> is used for <uri link="/doc/en/articles/">republished + articles</uri> + </li> + <li> + <b>draft</b> is used to indicate a document is still being worked on and + should not be considered official + </li> + <li> + <b>oldbook</b> is used on old handbooks to indicate they are not maintained + anymore + </li> + <li><b>obsolete</b> is used to mark a document as obsolete.</li> +</ul> + +<p> +When marking a document as obsolete, you might want to add a link to a new +version. The <c>redirect</c> attribute does just that. The user might be +automatically redirected to the new page but you should not rely on that +behaviour. +</p> + +<pre caption="Disclaimer sample"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header$ --> + +<guide link="/doc/en/gentoo-x86-install.xml" disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml"> +<title>Gentoo x86 Installation Guide</title> + +<author title="Author"> +... +</pre> + +</body> +</section> </chapter> <chapter> @@ -517,17 +570,20 @@ <p> <b>Word-wrapping</b> must be applied at 80 characters except inside -<c><pre></c>. Only when there is no other choice can be deviated from -this rule (for instance when a URL exceeds the maximum amount of characters). -The editor must then wrap whenever the first whitespace occurs. +<c><pre></c>. You may only deviate from this rule when there is no other +choice (for instance when a URL exceeds the maximum amount of characters). The +editor must then wrap whenever the first whitespace occurs. You should try to +keep the <e>rendered</e> content of <c><pre></c> elements within 80 +columns to help console users. </p> <p> -<b>Indentation</b> may not be used, except with the XML-constructs of which -the parent XML-tags are <c><tr></c> (from <c><table></c>), -<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation -is used, it <e>must</e> be two spaces for each indentation. That means <e>no</e> -tabs and <e>not</e> more spaces. +<b>Indentation</b> may not be used, except with the XML-constructs of which the +parent XML-tags are <c><tr></c> (from <c><table></c>), +<c><ul></c>, <c><ol></c> and <c><author></c>. If indentation +is used, it <e>must</e> be two spaces for each indentation. That means <e>no +tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in GuideXML +documents. </p> <p> -- [email protected] mailing list
