svn commit: r42391 - head/en_US.ISO8859-1/books/fdp-primer/writing-style
Warren Block
wblock at FreeBSD.org
Tue Jul 23 00:40:26 UTC 2013
Author: wblock
Date: Tue Jul 23 00:40:25 2013
New Revision: 42391
URL: http://svnweb.freebsd.org/changeset/doc/42391
Log:
More simplification and cleanups, replacement of CDATA sections with
sgmltags.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Tue Jul 23 00:00:21 2013 (r42390)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Tue Jul 23 00:40:25 2013 (r42391)
@@ -119,7 +119,7 @@
<title>Guidelines</title>
<para>To promote consistency between the myriad authors of the
- FreeBSD documentation, some guidelines have been drawn up for
+ &os; documentation, some guidelines have been drawn up for
authors to follow.</para>
<variablelist>
@@ -148,7 +148,7 @@
<listitem>
<para>Do not use contractions. Always spell the phrase out
- in full. <quote>Don't use contractions</quote> would be
+ in full. <quote>Don't use contractions</quote> is
wrong.</para>
<para>Avoiding contractions makes for a more formal tone, is
@@ -166,7 +166,7 @@
from the others with a comma and the word
<quote>and</quote>.</para>
- <para>For example, look at the following:</para>
+ <para>For example:</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
@@ -190,47 +190,44 @@
<term>Avoid redundant phrases</term>
<listitem>
- <para>Try not to use redundant phrases. In particular,
+ <para>Do not use redundant phrases. In particular,
<quote>the command</quote>, <quote>the file</quote>, and
- <quote>man command</quote> are probably redundant.</para>
+ <quote>man command</quote> are often redundant.</para>
- <para>These two examples show this for commands. The second
- example is preferred.</para>
+ <para>For example, commands:</para>
<informalexample>
- <para>Use the command <command>svn</command> to update
- your sources.</para>
+ <para>Wrong: Use the command <command>svn</command> to update
+ sources.</para>
</informalexample>
<informalexample>
- <para>Use <command>svn</command> to update your
+ <para>Right: Use <command>svn</command> to update
sources.</para>
</informalexample>
- <para>These two examples show this for filenames. The
- second example is preferred.</para>
+ <para>Filenames:</para>
<informalexample>
- <para>… in the filename
+ <para>Wrong: … in the filename
<filename>/etc/rc.local</filename>…</para>
</informalexample>
<informalexample>
- <para>… in
+ <para>Right: … in
<filename>/etc/rc.local</filename>…</para>
</informalexample>
- <para>These two examples show this for manual references.
- The second example is preferred (the second example uses
- <sgmltag>citerefentry</sgmltag>).</para>
+ <para>Manual page references (the second example uses
+ <sgmltag>citerefentry</sgmltag> with the <literal>&man.csh.1;</literal> entity):.</para>
<informalexample>
- <para>See <command>man csh</command> for more
+ <para>Wrong: See <command>man csh</command> for more
information.</para>
</informalexample>
<informalexample>
- <para>See &man.csh.1;.</para>
+ <para>Right: See &man.csh.1;.</para>
</informalexample>
</listitem>
</varlistentry>
@@ -239,7 +236,7 @@
<term>Two spaces between sentences</term>
<listitem>
- <para>Always use two spaces between sentences, as this
+ <para>Always use two spaces between sentences, as it
improves readability and eases use of tools such as
<application>Emacs</application>.</para>
@@ -300,16 +297,15 @@
<emphasis>regardless</emphasis> of the indentation level of
the file which might contain the current file.</para>
- <para>Opening tags increase the indentation level by 2 spaces.
- Closing tags decrease the indentation level by 2 spaces.
- Blocks of 8 spaces at the start of a line should be replaced
+ <para>Opening tags increase the indentation level by two spaces.
+ Closing tags decrease the indentation level by two spaces.
+ Blocks of eight spaces at the start of a line should be replaced
with a tab. Do not use spaces in front of tabs, and do not
add extraneous whitespace at the end of a line. Content
within elements should be indented by two spaces if the
content runs over more than one line.</para>
- <para>For example, the source for this section looks something
- like:</para>
+ <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>
@@ -345,31 +341,31 @@
at the same indent as a previous tag should not:</para>
<informalexample>
- <programlisting><![CDATA[<article lang='en'>
- <articleinfo>
- <title>NIS</title>
+ <programlisting><sgmltag class="starttag">article lang='en'</sgmltag>
+ <sgmltag class="starttag">articleinfo</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>NIS<sgmltag class="endtag">title</sgmltag>
- <pubdate>October 1999</pubdate>
+ <sgmltag class="starttag">pubdate</sgmltag>October 1999<sgmltag class="endtag">pubdate</sgmltag>
- <abstract>
- <para>...
+ <sgmltag class="starttag">abstract</sgmltag>
+ <sgmltag class="starttag">para</sgmltag>...
...
- ...</para>
- </abstract>
- </articleinfo>
+ ...<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">abstract</sgmltag>
+ <sgmltag class="endtag">articleinfo</sgmltag>
- <sect1>
- <title>...</title>
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag>
- <para>...</para>
- </sect1>
+ <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">sect1</sgmltag>
- <sect1>
- <title>...</title>
+ <sgmltag class="starttag">sect1</sgmltag>
+ <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag>
- <para>...</para>
- </sect1>
-</article>]]></programlisting>
+ <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag>
+ <sgmltag class="endtag">sect1</sgmltag>
+<sgmltag class="endtag">article</sgmltag></programlisting>
</informalexample>
</sect3>
@@ -404,25 +400,23 @@
</sect2>
<sect2>
- <title>White Space Changes</title>
+ <title>Whitespace Changes</title>
- <para>When committing changes, <emphasis>do not commit changes
- to the content at the same time as changes to the
+ <para><emphasis>Do not commit changes
+ to content at the same time as changes to
formatting</emphasis>.</para>
- <para>This is so that the teams that convert the documentation
- to other languages can quickly see what content has actually
- changed in your commit, without having to decide whether a
- line has changed because of the content, or just because it
- has been refilled.</para>
-
- <para>For example, if you have added two sentences to a
- paragraph, such that the line lengths on the paragraph now go
- over 80 columns, first commit your change with the too-long
- line lengths. Then fix the line wrapping, and commit this
+ <para>When content and whitespace changes are kept separate, translation teams
+ can easily see whether a change was content that must be translated
+ or only whitespace.</para>
+
+ <para>For example, if two sentences have been added to a
+ paragraph so that the line lengths now go
+ over 80 columns, first commit the change with the too-long
+ lines. Then fix the line wrapping, and commit this
second change. In the commit message for the second change,
- be sure to indicate that this is a whitespace-only change, and
- that the translation team can ignore it.</para>
+ indicate that this is a whitespace-only change that can be
+ ignored by translators.</para>
</sect2>
<sect2>
@@ -444,18 +438,18 @@ GB. Hardware compression …</lite
<itemizedlist>
<listitem>
<para>between numbers and units:</para>
- <programlisting><![CDATA[57600 bps]]></programlisting>
+ <programlisting>57600 bps</programlisting>
</listitem>
<listitem>
<para>between program names and version numbers:</para>
- <programlisting><![CDATA[FreeBSD 4.7]]></programlisting>
+ <programlisting>&os; 9.2</programlisting>
</listitem>
<listitem>
<para>between multiword names (use with caution when
applying this to more than 3-4 word names like
- <quote>The FreeBSD Brazilian Portuguese Documentation
+ <quote>The &os; Brazilian Portuguese Documentation
Project</quote>):</para>
<programlisting><![CDATA[Sun Microsystems]]></programlisting>
</listitem>
@@ -467,7 +461,7 @@ GB. Hardware compression …</lite
<title>Word List</title>
<para>This list of words shows the correct spelling and
- capitalization when used in FreeBSD Documentation. If a word is
+ capitalization when used in &os; documentation. If a word is
not on this list, ask about it on the &a.doc;.</para>
<informaltable frame="none" pgwide="0">
More information about the svn-doc-all
mailing list