From owner-svn-doc-head@FreeBSD.ORG Mon May 21 14:54:44 2012 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 8B5791065675; Mon, 21 May 2012 14:54:44 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 73B328FC0C; Mon, 21 May 2012 14:54:44 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q4LEsiqg062348; Mon, 21 May 2012 14:54:44 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q4LEsi2L062346; Mon, 21 May 2012 14:54:44 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201205211454.q4LEsi2L062346@svn.freebsd.org> From: Warren Block Date: Mon, 21 May 2012 14:54:44 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r38872 - head/en_US.ISO8859-1/books/fdp-primer/writing-style X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 21 May 2012 14:54:44 -0000 Author: wblock Date: Mon May 21 14:54:44 2012 New Revision: 38872 URL: http://svn.freebsd.org/changeset/doc/38872 Log: Whitespace-only fixes. Translators, please ignore. Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Mon May 21 14:43:21 2012 (r38871) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml Mon May 21 14:54:44 2012 (r38872) @@ -32,112 +32,117 @@ Writing Style - - In order to promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for authors to - follow. - + + In order 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. + 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. + 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. + 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. + 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. + 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: - + 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. - - These two examples show this for commands. The second example - is preferred. - + 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 cvsup to update your - sources. + Use the command cvsup to update + your sources. - + - Use cvsup to update your sources. + Use cvsup to update your + sources. - - These two examples show this for filenames. The second example - is preferred. - + + 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 + + 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;. @@ -152,11 +157,11 @@ 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. + 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. @@ -168,8 +173,9 @@ Style Guide - To keep the source for the documentation consistent when many different - people are editing it, please follow these style conventions. + To keep the source for the documentation consistent when + many different people are editing it, please follow these style + conventions. Letter Case @@ -177,9 +183,10 @@ Tags are entered in lower case, para, not PARA. - Text that appears in SGML contexts is generally written in upper - case, <!ENTITY…>, and - <!DOCTYPE…>, not + Text that appears in SGML contexts is generally written in + upper case, <!ENTITY…>, and + <!DOCTYPE…>, + not <!entity…> and <!doctype…>. @@ -188,36 +195,36 @@ Acronyms Acronyms should generally 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 chapter. + 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 + chapter. The first three uses of an acronym 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, 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. Indentation Each file starts with indentation set at column 0, - regardless of the indentation level of the file - which might contain this one. + regardless of the indentation level of + the file which might contain this one. Opening tags increase the indentation level by 2 spaces. - Closing tags decrease the indentation level by 2 spaces. Blocks - of 8 spaces at the start of a line should be replaced with a tab. - Do not use - spaces in front of tabs, and do not add extraneous whitespace at the - end of a line. Content - within elements should be indented by two spaces if the content runs - over more than one line. + Closing tags decrease the indentation level by 2 spaces. + Blocks of 8 spaces at the start of a line should be replaced + with a tab. Do not use spaces in front of tabs, and do not + add extraneous whitespace at the end of a line. Content + within elements should be indented by two spaces if the + content runs over more than one line. For example, the source for this section looks something like: @@ -244,12 +251,12 @@ V If you use Emacs or XEmacs to edit the files then - sgml-mode should be loaded automatically, and the - Emacs local variables at the bottom of each file should enforce these - styles. + sgml-mode should be loaded automatically, + and the Emacs local variables at + the bottom of each file should enforce these styles. - Vim users might want to configure - their editor with: + Vim users might want to + configure their editor with: augroup sgmledit autocmd FileType sgml set formatoptions=cq2l " Special formatting options @@ -267,7 +274,7 @@ augroup END 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: @@ -305,8 +312,8 @@ augroup END Separating Tags Tags like itemizedlist which will - always have further tags inside them, and in fact do not take - character data themselves, are always on a line by + always have further tags inside them, and in fact do not + take character data themselves, are always on a line by themselves. Tags like para and @@ -334,38 +341,40 @@ augroup END White Space Changes - When committing changes, do not commit changes to the - content at the same time as changes to the + When committing changes, do not commit changes + to the content at the same time as changes to the formatting. - - This is so that the teams that convert the documentation to other - languages can quickly see what content has actually changed in your - commit, without having to decide whether a line has changed because of - the content, or just because it has been refilled. - - For example, if you have added two sentences to a paragraph, such - that the line lengths on the paragraph now go over 80 columns, first - commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for - the second change, be sure to indicate that this is a whitespace-only - change, and that the translation team can ignore it. + + This is so that the teams that convert the documentation + to other languages can quickly see what content has actually + changed in your commit, without having to decide whether a + line has changed because of the content, or just because it + has been refilled. + + For example, if you have added two sentences to a + paragraph, such that the line lengths on the paragraph now go + over 80 columns, first commit your change with the too-long + line lengths. Then fix the line wrapping, and commit this + second change. In the commit message for the second change, + be sure to indicate that this is a whitespace-only change, and + that the translation team can ignore it. Non-Breaking Space - Avoid line breaks in places where they look ugly - or make it difficult to follow a sentence. Line breaks depend - on the width of the chosen output medium. In particular, viewing - the HTML documentation with a text browser can lead to badly + Avoid line breaks in places where they look ugly or make + it difficult to follow a sentence. Line breaks depend on the + width of the chosen output medium. In particular, viewing the + HTML documentation with a text browser can lead to badly formatted paragraphs like the next one: Data capacity ranges from 40 MB to 15 GB. Hardware compression … The general entity &nbsp; prohibits - line breaks between parts belonging together. Use non-breaking - spaces in the following places: + line breaks between parts belonging together. Use + non-breaking spaces in the following places: @@ -379,10 +388,11 @@ GB. Hardware compression … - between multiword names (use with caution when applying this - to more than 3-4 word names like The FreeBSD Brazilian - Portuguese Documentation Project): - + between multiword names (use with caution when + applying this to more than 3-4 word names like + The FreeBSD Brazilian Portuguese Documentation + Project): + @@ -395,8 +405,8 @@ GB. Hardware compression …O'Reilly - word list. + url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly + word list. @@ -471,7 +481,6 @@ GB. Hardware compression …web server -