From 1b63b7c4976f3d60dae6e2cc6d0debafb37e0c4f Mon Sep 17 00:00:00 2001 From: "Paul W. Frields" Date: Mon, 5 Feb 2007 00:33:47 +0000 Subject: Retagged some elements to make things more DocBooky. Use sgmltag to advantage, cool! --- en_US/writing-guidelines.xml | 125 ++++++++++++++++++++++++------------------- 1 file changed, 69 insertions(+), 56 deletions(-) (limited to 'en_US') diff --git a/en_US/writing-guidelines.xml b/en_US/writing-guidelines.xml index c791274..a51b0d0 100644 --- a/en_US/writing-guidelines.xml +++ b/en_US/writing-guidelines.xml @@ -17,7 +17,7 @@ RTFM - read the f*'ing manual + read the fine manual humor @@ -30,9 +30,8 @@ guidelines that must be followed such as naming conventions. This chapter only discusses tags used for documentation for the &PROJECT;, - not all available DocBook XML tags. For the complete list, refer to: - - http://www.docbook.org/tdg/en/html/docbook.html + not all available DocBook XML tags. For the complete list, refer to + .
@@ -57,7 +56,7 @@
]]> IDs are unique identifiers, allowing DocBook XML to know where - to cross-reference a section or chapter or the like. The + to cross-reference a section, chapter, or other element. The following general rules apply to IDs: @@ -74,7 +73,7 @@ Start the ID with the special short two-character label. This makes URLs and other references to this ID human readable, by - self-identifying what the XML container type is. + self-identifying the XML container type. Two-Character Naming Conventions @@ -90,36 +89,36 @@ - preface - pr- + preface + pr- - chapter - ch- + chapter + ch- - section - sn- + section + sn- - figure - fig- + figure + fig- - table - tb- + table + tb- - appendix - ap- + appendix + ap- - part - pt- + part + pt- - example - ex- + example + ex- @@ -152,79 +151,87 @@ Do Not Use Trademark Entities - Do not use the trademark entities &trade;, &copy;, or - &reg; because the do not produce HTML output that works for all - charsets. The HTML output produces by these entities are declared in - the DTD and cannot be changed via the stylesheet. + Do not use the trademark entities trade, copy, or reg because the do not produce + HTML output that works for all charsets. The HTML output + produces by these entities are declared in the DTD and + cannot be changed via the stylesheet. - Instead, use the trademark tag and its + Instead, use the trademark tag and its associates classes as follows: - <trademark>trademark symbol after me</trademark> + trademarktrademark symbol after + metrademark - <trademark class="registered">registered trademark symbol after me</trademark> + trademark + class="registered"registered trademark symbol + after metrademark - <trademark class="copyright">copyright symbol after me</trademark> + trademark + class="copyright"copyright symbol after + metrademark - Content inside para tags + Content inside para tags - In general, use para tags + In general, use para tags around anything other than a simple paragraph. Doing so will create additional white space within the text itself in the PDF version. - Specifically, do not use para tags around - the following (or, to put this another way, do not embed the - following within para tags): + Specifically, do not use para tags + around the following (or, to put this another way, do not + embed the following within para elements): - <screen> + screen - <itemizedlist> + itemizedlist - <orderedlist> + orderedlist - <variablelist> + variablelist - <table> + table - Content inside para tags within - listitem tags - - Tags and Entities Caveats - - - Content inside para tags within - listitem tags must start - immediately after the beginning <para> tag to avoid extra - white space in the PDF version. - + Content inside para elements within + listitem tags + + Content inside para + elements within listitem + elements must start immediately after + the beginning para tag + to avoid extra white space in the PDF version. - Content inside screen tags + Content inside screen tags - The content inside screen tags - (<screen> and </screen>) + The content inside screen tags + (screen and screen) must be flush left in the XML file; otherwise, the extraneous whitespace will appear in the HTML version. @@ -247,7 +254,7 @@ committed to CVS) the line is updated automatically to include information about the file. For example: - ]]> + ]]> @@ -301,7 +308,7 @@ note - + XML tags admonitions caution @@ -529,8 +536,11 @@ OK. + + @@ -576,8 +586,11 @@ 8032 pts/0 S 0:00 ssh user@host.example.com 8032 pts/1 S 0:00 ssh root@backup.example.com + + -- cgit