Mercurial > octave-nkf
annotate doc/interpreter/contrib.txi @ 15512:3ae8c1ee7365
maint: periodic merge of stable to default
| author | Jordi Gutiérrez Hermoso <jordigh@octave.org> |
|---|---|
| date | Fri, 12 Oct 2012 11:46:06 -0400 |
| parents | 6e834a113760 c49d891eb263 |
| children | 189241a7c3a9 |
| 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 |
|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
14038
diff
changeset
|
2 @c Copyright (C) 2008-2012 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 |
| 11195 | 39 The mailing list for Octave development discussion and sending |
| 40 contributions is @email{maintainers@@octave.org}. This concerns the | |
| 41 development of Octave core, i.e., code that goes to Octave directly. | |
| 42 You may consider developing and publishing a package instead; a great | |
| 43 place for this is the allied Octave-Forge project | |
|
15497
c49d891eb263
Update broken or inconsistent project and wiki urls
Mike Miller <mtmiller@ieee.org>
parents:
14150
diff
changeset
|
44 (@url{http://octave.sourceforge.net}). Note that the Octave project is |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
45 inherently more conservative and follows narrower rules. |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
46 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
47 @node Building the Development Sources |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
48 @section Building the Development Sources |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
49 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
50 In addition to all the tools (both optional and required) that are |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
51 listed in @ref{Build Dependencies} you will need: |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
52 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
53 @table @asis |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
54 @item Mercurial |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
55 Distributed version control system (@url{http://mercurial.selenic.com}). |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
56 Octave's sources are stored in a Mercurial archive. |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
57 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
58 @item Git |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
59 Distributed version control system (@url{http://git-scm.com}). The |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
60 gnulib sources that Octave depends on are stored in a Git archive. |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
61 @end table |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
62 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
63 Once you have the required tools installed, you can build Octave by |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
64 doing |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
65 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
66 @itemize @bullet |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
67 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
68 Check out a copy of the Octave sources: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
69 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
70 @example |
|
15497
c49d891eb263
Update broken or inconsistent project and wiki urls
Mike Miller <mtmiller@ieee.org>
parents:
14150
diff
changeset
|
71 hg clone http://www.octave.org/hg/octave |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
72 @end example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
73 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
74 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
75 Change to the top-level directory of the newly checked out sources: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
76 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
77 @example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
78 cd octave |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
79 @end example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
80 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
81 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
82 Generate the necessary configuration files: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
83 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
84 @example |
|
15414
494f9bac8862
build: Rename autogen.sh script to bootstrap to conform to GNU guidelines.
Rik <rik@octave.org>
parents:
14883
diff
changeset
|
85 ./bootstrap |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
86 @end example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
87 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
88 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
89 Create a build directory and change to it: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
90 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
91 @example |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
92 @group |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
93 mkdir build |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
94 cd build |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
95 @end group |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
96 @end example |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
97 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
98 By using a separate build directory, you will keep the source directory |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
99 clean and it will be easy to completely remove all files generated by |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
100 the build. You can also have parallel build trees for different |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
101 purposes that all share the same sources. For example, one build tree |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
102 may be configured to disable compiler optimization in order to allow for |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
103 easier debugging while another may be configured to test building with |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
104 other specialized compiler flags. |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
105 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
106 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
107 Run Octave's configure script from the build directory: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
108 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
109 @example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
110 ../configure |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
111 @end example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
112 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
113 @item |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
114 Run make in the build directory: |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
115 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
116 @example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
117 make |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
118 @end example |
|
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14150
diff
changeset
|
119 |
|
14150
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
120 @end itemize |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
121 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
122 Once the build is finished, you will see a message like the following: |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
123 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
124 @example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
125 @group |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
126 Octave successfully built. Now choose from the following: |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
127 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
128 ./run-octave - to run in place to test before installing |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
129 make check - to run the tests |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
130 make install - to install (PREFIX=...) |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
131 @end group |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
132 @end example |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
133 |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
134 @node Basics of Generating a Changeset |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
135 @section Basics of Generating a Changeset |
|
87f06b9990bb
doc: improve documentation for building Octave
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
136 |
| 11195 | 137 The preferable form of contribution is creating a Mercurial changeset |
|
14883
f20312fc9046
doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents:
14856
diff
changeset
|
138 and submit it to the @uref{http://savannah.gnu.org/bugs/?group=octave, bug} or |
|
f20312fc9046
doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents:
14856
diff
changeset
|
139 @uref{http://savannah.gnu.org/patch/?func=additem&group=octave, patch} |
|
f20312fc9046
doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents:
14856
diff
changeset
|
140 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
|
141 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
|
142 bug tracker instead.}. |
| 11195 | 143 Mercurial is the source code management system currently used to develop |
| 144 Octave. Other forms of contributions (e.g., simple diff patches) are | |
| 145 also acceptable, but they slow down the review process. If you want to | |
| 146 make more contributions, you should really get familiar with Mercurial. | |
| 147 A good place to start is | |
| 148 @url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. There | |
| 149 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
|
150 |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
151 A simple contribution sequence could look like this: |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
152 |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
153 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
154 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
155 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
|
156 # make a local copy of the octave |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
157 # source repository |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
158 cd octave |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
159 # change some sources@dots{} |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
160 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
|
161 # commit the changeset into your |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
162 # local repository |
|
8177
65c4ac814082
hg syntax bug in mercurial example
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8055
diff
changeset
|
163 hg export -o ../cool.diff tip |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
164 # export the changeset to a diff |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
165 # file |
|
14883
f20312fc9046
doc: recommend to use bug tracker rather than maintainers mailing list.
Carnë Draug <carandraug+dev@gmail.com>
parents:
14856
diff
changeset
|
166 # 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
|
167 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
168 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
169 |
| 11195 | 170 You may want to get familiar with Mercurial queues to manage your |
|
14038
b0cdd60db5e5
doc: Grammarcheck documentation ahead of 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
13168
diff
changeset
|
171 changesets. Here is a slightly more complex example using Mercurial |
|
12559
a12d7f53c2ab
Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents:
11576
diff
changeset
|
172 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
|
173 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
|
174 |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
175 @example |
|
13166
d624b6f216ac
Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12559
diff
changeset
|
176 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
|
177 # change sources@dots{} |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
178 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
|
179 # change even more@dots{} |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
180 hg qref -m "solution to nasty bug!" |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
181 # save again with commit message |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
182 hg export -o ../nasty.diff tip |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
183 # 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
|
184 # attach ../nasty.diff to your bug report |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
185 hg qpop # undo the application of the patch |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
186 # and remove the changes from the |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
187 # 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
|
188 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
|
189 # change doc sources@dots{} |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
190 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
|
191 # save the changes into the patch |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
192 hg export -o ../doc.diff tip |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
193 # 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
|
194 # attach ../doc.diff to your bug report |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
195 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
|
196 # 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
|
197 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
|
198 # change sources yet again @dots{} |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
199 hg qref |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
200 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
|
201 # attach ../nasty2.diff to your bug report |
|
8200
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
202 @end example |
|
837487bd3450
help new contributors with mercurial
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8177
diff
changeset
|
203 |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
204 @node General Guidelines |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
205 @section General Guidelines |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
206 |
| 11195 | 207 All Octave's sources are distributed under the General Public License |
| 208 (GPL). Currently, Octave uses GPL version 3. For details about this | |
| 209 license, see @url{http://www.gnu.org/licenses/gpl.html}. Therefore, | |
| 210 whenever you create a new source file, it should have the following | |
| 211 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
|
212 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
213 @example |
|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
14038
diff
changeset
|
214 ## Copyright (C) 1996-2012 John W. Eaton <jwe@@octave.org> |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
215 ## |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
216 ## This file is part of Octave. |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
217 ## |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
218 ## 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
|
219 ## 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
|
220 ## 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
|
221 ## 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
|
222 ## later version. |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
223 ## |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
224 ## 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
|
225 ## but WITHOUT ANY WARRANTY; without even the implied |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
226 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
227 ## PURPOSE. See the GNU General Public License for more |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
228 ## details. |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
229 ## |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
230 ## 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
|
231 ## 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
|
232 ## see <http://www.gnu.org/licenses/>. |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
233 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
234 |
|
13168
470ef1a5d66e
doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents:
13166
diff
changeset
|
235 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
|
236 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
|
237 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
|
238 @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
|
239 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
|
240 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
|
241 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
|
242 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
|
243 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
|
244 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
|
245 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
|
246 example: |
|
8055
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 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
249 @group |
|
13168
470ef1a5d66e
doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents:
13166
diff
changeset
|
250 look for methods before constructors |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
251 |
|
13168
470ef1a5d66e
doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents:
13166
diff
changeset
|
252 * 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
|
253 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
|
254 documentation. |
|
13166
d624b6f216ac
Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12559
diff
changeset
|
255 |
|
13168
470ef1a5d66e
doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents:
13166
diff
changeset
|
256 * 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
|
257 * 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
|
258 * 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
|
259 (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
|
260 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
261 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
262 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
263 @noindent |
|
13166
d624b6f216ac
Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12559
diff
changeset
|
264 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
|
265 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
|
266 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
|
267 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
|
268 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
|
269 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
|
270 reading it later. |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
271 |
|
13166
d624b6f216ac
Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12559
diff
changeset
|
272 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
|
273 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
|
274 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
|
275 |
|
a12d7f53c2ab
Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents:
11576
diff
changeset
|
276 @example |
|
a12d7f53c2ab
Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents:
11576
diff
changeset
|
277 @group |
|
13168
470ef1a5d66e
doc: tweak log guidelines in contrib.txi
John W. Eaton <jwe@octave.org>
parents:
13166
diff
changeset
|
278 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
|
279 @end group |
|
a12d7f53c2ab
Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents:
11576
diff
changeset
|
280 @end example |
|
a12d7f53c2ab
Document recommended format for commit messages which reference the bug tracker.
Rik <octave@nomad.inbox5.com>
parents:
11576
diff
changeset
|
281 |
| 11195 | 282 The preferred comment mark for places that may need further attention is |
| 283 FIXME. | |
|
8202
cf59d542f33e
replace all TODOs and XXXs with FIXMEs
Jaroslav Hajek <highegg@gmail.com>
parents:
8200
diff
changeset
|
284 |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
285 @node Octave Sources (m-files) |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
286 @section Octave Sources (m-files) |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
287 |
| 11195 | 288 Don't use tabs. Tabs cause trouble. If you are used to them, set up |
| 289 your editor so that it converts tabs to spaces. Indent the bodies of | |
| 290 the statement blocks. Recommended indent is 2 spaces. When calling | |
| 291 functions, put spaces after commas and before the calling parentheses, | |
| 292 like this: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
293 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
294 @example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
295 x = max (sin (y+3), 2); |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
296 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
297 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
298 @noindent |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
299 An exception are matrix and vector constructors: |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
300 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
301 @example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
302 [sin(x), cos(x)] |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
303 @end example |
|
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 @noindent |
| 11195 | 306 Here, putting spaces after @code{sin}, @code{cos} would result in a |
| 307 parse error. In indexing expression, do not put a space after the | |
| 308 identifier (this differentiates indexing and function calls nicely). | |
| 309 The space after comma is not necessary if index expressions are simple, | |
| 310 i.e., you may write | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
311 |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
312 @example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
313 A(:,i,j) |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
314 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
315 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
316 @noindent |
|
13166
d624b6f216ac
Update guidelines on how to write commit messages and changelogs
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12559
diff
changeset
|
317 but |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
318 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
319 @example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
320 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
|
321 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
322 |
| 11195 | 323 Use lowercase names if possible. Uppercase is acceptable for variable |
| 324 names consisting of 1-2 letters. Do not use mixed case names. Function | |
| 325 names must be lowercase. Function names are global, so choose them | |
| 326 wisely. | |
|
8055
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 Always use a specific end-of-block statement (like @code{endif}, |
| 11195 | 329 @code{endswitch}) rather than generic @code{end}. |
| 330 | |
| 331 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
|
332 conditions in parentheses, like in C: |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
333 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
334 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
335 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
336 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
|
337 s = sum (a); |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
338 endif |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
339 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
340 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
341 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
342 @noindent |
| 11195 | 343 Do not do this, however, with the iteration counter portion of a |
| 344 @code{for} statement. Write: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
345 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
346 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
347 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
348 for i = 1:n |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
349 b(i) = sum (a(:,i)); |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
350 endfor |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
351 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
352 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
353 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
354 @node C++ Sources |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
355 @section C++ Sources |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
356 |
| 11195 | 357 Don't use tabs. Tabs cause trouble. If you are used to them, set up |
| 358 your editor so that it converts tabs to spaces. Format function headers | |
| 359 like this: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
360 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
361 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
362 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
363 static bool |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
364 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
|
365 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
|
366 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
367 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
368 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
369 @noindent |
| 11195 | 370 The function name should start in column 1, and multi-line argument |
| 371 lists should be aligned on the first char after the open parenthesis. | |
| 372 You should put a space after the left open parenthesis and after commas, | |
| 373 for both function definitions and function calls. | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
374 |
| 11195 | 375 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
|
376 after control structures (like @code{if}, @code{while}, etc.). If there |
| 11195 | 377 is a compound statement, indent @emph{both} the curly braces and the |
| 378 body of the statement (so that the body gets indented by @emph{two} | |
| 379 indents). Example: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
380 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
381 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
382 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
383 if (have_args) |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
384 @{ |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
385 idx.push_back (first_args); |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
386 have_args = false; |
|
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 else |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
389 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
|
390 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
391 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
392 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
393 @noindent |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
394 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
|
395 clarification. |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
396 |
| 11195 | 397 Split long expressions in such a way that a continuation line starts |
| 398 with an operator rather than identifier. If the split occurs inside | |
| 399 braces, continuation should be aligned with the first char after the | |
| 400 innermost braces enclosing the split. Example: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
401 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
402 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
403 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
404 SVD::type type = ((nargout == 0 || nargout == 1) |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
405 ? SVD::sigma_only |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
406 : (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
|
407 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
408 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
409 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
410 @noindent |
| 11195 | 411 Consider putting extra braces around a multiline expression to make it |
| 412 more readable, even if they are not necessary. Also, do not hesitate to | |
| 413 put extra braces anywhere if it improves clarity. | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
414 |
| 11195 | 415 Declare variables just before they're needed. Use local variables of |
| 416 blocks---it helps optimization. Don't write multi-line variable | |
| 417 declaration with a single type specification and multiple variables. If | |
| 418 the variables don't fit on single line, repeat the type specification. | |
| 419 Example: | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
420 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
421 @example |
|
9081
c79cf77061b7
Cleanup documentation files contrib.texi, bugs.texi, install.texi, emacs.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
422 @group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
423 octave_value retval; |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
424 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
425 octave_idx_type nr = b.rows (); |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
426 octave_idx_type nc = b.cols (); |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
427 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
428 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
|
429 @end group |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
430 @end example |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
431 |
| 11195 | 432 Use lowercase names if possible. Uppercase is acceptable for variable |
| 433 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
|
434 |
| 11195 | 435 Use Octave's types and classes if possible. Otherwise, use the C++ |
| 436 standard library. Use of STL containers and algorithms is encouraged. | |
| 437 Use templates wisely to reduce code duplication. Avoid comma | |
| 438 expressions, labels and gotos, and explicit typecasts. If you need to | |
| 439 typecast, use the modern C++ casting operators. In functions, minimize | |
| 440 the number of @code{return} statements---use nested @code{if} statements | |
| 441 if possible. | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
442 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
443 @node Other Sources |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
444 @section Other Sources |
| 11195 | 445 Apart from C++ and Octave language (m-files), Octave's sources include |
| 446 files written in C, Fortran, M4, Perl, Unix shell, AWK, Texinfo and | |
| 447 @TeX{}. There are not many rules to follow when using these other | |
| 448 languages; some of them are summarized below. In any case, the golden | |
| 449 rule is: if you modify a source file, try to follow any conventions you | |
| 450 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
|
451 |
|
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
452 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
|
453 |
| 11195 | 454 If you modify a Fortran file, you should stay within Fortran 77 with |
| 455 common extensions like @code{END DO}. Currently, we want all sources to | |
| 456 be compilable with the f2c and g77 compilers, without special flags if | |
| 457 possible. This usually means that non-legacy compilers also accept the | |
| 458 sources. | |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
459 |
| 11195 | 460 The M4 macro language is mainly used for Autoconf configuration files. |
| 461 You should follow normal M4 rules when contributing to these files. | |
| 462 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
|
463 @url{http://autoconf-archive.cryp.to}. |
|
8055
d51c3541be28
contrib.txi: new documentation for contributors
Jaroslav Hajek <highegg@gmail.com>
parents:
diff
changeset
|
464 |
| 11195 | 465 If you give a code example in the documentation written in Texinfo with |
| 466 the @code{@@example} environment, you should be aware that the text | |
| 467 within such an environment will not be wrapped. It is recommended that | |
| 468 you keep the lines short enough to fit on pages in the generated pdf or | |
| 469 ps documents. Here is a ruler (in an @code{@@example} environment) for | |
| 470 finding the appropriate line width: | |
|
8348
d95c4e31bb2d
recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8204
diff
changeset
|
471 |
|
d95c4e31bb2d
recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8204
diff
changeset
|
472 @example |
| 8516 | 473 @group |
| 474 1 2 3 4 5 6 | |
| 475 123456789012345678901234567890123456789012345678901234567890 | |
| 476 @end group | |
|
8348
d95c4e31bb2d
recommend limited line width in code examples
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8204
diff
changeset
|
477 @end example |