diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml | 126 |
1 files changed, 58 insertions, 68 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml index d492ffde43..b461547327 100644 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml @@ -30,11 +30,10 @@ $FreeBSD$ --> - -<chapter id="writing-style"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style"> <title>Writing Style</title> - <sect1 id="writing-style-tips"> + <sect1 xml:id="writing-style-tips"> <title>Tips</title> <para>Technical documentation can be improved by consistent use of @@ -45,7 +44,7 @@ each other. Good writing consists of a balance between them.</para> - <sect2 id="writing-style-be-clear"> + <sect2 xml:id="writing-style-be-clear"> <title>Be Clear</title> <para>Clarity is extremely important. The reader may be a @@ -91,7 +90,7 @@ <quote>do this</quote>.</para> </sect2> - <sect2 id="writing-style-be-complete"> + <sect2 xml:id="writing-style-be-complete"> <title>Be Complete</title> <para>Do not make assumptions about the reader's abilities or @@ -102,7 +101,7 @@ them.</para> </sect2> - <sect2 id="writing-style-be-concise"> + <sect2 xml:id="writing-style-be-concise"> <title>Be Concise</title> <para>While features should be documented completely, sometimes @@ -115,7 +114,7 @@ </sect2> </sect1> - <sect1 id="writing-style-guidelines"> + <sect1 xml:id="writing-style-guidelines"> <title>Guidelines</title> <para>To promote consistency between the myriad authors of the @@ -219,7 +218,7 @@ </informalexample> <para>Manual page references (the second example uses - <sgmltag>citerefentry</sgmltag> with the + <tag>citerefentry</tag> with the <literal>&man.csh.1;</literal> entity):.</para> <informalexample> @@ -250,12 +249,11 @@ </varlistentry> </variablelist> - <para>For more information about writing style, see <ulink - url="http://www.bartleby.com/141/">Elements of - Style</ulink>, by William Strunk.</para> + <para>For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of + Style</link>, by William Strunk.</para> </sect1> - <sect1 id="writing-style-guide"> + <sect1 xml:id="writing-style-guide"> <title>Style Guide</title> <para>To keep the source for the documentation consistent when @@ -265,8 +263,8 @@ <sect2> <title>Letter Case</title> - <para>Tags are entered in lower case, <sgmltag>para</sgmltag>, - <emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para> + <para>Tags are entered in lower case, <tag>para</tag>, + <emphasis>not</emphasis> <tag>PARA</tag>.</para> <para>Text that appears in SGML contexts is generally written in upper case, <literal><!ENTITY…></literal>, and @@ -276,7 +274,7 @@ <literal><!doctype…></literal>.</para> </sect2> - <sect2 id="writing-style-acronyms"> + <sect2 xml:id="writing-style-acronyms"> <title>Acronyms</title> <para>Acronyms should be defined the first time they appear in a @@ -288,10 +286,10 @@ document.</para> <para>All acronyms should be enclosed in - <sgmltag>acronym</sgmltag> tags.</para> + <tag>acronym</tag> tags.</para> </sect2> - <sect2 id="writing-style-indentation"> + <sect2 xml:id="writing-style-indentation"> <title>Indentation</title> <para>The first line in each file starts with no indentation, @@ -309,33 +307,33 @@ <para>For example, the source for this section looks like this:</para> - <programlisting><sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">sect2</sgmltag> - <sgmltag class="starttag">title</sgmltag>Indentation<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>The first line in each file starts with no indentation, - <sgmltag class="starttag">emphasis</sgmltag>regardless<sgmltag class="endtag">emphasis</sgmltag> of the indentation level of - the file which might contain the current file.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>The first line in each file starts with no indentation, + <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of + the file which might contain the current file.<tag class="endtag">para</tag> ... - <sgmltag class="endtag">sect2</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">chapter</sgmltag></programlisting> + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> <para>Configurations to help various text editors conform to these guidelines can be found in <xref linkend="editor-config"/>.</para> </sect2> - <sect2 id="writing-style-tag-style"> + <sect2 xml:id="writing-style-tag-style"> <title>Tag Style</title> - <sect3 id="writing-style-tag-style-spacing"> + <sect3 xml:id="writing-style-tag-style-spacing"> <title>Tag Spacing</title> <para>Tags that start at the same indent as a previous tag @@ -343,44 +341,44 @@ at the same indent as a previous tag should not:</para> <informalexample> - <programlisting><sgmltag class="starttag">article lang='en'</sgmltag> - <sgmltag class="starttag">articleinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag>NIS<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">article lang='en'</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> - <sgmltag class="starttag">pubdate</sgmltag>October 1999<sgmltag class="endtag">pubdate</sgmltag> + <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag>... + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>... ... - ...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">articleinfo</sgmltag> + ...<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">article</sgmltag></programlisting> + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> </informalexample> </sect3> - <sect3 id="writing-style-tag-style-separating"> + <sect3 xml:id="writing-style-tag-style-separating"> <title>Separating Tags</title> - <para>Tags like <sgmltag>itemizedlist</sgmltag> which will + <para>Tags like <tag>itemizedlist</tag> which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves.</para> - <para>Tags like <sgmltag>para</sgmltag> and - <sgmltag>term</sgmltag> do not need other tags to contain + <para>Tags like <tag>para</tag> and + <tag>term</tag> do not need other tags to contain normal character data, and their contents begin immediately after the tag, <emphasis>on the same line</emphasis>.</para> @@ -401,7 +399,7 @@ </sect3> </sect2> - <sect2 id="writing-style-whitespace-changes"> + <sect2 xml:id="writing-style-whitespace-changes"> <title>Whitespace Changes</title> <para><emphasis>Do not commit changes @@ -421,7 +419,7 @@ ignored by translators.</para> </sect2> - <sect2 id="writing-style-nonbreaking-space"> + <sect2 xml:id="writing-style-nonbreaking-space"> <title>Non-Breaking Space</title> <para>Avoid line breaks in places where they look ugly or make @@ -459,7 +457,7 @@ GB. Hardware compression …</literallayout> </sect2> </sect1> - <sect1 id="writing-style-word-list"> + <sect1 xml:id="writing-style-word-list"> <title>Word List</title> <para>This list of words shows the correct spelling and @@ -480,16 +478,12 @@ GB. Hardware compression …</literallayout> <row> <entry>CD-ROM</entry> - <entry><sgmltag - class="starttag">acronym</sgmltag><literal>CD-ROM</literal><sgmltag - class="endtag">acronym</sgmltag></entry> + <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry> </row> <row> <entry>DoS (Denial of Service)</entry> - <entry><sgmltag - class="starttag">acronym</sgmltag><literal>DoS</literal><sgmltag - class="endtag">acronym</sgmltag></entry> + <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry> </row> <row> @@ -535,14 +529,10 @@ GB. Hardware compression …</literallayout> <row> <entry>Subversion</entry> - <entry><sgmltag - class="starttag">application</sgmltag><literal>Subversion</literal><sgmltag - class="endtag">application</sgmltag></entry> + <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry> <entry>Do not refer to the Subversion application as <literal>SVN</literal> in upper case. To refer to the - command, use <sgmltag - class="starttag">command</sgmltag><literal>svn</literal><sgmltag - class="endtag">command</sgmltag>.</entry> + command, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry> </row> <row> |