octave-lyh: doc/interpreter/contrib.txi comparison

comparison doc/interpreter/contrib.txi @ 11195:8f67fe9dd64e

contrib.txi: minor tweaks

author	John W. Eaton <jwe@octave.org>
date	Sat, 06 Nov 2010 09:08:47 -0400
parents	a4f482e66b65
children	fd0a3ac60b0e

comparison

equal deleted inserted replaced

-:b8585f8e11d5
+:8f67fe9dd64e
 * Other Sources::
 @end menu
 @node How to Contribute
 @section How to Contribute
-The mailing list for Octave development discussion and sending contributions is
+The mailing list for Octave development discussion and sending
-@email{maintainers@@octave.org}.  This concerns the development of Octave core,
+contributions is @email{maintainers@@octave.org}.  This concerns the
-i.e., code that goes to Octave directly.  You may consider developing and
+development of Octave core, i.e., code that goes to Octave directly.
-publishing a package instead; a great place for this is the allied Octave-Forge
+You may consider developing and publishing a package instead; a great
-project (@url{http://octave.sf.net}).  Note that the Octave project is
+place for this is the allied Octave-Forge project
+(@url{http://octave.sf.net}).  Note that the Octave project is
 inherently more conservative and follows narrower rules.
-The preferable form of contribution is creating a Mercurial changeset and
+The preferable form of contribution is creating a Mercurial changeset
-sending it via e-mail to the octave-maintainers mailing list.  Mercurial is the
+and sending it via e-mail to the octave-maintainers mailing list.
-source code management system currently used to develop Octave.  Other forms of
+Mercurial is the source code management system currently used to develop
-contributions (e.g., simple diff patches) are also acceptable, but they slow
+Octave.  Other forms of contributions (e.g., simple diff patches) are
-down the review process.  If you want to make more contributions, you should
+also acceptable, but they slow down the review process.  If you want to
-really get familiar with Mercurial.  A good place to start is
+make more contributions, you should really get familiar with Mercurial.
-@url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.  There you will
+A good place to start is
-also find help how to install Mercurial.
+@url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.  There
+you will also find help how to install Mercurial.
 A simple contribution sequence could look like this:
 @example
 @group
 # file
 # send ../cool.diff via email
 @end group
 @end example
-You may want to get familiar with Mercurial queues to manage your changesets.
+You may want to get familiar with Mercurial queues to manage your
-Here is a slightly less simple example using Mercurial queues, where you work
+changesets.  Here is a slightly less simple example using Mercurial
-on two unrelated changesets in parallel and update one of the changesets after
+queues, where you work on two unrelated changesets in parallel and
-discussion in the maintainers mailing list:
+update one of the changesets after discussion in the maintainers mailing
+list:
 @example
 hg qnew nasty_bug            # create a new patch
 # change sources@dots{}
 hg qref                      # save the changes into the patch
 @end example
 @node General Guidelines
 @section General Guidelines
-All Octave's sources are distributed under the General Public License (GPL).
+All Octave's sources are distributed under the General Public License
-Currently, Octave uses GPL version 3.  For details about this license, see
+(GPL).  Currently, Octave uses GPL version 3.  For details about this
-@url{http://www.gnu.org/licenses/gpl.html}.  Therefore, whenever you create a
+license, see @url{http://www.gnu.org/licenses/gpl.html}.  Therefore,
-new source file, it should have the following comment header (use appropriate
+whenever you create a new source file, it should have the following
-year, name and comment marks):
+comment header (use appropriate year, name and comment marks):
 @example
 ## Copyright (C) 1996, 1997, 2007 John W. Eaton <jwe@@octave.org>
 ##
 ## This file is part of Octave.
 ## 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
-Always include ChangeLog entries in changesets.  After making your source
+Always include ChangeLog entries in changesets.  After making your
-changes, record and briefly describe the changes in the nearest ChangeLog file
+source changes, record and briefly describe the changes in the nearest
-upwards in the directory tree.  Use the previous entries as a template.  Your
+ChangeLog file upwards in the directory tree.  Use the previous entries
-entry should contain your name and email, and the path to the modified source
+as a template.  Your entry should contain your name and email, and the
-file relative to the parent directory of the ChangeLog file.  If there are more
+path to the modified source file relative to the parent directory of the
-functions in the file, you should also include the name of the modified function
+ChangeLog file.  If there are more functions in the file, you should
-(in parentheses after file path).  Example:
+also include the name of the modified function (in parentheses after
+file path).  Example:
 @example
 @group
 2008-04-02  David Bateman  <dbateman@@free.fr>
 The ChangeLog entries 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 reading it later.
-The preferred comment mark for places that may need further attention is FIXME.
+The preferred comment mark for places that may need further attention is
+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
+Don't use tabs.  Tabs cause trouble.  If you are used to them, set up
-editor so that it converts tabs to spaces.  Indent the bodies of the statement
+your editor so that it converts tabs to spaces.  Indent the bodies of
-blocks.  Recommended indent is 2 spaces.  When calling functions, put spaces
+the statement blocks.  Recommended indent is 2 spaces.  When calling
-after commas and before the calling parentheses, like this:
+functions, put spaces after commas and before the calling parentheses,
+like this:
 @example
 x = max (sin (y+3), 2);
 @end example
 @example
 [sin(x), cos(x)]
 @end example
 @noindent
-Here, putting spaces after @code{sin}, @code{cos} would result in a parse error.
+Here, putting spaces after @code{sin}, @code{cos} would result in a
-In indexing expression, do not put a space after the identifier (this
+parse error.  In indexing expression, do not put a space after the
-differentiates indexing and function calls nicely).  The space after comma is
+identifier (this differentiates indexing and function calls nicely).
-not necessary if index expressions are simple, i.e., you may write
+The space after comma is not necessary if index expressions are simple,
+i.e., you may write
 @example
 A(:,i,j)
 @end example
 @example
 A([1:i-1;i+1:n], XI(:,2:n-1))
 @end example
-Use lowercase names if possible.  Uppercase is acceptable for variable names
+Use lowercase names if possible.  Uppercase is acceptable for variable
-consisting of 1-2 letters.  Do not use mixed case names.  Function names must be
+names consisting of 1-2 letters.  Do not use mixed case names.  Function
-lowercase.  Function names are global, so choose them wisely.
+names must be lowercase.  Function names are global, so choose them
+wisely.
 Always use a specific end-of-block statement (like @code{endif},
-@code{endswitch}) rather than generic @code{end}.  Enclose the @code{if},
+@code{endswitch}) rather than generic @code{end}.
-@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, like in C:
 @example
 @group
 if (isvector (a))
 s = sum(a);
 endif
 @end group
 @end example
 @noindent
-Do not do this, however, with @code{for}:
+Do not do this, however, with the iteration counter portion of a
+@code{for} statement.  Write:
 @example
 @group
 for i = 1:n
 b(i) = sum (a(:,i));
 @end example
 @node C++ Sources
 @section C++ Sources
-Don't use tabs.  Tabs cause trouble.  If you are used to them, set up your
+Don't use tabs.  Tabs cause trouble.  If you are used to them, set up
-editor so that it converts tabs to spaces.  Format function headers like this:
+your editor so that it converts tabs to spaces.  Format function headers
+like this:
 @example
 @group
 static bool
 matches_patterns (const string_vector& patterns, int pat_idx,
 int num_pat, const std::string& name)
 @end group
 @end example
 @noindent
-The function name should start in column 1, and multi-line argument lists should
+The function name should start in column 1, and multi-line argument
-be aligned on the first char after the open parenthesis.  You should put a space
+lists should be aligned on the first char after the open parenthesis.
-after the left open parenthesis and after commas, for both function definitions
+You should put a space after the left open parenthesis and after commas,
-and function calls.
+for both function definitions and function calls.
-Recommended indent is 2 spaces.  When indenting, indent the statement after
+Recommended indent is 2 spaces.  When indenting, indent the statement
-control structures (like @code{if}, @code{while}, etc.). If there is a compound
+after control structures (like @code{if}, @code{while}, etc.). If there
-statement, indent @emph{both} the curly braces and the body of the statement (so
+is a compound statement, indent @emph{both} the curly braces and the
-that the body gets indented by @emph{two} indents).  Example:
+body of the statement (so that the body gets indented by @emph{two}
+indents).  Example:
 @example
 @group
 if (have_args)
 @{
 @noindent
 If you have nested @code{if} statements, use extra braces for extra
 clarification.
-Split long expressions in such a way that a continuation line starts with an
+Split long expressions in such a way that a continuation line starts
-operator rather than identifier.  If the split occurs inside braces,
+with an operator rather than identifier.  If the split occurs inside
-continuation should be aligned with the first char after the innermost braces
+braces, continuation should be aligned with the first char after the
-enclosing the split.  Example:
+innermost braces enclosing the split.  Example:
 @example
 @group
 SVD::type type = ((nargout == 0 || nargout == 1)
 ? SVD::sigma_only
 : (nargin == 2) ? SVD::economy : SVD::std);
 @end group
 @end example
 @noindent
-Consider putting extra braces around a multiline expression to make it more
+Consider putting extra braces around a multiline expression to make it
-readable, even if they are not necessary.  Also, do not hesitate to put extra
+more readable, even if they are not necessary.  Also, do not hesitate to
-braces anywhere if it improves clarity.
+put extra braces anywhere if it improves clarity.
-Try declaring variables just before they're needed.  Use local variables of
+Declare variables just before they're needed.  Use local variables of
-blocks - it helps optimization.  Don't write multi-line variable declaration
+blocks---it helps optimization.  Don't write multi-line variable
-with a single type specification and multiple variables.  If the variables don't
+declaration with a single type specification and multiple variables.  If
-fit on single line, repeat the type specification.  Example:
+the variables don't fit on single line, repeat the type specification.
+Example:
 @example
 @group
 octave_value retval;
 double d1, d2;
 @end group
 @end example
-Use lowercase names if possible.  Uppercase is acceptable for variable names
+Use lowercase names if possible.  Uppercase is acceptable for variable
-consisting of 1-2 letters.  Do not use mixed case names.
+names consisting of 1-2 letters.  Do not use mixed case names.
-Try to use Octave's types and classes if possible.  Otherwise, try to use C++
+Use Octave's types and classes if possible.  Otherwise, use the C++
-standard library.  Use of STL containers and algorithms is encouraged.  Use
+standard library.  Use of STL containers and algorithms is encouraged.
-templates wisely to reduce code duplication.  Avoid comma expressions, labels
+Use templates wisely to reduce code duplication.  Avoid comma
-and gotos, and explicit typecasts.  If you need to typecast, use the modern C++
+expressions, labels and gotos, and explicit typecasts.  If you need to
-casting operators.  In functions, try to reduce the number of @code{return}
+typecast, use the modern C++ casting operators.  In functions, minimize
-statements - use nested @code{if} statements if possible.
+the number of @code{return} statements---use nested @code{if} statements
+if possible.
 @node Other Sources
 @section Other Sources
-Apart from C++ and Octave language (m-files), Octave's sources include files
+Apart from C++ and Octave language (m-files), Octave's sources include
-written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo and @TeX{}.  There are
+files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo and
-not many rules to follow when using these other languages; some of them are
+@TeX{}.  There are not many rules to follow when using these other
-summarized below.  In any case, the golden rule is: if you modify a source
+languages; some of them are summarized below.  In any case, the golden
-file, try to follow any conventions you can detect in the file or other similar
+rule is: if you modify a source file, try to follow any conventions you
-files.
+can detect in the file or other similar files.
 For C you should obviously follow all C++ rules that can apply.
-If you happen to modify a Fortran file, you should stay within Fortran 77
+If you modify a Fortran file, you should stay within Fortran 77 with
-with common extensions like @code{END DO}.  Currently, we want all sources
+common extensions like @code{END DO}.  Currently, we want all sources to
-to be compilable with the f2c and g77 compilers, without special flags if
+be compilable with the f2c and g77 compilers, without special flags if
-possible.  This usually means that non-legacy compilers also accept the sources.
+possible.  This usually means that non-legacy compilers also accept the
+sources.
-The M4 macro language is mainly used for Autoconf configuration files.  You
-should follow normal M4 rules when contributing to these files.  Some M4 files
+The M4 macro language is mainly used for Autoconf configuration files.
-come from external source, namely the Autoconf archive
+You should follow normal M4 rules when contributing to these files.
+Some M4 files come from external source, namely the Autoconf archive
 @url{http://autoconf-archive.cryp.to}.
-If you give a code example in the documentation written in Texinfo with the
+If you give a code example in the documentation written in Texinfo with
-@code{@@example} environment, you should be aware that the text within such an
+the @code{@@example} environment, you should be aware that the text
-environment will not be wrapped.  It is recommended that you keep the lines
+within such an environment will not be wrapped.  It is recommended that
-short enough to fit on pages in the generated pdf or ps documents.  Here is a
+you keep the lines short enough to fit on pages in the generated pdf or
-ruler (in an @code{@@example} environment) for finding the appropriate line
+ps documents.  Here is a ruler (in an @code{@@example} environment) for
-width:
+finding the appropriate line width:
 @example
 @group
 1         2         3         4         5         6
 123456789012345678901234567890123456789012345678901234567890

Mercurial > hg > octave-lyh

comparison doc/interpreter/contrib.txi @ 11195:8f67fe9dd64e