From owner-freebsd-doc  Wed Oct  6  6:28:45 1999
Delivered-To: freebsd-doc@freebsd.org
Received: from terrapin.ru.ac.za (terrapin.ru.ac.za [146.231.128.6])
	by hub.freebsd.org (Postfix) with ESMTP id C66F1152AD
	for <doc@freebsd.org>; Wed,  6 Oct 1999 06:28:18 -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 11Yr71-000Jbz-00
	for doc@FreeBSD.org; Wed, 06 Oct 1999 15:28:07 +0200
Received: (qmail 33366 invoked by uid 1001); 6 Oct 1999 13:25:49 -0000
Date: Wed, 6 Oct 1999 15:25:49 +0200
From: Neil Blakey-Milner <nbm@mithrandr.moria.org>
To: FreeBSD Documentation Project <doc@FreeBSD.org>
Subject: Style Challenge!
Message-ID: <19991006152549.A33181@mithrandr.moria.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Mailer: Mutt 0.95.1i
Organization: Rhodes University Computer Users' Society
X-Operating-System: FreeBSD 4.0-CURRENT i386
X-URL: http://rucus.ru.ac.za/~nbm/
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

Hi,

(First of all, excuses to those who understand what the topic refers
to.)

I've just re-indented and re-marked-up all the articles, and here's
the rules of thumb I used, and would like discussion on:

(I used vim with 'set ai sts=2 ts=8 sw=2 tw=70')

. 70 column wrap?  (Emacs' sgml-mode seemed to give me that, when
sgml-fill worked properly)

. Two spaces after '.'

. No spaces at the end of a line (including no "empty" lines with spaces
in them - is it Emacs that does this?)

. Ignoring the above for <screen>/<programlisting>

. Try not to use <para> around <screen>, <variablelist>, <itemizedlist>,
<qandaset> if at all possible.

. Treat <note>, <warning>, <listitem>, <abstract>, <question>, <answer>,
<footnote> as block tags.

. Always separate tags with tags on same indent level by an empty line,
and no empty line on reducing/increasing indent -

<para>foo
  foo</para>

<para>

and:
<sect2>
  <title>foo</title>

  <para>foo</para>
</sect2>

. Always close inline tags on the same line as its contents - ie, never:

<para>foo foo blah blah blah
  </para>

Any comments?

(oh, and does it matter about combining whitespace/markup/content
changes in the articles at this point, without any translations?)

Neil
-- 
Neil Blakey-Milner
nbm@rucus.ru.ac.za


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message