Mercurial > hg > octave-nkf

annotate doc/interpreter/contrib.txi @ 20096:966a1933f3fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
respect x- or y-only pan mode when clicking and dragging (bug #44408) * Canvas.cc (Canvas::canvasMouseMoveEvent): Get pan mode and pass it to translate_view function.
author John W. Eaton <jwe@octave.org>
date Mon, 02 Mar 2015 20:48:00 -0500
parents 4197fc428c7d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
1 @c Copyright (C) 2012 John W. Eaton
19898
4197fc428c7d maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents: 19344
diff changeset
2 @c Copyright (C) 2008-2015 Jaroslav Hajek
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
3 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
4 @c This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
5 @c
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
6 @c Octave is free software; you can redistribute it and/or modify it
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
7 @c under the terms of the GNU General Public License as published by the
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
8 @c Free Software Foundation; either version 3 of the License, or (at
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
9 @c your option) any later version.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
10 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
14 @c for more details.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
15 @c
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
16 @c You should have received a copy of the GNU General Public License
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
17 @c along with Octave; see the file COPYING. If not, see
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
18 @c <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
19
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
20 @node Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
21 @appendix Contributing Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
22 @cindex coding standards
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
23 @cindex Octave development
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
24
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
25 This chapter is dedicated to those who wish to contribute code to Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
26
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
27 @menu
9032
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
28 * How to Contribute::
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
29 * Building the Development Sources::
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
30 * Basics of Generating a Changeset::
9032
349616d9c38e Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
31 * General Guidelines::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
32 * Octave Sources (m-files)::
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
33 * C++ Sources::
10599
d0e0bb2ebebb Remove tabs in .txi files causing problems with pdf formatting.
Rik <octave@nomad.inbox5.com>
parents: 9322
diff changeset
34 * Other Sources::
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
35 @end menu
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
36
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
37 @node How to Contribute
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
38 @section How to Contribute
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
39 The mailing list for Octave development discussions is
17680
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
40 @email{maintainers@@octave.org}. Patches should be submitted to
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
41 @url{https://savannah.gnu.org/patch/?func=additem&group=octave, Octave's patch tracker}.
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
42 This concerns the development of Octave core, i.e., code that goes in to Octave
17680
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
43 directly. You may consider developing and publishing a package instead;
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
44 a great place for this is the allied Octave-Forge project
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
45 (@url{http://octave.sourceforge.net}). Note that the Octave core
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
46 project is inherently more conservative and follows narrower rules.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
47
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
48 @node Building the Development Sources
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
49 @section Building the Development Sources
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
50
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
51 The directions for building from the development sources change from
16666
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
52 time to time, so you should read the resources for developers on the web
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
53 or in the development sources archive. Start here:
af7287d567dc minor change to wording for previous change
John W. Eaton <jwe@octave.org>
parents: 16665
diff changeset
54 @url{http://www.octave.org/get-involved.html}.
14150
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
55
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
56 @node Basics of Generating a Changeset
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
57 @section Basics of Generating a Changeset
87f06b9990bb doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents: 14138
diff changeset
58
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
59 The best way to contribute is to create a Mercurial changeset and submit it to
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
60 the @url{http://savannah.gnu.org/bugs/?group=octave, bug} or
16792
b157ba28f123 doc: Use Texinfo @url command consistently throughout documentation.
Rik <rik@octave.org>
parents: 16791
diff changeset
61 @url{http://savannah.gnu.org/patch/?func=additem&group=octave, patch}
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
62 trackers@footnote{Please use the patch tracker only for patches which add new
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
63 features. If you have a patch to submit that fixes a bug, you should use the
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
64 bug tracker instead.}.
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
65 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
66 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
67 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
68 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
69 A good place to start is
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
70 @url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. There
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
71 you will also find help about how to install Mercurial.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
72
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
73 A simple contribution sequence could look like this:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
74
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
75 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
76 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
77 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
78 # make a local copy of the octave
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
79 # source repository
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
80 cd octave
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
81 # change some sources@dots{}
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
82 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
83 # commit the changeset into your
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
84 # local repository
8177
65c4ac814082 hg syntax bug in mercurial example
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8055
diff changeset
85 hg export -o ../cool.diff tip
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
86 # export the changeset to a diff
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
87 # file
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
88 # attach ../cool.diff to your bug report
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
89 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
90 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
91
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
92 You may want to get familiar with Mercurial queues to manage your
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
93 changesets. To work with queues you must activate the extension
16826
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
94 @nospell{mq} with the following entry in Mercurial's configuration file
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
95 @file{.hgrc} (or @file{Mercurial.ini} on Windows):
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
96
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
97 @example
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
98 @group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
99 [extensions]
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
100 mq=
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
101 @end group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
102 @end example
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
103
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
104 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
105 queues, where work on two unrelated changesets is done in parallel and
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
106 one of the changesets is updated after discussion on the bug tracker:
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
107
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
108 @example
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
109 hg qnew 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
110 # change sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
111 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
112 # change even more@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
113 hg qref -m "solution to nasty bug!"
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
114 # save again with commit message
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
115 hg export -o ../nasty.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
116 # export the patch
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
117 # attach ../nasty.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
118 hg qpop # undo the application of the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
119 # and remove the changes from the
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
120 # 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
121 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
122 # change doc sources@dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
123 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
124 # save the changes into the patch
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
125 hg export -o ../doc.diff tip
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
126 # export the second patch
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
127 # attach ../doc.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
128 hg qpop
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
129 # discussion in the bug tracker @dots{}
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
130 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
131 # change sources yet again @dots{}
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
132 hg qref
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
133 hg export -o ../nasty2.diff tip
14883
f20312fc9046 doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents: 14856
diff changeset
134 # attach ../nasty2.diff to your bug report
8200
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
135 @end example
837487bd3450 help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8177
diff changeset
136
18073
42c3e30557a4 doc: Small fixes to the octave manual (bug #40557).
Rik <rik@octave.org>
parents: 17744
diff changeset
137 Mercurial has a few more useful extensions that really should be enabled.
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
138 They are not enabled by default due to a number of factors
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
139 (mostly because they don't work in all terminal types).
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
140
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
141 The following entries in the @file{.hgrc} are recommended
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
142
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
143 @example
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
144 @group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
145 [extensions]
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
146 graphlog=
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
147 color=
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
148 progress=
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
149 pager=
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
150 @end group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
151 @end example
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
152
16826
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
153 For the color extension, default color and formatting
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
154 of @code{hg status} can be modified by
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
155
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
156 @example
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
157 @group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
158 [color]
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
159 status.modified = magenta bold
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
160 status.added = green bold
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
161 status.removed = red bold
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
162 status.deleted = cyan bold
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
163 status.unknown = black bold
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
164 status.ignored = black bold
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
165 @end group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
166 @end example
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
167
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
168 Sometimes a few further improvements for the pager extension are
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
169 necessary. The following options should not be enabled unless paging
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
170 is not working correctly.
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
171
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
172 @example
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
173 @group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
174 [pager]
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
175 # Some options for the less pager, see less(1) for their meaning.
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
176 pager = LESS='FSRX' less
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
177
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
178 # Some commands that aren't paged by default; also enable paging
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
179 # for them
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
180 attend = tags, help, annotate, cat, diff, export, status, \
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
181 outgoing, incoming
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
182 @end group
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
183 @end example
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
184
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
185 Enabling the described extensions should immediately lead to a difference
16826
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
186 when using the command line version of @nospell{hg}. Of these options, the
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
187 only one that enables a new command is @nospell{graphlog}. It is recommanded
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
188 that to use the command @code{hg glog}, instead of @code{hg log}, for a better
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
189 feel about what commits are being based on.
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
190
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
191 @node General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
192 @section General Guidelines
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
193
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
194 All Octave's sources are distributed under the GNU General Public License
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
195 (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
196 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
197 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
198 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
199
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
200 @example
19344
0f9c5a15c8fa doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 19007
diff changeset
201 @group
19898
4197fc428c7d maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents: 19344
diff changeset
202 ## Copyright (C) 1996-2015 John W. Eaton <jwe@@octave.org>
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
203 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
204 ## This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
205 ##
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
206 ## Octave is free software; you can redistribute it and/or modify it
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
207 ## under the terms of the GNU General Public License as published by
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
208 ## the Free Software Foundation; either version 3 of the License, or
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
209 ## (at your option) any later version.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
210 ##
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
211 ## Octave is distributed in the hope that it will be useful, but
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
212 ## WITHOUT ANY WARRANTY; without even the implied warranty of
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
213 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
214 ## GNU General Public License for more details.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
215 ##
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
216 ## You should have received a copy of the GNU General Public License
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
217 ## along with Octave; see the file COPYING. If not,
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
218 ## see <http://www.gnu.org/licenses/>.
19344
0f9c5a15c8fa doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 19007
diff changeset
219 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
220 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
221
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
222 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
223 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
224 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
225 @file{Mercurial.ini} on Windows) with your name and email, which will
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
226 be automatically added to your commit message. Your commit message
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
227 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
228 are patching a bug, this one-line explanation should mention the bug
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
229 number at the end. If your change is small and only touches one file then
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
230 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
231 several parts of one file, you should enumerate your changes roughly
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
232 following the GNU coding standards for changelogs, as in the following
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
233 example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
234
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
235 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
236 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
237 look for methods before constructors
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
238
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
239 * 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
240 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
241 documentation.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
242
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
243 * 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
244 * 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
245 * 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
246 (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
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
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
251 In this example, the names of the file changed is listed first, and in
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
252 parentheses the name of the function in that file that was modified. There
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
253 is no need to mention the function for m-files that only contain one function.
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
254 The commit message should describe what was changed, not why it was changed.
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
255 Any explanation for why a change is needed should appear as comments in the
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
256 code, particularly if there is something that might not be obvious to someone
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
257 reading it later.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
258
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
259 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
260 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
261 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
262
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
263 @example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
264 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
265 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
266 @end group
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
267 @end example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
268
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
269 The preferred comment mark for places that may need further attention is
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
270 @code{FIXME:}.
8202
cf59d542f33e replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents: 8200
diff changeset
271
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
272 @node Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
273 @section Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
274
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
275 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
276 your editor so that it converts tabs to spaces. Indent the bodies of
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
277 statement blocks. The recommended indent is 2 spaces. When calling
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
278 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
279 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
280
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
281 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
282 x = max (sin (y+3), 2);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
283 @end example
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 @noindent
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
286 An exception are matrix or cell constructors:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
287
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
288 @example
19007
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18598
diff changeset
289 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
290 [sin(x), cos(x)]
18598
186ea1c2bbd4 contrib.txi: Use correct Texinfo to generate curly braces.
Rik <rik@octave.org>
parents: 18597
diff changeset
291 @{sin(x), cos(x)@}
19007
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18598
diff changeset
292 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
293 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
294
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
295 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
296 Here, putting spaces after @code{sin}, @code{cos} would result in a
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
297 parse error. For an indexing expression, do not put a space after the
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
298 identifier (this differentiates indexing and function calls nicely).
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
299 The space after a comma is not necessary if index expressions are simple,
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
300 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
301
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
302 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
303 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
304 @end example
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 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
307 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
308
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
309 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
310 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
311 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
312
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
313 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
314 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
315 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
316 wisely.
8055
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 Always use a specific end-of-block statement (like @code{endif},
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
319 @code{endswitch}) rather than the generic @code{end}.
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
320
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
321 Enclose the @code{if}, @code{while}, @code{until}, and @code{switch}
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
322 conditions in parentheses, as in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
323
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
324 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
325 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
326 if (isvector (a))
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14853
diff changeset
327 s = sum (a);
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
328 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
329 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
330 @end example
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 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
333 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
334 @code{for} statement. Write:
8055
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
337 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
338 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
339 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
340 endfor
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
341 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
342 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
343
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
344 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
345 @section C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
346
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
347 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
348 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
349 like this:
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
352 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
353 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
354 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
355 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
356 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
357 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
358
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
359 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
360 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
361 lists should be aligned on the first char after the open parenthesis.
17498
cdeadf62663f doc: Fix recommendation on where to put spaces around parens
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 16826
diff changeset
362 You should put a space before the left open parenthesis and after commas,
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
363 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
364
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
365 The 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
366 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
367 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
368 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
369 indents). Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
370
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
371 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
372 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
373 if (have_args)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
374 @{
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
375 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
376 have_args = false;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
377 @}
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
378 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
379 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
380 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
381 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
382
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
383 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
384 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
385 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
386
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
387 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
388 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
389 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
390 innermost braces enclosing the split. Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
391
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
392 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
393 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
394 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
395 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
396 : (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
397 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
398 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
399
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
400 @noindent
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
401 Consider putting extra braces around a multi-line expression to make it
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
402 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
403 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
404
18597
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
405 Declare variables just before they are needed. Use local variables of
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
406 blocks---it helps optimization. Don't write a multi-line variable
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
407 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
408 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
409 Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
410
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
411 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
412 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
413 octave_value retval;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
414
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
415 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
416 octave_idx_type nc = b.cols ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
417
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
418 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
419 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
420 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
421
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
422 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
423 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
424
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
425 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
426 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
427 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
428 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
429 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
430 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
431 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
432
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
433 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
434 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
435 Apart from C++ and Octave language (m-files), Octave's sources include
16791
acd6a21259a9 doc: Use the serial comma in Contributors chapter.
Rik <rik@octave.org>
parents: 16666
diff changeset
436 files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo, and
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
437 @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
438 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
439 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
440 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
441
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
442 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
443
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
444 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
445 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
446 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
447 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
448 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
449
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
450 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
451 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
452 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
453 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
454
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
455 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
456 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
457 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
458 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
459 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
460 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
461
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
462 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
463 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
464 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
465 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
466 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
467 @end example