Apply Neil's PR before he does :-). Codify the writing style a little

further.

PR:             docs/14248
Submitted by:   Neil Blakey-Milner <nbm@mithrandr.moria.org>

1 files changed, 111 insertions, 2 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index 51801ef575..95c9cb768b 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -27,7 +27,7 @@
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
-     $FreeBSD$
+     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v 1.5 1999/09/06 06:52:44 peter Exp $
 -->
 
 <chapter id="writing-style">
@@ -123,6 +123,22 @@
 	</informalexample>
       </listitem>
     </varlistentry>
+    <varlistentry>
+      <term>Two spaces at the end of sentences</term>
+
+      <listitem>
+	<para>Always use two spaces at the end of sentences, as this
+	  improves readability, and eases use of tools such as
+	  <application>emacs</application>.</para>
+
+	<para>While it may be argued that a capital letter following
+	  the end of sentence period, this is not the case, especially
+	  in name usage.  <quote>Jordan K. Hubbard</quote> is a good
+	  example; it has a capital <literal>H</literal> following a
+	  period and a space, and there certainly isn't a new sentence
+	  there.</para>
+      </listitem>
+    </varlistentry>
   </variablelist>
 
   <para>For more information about writing style, see <ulink
@@ -161,7 +177,7 @@
 	over more than one line.</para>
 
       <para>For example, the source for this section looks something
-	like;</para>
+	like:</para>
 
       <programlisting>
 <![ CDATA [+--- This is column 0
@@ -197,6 +213,99 @@ V
     </sect2>
 
     <sect2>
+      <title>Tag style</title>
+
+      <sect3>
+	<title>Tag spacing</title>
+	
+	<para>Tags that start at the same indent as a previous tag
+	  should be separated by a blank line, and those that are not
+	  at the same indent as a previous tag should not:</para>
+
+	<informalexample>
+	  <programlisting><![ CDATA [<article>
+  <artheader>
+    <title>NIS</title>
+
+    <pubdate>October 1999</pubdata>
+
+    <abstract>
+      <para>...
+	...
+	...</para>
+    </abstract>
+  </artheader>
+
+  <sect1>
+    <title>...</title>
+
+    <para>...</para>
+  </sect1>
+
+  <sect1>
+    <title>...</title>
+
+    <para>...</para>
+  </sect1>
+</article>]]></programlisting>
+	</informalexample>
+      </sect3>
+
+      <sect3>
+	<title>Special tags</title>
+
+	<para>Some tags just don't follow the indenting rules of the
+	  previous section; <sgmltag>screen</sgmltag> and
+	  <sgmltag>programlisting</sgmltag> should always be
+	  left-aligned.</para>
+
+	<informalexample>
+	  <programlisting><![ RCDATA [<informalexample>
+<programlisting>
+&hellip;
+</programlisting>
+</informalexample>]]></programlisting>
+	</informalexample>
+
+	<para><sgmltag>informalexample</sgmltag> also should be
+	  left-aligned when it wraps a <sgmltag>screen</sgmltag> or
+	  <sgmltag>programlisting</sgmltag>.</para>
+
+	<para>These examples should be separated from the rest of the
+	  content by a blank line before and after.</para>
+      </sect3>
+
+      <sect3>
+	<title>Separating tags</title>
+
+	<para>Tags like <sgmltag>itemizedlist</sgmltag> which will
+	  always have further tags inside them, and in fact don't take
+	  character data themselves, are always on a line by
+	  themselves.</para>
+
+	<para>Tags like <sgmltag>para</sgmltag> and
+	  <sgmltag>term</sgmltag> don't need other tags to contain
+	  normal character data, and their contents begin immediately
+	  after the tag, <emphasis>on the same line</emphasis>.</para>
+
+	<para>The same applies to when these two types of tags
+	  close.</para>
+
+	<para>This leads to an obvious problem when mixing these
+	  tags.</para>
+
+	<para>When a starting tag which cannot contain character data
+	  directly follows a tag of the type that requires other tags
+	  within it to use character data, they are on separate lines.
+	  The second tag should be properly indented.</para>
+
+	<para>When a tag which can contain character data closes
+	  directly after a tag which cannot contain character data
+	  closes, they co-exist on the same line.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
       <title>White space changes</title>
 
       <para>When committing changes, <emphasis>do not commit changes to the