From owner-svn-doc-all@FreeBSD.ORG Mon Jul 22 03:57:41 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id EDF59924; Mon, 22 Jul 2013 03:57:40 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id DF88B20BA; Mon, 22 Jul 2013 03:57:40 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6M3veSq002361; Mon, 22 Jul 2013 03:57:40 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6M3vehk002360; Mon, 22 Jul 2013 03:57:40 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307220357.r6M3vehk002360@svn.freebsd.org> From: Warren Block Date: Mon, 22 Jul 2013 03:57:40 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42368 - head/en_US.ISO8859-1/books/fdp-primer/writing-style X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 22 Jul 2013 03:57:41 -0000 Author: wblock Date: Mon Jul 22 03:57:40 2013 New Revision: 42368 URL: http://svnweb.freebsd.org/changeset/doc/42368 Log: Spelling correction. Explain that two spaces come between sentences, not at the beginning or end of a sentence. Modernize the acronym guidelines. Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Mon Jul 22 01:45:43 2013 (r42367) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Mon Jul 22 03:57:40 2013 (r42368) @@ -38,7 +38,7 @@ Tips Technical documentation can be improved by consistent use of - several principes. Most of these can be classified into three + several principles. Most of these can be classified into three goals: be clear, be complete, and be concise. These goals can conflict with @@ -236,20 +236,19 @@ - Two spaces at the end of sentences + Two spaces between sentences - Always use two spaces at the end of sentences, as this - improves readability, and eases use of tools such as + Always use two spaces between sentences, as this + improves readability and eases use of tools such as Emacs. - While it may be argued that a capital letter following - a period denotes a new sentence, this is not the case, - especially in name usage. - Jordan K. Hubbard is a good example; it has + A period and spaces followed by a capital letter + does not always mark a new sentence, + especially in names. + Jordan K. Hubbard is a good example. It has a capital H following a period and a - space, and there certainly is not a new sentence - there. + space, and is certainly not a new sentence. @@ -283,21 +282,18 @@ Acronyms - Acronyms should generally be spelled out the first time + Acronyms should be spelled out the first time they appear in a document, as in: Network Time Protocol - (NTP). - After the acronym has been defined, you should generally use - the acronym only (not the whole term, unless it makes more - sense contextually to use the whole term). Usually, acronyms - are defined only one per document. But if you prefer, you can - also define them the first time they appear in each + (NTP). + After the acronym has been defined, use + the acronym alone unless it makes more + sense contextually to use the whole term. Usually, acronyms + are defined only one per document. But they can also be + defined the first time they appear in a chapter. All acronyms should be enclosed in - acronym tags, with a - role attribute with the full term defined. - This allows a link to the glossary to be created, and for - mouseovers to be rendered with the fully expanded term. + acronym tags. @@ -338,9 +334,9 @@ V ]]> - If you use Emacs or - XEmacs to edit the files then - sgml-mode should be loaded automatically, + Emacs or + XEmacs should load + sgml-mode automatically, and the Emacs local variables at the bottom of each file should enforce these styles.