Mercurial > octave
annotate doc/interpreter/tips.txi @ 12576:a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
| author | Rik <octave@nomad.inbox5.com> |
|---|---|
| date | Mon, 04 Apr 2011 15:56:49 -0700 |
| parents | d0b799dafede |
| children | 050bc580cb60 |
| rev | line source |
|---|---|
| 11523 | 1 @c Copyright (C) 1996-2011 John W. Eaton |
| 7018 | 2 @c |
| 3 @c This file is part of Octave. | |
| 4 @c | |
| 5 @c Octave is free software; you can redistribute it and/or modify it | |
| 6 @c under the terms of the GNU General Public License as published by the | |
| 7 @c Free Software Foundation; either version 3 of the License, or (at | |
| 8 @c your option) any later version. | |
| 9 @c | |
| 10 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
| 11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 13 @c for more details. | |
| 14 @c | |
| 15 @c You should have received a copy of the GNU General Public License | |
| 16 @c along with Octave; see the file COPYING. If not, see | |
| 17 @c <http://www.gnu.org/licenses/>. | |
| 3294 | 18 |
|
9032
349616d9c38e
Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
19 @node Tips and Standards |
| 3294 | 20 @appendix Tips and Standards |
| 21 @cindex tips | |
| 22 @cindex standards of coding style | |
| 23 @cindex coding standards | |
| 24 | |
| 25 This chapter describes no additional features of Octave. Instead it | |
| 26 gives advice on making effective use of the features described in the | |
| 27 previous chapters. | |
| 28 | |
| 29 @menu | |
| 30 * Style Tips:: Writing clean and robust programs. | |
| 31 * Coding Tips:: Making code run faster. | |
| 32 * Comment Tips:: Conventions for writing comments. | |
| 33 * Function Headers:: Standard headers for functions. | |
| 6574 | 34 * Documentation Tips:: Writing readable documentation strings. |
| 3294 | 35 @end menu |
| 36 | |
| 4167 | 37 @node Style Tips |
| 3294 | 38 @section Writing Clean Octave Programs |
| 39 | |
| 40 Here are some tips for avoiding common errors in writing Octave code | |
| 41 intended for widespread use: | |
| 42 | |
| 43 @itemize @bullet | |
| 44 @item | |
| 45 Since all global variables share the same name space, and all functions | |
| 46 share another name space, you should choose a short word to distinguish | |
| 47 your program from other Octave programs. Then take care to begin the | |
| 48 names of all global variables, constants, and functions with the chosen | |
| 49 prefix. This helps avoid name conflicts. | |
| 50 | |
| 51 If you write a function that you think ought to be added to Octave under | |
| 52 a certain name, such as @code{fiddle_matrix}, don't call it by that name | |
| 53 in your program. Call it @code{mylib_fiddle_matrix} in your program, | |
| 5041 | 54 and send mail to @email{maintainers@@octave.org} suggesting that it |
| 3294 | 55 be added to Octave. If and when it is, the name can be changed easily |
| 56 enough. | |
| 57 | |
| 58 If one prefix is insufficient, your package may use two or three | |
| 59 alternative common prefixes, so long as they make sense. | |
| 60 | |
| 61 Separate the prefix from the rest of the symbol name with an underscore | |
| 62 @samp{_}. This will be consistent with Octave itself and with most | |
| 63 Octave programs. | |
| 64 | |
| 65 @item | |
| 66 When you encounter an error condition, call the function @code{error} | |
| 67 (or @code{usage}). The @code{error} and @code{usage} functions do not | |
| 68 return. | |
| 69 @xref{Errors}. | |
| 70 | |
| 71 @item | |
| 72 Please put a copyright notice on the file if you give copies to anyone. | |
| 73 Use the same lines that appear at the top of the function files | |
| 74 distributed with Octave. If you have not signed papers to assign the | |
| 75 copyright to anyone else, then place your name in the copyright notice. | |
| 76 @end itemize | |
| 77 | |
| 4167 | 78 @node Coding Tips |
| 3294 | 79 @section Tips for Making Code Run Faster. |
| 80 @cindex execution speed | |
| 81 @cindex speedups | |
| 82 | |
| 83 Here are some ways of improving the execution speed of Octave programs. | |
| 84 | |
| 85 @itemize @bullet | |
| 86 @item | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
87 Vectorize loops. For instance, rather than |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
88 |
| 9356 | 89 @example |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
90 @group |
| 9356 | 91 for i = 1:n-1 |
| 92 a(i) = b(i+1) - b(i); | |
| 93 endfor | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
94 @end group |
| 9356 | 95 @end example |
| 96 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
97 @noindent |
| 9356 | 98 write |
| 99 | |
| 100 @example | |
| 101 a = b(2:n) - b(1:n-1); | |
| 102 @end example | |
| 103 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
104 This is especially important for loops with "cheap" bodies. Often it suffices |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
105 to vectorize just the innermost loop to get acceptable performance. A general |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
106 rule of thumb is that the "order" of the vectorized body should be greater or |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
107 equal to the "order" of the enclosing loop. |
| 9356 | 108 |
| 109 @item | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
110 Use built-in and library functions if possible. Built-in and compiled functions |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
111 are very fast. Even with a m-file library function, chances are good that it is |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
112 already optimized, or will be optimized more in a future release. |
| 9356 | 113 |
| 10812 | 114 For instance, even better than |
| 115 | |
| 116 @example | |
| 117 a = b(2:n) - b(1:n-1); | |
| 118 @end example | |
| 119 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
120 @noindent |
| 10812 | 121 is |
| 122 | |
| 123 @example | |
| 124 a = diff (b); | |
| 125 @end example | |
| 126 | |
| 127 | |
| 9356 | 128 @item |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
129 Avoid computing costly intermediate results multiple times. Octave currently |
| 9356 | 130 does not eliminate common subexpressions. |
| 9486 | 131 Also, certain internal computation results are cached for variables. |
| 132 For instance, if a matrix variable is used multiple times as an index, | |
| 133 checking the indices (and internal conversion to integers) is only done once. | |
| 3294 | 134 |
| 135 @item | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
136 Be aware of lazy copies (copy-on-write). When a copy of an object |
|
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
137 is created, the data is not immediately copied, but rather shared. The actual |
|
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
138 copying is postponed until the copied data needs to be modified. For example: |
| 9356 | 139 |
| 140 @example | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
141 @group |
| 9356 | 142 a = zeros (1000); # create a 1000x1000 matrix |
| 143 b = a; # no copying done here | |
| 144 b(1) = 1; # copying done here | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
145 @end group |
| 9356 | 146 @end example |
| 147 | |
| 148 Lazy copying applies to whole Octave objects such as matrices, cells, struct, | |
| 149 and also individual cell or struct elements (not array elements). | |
| 150 | |
| 151 Additionally, index expressions also use lazy copying when Octave can determine | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
152 that the indexed portion is contiguous in memory. For example: |
| 9356 | 153 |
| 154 @example | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
155 @group |
| 9356 | 156 a = zeros (1000); # create a 1000x1000 matrix |
| 157 b = a(:,10:100); # no copying done here | |
| 158 b = a(10:100,:); # copying done here | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
159 @end group |
| 9356 | 160 @end example |
| 161 | |
| 162 This applies to arrays (matrices), cell arrays, and structs indexed using (). | |
| 163 Index expressions generating cs-lists can also benefit of shallow copying | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
164 in some cases. In particular, when @var{a} is a struct array, expressions like |
| 9356 | 165 @code{@{a.x@}, @{a(:,2).x@}} will use lazy copying, so that data can be shared |
| 166 between a struct array and a cell array. | |
| 167 | |
| 168 Most indexing expressions do not live longer than their `parent' objects. | |
| 169 In rare cases, however, a lazily copied slice outlasts its parent, in which | |
| 170 case it becomes orphaned, still occupying unnecessarily more memory than needed. | |
| 171 To provide a remedy working in most real cases, | |
| 172 Octave checks for orphaned lazy slices at certain situations, when a value | |
| 173 is stored into a "permanent" location, such as a named variable or cell or | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
174 struct element, and possibly economizes them. For example: |
| 9356 | 175 |
| 176 @example | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
177 @group |
| 9356 | 178 a = zeros (1000); # create a 1000x1000 matrix |
|
12575
d0b799dafede
Grammarcheck files for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12546
diff
changeset
|
179 b = a(:,10:100); # lazy slice |
| 9356 | 180 a = []; # the original a array is still allocated |
| 181 c@{1@} = b; # b is reallocated at this point | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
182 @end group |
| 9356 | 183 @end example |
| 3294 | 184 |
| 185 @item | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
186 Avoid deep recursion. Function calls to m-file functions carry a relatively |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
187 significant overhead, so rewriting a recursion as a loop often helps. Also, |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
188 note that the maximum level of recursion is limited. |
| 9356 | 189 |
| 190 @item | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
191 Avoid resizing matrices unnecessarily. When building a single result |
| 3294 | 192 matrix from a series of calculations, set the size of the result matrix |
| 193 first, then insert values into it. Write | |
| 194 | |
| 195 @example | |
| 196 @group | |
| 197 result = zeros (big_n, big_m) | |
| 198 for i = over:and_over | |
| 199 r1 = @dots{} | |
| 200 r2 = @dots{} | |
| 201 result (r1, r2) = new_value (); | |
| 202 endfor | |
| 203 @end group | |
| 204 @end example | |
| 205 | |
| 206 @noindent | |
| 207 instead of | |
| 208 | |
| 209 @example | |
| 210 @group | |
| 211 result = []; | |
| 212 for i = ever:and_ever | |
| 213 result = [ result, new_value() ]; | |
| 214 endfor | |
| 215 @end group | |
| 216 @end example | |
| 217 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
218 Sometimes the number of items can't be computed in advance, and stack-like |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
219 operations are needed. When elements are being repeatedly inserted at/removed |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
220 from the end of an array, Octave detects it as stack usage and attempts to use a |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
221 smarter memory management strategy pre-allocating the array in bigger chunks. |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
222 Likewise works for cell and struct arrays. |
| 9356 | 223 |
| 224 @example | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
225 @group |
| 9356 | 226 a = []; |
| 227 while (condition) | |
| 228 @dots{} | |
| 229 a(end+1) = value; # "push" operation | |
| 230 @dots{} | |
| 231 a(end) = []; # "pop" operation | |
| 232 @dots{} | |
| 233 endwhile | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
234 @end group |
| 9356 | 235 @end example |
| 236 | |
| 3294 | 237 @item |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
238 Use @code{cellfun} intelligently. The @code{cellfun} function is a useful tool |
|
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
239 for avoiding loops. @xref{Processing Data in Cell Arrays}. |
| 10284 | 240 @code{cellfun} is often used with anonymous function handles; however, calling |
| 9356 | 241 an anonymous function involves an overhead quite comparable to the overhead |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
242 of an m-file function. Passing a handle to a built-in function is faster, |
|
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
243 because the interpreter is not involved in the internal loop. For example: |
| 9356 | 244 |
| 245 @example | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
246 @group |
| 9356 | 247 a = @{@dots{}@} |
| 248 v = cellfun (@@(x) det(x), a); # compute determinants | |
| 249 v = cellfun (@@det, a); # faster | |
|
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9486
diff
changeset
|
250 @end group |
| 9356 | 251 @end example |
| 252 | |
| 253 @item | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
254 Octave includes a number of other functions that can replace common types of |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
255 loops, including @code{bsxfun}, @code{arrayfun}, @code{structfun}, |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
256 @code{accumarray}. These functions can take an arbitrary function as a handle. |
| 10812 | 257 Be sure to get familiar with them if you want to become an Octave expert. |
| 10284 | 258 |
| 259 @item | |
| 9356 | 260 Avoid calling @code{eval} or @code{feval} excessively, because |
| 3294 | 261 they require Octave to parse input or look up the name of a function in |
| 262 the symbol table. | |
| 263 | |
| 264 If you are using @code{eval} as an exception handling mechanism and not | |
| 265 because you need to execute some arbitrary text, use the @code{try} | |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
266 statement instead. @xref{The @code{try} Statement}. |
| 3294 | 267 |
| 268 @item | |
| 269 If you are calling lots of functions but none of them will need to | |
| 270 change during your run, set the variable | |
| 271 @code{ignore_function_time_stamp} to @code{"all"} so that Octave doesn't | |
| 272 waste a lot of time checking to see if you have updated your function | |
| 273 files. | |
| 274 @end itemize | |
| 275 | |
| 4167 | 276 @node Comment Tips |
| 3294 | 277 @section Tips on Writing Comments |
| 278 | |
| 279 Here are the conventions to follow when writing comments. | |
| 280 | |
| 281 @table @samp | |
| 282 @item # | |
| 283 Comments that start with a single sharp-sign, @samp{#}, should all be | |
| 284 aligned to the same column on the right of the source code. Such | |
| 285 comments usually explain how the code on the same line does its job. In | |
| 286 the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) | |
| 287 command automatically inserts such a @samp{#} in the right place, or | |
| 288 aligns such a comment if it is already present. | |
| 289 | |
| 290 @item ## | |
| 7345 | 291 Comments that start with a double sharp-sign, @samp{##}, should be aligned to |
| 3294 | 292 the same level of indentation as the code. Such comments usually |
| 293 describe the purpose of the following lines or the state of the program | |
| 294 at that point. | |
| 295 @end table | |
| 296 | |
| 297 @noindent | |
| 298 The indentation commands of the Octave mode in Emacs, such as @kbd{M-;} | |
| 299 (@code{indent-for-comment}) and @kbd{TAB} (@code{octave-indent-line}) | |
| 300 automatically indent comments according to these conventions, | |
| 301 depending on the number of semicolons. @xref{Comments,, | |
| 302 Manipulating Comments, emacs, The GNU Emacs Manual}. | |
| 303 | |
| 4167 | 304 @node Function Headers |
| 3294 | 305 @section Conventional Headers for Octave Functions |
| 306 @cindex header comments | |
| 307 | |
| 308 Octave has conventions for using special comments in function files | |
| 309 to give information such as who wrote them. This section explains these | |
| 310 conventions. | |
| 311 | |
| 312 The top of the file should contain a copyright notice, followed by a | |
| 313 block of comments that can be used as the help text for the function. | |
| 314 Here is an example: | |
| 315 | |
| 316 @example | |
| 6778 | 317 ## Copyright (C) 1996, 1997, 2007 John W. Eaton |
| 3294 | 318 ## |
| 319 ## This file is part of Octave. | |
| 320 ## | |
| 321 ## Octave is free software; you can redistribute it and/or | |
| 322 ## modify it under the terms of the GNU General Public | |
| 323 ## License as published by the Free Software Foundation; | |
| 7081 | 324 ## either version 3 of the License, or (at your option) any |
| 325 ## later version. | |
| 3294 | 326 ## |
| 327 ## Octave is distributed in the hope that it will be useful, | |
| 328 ## but WITHOUT ANY WARRANTY; without even the implied | |
| 329 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR | |
| 330 ## PURPOSE. See the GNU General Public License for more | |
| 331 ## details. | |
| 332 ## | |
| 333 ## You should have received a copy of the GNU General Public | |
| 334 ## License along with Octave; see the file COPYING. If not, | |
| 7016 | 335 ## see <http://www.gnu.org/licenses/>. |
| 3294 | 336 |
| 337 ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) | |
| 338 ## | |
| 339 ## Start a subprocess with two-way communication. COMMAND | |
| 340 ## specifies the name of the command to start. ARGS is an | |
| 341 ## array of strings containing options for COMMAND. IN and | |
| 342 ## OUT are the file ids of the input and streams for the | |
| 343 ## subprocess, and PID is the process id of the subprocess, | |
| 344 ## or -1 if COMMAND could not be executed. | |
| 345 ## | |
| 346 ## Example: | |
| 347 ## | |
| 348 ## [in, out, pid] = popen2 ("sort", "-nr"); | |
| 349 ## fputs (in, "these\nare\nsome\nstrings\n"); | |
| 350 ## fclose (in); | |
|
7768
a2d9f325b65a
Use isschar instead of deprecated isstr
Rafael Laboissiere <rafael@debian.org>
parents:
7345
diff
changeset
|
351 ## while (ischar (s = fgets (out))) |
| 3294 | 352 ## fputs (stdout, s); |
| 353 ## endwhile | |
| 354 ## fclose (out); | |
| 355 @end example | |
| 356 | |
| 357 Octave uses the first block of comments in a function file that do not | |
| 358 appear to be a copyright notice as the help text for the file. For | |
| 359 Octave to recognize the first comment block as a copyright notice, it | |
| 6530 | 360 must start with the word `Copyright' after stripping the leading |
| 361 comment characters. | |
| 3294 | 362 |
| 363 After the copyright notice and help text come several @dfn{header | |
| 364 comment} lines, each beginning with @samp{## @var{header-name}:}. For | |
| 365 example, | |
| 366 | |
| 367 @example | |
| 368 @group | |
| 369 ## Author: jwe | |
| 370 ## Keywords: subprocesses input-output | |
| 371 ## Maintainer: jwe | |
| 372 @end group | |
| 373 @end example | |
| 374 | |
| 375 Here is a table of the conventional possibilities for @var{header-name}: | |
| 376 | |
| 377 @table @samp | |
| 378 @item Author | |
| 379 This line states the name and net address of at least the principal | |
| 380 author of the library. | |
| 381 | |
| 6670 | 382 @example |
| 9322 | 383 ## Author: John W. Eaton <jwe@@octave.org> |
| 6670 | 384 @end example |
| 3294 | 385 |
| 386 @item Maintainer | |
| 387 This line should contain a single name/address as in the Author line, or | |
| 388 an address only, or the string @samp{jwe}. If there is no maintainer | |
| 389 line, the person(s) in the Author field are presumed to be the | |
| 390 maintainers. The example above is mildly bogus because the maintainer | |
| 391 line is redundant. | |
| 392 | |
| 393 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make | |
| 394 possible a function to ``send mail to the maintainer'' without | |
| 395 having to mine the name out by hand. | |
| 396 | |
| 397 Be sure to surround the network address with @samp{<@dots{}>} if | |
| 398 you include the person's full name as well as the network address. | |
| 399 | |
| 400 @item Created | |
| 401 This optional line gives the original creation date of the | |
| 402 file. For historical interest only. | |
| 403 | |
| 404 @item Version | |
| 405 If you wish to record version numbers for the individual Octave program, | |
| 406 put them in this line. | |
| 407 | |
| 408 @item Adapted-By | |
| 409 In this header line, place the name of the person who adapted the | |
| 410 library for installation (to make it fit the style conventions, for | |
| 411 example). | |
| 412 | |
| 413 @item Keywords | |
| 414 This line lists keywords. Eventually, it will be used by an apropos | |
| 415 command to allow people will find your package when they're looking for | |
| 416 things by topic area. To separate the keywords, you can use spaces, | |
| 417 commas, or both. | |
| 418 @end table | |
| 419 | |
| 420 Just about every Octave function ought to have the @samp{Author} and | |
| 421 @samp{Keywords} header comment lines. Use the others if they are | |
| 422 appropriate. You can also put in header lines with other header | |
| 423 names---they have no standard meanings, so they can't do any harm. | |
| 6574 | 424 |
| 425 @node Documentation Tips | |
| 426 @section Tips for Documentation Strings | |
| 427 | |
| 428 As noted above, documentation is typically in a commented header block | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
429 on an Octave function following the copyright statement. The help string |
| 7001 | 430 shown above is an unformatted string and will be displayed as is by |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
431 Octave. Here are some tips for the writing of documentation strings. |
| 6574 | 432 |
| 433 @itemize @bullet | |
| 434 @item | |
| 435 Every command, function, or variable intended for users to know about | |
| 436 should have a documentation string. | |
| 437 | |
| 438 @item | |
| 439 An internal variable or subroutine of an Octave program might as well have | |
| 440 a documentation string. | |
| 441 | |
| 442 @item | |
| 443 The first line of the documentation string should consist of one or two | |
| 444 complete sentences that stand on their own as a summary. | |
| 445 | |
| 446 The documentation string can have additional lines that expand on the | |
| 447 details of how to use the function or variable. The additional lines | |
| 448 should also be made up of complete sentences. | |
| 449 | |
| 450 @item | |
| 451 For consistency, phrase the verb in the first sentence of a | |
| 452 documentation string as an infinitive with ``to'' omitted. For | |
| 453 instance, use ``Return the frob of A and B.'' in preference to ``Returns | |
| 454 the frob of A and B@.'' Usually it looks good to do likewise for the | |
| 455 rest of the first paragraph. Subsequent paragraphs usually look better | |
| 456 if they have proper subjects. | |
| 457 | |
| 458 @item | |
| 459 Write documentation strings in the active voice, not the passive, and in | |
| 460 the present tense, not the future. For instance, use ``Return a list | |
| 461 containing A and B.'' instead of ``A list containing A and B will be | |
| 462 returned.'' | |
| 463 | |
| 464 @item | |
| 465 Avoid using the word ``cause'' (or its equivalents) unnecessarily. | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
466 Instead of, ``Cause Octave to display text in boldface,'' just write |
| 6574 | 467 ``Display text in boldface.'' |
| 468 | |
| 469 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
470 Use two spaces between the period marking the end of a sentence and the |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
471 word which opens the next sentence. This convention has no effect for |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
472 typeset formats like @TeX{}, but improves the readability of the documentation |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
473 in fixed-width environments such as the Info reader. |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
474 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
475 @item |
| 6574 | 476 Do not start or end a documentation string with whitespace. |
| 477 | |
| 478 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
479 Format the documentation string so that it fits within an 80-column screen. |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
480 It is a good idea for most lines to be no wider than 60 characters. |
| 6574 | 481 |
| 482 However, rather than simply filling the entire documentation string, you | |
| 483 can make it much more readable by choosing line breaks with care. | |
| 484 Use blank lines between topics if the documentation string is long. | |
| 485 | |
| 486 @item | |
| 487 @strong{Do not} indent subsequent lines of a documentation string so | |
| 488 that the text is lined up in the source code with the text of the first | |
| 489 line. This looks nice in the source code, but looks bizarre when users | |
| 490 view the documentation. Remember that the indentation before the | |
| 491 starting double-quote is not part of the string! | |
| 492 | |
| 493 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
494 When choosing variable names try to adhere to the following guidelines. |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
495 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
496 @table @asis |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
497 @item |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
498 vectors : x,y,z,t,w |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
499 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
500 @item |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
501 matrices : A,B,M |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
502 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
503 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
504 strings : @nospell{str},s |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
505 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
506 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
507 filenames : @nospell{fname} |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
508 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
509 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
510 cells,@nospell{cellstrs} : c,@nospell{cstr} |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
511 @end table |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
512 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
513 @item |
| 6574 | 514 The documentation string for a variable that is a yes-or-no flag should |
| 515 start with words such as ``Nonzero means@dots{}'', to make it clear that | |
| 516 all nonzero values are equivalent and indicate explicitly what zero and | |
| 517 nonzero mean. | |
| 518 | |
| 519 @item | |
| 520 When a function's documentation string mentions the value of an argument | |
| 521 of the function, use the argument name in capital letters as if it were | |
| 522 a name for that value. Thus, the documentation string of the operator | |
| 523 @code{/} refers to its second argument as @samp{DIVISOR}, because the | |
| 524 actual argument name is @code{divisor}. | |
| 525 | |
| 526 Also use all caps for meta-syntactic variables, such as when you show | |
| 527 the decomposition of a list or vector into subunits, some of which may | |
| 528 vary. | |
| 529 @end itemize | |
| 530 | |
| 531 Octave also allows extensive formatting of the help string of functions | |
| 532 using Texinfo. The effect on the online documentation is relatively | |
| 533 small, but makes the help string of functions conform to the help of | |
| 534 Octave's own functions. However, the effect on the appearance of printed | |
| 535 or online documentation will be greatly improved. | |
| 536 | |
| 537 The fundamental building block of Texinfo documentation strings is the | |
| 538 Texinfo-macro @code{@@deftypefn}, which takes three arguments: The class | |
| 539 the function is in, its output arguments, and the function's | |
| 540 signature. Typical classes for functions include @code{Function File} | |
| 541 for standard Octave functions, and @code{Loadable Function} for | |
| 542 dynamically linked functions. A skeletal Texinfo documentation string | |
| 543 therefore looks like this | |
| 544 | |
| 545 @example | |
| 546 @group | |
| 547 -*- texinfo -*- | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
548 @@deftypefn@{Function File@} @{@@var@{ret@} =@} fn (@dots{}) |
| 6574 | 549 @@cindex index term |
| 7081 | 550 Help text in Texinfo format. Code samples should be marked |
| 551 like @@code@{sample of code@} and variables should be marked | |
| 552 as @@var@{variable@}. | |
| 553 @@seealso@{fn2@} | |
| 6574 | 554 @@end deftypefn |
| 555 @end group | |
| 556 @end example | |
| 557 | |
| 558 This help string must be commented in user functions, or in the help | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
559 string of the @w{@code{DEFUN_DLD}} macro for dynamically loadable |
| 6574 | 560 functions. The important aspects of the documentation string are |
| 561 | |
| 562 @table @asis | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
563 @item -*- @nospell{texinfo} -*- |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7768
diff
changeset
|
564 This string signals Octave that the following text is in Texinfo format, |
| 6574 | 565 and should be the first part of any help string in Texinfo format. |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
566 |
| 6574 | 567 @item @@deftypefn@{class@} @dots{} @@end deftypefn |
| 568 The entire help string should be enclosed within the block defined by | |
| 569 deftypefn. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
570 |
| 6574 | 571 @item @@cindex index term |
| 572 This generates an index entry, and can be useful when the function is | |
| 573 included as part of a larger piece of documentation. It is ignored | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
574 within Octave's help viewer. Only one index term may appear per line |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
575 but multiple @@cindex lines are valid if the function should be |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
576 filed under different terms. |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
577 |
| 6574 | 578 @item @@var@{variable@} |
| 579 All variables should be marked with this macro. The markup of variables | |
| 580 is then changed appropriately for display. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
581 |
| 6574 | 582 @item @@code@{sample of code@} |
| 583 All samples of code should be marked with this macro for the same | |
| 584 reasons as the @@var macro. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
585 |
| 6574 | 586 @item @@seealso@{function2@} |
| 587 This is a comma separated list of function names that allows cross | |
| 588 referencing from one function documentation string to another. | |
| 589 @end table | |
| 590 | |
| 591 Texinfo format has been designed to generate output for online viewing | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
592 with text terminals as well as generating high-quality printed output. |
| 6574 | 593 To these ends, Texinfo has commands which control the diversion of parts |
| 594 of the document into a particular output processor. Three formats are | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
595 of importance: info, HTML and @TeX{}. These are selected with |
| 6574 | 596 |
| 597 @example | |
| 598 @group | |
| 599 @@ifinfo | |
| 600 Text area for info only | |
| 601 @@end ifinfo | |
| 602 @end group | |
| 603 @end example | |
| 604 | |
| 605 @example | |
| 606 @group | |
| 607 @@ifhtml | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
608 Text area for HTML only |
| 6574 | 609 @@end ifhtml |
| 610 @end group | |
| 611 @end example | |
| 612 | |
| 613 @example | |
| 614 @group | |
| 615 @@tex | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
616 Text area for TeX only |
| 6574 | 617 @@end tex |
| 618 @end group | |
| 619 @end example | |
| 620 | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
621 Note that often @TeX{} output can be used in HTML documents and so often |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
622 the @code{@@ifhtml} blocks are unnecessary. If no specific output |
| 6574 | 623 processor is chosen, by default, the text goes into all output |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
624 processors. It is usual to have the above blocks in pairs to allow the |
| 6574 | 625 same information to be conveyed in all output formats, but with a |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
626 different markup. Currently, most Octave documentation only makes a |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
627 distinction between @TeX{} and all other formats. Therefore, the |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
628 following construct is seen repeatedly. |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
629 |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
630 @example |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
631 @group |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
632 @@tex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
633 text for TeX only |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
634 @@end tex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
635 @@ifnottex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
636 text for info, HTML, plaintext |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
637 @@end ifnottex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
638 @end group |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
639 @end example |
| 6574 | 640 |
| 641 Another important feature of Texinfo that is often used in Octave help | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
642 strings is the @code{@@example} environment. An example of its use is |
| 6574 | 643 |
| 644 @example | |
| 645 @group | |
| 646 @@example | |
| 647 @@group | |
| 648 @@code@{2 * 2@} | |
| 649 @@result@{@} 4 | |
| 650 @@end group | |
| 651 @@end example | |
| 652 @end group | |
| 653 @end example | |
| 654 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
655 @noindent |
| 6574 | 656 which produces |
| 657 | |
| 658 @example | |
| 659 @group | |
| 660 @code{2 * 2} | |
| 661 @result{} 4 | |
| 662 @end group | |
| 663 @end example | |
| 664 | |
| 665 The @code{@@group} block prevents the example from being split across a | |
| 666 page boundary, while the @code{@@result@{@}} macro produces a right | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
667 arrow signifying the result of a command. If your example is larger than |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
668 20 lines it is better NOT to use grouping so that a reasonable page boundary |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
669 can be calculated. |
| 6574 | 670 |
| 8828 | 671 In many cases a function has multiple ways in which it can be called, |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
672 and the @code{@@deftypefnx} macro can be used to give alternatives. For |
| 6574 | 673 example |
| 674 | |
| 675 @example | |
| 676 @group | |
| 677 -*- texinfo -*- | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
678 @@deftypefn @{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{}) |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
679 @@deftypefnx@{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{}) |
| 6574 | 680 Help text in Texinfo format. |
| 681 @@end deftypefn | |
| 682 @end group | |
| 683 @end example | |
| 684 | |
| 685 Many complete examples of Texinfo documentation can be taken from the | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
686 help strings for the Octave functions themselves. A relatively complete |
|
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
687 example of which is the @code{nchoosek} function. The Texinfo |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
688 documentation string for @code{nchoosek} is |
| 6574 | 689 |
| 690 @example | |
| 691 -*- texinfo -*- | |
| 7081 | 692 @@deftypefn @{Function File@} @{@} nchoosek (@@var@{n@}, @@var@{k@}) |
| 6574 | 693 |
| 7081 | 694 Compute the binomial coefficient or all combinations of |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
695 @@var@{n@}. If @@var@{n@} is a scalar then, calculate the |
| 7081 | 696 binomial coefficient of @@var@{n@} and @@var@{k@}, defined as |
| 6574 | 697 |
| 698 @@tex | |
| 699 $$ | |
| 700 @{n \choose k@} = @{n (n-1) (n-2) \cdots (n-k+1) \over k!@} | |
| 701 $$ | |
| 702 @@end tex | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
703 @@ifnottex |
| 6574 | 704 |
| 705 @@example | |
| 706 @@group | |
| 707 / \ | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
708 | n | n (n-1) (n-2) @dots{} (n-k+1) |
| 6574 | 709 | | = ------------------------- |
| 710 | k | k! | |
| 711 \ / | |
| 712 @@end group | |
| 713 @@end example | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
714 @@end ifnottex |
| 6574 | 715 |
| 7081 | 716 If @@var@{n@} is a vector, this generates all combinations |
| 717 of the elements of @@var@{n@}, taken @@var@{k@} at a time, | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
718 one row per combination. The resulting @@var@{c@} has size |
| 7081 | 719 @@code@{[nchoosek (length (@@var@{n@}),@@var@{k@}), @@var@{k@}]@}. |
| 6574 | 720 |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
721 @@code@{nchoosek@} works only for non-negative integer arguments; use |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
722 @@code@{bincoeff@} for non-integer scalar arguments and for using vector |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
723 arguments to compute many coefficients at once. |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
724 |
| 6574 | 725 @@seealso@{bincoeff@} |
| 726 @@end deftypefn | |
| 727 @end example | |
| 728 | |
| 729 which demonstrates most of the concepts discussed above. | |
| 730 @iftex | |
| 731 This documentation string renders as | |
| 732 | |
| 733 @c Note actually use the output of info below rather than try and | |
| 734 @c reproduce it here to prevent it looking different than how it would | |
| 735 @c appear with info. | |
| 736 @example | |
| 737 @group | |
| 738 -- Function File: C = nchoosek (N, K) | |
| 7081 | 739 Compute the binomial coefficient or all combinations |
| 740 of N. If N is a scalar then, calculate the binomial | |
| 741 coefficient of N and K, defined as | |
| 6574 | 742 |
| 743 / \ | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
744 | n | n (n-1) (n-2) @dots{} (n-k+1) n! |
| 7081 | 745 | | = ------------------------- = --------- |
| 746 | k | k! k! (n-k)! | |
| 6574 | 747 \ / |
| 748 | |
| 7081 | 749 If N is a vector generate all combinations of the |
| 750 elements of N, taken K at a time, one row per | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
751 combination. The resulting C has size `[nchoosek |
| 7081 | 752 (length (N), K), K]'. |
| 6574 | 753 |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
754 `nchoosek' works only for non-negative integer |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
755 arguments; use `bincoeff' for non-integer scalar |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
756 arguments and for using vector arguments to compute |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
757 many coefficients at once. |
| 6574 | 758 |
| 759 See also: bincoeff. | |
| 760 @end group | |
| 761 @end example | |
| 762 | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
763 using info, whereas in a printed documentation using @TeX{} it will appear |
| 6574 | 764 as |
| 765 | |
| 766 @deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k}) | |
| 767 | |
| 6576 | 768 Compute the binomial coefficient or all combinations of @var{n}. |
| 6574 | 769 If @var{n} is a scalar then, calculate the binomial coefficient |
| 770 of @var{n} and @var{k}, defined as | |
| 771 | |
| 772 @tex | |
| 773 $$ | |
| 774 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} | |
| 775 $$ | |
| 776 @end tex | |
| 777 | |
| 778 If @var{n} is a vector generate all combinations of the elements | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
779 of @var{n}, taken @var{k} at a time, one row per combination. The |
| 6574 | 780 resulting @var{c} has size @code{[nchoosek (length (@var{n}), |
| 781 @var{k}), @var{k}]}. | |
| 782 | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
783 @code{nchoosek} works only for non-negative integer arguments; use |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
784 @code{bincoeff} for non-integer scalar arguments and for using vector |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
785 arguments to compute many coefficients at once. |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
786 |
| 6574 | 787 @seealso{bincoeff} |
| 788 @end deftypefn | |
| 789 | |
| 790 @end iftex |