Date: 10 Oct 1999 15:09:14 -0000 From: nbm@rucus.ru.ac.za To: FreeBSD-gnats-submit@freebsd.org Subject: docs/14248: codify proposed style Message-ID: <19991010150914.86593.qmail@mithrandr.moria.org>
next in thread | raw e-mail | index | archive | help
>Number: 14248
>Category: docs
>Synopsis: codify proposed style
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sun Oct 10 08:10:00 PDT 1999
>Closed-Date:
>Last-Modified:
>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>
+…
+</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:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19991010150914.86593.qmail>