From owner-freebsd-doc Sun Oct 10 8:10:13 1999 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id CE485154AA for ; Sun, 10 Oct 1999 08:10:06 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id IAA65978; Sun, 10 Oct 1999 08:10:06 -0700 (PDT) (envelope-from gnats@FreeBSD.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 ; 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 Reply-To: nbm@rucus.ru.ac.za To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/14248: codify proposed style Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >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 / 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 @@ + + Two spaces at the end of sentences + + + Always use two spaces at the end of sentences, as this + improves readability, and eases use of tools such as + emacs. + + While it may be argued that a capital letter following + the end of sentence period, this is not the case, especially + in name usage. Jordan K. Hubbard is a good + example; it has a capital H following a + period and a space, and there certainly isn't a new sentence + there. + + For more information about writing style, see For example, the source for this section looks something - like; + like: sgml-mode should be loaded automatically, and the Emacs local variables at the bottom of each file should enforce these styles. + + + + Tag style + + + Tag spacing + + 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: + + + + + + NIS + + October 1999 + + + ... + ... + ... + + + + + ... + + ... + + + + ... + + ... + + +]]> + + + + + + Special tags + + Some tags just don't follow the indenting rules of the + previous section; screen and + programlisting should always be + left-aligned. + + + + + +… + + +]]> + + + + informalexample also should be + left-aligned when it wraps a screen or + programlisting. + + These examples should be separated from the rest of the + content by a blank line before and after. + + + + Separating tags + + Tags like itemizedlist which will + always have further tags inside them, and in fact don't take + character data themselves, are always on a line by + themselves. + + Tags like para and + term don't need other tags to contain + normal character data, and their contents begin immediately + after the tag, on the same line. + + The same applies to when these two types of tags + close. + + This leads to an obvious problem when mixing these + tags. + + 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. + + 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. + >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message