Mercurial > hg > octave-lyh

annotate doc/interpreter/contrib.txi @ 13166:d624b6f216ac stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update guidelines on how to write commit messages and changelogs
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
date Mon, 19 Sep 2011 20:01:43 -0500
parents a12d7f53c2ab
children 470ef1a5d66e
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
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
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
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
139 Always include commit messages in changesets. After making your source
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
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
143 get automatically added to your commit message. 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
144 should have a brief one-line explanation of what the commit does. If you
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
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
146 number at the end. If your change is small and only touches one file,
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
147 this is typically sufficient. If you are modifying several files or
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
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
154 look for methods before constructors
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
155
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
156 * symtab.cc (symbol_table::fcn_info::fcn_info_rep::find):
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
157 Look for class methods before constructors, contrary to Matlab
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
158 documentation.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
159
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
160 * test/ctor-vs-method: New directory of test classes.
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
161 * test/test_ctor_vs_method.m: New file.
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
162 * test/Makefile.am: Include ctor-vs-method/module.mk.
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
163 (FCN_FILES): Include test_ctor_vs_method.m in the list.
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
164
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
165 * DLD-FUNCTIONS/regexp.cc (octregexp_list): Handle repeated matches
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
166 in the list of matches returned by pcre.
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
167 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
168 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
169
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
170 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
171 In this example, the names of files is mentioned, and in parentheses the
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
172 name of the function in that file that was modified. There is no need to
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
173 mention the function for m-files that only contain one function. The
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
174 commit message should describe what is changed, not why. Any explanation
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
175 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
176 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
177 reading it later.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
178
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
179 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
180 tracker (@url{http://bugs.octave.org}), please add '(bug #XXXXX)' to the
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
181 commit messages. Example:
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
182
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
183 @example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
184 @group
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
185 * ols.m: Fix erroneous degrees of freedom when computing the
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
186 covariance estimator (bug #32892).
12559
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
187 @end group
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
188 @end example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
189
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
190 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
191 FIXME.
8202
cf59d542f33e replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents: 8200
diff changeset
192
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
193 @node Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
194 @section Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
195
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
196 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
197 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
198 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
199 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
200 like this:
8055
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 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
203 x = max (sin (y+3), 2);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
204 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
205
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
206 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
207 An exception are matrix and vector constructors:
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 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
210 [sin(x), cos(x)]
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
211 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
212
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
213 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
214 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
215 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
216 identifier (this differentiates indexing and function calls nicely).
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
217 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
218 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
219
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
220 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
221 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
222 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
223
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
224 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
225 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
226
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
227 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
228 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
229 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
230
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
231 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
232 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
233 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
234 wisely.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
235
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
236 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
237 @code{endswitch}) rather than generic @code{end}.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
238
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
239 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
240 conditions in parentheses, like in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
241
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
242 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
243 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
244 if (isvector (a))
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
245 s = sum(a);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
246 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
247 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
248 @end example
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 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
251 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
252 @code{for} statement. Write:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
253
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
254 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
255 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
256 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
257 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
258 endfor
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
259 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
260 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
261
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
262 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
263 @section C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
264
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
265 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
266 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
267 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
268
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
269 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
270 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
271 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
272 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
273 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
274 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
275 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
276
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
277 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
278 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
279 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
280 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
281 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
282
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
283 Recommended indent is 2 spaces. When indenting, indent the statement
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
284 after control structures (like @code{if}, @code{while}, etc.). If there
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
285 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
286 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
287 indents). Example:
8055
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
290 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
291 if (have_args)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
292 @{
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
293 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
294 have_args = false;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
295 @}
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
296 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
297 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
298 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
299 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
300
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
301 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
302 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
303 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
304
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
305 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
306 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
307 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
308 innermost braces enclosing the split. Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
309
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
310 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
311 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
312 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
313 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
314 : (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
315 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
316 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
317
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
318 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
319 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
320 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
321 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
322
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
323 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
324 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
325 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
326 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
327 Example:
8055
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
330 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
331 octave_value retval;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
332
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
333 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
334 octave_idx_type nc = b.cols ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
335
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
336 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
337 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
338 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
339
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
340 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
341 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
342
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
343 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
344 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
345 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
346 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
347 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
348 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
349 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
350
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
351 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
352 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
353 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
354 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
355 @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
356 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
357 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
358 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
359
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
360 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
361
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
362 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
363 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
364 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
365 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
366 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
367
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
368 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
369 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
370 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
371 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
372
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
373 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
374 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
375 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
376 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
377 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
378 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
379
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
380 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
381 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
382 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
383 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
384 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
385 @end example