Mercurial > hg > octave-nkf

annotate doc/interpreter/contrib.txi @ 14119:94e2a76f1e5a stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Final grammarcheck and spellcheck before 3.6.0 release. * container.txi, aspell-octave.en.pws, expr.txi, vectorize.txi, accumarray.m, accumdim.m, interpft.m, strread.m, parseparams.m, warning_ids.m, cellfun.cc, help.cc: grammarcheck and spellcheck docstrings.
author Rik <octave@nomad.inbox5.com>
date Thu, 29 Dec 2011 06:05:00 -0800
parents b0cdd60db5e5
children 72c96de7a403
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11523
fd0a3ac60b0e update copyright notices
John W. Eaton <jwe@octave.org>
parents: 11195
diff changeset
1 @c Copyright (C) 2008-2011 Jaroslav Hajek
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
2 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
3 @c This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
4 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
5 @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
6 @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
7 @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
8 @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
9 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
10 @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
11 @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
12 @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
13 @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
14 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
15 @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
16 @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
17 @c <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
18
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
19 @node Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
20 @appendix Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
21 @cindex coding standards
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
22 @cindex Octave development
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
23
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
24 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
25
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
26 @menu
9032
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
27 * How to Contribute::
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
28 * General Guidelines::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
29 * Octave Sources (m-files)::
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
30 * C++ Sources::
10599
d0e0bb2ebebb Remove tabs in .txi files causing problems with pdf formatting.
Rik <octave@nomad.inbox5.com>
parents: 9322
diff changeset
31 * Other Sources::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
32 @end menu
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
33
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
34 @node How to Contribute
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
35 @section How to Contribute
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
36 The mailing list for Octave development discussion and sending
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
37 contributions is @email{maintainers@@octave.org}. This concerns the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
38 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
39 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
40 place for this is the allied Octave-Forge project
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
41 (@url{http://octave.sf.net}). Note that the Octave project is
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
42 inherently more conservative and follows narrower rules.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
43
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
44 The preferable form of contribution is creating a Mercurial changeset
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
45 and sending it via e-mail to the octave-maintainers mailing list.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
46 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
47 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
48 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
49 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
50 A good place to start is
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
51 @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
52 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
53
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
54 A simple contribution sequence could look like this:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
55
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
56 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
57 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
58 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
59 # make a local copy of the octave
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
60 # source repository
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
61 cd octave
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
62 # change some sources@dots{}
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
63 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
64 # commit the changeset into your
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
65 # local repository
8177
65c4ac814082 hg syntax bug in mercurial example
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8055
diff changeset
66 hg export -o ../cool.diff tip
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
67 # export the changeset to a diff
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
68 # file
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
69 # send ../cool.diff via email
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
70 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
71 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
72
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
73 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
74 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
75 queues, where work on two unrelated changesets is done in parallel and
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
76 one of the changesets is updated after discussion on the maintainers
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
77 mailing list:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
78
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
79 @example
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
80 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
81 # change sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
82 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
83 # change even more@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
84 hg qref -m "solution to nasty bug!"
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
85 # save again with commit message
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
86 hg export -o ../nasty.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
87 # export the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
88 # send ../nasty.diff via email
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
89 hg qpop # undo the application of the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
90 # and remove the changes from the
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
91 # 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
92 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
93 # change doc sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
94 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
95 # save the changes into the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
96 hg export -o ../doc.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
97 # export the second patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
98 # send ../doc.diff tip via email
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
99 hg qpop
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
100 # discussion in the maintainers mailing list @dots{}
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
101 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
102 # change sources yet again @dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
103 hg qref
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
104 hg export -o ../nasty2.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
105 # send ../nasty2.diff via email
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
106 @end example
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
107
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
108 @node General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
109 @section General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
110
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
111 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
112 (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
113 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
114 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
115 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
116
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
117 @example
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
118 ## Copyright (C) 1996-2011 John W. Eaton <jwe@@octave.org>
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
119 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
120 ## This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
121 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
122 ## 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
123 ## 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
124 ## 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
125 ## 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
126 ## later version.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
127 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
128 ## 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
129 ## but WITHOUT ANY WARRANTY; without even the implied
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
130 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
131 ## PURPOSE. See the GNU General Public License for more
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
132 ## details.
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 ## 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
135 ## 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
136 ## see <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
137 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
138
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
139 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
140 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
141 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
142 @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
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150 example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
151
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
152 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
153 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
154 look for methods before constructors
8055
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 * 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
157 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
158 documentation.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
159
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
160 * 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
161 * 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
162 * 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
163 (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
164 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
165 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
166
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
167 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
168 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
169 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
170 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
171 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
172 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
173 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
174 reading it later.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
175
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
176 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
177 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
178 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
179
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
180 @example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
181 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
182 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
183 @end group
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
184 @end example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
185
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
186 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
187 FIXME.
8202
cf59d542f33e replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents: 8200
diff changeset
188
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
189 @node Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
190 @section Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
191
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
192 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
193 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
194 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
195 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
196 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
197
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
198 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
199 x = max (sin (y+3), 2);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
200 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
201
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
202 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
203 An exception are matrix and vector constructors:
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
204
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
205 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
206 [sin(x), cos(x)]
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
207 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
208
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
209 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
210 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
211 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
212 identifier (this differentiates indexing and function calls nicely).
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
213 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
214 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
215
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
216 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
217 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
218 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
219
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
220 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
221 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
222
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
223 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
224 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
225 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
226
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
227 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
228 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
229 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
230 wisely.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
231
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
232 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
233 @code{endswitch}) rather than generic @code{end}.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
234
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
235 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
236 conditions in parentheses, like in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
237
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
238 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
239 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
240 if (isvector (a))
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
241 s = sum(a);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
242 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
243 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
244 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
245
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
246 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
247 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
248 @code{for} statement. Write:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
249
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
250 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
251 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
252 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
253 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
254 endfor
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
255 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
256 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
257
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
258 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
259 @section C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
260
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
261 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
262 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
263 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
264
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
265 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
266 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
267 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
268 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
269 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
270 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
271 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
272
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
273 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
274 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
275 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
276 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
277 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
278
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
279 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
280 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
281 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
282 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
283 indents). Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
284
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
285 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
286 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
287 if (have_args)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
288 @{
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
289 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
290 have_args = false;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
291 @}
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
292 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
293 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
294 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
295 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
296
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
297 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
298 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
299 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
300
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
301 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
302 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
303 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
304 innermost braces enclosing the split. Example:
8055
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
307 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
308 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
309 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
310 : (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
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
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
315 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
316 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
317 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
318
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
319 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
320 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
321 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
322 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
323 Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
324
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
325 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
326 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
327 octave_value retval;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
328
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
329 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
330 octave_idx_type nc = b.cols ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
331
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
332 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
333 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
334 @end example
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 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
337 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
338
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
339 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
340 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
341 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
342 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
343 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
344 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
345 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
346
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
347 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
348 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
349 Apart from C++ and Octave language (m-files), Octave's sources include
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
350 files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo and
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
351 @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
352 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
353 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
354 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
355
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
356 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
357
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
358 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
359 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
360 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
361 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
362 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
363
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
364 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
365 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
366 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
367 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
368
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
369 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
370 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
371 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
372 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
373 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
374 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
375
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
376 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
377 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
378 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
379 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
380 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
381 @end example