Mercurial > hg > octave-nkf

annotate doc/interpreter/contrib.txi @ 18552:02ce68d63fba stable rc-3-8-1-3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fix release date for 3.8.1 and bump release to 3.8.1-rc3 * configure.ac (OCTAVE_VERSION): Bump to 3.8.1-rc3. (OCTAVE_MINOR_VERSION): Bump to 1-rc3. (OCTAVE_RELEASE_DATE): Set to 2014-02-17.
author John W. Eaton <jwe@octave.org>
date Mon, 17 Feb 2014 03:30:17 -0500
parents 42c3e30557a4
children 3e731fc1e4d5
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
17680
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
39 The mailing list for Octave development discussion is
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}.
4264c78951ec doc: refer to patch tracker instead of mailing list for bugs.
Rüdiger Sonderfeld <ruediger@c-plusplus.de>
parents: 17498
diff changeset
42 This concerns the development of Octave core, i.e., code that goes to Octave
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
16665
d68e72ee28bf remove instructions for building dev sources from manual
John W. Eaton <jwe@octave.org>
parents: 16601
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
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
59 The preferable form of contribution is creating a Mercurial changeset
16792
b157ba28f123 doc: Use Texinfo @url command consistently throughout documentation.
Rik <rik@octave.org>
parents: 16791
diff changeset
60 and submit it to the @url{http://savannah.gnu.org/bugs/?group=octave, bug} or
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
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
71 you will also find help how to install Mercurial.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
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
16816
12005245b645 doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 16797
diff changeset
93 changesets. For working with queues you have to 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
16797
aac60c9bfc77 add Jordi's tips on hg extensions to the manual
Torsten <ttl@justmail.de>
parents: 16792
diff changeset
170 isn't working correctly:
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
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
188 that you use the command @code{hg glog} instead of @code{hg log} for a better
a4969508008e doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents: 16816
diff changeset
189 feel 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
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
194 All Octave's sources are distributed under the General Public License
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
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 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
205 ## Octave is free software; you can redistribute it and/or
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
206 ## modify it under the terms of the GNU General Public
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
207 ## License as published by the Free Software Foundation;
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
208 ## either version 3 of the License, or (at your option) any
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
209 ## later version.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
210 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
211 ## Octave is distributed in the hope that it will be useful,
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
212 ## but WITHOUT ANY WARRANTY; without even the implied
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
213 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
214 ## PURPOSE. See the GNU General Public License for more
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
215 ## details.
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
216 ##
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
217 ## You should have received a copy of the GNU General Public
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
218 ## License along with Octave; see the file COPYING. If not,
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
219 ## see <http://www.gnu.org/licenses/>.
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
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
226 get automatically added to your commit message. Your commit message
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
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
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
229 number at the end. If your change is small and only touches one file,
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
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
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
232 following the GNU coding standards on changelogs, like the following
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
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
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
251 In this example, the names of files is mentioned, and in parentheses the
13168
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
252 name of the function in that file that was modified. There is no need to
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
253 mention the function for m-files that only contain one function. The
470ef1a5d66e doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents: 13166
diff changeset
254 commit message should describe what is changed, not why. Any explanation
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
255 of why a change is needed should appear as comments in the code,
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
256 particularly if there is something that might not be obvious to someone
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
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
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
270 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
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
277 the statement blocks. Recommended indent is 2 spaces. When calling
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
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
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
286 An exception are matrix and vector constructors:
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
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
289 [sin(x), cos(x)]
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
290 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
291
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
292 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
293 Here, putting spaces after @code{sin}, @code{cos} would result in a
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
294 parse error. In indexing expression, do not put a space after the
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
295 identifier (this differentiates indexing and function calls nicely).
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
296 The space after comma is not necessary if index expressions are simple,
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
297 i.e., you may write
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
298
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
299 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
300 A(:,i,j)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
301 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
302
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
303 @noindent
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
304 but
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
305
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
306 @example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
307 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
308 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
309
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
310 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
311 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
312 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
313 wisely.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
314
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
315 Always use a specific end-of-block statement (like @code{endif},
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
316 @code{endswitch}) rather than generic @code{end}.
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
317
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
318 Enclose the @code{if}, @code{while}, @code{until} and @code{switch}
13166
d624b6f216ac Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 12559
diff changeset
319 conditions in parentheses, like in C:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
320
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
321 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
322 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
323 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
324 s = sum (a);
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
325 endif
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
326 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
327 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
328
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
329 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
330 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
331 @code{for} statement. Write:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
332
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
333 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
334 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
335 for i = 1:n
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
336 b(i) = sum (a(:,i));
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
337 endfor
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
338 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
339 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
340
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
341 @node C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
342 @section C++ Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
343
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
344 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
345 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
346 like this:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
347
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
348 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
349 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
350 static bool
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
351 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
352 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
353 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
354 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
355
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
356 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
357 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
358 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
359 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
360 for both function definitions and function calls.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
361
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
362 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
363 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
364 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
365 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
366 indents). Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
367
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
368 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
369 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
370 if (have_args)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
371 @{
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
372 idx.push_back (first_args);
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
373 have_args = false;
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 else
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
376 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
377 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
378 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
379
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
380 @noindent
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
381 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
382 clarification.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
383
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
384 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
385 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
386 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
387 innermost braces enclosing the split. Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
388
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
389 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
390 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
391 SVD::type type = ((nargout == 0 || nargout == 1)
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
392 ? SVD::sigma_only
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
393 : (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
394 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
395 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
396
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
397 @noindent
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
398 Consider putting extra braces around a multiline expression to make it
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
399 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
400 put extra braces anywhere if it improves clarity.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
401
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
402 Declare variables just before they're needed. Use local variables of
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
403 blocks---it helps optimization. Don't write multi-line variable
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
404 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
405 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
406 Example:
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
407
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
408 @example
9081
c79cf77061b7 Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents: 9032
diff changeset
409 @group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
410 octave_value retval;
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
411
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
412 octave_idx_type nr = b.rows ();
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
413 octave_idx_type nc = b.cols ();
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 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
416 @end group
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
417 @end example
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
418
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
419 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
420 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
421
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
422 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
423 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
424 Use templates wisely to reduce code duplication. Avoid comma
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
425 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
426 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
427 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
428 if possible.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
429
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
430 @node Other Sources
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
431 @section Other Sources
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
432 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
433 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
434 @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
435 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
436 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
437 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
438
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
439 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
440
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
441 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
442 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
443 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
444 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
445 sources.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
446
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
447 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
448 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
449 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
450 @url{http://autoconf-archive.cryp.to}.
8055
d51c3541be28 contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff changeset
451
11195
8f67fe9dd64e contrib.txi: minor tweaks
John W. Eaton <jwe@octave.org>
parents: 10846
diff changeset
452 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
453 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
454 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
455 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
456 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
457 finding the appropriate line width:
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
458
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
459 @example
8516
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
460 @group
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
461 1 2 3 4 5 6
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
462 123456789012345678901234567890123456789012345678901234567890
e2a179415bac doc fixes
John W. Eaton <jwe@octave.org>
parents: 8348
diff changeset
463 @end group
8348
d95c4e31bb2d recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8204
diff changeset
464 @end example