# HG changeset patch # User Jaroslav Hajek # Date 1219741835 -7200 # Node ID 910cfc55b994de21db20343408ce5f0491894477 # Parent 272eaebbb6ba3576d45cc31d03b4da67f2f2c3aa [mq]: contrib diff --git a/doc/interpreter/Makefile.in b/doc/interpreter/Makefile.in --- 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 \ diff --git a/doc/interpreter/contrib.txi b/doc/interpreter/contrib.txi new file mode 100644 --- /dev/null +++ b/doc/interpreter/contrib.txi @@ -0,0 +1,266 @@ address@hidden Copyright (C) 2008 Jaroslav Hajek address@hidden address@hidden This file is part of Octave. address@hidden address@hidden Octave is free software; you can redistribute it and/or modify it address@hidden under the terms of the GNU General Public License as published by the address@hidden Free Software Foundation; either version 3 of the License, or (at address@hidden your option) any later version. address@hidden address@hidden Octave is distributed in the hope that it will be useful, but WITHOUT address@hidden ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or address@hidden FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License address@hidden for more details. address@hidden address@hidden You should have received a copy of the GNU General Public License address@hidden along with Octave; see the file COPYING. If not, see address@hidden . + address@hidden Contributing guidelines address@hidden Contributing guidelines address@hidden coding standards address@hidden Octave development + +This chapter is dedicated to those who wish to contribute code to Octave. + address@hidden +* 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:: address@hidden menu + address@hidden How to contribute address@hidden How to contribute +The mailing list for Octave development discussion and sending contributions is address@hidden@@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 address@hidden://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. +A simplified contribution sequence could look like this: + address@hidden +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 address@hidden example + address@hidden General guidelines address@hidden 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 address@hidden://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): + address@hidden +## Copyright (C) 1996, 1997, 2007 John W. Eaton +## +## 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 . address@hidden 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: + address@hidden +2008-04-02 David Bateman + + * graphics.cc (void gnuplot_backend::close_figure (const + octave_value&) const): Allow for an input and output stream. address@hidden example + address@hidden +The ChangeLog entries should describe what is changed, not why. The reason of +the change should appear in the commit message. + address@hidden Octave sources (m-files) address@hidden 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: + address@hidden + x = max (sin (y+3), 2); address@hidden example + address@hidden +An exception are matrix and vector constructors: + address@hidden + [sin(x), cos(x)] address@hidden example + address@hidden +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 address@hidden + A(:,i,j) address@hidden example + address@hidden +but + address@hidden + A([1:i-1;i+1:n], XI(:,2:n-1)) address@hidden 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}, address@hidden) rather than generic @code{end}. Enclose the @code{if}, address@hidden, @code{until} and @code{switch} conditions in parentheses, +like in C: + address@hidden +if (isvector (a)) + s = sum(a); +endif address@hidden example + address@hidden +Do not do this, however, with @code{for}: + address@hidden +for i = 1:n + b(i) = sum (a(:,i)); +endfor address@hidden example + address@hidden C++ sources address@hidden 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: + address@hidden +static bool +matches_patterns (const string_vector& patterns, int pat_idx, + int num_pat, const std::string& name) address@hidden example + address@hidden +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: + address@hidden +if (have_args) + @{ + idx.push_back (first_args); + have_args = false; + @} +else + idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp)); address@hidden example + address@hidden +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: + address@hidden +SVD::type type = ((nargout == 0 || nargout == 1) + ? SVD::sigma_only + : (nargin == 2) ? SVD::economy : SVD::std); address@hidden example + address@hidden +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: + address@hidden +octave_value retval; + +octave_idx_type nr = b.rows (); +octave_idx_type nc = b.cols (); + +double d1, d2; address@hidden 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. + address@hidden Other sources address@hidden 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}. + diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi --- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -615,6 +615,7 @@ @include dynamic.texi @include testfun.texi @include tips.texi address@hidden contrib.texi @include bugs.texi @include install.texi @include emacs.texi