Mercurial > hg > octave-lojdl
changeset 8055:d51c3541be28
contrib.txi: new documentation for contributors
author | Jaroslav Hajek <highegg@gmail.com> |
---|---|
date | Tue, 26 Aug 2008 11:00:09 -0400 |
parents | 272eaebbb6ba |
children | 9a6f4713f765 |
files | doc/ChangeLog doc/interpreter/Makefile.in doc/interpreter/contrib.txi doc/interpreter/octave.texi doc/interpreter/plot.txi |
diffstat | 5 files changed, 276 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2008-08-26 Jaroslav Hajek <highegg@gmail.com> + + * interpreter/contrib.txi: New file. + * interpreter/octave.texi: Include it here. + * interpreter/Makefile.in (SUB_SOURCE): Add contrib.txi to the list. + 2008-08-21 David Bateman <dbateman@free.fr> * interpreter/plot.txi: Document ezplot.
--- a/doc/interpreter/Makefile.in +++ b/doc/interpreter/Makefile.in @@ -94,7 +94,7 @@ IMAGES = $(IMAGES_EPS) $(IMAGES_PDF) $(IMAGES_PNG) $(IMAGES_TXT) SUB_SOURCE := arith.txi audio.txi basics.txi bugs.txi \ - container.txi cp-idx.txi data.txi \ + container.txi contrib.txi cp-idx.txi data.txi \ debug.txi diffeq.txi dynamic.txi emacs.txi errors.txi eval.txi \ expr.txi fn-idx.txi func.txi geometry.txi gpl.txi \ grammar.txi image.txi install.txi interp.txi \
new file mode 100644 --- /dev/null +++ b/doc/interpreter/contrib.txi @@ -0,0 +1,266 @@ +@c Copyright (C) 2008 Jaroslav Hajek <highegg@gmail.com> +@c +@c This file is part of Octave. +@c +@c Octave is free software; you can redistribute it and/or modify it +@c under the terms of the GNU General Public License as published by the +@c Free Software Foundation; either version 3 of the License, or (at +@c your option) any later version. +@c +@c Octave is distributed in the hope that it will be useful, but WITHOUT +@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +@c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +@c for more details. +@c +@c You should have received a copy of the GNU General Public License +@c along with Octave; see the file COPYING. If not, see +@c <http://www.gnu.org/licenses/>. + +@node Contributing Guidelines +@appendix Contributing Guidelines +@cindex coding standards +@cindex Octave development + +This chapter is dedicated to those who wish to contribute code to Octave. + +@menu +* How to Contribute:: How you may start contributing code. +* General Guidelines:: Advices applicable to any type of source. +* Octave Sources (m-files):: +* C++ Sources:: +* Other Sources:: +@end menu + +@node How to Contribute +@section How to Contribute +The mailing list for Octave development discussion and sending contributions is +@email{maintainers@@octave.org}. This concerns the development of Octave core, +i.e. code that goes 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.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 +sending it via e-mail to the octave-maintainers mailing list. Mercurial is the +SCM system currently used to develop Octave. Other forms of contributions (e.g. +simple diff patches) are also acceptable, but they slow down the review process. +If you want to 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}. +A simplified contribution sequence could look like this: + +@example +hg clone http://www.octave.org/hg/octave +cd octave +# change some sources... +hg commit -m "make Octave the coolest software ever" +hg export ../cool.diff +# send ../cool.diff via email +@end example + +@node General Guidelines +@section General Guidelines + +All Octave's sources are distributed under the 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 comment header (use appropriate +year, name and comment marks): + +@example +## Copyright (C) 1996, 1997, 2007 John W. Eaton <jwe@@bevo.che.wisc.edu> +## +## 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 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, +## see <http://www.gnu.org/licenses/>. +@end example + +Always include ChangeLog entries in changesets. After making your source +changes, record and briefly describe the changes in the nearest ChangeLog file +upwards in the directory tree. Use the previous entries as a template. Your +entry should contain your name and email, and the path to the modified source +file relative to the parent directory of the ChangeLog file. If there are more +functions in the file, you should also include the name of the modified function +(in parentheses after file path). Example: + +@example +2008-04-02 David Bateman <dbateman@@free.fr> + + * graphics.cc (void gnuplot_backend::close_figure (const + octave_value&) const): Allow for an input and output stream. +@end example + +@noindent +The ChangeLog entries should describe what is changed, not why. The reason of +the change should appear in the commit message. + +@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 functions, put spaces after commas +and before the calling parentheses, like this: + +@example + x = max (sin (y+3), 2); +@end example + +@noindent +An exception are matrix and vector constructors: + +@example + [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 identifier (this +differentiates indexing and function calls nicely). The space after comma is not +necessary if index expressions are simple, i.e. you may write +@example + A(:,i,j) +@end example + +@noindent +but + +@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 +consisting of 1-2 letters. Do not use mixed case names. Function 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{while}, @code{until} and @code{switch} conditions in parentheses, +like in C: + +@example +if (isvector (a)) + s = sum(a); +endif +@end example + +@noindent +Do not do this, however, with @code{for}: + +@example +for i = 1:n + b(i) = sum (a(:,i)); +endfor +@end example + +@node C++ Sources +@section C++ Sources + +Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor +so that it converts tabs to spaces. Format function headers like this: + +@example +static bool +matches_patterns (const string_vector& patterns, int pat_idx, + int num_pat, const std::string& name) +@end example + +@noindent +The function name should start in column 1, and multi-line argument lists should +be aligned on the first char after the open parenthesis. You should put a space +after the left open parenthesis and after commas, for both function definitions +and function calls. + +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 @i{both} the curly braces and the body of the statement (so +that the body gets indented by @i{two} indents). Example: + +@example +if (have_args) + @{ + idx.push_back (first_args); + have_args = false; + @} +else + idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp)); +@end example + +@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 +operator rather than identifier. If the split occurs inside braces, continuation +should be aligned with the first char after the innermost braces enclosing the +split. Example: + +@example +SVD::type type = ((nargout == 0 || nargout == 1) + ? SVD::sigma_only + : (nargin == 2) ? SVD::economy : SVD::std); +@end example + +@noindent +Consider putting extra braces around a multiline 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. + +Try declaring variables just before they're needed. Use local variables of +blocks - it helps optimization. Don't write 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: + +@example +octave_value retval; + +octave_idx_type nr = b.rows (); +octave_idx_type nc = b.cols (); + +double d1, d2; +@end example + +Use lowercase names if possible. Uppercase is acceptable for variable 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++ +standard library. Use of STL containers and algorithms is encouraged. Use +templates wisely to reduce code duplication. Avoid comma expressions, labels +and gotos, and explicit typecasts. If you need to typecast, use the modern C++ +casting operators. In functions, try to reduce 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 +written in C, Fortran, M4, perl, unix shell, AWK, texinfo and TeX. There are +not many rules to follow when using these other languages; some of them are +summarized below. In any case, the golden rule is: if you modify a source +file, try to follow any conventions you 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 +with common extensions like @code{END DO}. Currently, we want all sources +to be compilable with the f2c and g77 compilers, without special flags if +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 come +from external source, namely the Autoconf archive @url{http://autoconf-archive.cryp.to}. +
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -182,6 +182,7 @@ * Dynamically Linked Functions:: * Test and Demo Functions:: * Tips:: +* Contributing Guidelines:: * Trouble:: If you have trouble installing Octave. * Installation:: How to configure, compile and install Octave. * Emacs:: @@ -615,6 +616,7 @@ @include dynamic.texi @include testfun.texi @include tips.texi +@include contrib.texi @include bugs.texi @include install.texi @include emacs.texi
--- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -208,7 +208,7 @@ @DOCSTRING(fplot) Other functions that can create two-dimensional plots directly from a -function include @code{ezplot), @code{ezcontour}, @code{ezcontourf} and +function include @code{ezplot}, @code{ezcontour}, @code{ezcontourf} and @code{ezpolar}. @DOCSTRING(ezplot)