From owner-svn-doc-all@FreeBSD.ORG Thu Jun 20 16:46:55 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 CEDBD7B6; Thu, 20 Jun 2013 16:46:55 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id BF6741659; Thu, 20 Jun 2013 16:46:55 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5KGktAg093582; Thu, 20 Jun 2013 16:46:55 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5KGktTe093581; Thu, 20 Jun 2013 16:46:55 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306201646.r5KGktTe093581@svn.freebsd.org> From: Warren Block Date: Thu, 20 Jun 2013 16:46:55 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41971 - 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: Thu, 20 Jun 2013 16:46:55 -0000 Author: wblock Date: Thu Jun 20 16:46:55 2013 New Revision: 41971 URL: http://svnweb.freebsd.org/changeset/doc/41971 Log: Whitespace-only fixes. Translators, please ignore. 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 Thu Jun 20 16:40:42 2013 (r41970) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Thu Jun 20 16:46:55 2013 (r41971) @@ -54,7 +54,7 @@ concepts. Avoid flowery or embellished speech, jokes, or colloquial - expressions. Write as simply and clearly as possible. Simple + expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate. Keep explanations as short, simple, and clear as possible. @@ -108,142 +108,145 @@ Guidelines - To promote consistency between the myriad authors of - the FreeBSD documentation, some guidelines have been drawn up for - authors to follow. - - - - Use American English Spelling - - - There are several variants of English, with different - spellings for the same word. Where spellings differ, use - the American English variant. color, not - colour, rationalize, not - rationalise, and so on. - - - The use of British English may be accepted in the case - of a contributed article, however the spelling must be - consistent within the whole document. The other documents - such as books, web site, manual pages, etc. will have to - use American English. - - - - - - Do not use contractions - - - Do not use contractions. Always spell the phrase out in - full. Don't use contractions would be - wrong. - - Avoiding contractions makes for a more formal tone, is - more precise, and is slightly easier for translators. - - - - - Use the serial comma - - - In a list of items within a paragraph, separate each - item from the others with a comma. Separate the last item - from the others with a comma and the word - and. - - For example, look at the following: - -
- This is a list of one, two and three items. -
- - Is this a list of three items, one, - two, and three, or a list of - two items, one and two and - three? - - It is better to be explicit and include a serial - comma: - -
- This is a list of one, two, and three items. -
- - - - - Avoid redundant phrases - - - Try not to use redundant phrases. In particular, - the command, the file, and - man command are probably redundant. + To promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for + authors to follow. + + + + Use American English Spelling - These two examples show this for commands. The second - example is preferred. + + There are several variants of English, with different + spellings for the same word. Where spellings differ, use + the American English variant. color, not + colour, rationalize, not + rationalise, and so on. + + + The use of British English may be accepted in the + case of a contributed article, however the spelling must + be consistent within the whole document. The other + documents such as books, web site, manual pages, etc. + will have to use American English. + + + - - Use the command svn to update - your sources. - + + Do not use contractions - - Use svn to update your - sources. - + + Do not use contractions. Always spell the phrase out + in full. Don't use contractions would be + wrong. + + Avoiding contractions makes for a more formal tone, is + more precise, and is slightly easier for + translators. + + - These two examples show this for filenames. The second - example is preferred. + + Use the serial comma - - … in the filename - /etc/rc.local… - + + In a list of items within a paragraph, separate each + item from the others with a comma. Separate the last item + from the others with a comma and the word + and. + + For example, look at the following: + +
+ This is a list of one, two and three items. +
+ + Is this a list of three items, one, + two, and three, or a list of + two items, one and two and + three? + + It is better to be explicit and include a serial + comma: + +
+ This is a list of one, two, and three items. +
+ + - - … in - /etc/rc.local… - + + Avoid redundant phrases - These two examples show this for manual references. The - second example is preferred (the second example uses - citerefentry). + + Try not to use redundant phrases. In particular, + the command, the file, and + man command are probably redundant. + + These two examples show this for commands. The second + example is preferred. + + + Use the command svn to update + your sources. + + + + Use svn to update your + sources. + + + These two examples show this for filenames. The + second example is preferred. + + + … in the filename + /etc/rc.local… + + + + … in + /etc/rc.local… + + + These two examples show this for manual references. + The second example is preferred (the second example uses + citerefentry). + + + See man csh for more + information. + + + + See &man.csh.1;. + + + - - See man csh for more - information. - + + Two spaces at the end of sentences - - See &man.csh.1;. - - - - - 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 - 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 capital H - following a period and a space, and there certainly is not a - new sentence there. - - - - - For more information about writing style, see Elements of - Style, by William Strunk. + + 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 + 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 capital H following a period and a + space, and there certainly is not a new sentence + there. + + + + + For more information about writing style, see Elements of + Style, by William Strunk.