changeset 18529:3e731fc1e4d5 stable

contrib.txi: Improve the documentation for Contribution Guidelines. * contrib.txi: Improve the documentation for Contribution Guidelines.
author Rik <rik@octave.org>
date Thu, 27 Feb 2014 22:31:11 -0800
parents ae1b1ba1b693
children 186ea1c2bbd4
files doc/interpreter/contrib.txi
diffstat 1 files changed, 44 insertions(+), 45 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/contrib.txi	Thu Feb 27 11:33:57 2014 -0500
+++ b/doc/interpreter/contrib.txi	Thu Feb 27 22:31:11 2014 -0800
@@ -36,10 +36,10 @@
 
 @node How to Contribute
 @section How to Contribute
-The mailing list for Octave development discussion is
+The mailing list for Octave development discussions is
 @email{maintainers@@octave.org}.  Patches should be submitted to
 @url{https://savannah.gnu.org/patch/?func=additem&group=octave, Octave's patch tracker}.
-This concerns the development of Octave core, i.e., code that goes to Octave
+This concerns the development of Octave core, i.e., code that goes in to Octave
 directly.  You may consider developing and publishing a package instead;
 a great place for this is the allied Octave-Forge project
 (@url{http://octave.sourceforge.net}).  Note that the Octave core
@@ -48,7 +48,7 @@
 @node Building the Development Sources
 @section Building the Development Sources
 
-The directions for building from the Development sources change from
+The directions for building from the development sources change from
 time to time, so you should read the resources for developers on the web
 or in the development sources archive.  Start here:
 @url{http://www.octave.org/get-involved.html}.
@@ -56,8 +56,8 @@
 @node Basics of Generating a Changeset
 @section Basics of Generating a Changeset
 
-The preferable form of contribution is creating a Mercurial changeset
-and submit it to the @url{http://savannah.gnu.org/bugs/?group=octave, bug} or
+The best way to contribute is to create a Mercurial changeset and submit it to
+the @url{http://savannah.gnu.org/bugs/?group=octave, bug} or
 @url{http://savannah.gnu.org/patch/?func=additem&group=octave, patch}
 trackers@footnote{Please use the patch tracker only for patches which add new
 features.  If you have a patch to submit that fixes a bug, you should use the
@@ -68,7 +68,7 @@
 make more contributions, you should really get familiar with Mercurial.
 A good place to start is
 @url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.  There
-you will also find help how to install Mercurial.
+you will also find help about how to install Mercurial.
 
 A simple contribution sequence could look like this:
 
@@ -90,7 +90,7 @@
 @end example
 
 You may want to get familiar with Mercurial queues to manage your
-changesets.  For working with queues you have to activate the extension
+changesets.  To work with queues you must activate the extension
 @nospell{mq} with the following entry in Mercurial's configuration file
 @file{.hgrc} (or @file{Mercurial.ini} on Windows):
 
@@ -167,7 +167,7 @@
 
 Sometimes a few further improvements for the pager extension are
 necessary.  The following options should not be enabled unless paging
-isn't working correctly:
+is not working correctly.
 
 @example
 @group
@@ -185,13 +185,13 @@
 Enabling the described extensions should immediately lead to a difference
 when using the command line version of @nospell{hg}.  Of these options, the
 only one that enables a new command is @nospell{graphlog}.  It is recommanded
-that you use the command @code{hg glog} instead of @code{hg log} for a better
-feel what commits are being based on.
+that to use the command @code{hg glog}, instead of @code{hg log}, for a better
+feel about what commits are being based on.
 
 @node General Guidelines
 @section General Guidelines
 
-All Octave's sources are distributed under the General Public License
+All Octave's sources are distributed under the GNU General Public License
 (GPL).  Currently, Octave uses GPL version 3.  For details about this
 license, see @url{http://www.gnu.org/licenses/gpl.html}.  Therefore,
 whenever you create a new source file, it should have the following
@@ -202,20 +202,18 @@
 ##
 ## This file is part of Octave.
 ##
-## Octave is free software; you can redistribute it and/or
-## modify it under the terms of the GNU General Public
-## License as published by the Free Software Foundation;
-## either version 3 of the License, or (at your option) any
-## later version.
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
 ##
-## Octave is distributed in the hope that it will be useful,
-## but WITHOUT ANY WARRANTY; without even the implied
-## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
-## PURPOSE.  See the GNU General Public License for more
-## details.
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
 ##
-## You should have received a copy of the GNU General Public
-## License along with Octave; see the file COPYING.  If not,
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not,
 ## see <http://www.gnu.org/licenses/>.
 @end example
 
@@ -223,13 +221,13 @@
 changes, record and briefly describe the changes in your commit message.
 You should have previously configured your @file{.hgrc} (or
 @file{Mercurial.ini} on Windows) with your name and email, which will
-get automatically added to your commit message.  Your commit message
+be automatically added to your commit message.  Your commit message
 should have a brief one-line explanation of what the commit does.  If you
 are patching a bug, this one-line explanation should mention the bug
-number at the end.  If your change is small and only touches one file,
-this is typically sufficient.  If you are modifying several files or
+number at the end.  If your change is small and only touches one file then
+this is typically sufficient.  If you are modifying several files, or
 several parts of one file, you should enumerate your changes roughly
-following the GNU coding standards on changelogs, like the following
+following the GNU coding standards for changelogs, as in the following
 example:
 
 @example
@@ -248,12 +246,12 @@
 @end example
 
 @noindent
-In this example, the names of files is mentioned, and in parentheses the
-name of the function in that file that was modified.  There is no need to
-mention the function for m-files that only contain one function.  The
-commit message should describe what is changed, not why.  Any explanation
-of why a change is needed should appear as comments in the code,
-particularly if there is something that might not be obvious to someone
+In this example, the names of the file changed is listed first, and in
+parentheses the name of the function in that file that was modified.  There
+is no need to mention the function for m-files that only contain one function.
+The commit message should describe what was changed, not why it was changed.
+Any explanation for why a change is needed should appear as comments in the
+code, particularly if there is something that might not be obvious to someone
 reading it later.
 
 When submitting code which addresses a known bug on the Octave bug
@@ -267,14 +265,14 @@
 @end example
 
 The preferred comment mark for places that may need further attention is
-FIXME.
+@code{FIXME:}.
 
 @node Octave Sources (m-files)
 @section Octave Sources (m-files)
 
 Don't use tabs.  Tabs cause trouble.  If you are used to them, set up
 your editor so that it converts tabs to spaces.  Indent the bodies of
-the statement blocks.  Recommended indent is 2 spaces.  When calling
+statement blocks.  The recommended indent is 2 spaces.  When calling
 functions, put spaces after commas and before the calling parentheses,
 like this:
 
@@ -283,17 +281,18 @@
 @end example
 
 @noindent
-An exception are matrix and vector constructors:
+An exception are matrix or cell constructors:
 
 @example
   [sin(x), cos(x)]
+  {sin(x), cos(x)}
 @end example
 
 @noindent
 Here, putting spaces after @code{sin}, @code{cos} would result in a
-parse error.  In indexing expression, do not put a space after the
+parse error.  For an indexing expression, do not put a space after the
 identifier (this differentiates indexing and function calls nicely).
-The space after comma is not necessary if index expressions are simple,
+The space after a comma is not necessary if index expressions are simple,
 i.e., you may write
 
 @example
@@ -313,10 +312,10 @@
 wisely.
 
 Always use a specific end-of-block statement (like @code{endif},
-@code{endswitch}) rather than generic @code{end}.
+@code{endswitch}) rather than the generic @code{end}.
 
-Enclose the @code{if}, @code{while}, @code{until} and @code{switch}
-conditions in parentheses, like in C:
+Enclose the @code{if}, @code{while}, @code{until}, and @code{switch}
+conditions in parentheses, as in C:
 
 @example
 @group
@@ -359,7 +358,7 @@
 You should put a space before the left open parenthesis and after commas,
 for both function definitions and function calls.
 
-Recommended indent is 2 spaces.  When indenting, indent the statement
+The recommended indent is 2 spaces.  When indenting, indent the statement
 after control structures (like @code{if}, @code{while}, etc.).  If there
 is a compound statement, indent @emph{both} the curly braces and the
 body of the statement (so that the body gets indented by @emph{two}
@@ -395,12 +394,12 @@
 @end example
 
 @noindent
-Consider putting extra braces around a multiline expression to make it
+Consider putting extra braces around a multi-line expression to make it
 more readable, even if they are not necessary.  Also, do not hesitate to
 put extra braces anywhere if it improves clarity.
 
-Declare variables just before they're needed.  Use local variables of
-blocks---it helps optimization.  Don't write multi-line variable
+Declare variables just before they are needed.  Use local variables of
+blocks---it helps optimization.  Don't write a multi-line variable
 declaration with a single type specification and multiple variables.  If
 the variables don't fit on single line, repeat the type specification.
 Example: