From owner-svn-doc-head@FreeBSD.ORG Tue Jul 23 00:40:26 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 27A4B534; Tue, 23 Jul 2013 00:40:26 +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 1808B2CCE; Tue, 23 Jul 2013 00:40:26 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6N0ePEm083977; Tue, 23 Jul 2013 00:40:25 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6N0ePfb083976; Tue, 23 Jul 2013 00:40:25 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307230040.r6N0ePfb083976@svn.freebsd.org> From: Warren Block Date: Tue, 23 Jul 2013 00:40:25 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42391 - 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-head@freebsd.org X-Mailman-Version: 2.1.14 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: Tue, 23 Jul 2013 00:40:26 -0000 Author: wblock Date: Tue Jul 23 00:40:25 2013 New Revision: 42391 URL: http://svnweb.freebsd.org/changeset/doc/42391 Log: More simplification and cleanups, replacement of CDATA sections with sgmltags. 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 Tue Jul 23 00:00:21 2013 (r42390) +++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Tue Jul 23 00:40:25 2013 (r42391) @@ -119,7 +119,7 @@ Guidelines To promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for + &os; documentation, some guidelines have been drawn up for authors to follow. @@ -148,7 +148,7 @@ Do not use contractions. Always spell the phrase out - in full. Don't use contractions would be + in full. Don't use contractions is wrong. Avoiding contractions makes for a more formal tone, is @@ -166,7 +166,7 @@ from the others with a comma and the word and. - For example, look at the following: + For example:
This is a list of one, two and three items. @@ -190,47 +190,44 @@ Avoid redundant phrases - Try not to use redundant phrases. In particular, + Do not use redundant phrases. In particular, the command, the file, and - man command are probably redundant. + man command are often redundant. - These two examples show this for commands. The second - example is preferred. + For example, commands: - Use the command svn to update - your sources. + Wrong: Use the command svn to update + sources. - Use svn to update your + Right: Use svn to update sources. - These two examples show this for filenames. The - second example is preferred. + Filenames: - … in the filename + Wrong: … in the filename /etc/rc.local… - … in + Right: … in /etc/rc.local… - These two examples show this for manual references. - The second example is preferred (the second example uses - citerefentry). + Manual page references (the second example uses + citerefentry with the &man.csh.1; entity):. - See man csh for more + Wrong: See man csh for more information. - See &man.csh.1;. + Right: See &man.csh.1;. @@ -239,7 +236,7 @@ Two spaces between sentences - Always use two spaces between sentences, as this + Always use two spaces between sentences, as it improves readability and eases use of tools such as Emacs. @@ -300,16 +297,15 @@ regardless of the indentation level of the file which might contain the current file. - 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 + Opening tags increase the indentation level by two spaces. + Closing tags decrease the indentation level by two spaces. + Blocks of eight 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: + For example, the source for this section looks like this: chapter title...title @@ -345,31 +341,31 @@ at the same indent as a previous tag should not: - - - NIS + article lang='en' + articleinfo + titleNIStitle - October 1999 + pubdateOctober 1999pubdate - - ... + abstract + para... ... - ... - - + ...para + abstract + articleinfo - - ... + sect1 + title...title - ... - + para...para + sect1 - - ... + sect1 + title...title - ... - -]]> + para...para + sect1 +article @@ -404,25 +400,23 @@ - White Space Changes + Whitespace Changes - When committing changes, do not commit changes - to the content at the same time as changes to the + Do not commit changes + to content at the same time as changes to 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 + When content and whitespace changes are kept separate, translation teams + can easily see whether a change was content that must be translated + or only whitespace. + + For example, if two sentences have been added to a + paragraph so that the line lengths now go + over 80 columns, first commit the change with the too-long + lines. 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. + indicate that this is a whitespace-only change that can be + ignored by translators. @@ -444,18 +438,18 @@ GB. Hardware compression … between numbers and units: - + 57600&nbsp;bps between program names and version numbers: - + &os;&nbsp;9.2 between multiword names (use with caution when applying this to more than 3-4 word names like - The FreeBSD Brazilian Portuguese Documentation + The &os; Brazilian Portuguese Documentation Project): @@ -467,7 +461,7 @@ GB. Hardware compression …Word List This list of words shows the correct spelling and - capitalization when used in FreeBSD Documentation. If a word is + capitalization when used in &os; documentation. If a word is not on this list, ask about it on the &a.doc;.