Mercurial > octave-nkf

annotate doc/interpreter/contrib.txi @ 18530:186ea1c2bbd4 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
contrib.txi: Use correct Texinfo to generate curly braces. * contrib.txi: Use correct Texinfo to generate curly braces.
author Rik <rik@octave.org>
date Fri, 28 Feb 2014 13:50:08 -0800
parents 3e731fc1e4d5
children 9ac2357f19bc
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
17744
d63878346099 maint: Update copyright notices for release.
John W. Eaton <jwe@octave.org>
parents: 17680
diff changeset
2 @c Copyright (C) 2008-2013 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
18529
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}.
18529
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
18529
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
18529
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
18529
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
18529
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
18529
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
18529
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
18529
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
17744
d63878346099 maint: Update copyright notices for release.
John W. Eaton <jwe@octave.org>
parents: 17680
diff changeset
201 ## Copyright (C) 1996-2013 John W. Eaton <jwe@@octave.org>
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
202 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
203 ## This file is part of Octave.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
204 ##
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
205 ## 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
206 ## 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
207 ## 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
208 ## (at your option) any later version.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
209 ##
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
210 ## 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
211 ## 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
212 ## 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
213 ## GNU General Public License for more details.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
214 ##
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
215 ## 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
216 ## 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
217 ## see <http://www.gnu.org/licenses/>.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
218 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
219
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
220 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
221 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
222 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
223 @file{Mercurial.ini} on Windows) with your name and email, which will
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
224 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
225 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
226 are patching a bug, this one-line explanation should mention the bug
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
227 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
228 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
229 several parts of one file, you should enumerate your changes roughly
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
230 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
231 example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
232
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
233 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
234 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
235 look for methods before constructors
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
236
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
237 * 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
238 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
239 documentation.
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
240
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
241 * 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
242 * 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
243 * 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
244 (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
245 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
246 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
247
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
248 @noindent
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
249 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
250 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
251 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
252 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
253 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
254 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
255 reading it later.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
256
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
257 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
258 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
259 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
260
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
261 @example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
262 @group
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
263 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
264 @end group
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
265 @end example
a12d7f53c2ab Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents: 11576
diff changeset
266
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
267 The preferred comment mark for places that may need further attention is
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
268 @code{FIXME:}.
8202
cf59d542f33e replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents: 8200
diff changeset
269
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
270 @node Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
271 @section Octave Sources (m-files)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
272
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
273 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
274 your editor so that it converts tabs to spaces. Indent the bodies of
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
275 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
276 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
277 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
278
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
279 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
280 x = max (sin (y+3), 2);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
281 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
282
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
283 @noindent
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
284 An exception are matrix or cell constructors:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
285
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
286 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
287 [sin(x), cos(x)]
18530
186ea1c2bbd4 contrib.txi: Use correct Texinfo to generate curly braces.
Rik <rik@octave.org>
parents: 18529
diff changeset
288 @{sin(x), cos(x)@}
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
289 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
290
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
291 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
292 Here, putting spaces after @code{sin}, @code{cos} would result in a
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
293 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
294 identifier (this differentiates indexing and function calls nicely).
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
295 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
296 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
297
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
298 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
299 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
300 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
301
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
302 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
303 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
304
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
305 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
306 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
307 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
308
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
309 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
310 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
311 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
312 wisely.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
313
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
314 Always use a specific end-of-block statement (like @code{endif},
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
315 @code{endswitch}) rather than the generic @code{end}.
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
316
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
317 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
318 conditions in parentheses, as in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
319
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
320 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
321 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
322 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
323 s = sum (a);
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
324 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
325 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
326 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
327
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
328 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
329 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
330 @code{for} statement. Write:
8055
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 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
333 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
334 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
335 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
336 endfor
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
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
340 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
341 @section C++ Sources
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 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
344 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
345 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
346
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
347 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
348 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
349 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
350 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
351 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
352 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
353 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
354
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
355 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
356 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
357 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
358 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
359 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
360
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
361 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
362 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
363 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
364 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
365 indents). Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
366
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
367 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
368 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
369 if (have_args)
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 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
372 have_args = false;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
373 @}
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
374 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
375 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
376 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
377 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
378
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
379 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
380 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
381 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
382
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
383 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
384 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
385 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
386 innermost braces enclosing the split. Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
387
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
388 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
389 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
390 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
391 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
392 : (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
393 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
394 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
395
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
396 @noindent
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
397 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
398 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
399 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
400
18529
3e731fc1e4d5 contrib.txi: Improve the documentation for Contribution Guidelines.
Rik <rik@octave.org>
parents: 18073
diff changeset
401 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
402 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
403 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
404 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
405 Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
406
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
407 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
408 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
409 octave_value retval;
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 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
412 octave_idx_type nc = b.cols ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
413
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
414 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
415 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
416 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
417
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
418 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
419 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
420
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
421 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
422 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
423 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
424 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
425 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
426 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
427 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
428
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
429 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
430 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
431 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
432 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
433 @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
434 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
435 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
436 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
437
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
438 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
439
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
440 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
441 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
442 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
443 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
444 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
445
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
446 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
447 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
448 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
449 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
450
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
451 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
452 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
453 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
454 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
455 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
456 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
457
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
458 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
459 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
460 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
461 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
462 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
463 @end example