Mercurial > hg > octave-nkf

annotate doc/interpreter/contrib.txi @ 16791:acd6a21259a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Use the serial comma in Contributors chapter. * doc/interpreter/contrib.txi: Use the serial comma.
author Rik <rik@octave.org>
date Thu, 20 Jun 2013 19:14:55 -0700
parents af7287d567dc
children b157ba28f123
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
1 @c Copyright (C) 2012 John W. Eaton
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 14038
diff changeset
2 @c Copyright (C) 2008-2012 Jaroslav Hajek
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
3 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
4 @c This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
5 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
6 @c Octave is free software; you can redistribute it and/or modify it
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
7 @c under the terms of the GNU General Public License as published by the
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
8 @c Free Software Foundation; either version 3 of the License, or (at
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
9 @c your option) any later version.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
10 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
14 @c for more details.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
15 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
16 @c You should have received a copy of the GNU General Public License
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
17 @c along with Octave; see the file COPYING. If not, see
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
18 @c <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
19
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
20 @node Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
21 @appendix Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
22 @cindex coding standards
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
23 @cindex Octave development
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
24
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
25 This chapter is dedicated to those who wish to contribute code to Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
26
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
27 @menu
9032
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
28 * How to Contribute::
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
29 * Building the Development Sources::
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
30 * Basics of Generating a Changeset::
9032
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
31 * General Guidelines::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
32 * Octave Sources (m-files)::
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
33 * C++ Sources::
10599
d0e0bb2ebebb Remove tabs in .txi files causing problems with pdf formatting.
Rik <octave@nomad.inbox5.com>
parents: 9322
diff changeset
34 * Other Sources::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
35 @end menu
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
36
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
37 @node How to Contribute
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
38 @section How to Contribute
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
39 The mailing list for Octave development discussion and sending
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
40 contributions is @email{maintainers@@octave.org}. This concerns the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
41 development of Octave core, i.e., code that goes to Octave directly.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
42 You may consider developing and publishing a package instead; a great
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
43 place for this is the allied Octave-Forge project
16791
acd6a21259a9 doc: Use the serial comma in Contributors chapter.
Rik <rik@octave.org>
parents: 16666
diff changeset
44 (@url{http://octave.sourceforge.net}). Note that the Octave core project is
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
45 inherently more conservative and follows narrower rules.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
46
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
47 @node Building the Development Sources
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
48 @section Building the Development Sources
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
49
16665
d68e72ee28bf remove instructions for building dev sources from manual
John W. Eaton <jwe@octave.org>
parents: 16601
diff changeset
50 The directions for building from the Development sources change from
16666
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
51 time to time, so you should read the resources for developers on the web
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
52 or in the development sources archive. Start here:
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
53 @url{http://www.octave.org/get-involved.html}.
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
54
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
55 @node Basics of Generating a Changeset
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
56 @section Basics of Generating a Changeset
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
57
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
58 The preferable form of contribution is creating a Mercurial changeset
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
59 and submit it to the @uref{http://savannah.gnu.org/bugs/?group=octave, bug} or
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
60 @uref{http://savannah.gnu.org/patch/?func=additem&group=octave, patch}
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
61 trackers@footnote{Please use the patch tracker only for patches which add new
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
62 features. If you have a patch to submit that fixes a bug, you should use the
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
63 bug tracker instead.}.
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
64 Mercurial is the source code management system currently used to develop
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
65 Octave. Other forms of contributions (e.g., simple diff patches) are
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
66 also acceptable, but they slow down the review process. If you want to
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
67 make more contributions, you should really get familiar with Mercurial.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
68 A good place to start is
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
69 @url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. There
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
70 you will also find help how to install Mercurial.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
71
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
72 A simple contribution sequence could look like this:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
73
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
74 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
75 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
76 hg clone http://www.octave.org/hg/octave
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
77 # make a local copy of the octave
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
78 # source repository
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
79 cd octave
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
80 # change some sources@dots{}
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
81 hg commit -m "make Octave the coolest software ever"
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
82 # commit the changeset into your
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
83 # local repository
8177
65c4ac814082 hg syntax bug in mercurial example
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8055
diff changeset
84 hg export -o ../cool.diff tip
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
85 # export the changeset to a diff
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
86 # file
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
87 # attach ../cool.diff to your bug report
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
88 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
89 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
90
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
91 You may want to get familiar with Mercurial queues to manage your
14038
b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 13168
diff changeset
92 changesets. Here is a slightly more complex example using Mercurial
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
93 queues, where work on two unrelated changesets is done in parallel and
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
94 one of the changesets is updated after discussion on the bug tracker:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
95
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
96 @example
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
97 hg qnew nasty_bug # create a new patch
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
98 # change sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
99 hg qref # save the changes into the patch
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
100 # change even more@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
101 hg qref -m "solution to nasty bug!"
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
102 # save again with commit message
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
103 hg export -o ../nasty.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
104 # export the patch
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
105 # attach ../nasty.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
106 hg qpop # undo the application of the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
107 # and remove the changes from the
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
108 # source tree
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
109 hg qnew doc_improvements # create an unrelated patch
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
110 # change doc sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
111 hg qref -m "could not find myfav.m in the doc"
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
112 # save the changes into the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
113 hg export -o ../doc.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
114 # export the second patch
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
115 # attach ../doc.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
116 hg qpop
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
117 # discussion in the bug tracker @dots{}
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
118 hg qpush nasty_bug # apply the patch again
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
119 # change sources yet again @dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
120 hg qref
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
121 hg export -o ../nasty2.diff tip
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
122 # attach ../nasty2.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
123 @end example
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
124
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
125 @node General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
126 @section General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
127
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
128 All Octave's sources are distributed under the General Public License
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
129 (GPL). Currently, Octave uses GPL version 3. For details about this
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
130 license, see @url{http://www.gnu.org/licenses/gpl.html}. Therefore,
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
131 whenever you create a new source file, it should have the following
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
132 comment header (use appropriate year, name and comment marks):
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
133
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
134 @example
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 14038
diff changeset
135 ## Copyright (C) 1996-2012 John W. Eaton <jwe@@octave.org>
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
136 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
137 ## This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
138 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
139 ## Octave is free software; you can redistribute it and/or
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
140 ## modify it under the terms of the GNU General Public
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
141 ## License as published by the Free Software Foundation;
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
142 ## either version 3 of the License, or (at your option) any
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
143 ## later version.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
144 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
145 ## Octave is distributed in the hope that it will be useful,
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
146 ## but WITHOUT ANY WARRANTY; without even the implied
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
147 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
148 ## PURPOSE. See the GNU General Public License for more
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
149 ## details.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
150 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
151 ## You should have received a copy of the GNU General Public
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
152 ## License along with Octave; see the file COPYING. If not,
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
153 ## see <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
154 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
155
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
156 Always include commit messages in changesets. After making your source
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
157 changes, record and briefly describe the changes in your commit message.
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
158 You should have previously configured your @file{.hgrc} (or
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
159 @file{Mercurial.ini} on Windows) with your name and email, which will
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
160 get automatically added to your commit message. Your commit message
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
161 should have a brief one-line explanation of what the commit does. If you
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
162 are patching a bug, this one-line explanation should mention the bug
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
163 number at the end. If your change is small and only touches one file,
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
164 this is typically sufficient. If you are modifying several files or
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
165 several parts of one file, you should enumerate your changes roughly
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
166 following the GNU coding standards on changelogs, like the following
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
167 example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
168
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
169 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
170 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
171 look for methods before constructors
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
172
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
173 * symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
14038
b0cdd60db5e5 doc: Grammarcheck documentation ahead of 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 13168
diff changeset
174 Look for class methods before constructors, contrary to @sc{matlab}
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
175 documentation.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
176
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
177 * test/ctor-vs-method: New directory of test classes.
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
178 * test/test_ctor_vs_method.m: New file.
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
179 * test/Makefile.am: Include ctor-vs-method/module.mk.
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
180 (FCN_FILES): Include test_ctor_vs_method.m in the list.
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
181 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
182 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
183
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
184 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
185 In this example, the names of files is mentioned, and in parentheses the
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
186 name of the function in that file that was modified. There is no need to
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
187 mention the function for m-files that only contain one function. The
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
188 commit message should describe what is changed, not why. Any explanation
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
189 of why a change is needed should appear as comments in the code,
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
190 particularly if there is something that might not be obvious to someone
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
191 reading it later.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
192
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
193 When submitting code which addresses a known bug on the Octave bug
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
194 tracker (@url{http://bugs.octave.org}), please add '(bug #XXXXX)' to the
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
195 first line of the commit messages. For example:
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
196
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
197 @example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
198 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
199 Fix bug for complex input for gradient (bug #34292).
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
200 @end group
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
201 @end example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
202
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
203 The preferred comment mark for places that may need further attention is
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
204 FIXME.
8202
cf59d542f33e replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents: 8200
diff changeset
205
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
206 @node Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
207 @section Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
208
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
209 Don't use tabs. Tabs cause trouble. If you are used to them, set up
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
210 your editor so that it converts tabs to spaces. Indent the bodies of
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
211 the statement blocks. Recommended indent is 2 spaces. When calling
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
212 functions, put spaces after commas and before the calling parentheses,
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
213 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
214
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
215 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
216 x = max (sin (y+3), 2);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
217 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
218
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
219 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
220 An exception are matrix and vector constructors:
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
221
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
222 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
223 [sin(x), cos(x)]
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
224 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
225
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
226 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
227 Here, putting spaces after @code{sin}, @code{cos} would result in a
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
228 parse error. In indexing expression, do not put a space after the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
229 identifier (this differentiates indexing and function calls nicely).
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
230 The space after comma is not necessary if index expressions are simple,
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
231 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
232
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
233 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
234 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
235 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
236
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
237 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
238 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
239
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
240 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
241 A([1:i-1;i+1:n], XI(:,2:n-1))
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
242 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
243
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
244 Use lowercase names if possible. Uppercase is acceptable for variable
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
245 names consisting of 1-2 letters. Do not use mixed case names. Function
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
246 names must be lowercase. Function names are global, so choose them
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
247 wisely.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
248
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
249 Always use a specific end-of-block statement (like @code{endif},
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
250 @code{endswitch}) rather than generic @code{end}.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
251
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
252 Enclose the @code{if}, @code{while}, @code{until} and @code{switch}
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
253 conditions in parentheses, like in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
254
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
255 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
256 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
257 if (isvector (a))
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14853
diff changeset
258 s = sum (a);
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
259 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
260 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
261 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
262
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
263 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
264 Do not do this, however, with the iteration counter portion of a
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
265 @code{for} statement. Write:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
266
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
267 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
268 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
269 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
270 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
271 endfor
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
272 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
273 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
274
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
275 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
276 @section C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
277
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
278 Don't use tabs. Tabs cause trouble. If you are used to them, set up
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
279 your editor so that it converts tabs to spaces. Format function headers
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
280 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
281
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
282 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
283 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
284 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
285 matches_patterns (const string_vector& patterns, int pat_idx,
10599
d0e0bb2ebebb Remove tabs in .txi files causing problems with pdf formatting.
Rik <octave@nomad.inbox5.com>
parents: 9322
diff changeset
286 int num_pat, const std::string& name)
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
287 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
288 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
289
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
290 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
291 The function name should start in column 1, and multi-line argument
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
292 lists should be aligned on the first char after the open parenthesis.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
293 You should put a space after the left open parenthesis and after commas,
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
294 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
295
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
296 Recommended indent is 2 spaces. When indenting, indent the statement
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
297 after control structures (like @code{if}, @code{while}, etc.). If there
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
298 is a compound statement, indent @emph{both} the curly braces and the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
299 body of the statement (so that the body gets indented by @emph{two}
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
300 indents). Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
301
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
302 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
303 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
304 if (have_args)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
305 @{
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
306 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
307 have_args = false;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
308 @}
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
309 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
310 idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp));
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
311 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
312 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
313
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
314 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
315 If you have nested @code{if} statements, use extra braces for extra
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
316 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
317
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
318 Split long expressions in such a way that a continuation line starts
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
319 with an operator rather than identifier. If the split occurs inside
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
320 braces, continuation should be aligned with the first char after the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
321 innermost braces enclosing the split. Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
322
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
323 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
324 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
325 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
326 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
327 : (nargin == 2) ? SVD::economy : SVD::std);
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
328 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
329 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
330
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
331 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
332 Consider putting extra braces around a multiline expression to make it
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
333 more readable, even if they are not necessary. Also, do not hesitate to
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
334 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
335
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
336 Declare variables just before they're needed. Use local variables of
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
337 blocks---it helps optimization. Don't write multi-line variable
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
338 declaration with a single type specification and multiple variables. If
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
339 the variables don't fit on single line, repeat the type specification.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
340 Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
341
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
342 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
343 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
344 octave_value retval;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
345
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
346 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
347 octave_idx_type nc = b.cols ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
348
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
349 double d1, d2;
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
350 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
351 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
352
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
353 Use lowercase names if possible. Uppercase is acceptable for variable
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
354 names consisting of 1-2 letters. Do not use mixed case names.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
355
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
356 Use Octave's types and classes if possible. Otherwise, use the C++
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
357 standard library. Use of STL containers and algorithms is encouraged.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
358 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
359 expressions, labels and gotos, and explicit typecasts. If you need to
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
360 typecast, use the modern C++ casting operators. In functions, minimize
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
361 the number of @code{return} statements---use nested @code{if} statements
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
362 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
363
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
364 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
365 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
366 Apart from C++ and Octave language (m-files), Octave's sources include
16791
acd6a21259a9 doc: Use the serial comma in Contributors chapter.
Rik <rik@octave.org>
parents: 16666
diff changeset
367 files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo, and
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
368 @TeX{}. There are not many rules to follow when using these other
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
369 languages; some of them are summarized below. In any case, the golden
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
370 rule is: if you modify a source file, try to follow any conventions you
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
371 can detect in the file or other similar files.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
372
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
373 For C you should obviously follow all C++ rules that can apply.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
374
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
375 If you modify a Fortran file, you should stay within Fortran 77 with
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
376 common extensions like @code{END DO}. Currently, we want all sources to
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
377 be compilable with the f2c and g77 compilers, without special flags if
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
378 possible. This usually means that non-legacy compilers also accept the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
379 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
380
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
381 The M4 macro language is mainly used for Autoconf configuration files.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
382 You should follow normal M4 rules when contributing to these files.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
383 Some M4 files come from external source, namely the Autoconf archive
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
384 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
385
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
386 If you give a code example in the documentation written in Texinfo with
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
387 the @code{@@example} environment, you should be aware that the text
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
388 within such an environment will not be wrapped. It is recommended that
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
389 you keep the lines short enough to fit on pages in the generated pdf or
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
390 ps documents. Here is a ruler (in an @code{@@example} environment) for
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
391 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
392
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
393 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
394 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
395 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
396 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
397 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
398 @end example