From nbm@mithrandr.moria.org Sun Oct 10 08:10:00 1999
Return-Path: <nbm@mithrandr.moria.org>
Received: from terrapin.ru.ac.za (terrapin.ru.ac.za [146.231.128.6])
	by hub.freebsd.org (Postfix) with ESMTP id CBB9D1555B
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 10 Oct 1999 08:09:26 -0700 (PDT)
	(envelope-from nbm@mithrandr.moria.org)
Received: from duca.dialup.ru.ac.za ([146.231.98.24] helo=mithrandr.moria.org)
	by terrapin.ru.ac.za with esmtp (Exim 3.03 #1)
	id 11aKbC-000Irb-00
	for FreeBSD-gnats-submit@freebsd.org; Sun, 10 Oct 1999 17:09:23 +0200
Received: (qmail 86594 invoked by uid 1001); 10 Oct 1999 15:09:14 -0000
Message-Id: <19991010150914.86593.qmail@mithrandr.moria.org>
Date: 10 Oct 1999 15:09:14 -0000
From: nbm@rucus.ru.ac.za
Sender: nbm@mithrandr.moria.org
Reply-To: nbm@rucus.ru.ac.za
To: FreeBSD-gnats-submit@freebsd.org
Subject: codify proposed style
X-Send-Pr-Version: 3.2

>Number:         14248
>Category:       docs
>Synopsis:       codify proposed style
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Oct 10 08:10:00 PDT 1999
>Closed-Date:    Tue Dec 14 09:01:01 PST 1999
>Last-Modified:  Tue Dec 14 09:01:52 PST 1999
>Originator:     Neil Blakey-Milner
>Release:        FreeBSD 4.0-CURRENT i386
>Organization:
Rhodes University Computer Users' Society
>Environment:

FreeBSD mithrandr.moria.org 4.0-CURRENT FreeBSD 4.0-CURRENT #2: Wed Sep 29 17:30:21 SAST 1999     root@mithrandr.moria.org:/usr/src/sys/compile/MITHRANDR  i386

>Description:

Codify the proposed style into the writing-style chapter of the
fdp-primer.

I've left out the <programlisting>/<screen> stuff, awaiting further
discussion.

>How-To-Repeat:

>Fix:

cvs diff: Diffing writing-style
Index: writing-style/chapter.sgml
===================================================================
RCS file: /home/nbm/ncvs/doc/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml,v
retrieving revision 1.5
diff -u -r1.5 chapter.sgml
--- chapter.sgml	1999/09/06 06:52:44	1.5
+++ chapter.sgml	1999/10/10 13:55:40
@@ -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
@@ -194,6 +210,107 @@
 	<literal>sgml-mode</literal> should be loaded automatically, and the
 	Emacs local variables at the bottom of each file should enforce these
 	styles.</para>
+    </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>
+<![ CDATA [
+<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>



>Release-Note:
>Audit-Trail:

From: Tim Vanderhoek <vanderh@ecf.utoronto.ca>
To: nbm@rucus.ru.ac.za
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/14248: codify proposed style
Date: Sun, 10 Oct 1999 18:18:52 -0400

 On Sun, Oct 10, 1999 at 03:09:14PM -0000, nbm@rucus.ru.ac.za wrote:
 > 
 > +	<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>
 
 First quoted line, do you mean "a starting tag which _can_ contain ..."?
 Or do I misunderstand?  (In which case this last piece needs an
 example!)
 
 
 > +	<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>
 
 Although I realize this is how it's currently done, it seems a little
 backwards...
 
 
 -- 
 This is my .signature which gets appended to the end of my messages.
 

From: Neil Blakey-Milner <nbm@mithrandr.moria.org>
To: Tim Vanderhoek <vanderh@ecf.utoronto.ca>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/14248: codify proposed style
Date: Tue, 12 Oct 1999 13:45:22 +0200

 On Sun 1999-10-10 (18:18), Tim Vanderhoek wrote:
 > > +	<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>
 > 
 > First quoted line, do you mean "a starting tag which _can_ contain ..."?
 > Or do I misunderstand?  (In which case this last piece needs an
 > example!)
 
 I mean which cannot (or do not normally) directly contain character
 data, like <informalexample>, <itemizedlist>, <listitem>, and so
 forth.  I suppose there should be a name for it - block and inline is
 a slightly different distinction though.
 
 Things that directly contain character data, like <para> and <term>
 (there must be more) are the other type.
 
 I'll probably have a more coherent patch next week sometime, after
 my sysdev is over.
 
 > > +	<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>
 > 
 > Although I realize this is how it's currently done, it seems a little
 > backwards...
 
 Ok, this is what I had in mind:
 
 <para>Ok, here we go!
   <footnote>
     <para>Well, not really, but almost!</para>
   </footnote></para>
 
 I like this way of doing footnotes, but I suppose we'd better make
 a decision on it. (see my programming-tools patch)
 
 Similarly:
 
 <para>Somehow the next list is in this para
   <itemizedlist>
     <listitem>
       <para>Survival</para>
     </listitem>
     <listitem>
       <para>Self-actualisation</para>
     </listitem>
   </itemizedlist></para>
 
 Where else would you like to put that closing tag?  I don't like this
 way too much either.
 
 Neil
 -- 
 Neil Blakey-Milner
 nbm@rucus.ru.ac.za
 
State-Changed-From-To: open->closed 
State-Changed-By: nik 
State-Changed-When: Tue Dec 14 09:01:01 PST 1999 
State-Changed-Why:  
Patch applied, modulo a couple of minor changes (CDATA -> RCDATA) 
>Unformatted:
