Mercurial > octave-nkf
annotate doc/interpreter/tips.txi @ 14116:951eacaf9381 stable
Initial documentation for broadcasting and general vectorization guidelines
* vectorize.txi: New file.
* NEWS: Update with location of broadcasting documentation.
* Makefile.am: Add vectorize.texi
* arith.txi: Move accumarray and accumdim docstring to vectorize.txi
* container.txi: Move structfun docstring to vectorize.txi
* expr.txi: Mention broadcasting where relevant.
* func.txi: Move vectorize docstring to vectorize.txi
* matrix.txi: Move function application section to vectorize.txi
* octave.texi: Add vectorize.txi and its menu options
* sparse.txi: Move spfun to vectorize.txi
* tips.txi: Move and rewrite coding tips section in vectorize.txi
* bsxfun.h (is_valid_bsxfun, is_valid_inplace_bsxfun): Rename warning
to "Octave:broadcast"
* accumdim.m: Reformat to use @example in lieu of @smallexample
* warning_ids.m: Add Octave:broadcast
* bsxfun.cc: Reword docstring to mention broadcasting
* cellfun.cc: Move comment about efficiency from tips.txi
* version.h.in: Add a big startup warning about broadcasting
| author | Jordi Gutiérrez Hermoso <jordigh@octave.org> |
|---|---|
| date | Tue, 27 Dec 2011 15:15:41 -0500 |
| parents | 050bc580cb60 |
| children | 72c96de7a403 |
| 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 * Comment Tips:: Conventions for writing comments. | |
| 32 * Function Headers:: Standard headers for functions. | |
| 6574 | 33 * Documentation Tips:: Writing readable documentation strings. |
| 3294 | 34 @end menu |
| 35 | |
| 4167 | 36 @node Style Tips |
| 3294 | 37 @section Writing Clean Octave Programs |
| 38 | |
| 39 Here are some tips for avoiding common errors in writing Octave code | |
| 40 intended for widespread use: | |
| 41 | |
| 42 @itemize @bullet | |
| 43 @item | |
| 44 Since all global variables share the same name space, and all functions | |
| 45 share another name space, you should choose a short word to distinguish | |
| 46 your program from other Octave programs. Then take care to begin the | |
| 47 names of all global variables, constants, and functions with the chosen | |
| 48 prefix. This helps avoid name conflicts. | |
| 49 | |
| 50 If you write a function that you think ought to be added to Octave under | |
| 51 a certain name, such as @code{fiddle_matrix}, don't call it by that name | |
| 52 in your program. Call it @code{mylib_fiddle_matrix} in your program, | |
| 5041 | 53 and send mail to @email{maintainers@@octave.org} suggesting that it |
| 3294 | 54 be added to Octave. If and when it is, the name can be changed easily |
| 55 enough. | |
| 56 | |
| 57 If one prefix is insufficient, your package may use two or three | |
| 58 alternative common prefixes, so long as they make sense. | |
| 59 | |
| 60 Separate the prefix from the rest of the symbol name with an underscore | |
| 61 @samp{_}. This will be consistent with Octave itself and with most | |
| 62 Octave programs. | |
| 63 | |
| 64 @item | |
| 65 When you encounter an error condition, call the function @code{error} | |
| 66 (or @code{usage}). The @code{error} and @code{usage} functions do not | |
| 67 return. | |
| 68 @xref{Errors}. | |
| 69 | |
| 70 @item | |
| 71 Please put a copyright notice on the file if you give copies to anyone. | |
| 72 Use the same lines that appear at the top of the function files | |
| 73 distributed with Octave. If you have not signed papers to assign the | |
| 74 copyright to anyone else, then place your name in the copyright notice. | |
| 75 @end itemize | |
| 76 | |
| 77 | |
| 4167 | 78 @node Comment Tips |
| 3294 | 79 @section Tips on Writing Comments |
| 80 | |
| 81 Here are the conventions to follow when writing comments. | |
| 82 | |
| 83 @table @samp | |
| 84 @item # | |
| 85 Comments that start with a single sharp-sign, @samp{#}, should all be | |
| 86 aligned to the same column on the right of the source code. Such | |
| 87 comments usually explain how the code on the same line does its job. In | |
| 88 the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) | |
| 89 command automatically inserts such a @samp{#} in the right place, or | |
| 90 aligns such a comment if it is already present. | |
| 91 | |
| 92 @item ## | |
| 7345 | 93 Comments that start with a double sharp-sign, @samp{##}, should be aligned to |
| 3294 | 94 the same level of indentation as the code. Such comments usually |
| 95 describe the purpose of the following lines or the state of the program | |
| 96 at that point. | |
| 97 @end table | |
| 98 | |
| 99 @noindent | |
| 100 The indentation commands of the Octave mode in Emacs, such as @kbd{M-;} | |
| 101 (@code{indent-for-comment}) and @kbd{TAB} (@code{octave-indent-line}) | |
| 102 automatically indent comments according to these conventions, | |
| 103 depending on the number of semicolons. @xref{Comments,, | |
| 104 Manipulating Comments, emacs, The GNU Emacs Manual}. | |
| 105 | |
| 4167 | 106 @node Function Headers |
| 3294 | 107 @section Conventional Headers for Octave Functions |
| 108 @cindex header comments | |
| 109 | |
| 110 Octave has conventions for using special comments in function files | |
| 111 to give information such as who wrote them. This section explains these | |
| 112 conventions. | |
| 113 | |
| 114 The top of the file should contain a copyright notice, followed by a | |
| 115 block of comments that can be used as the help text for the function. | |
| 116 Here is an example: | |
| 117 | |
| 118 @example | |
| 6778 | 119 ## Copyright (C) 1996, 1997, 2007 John W. Eaton |
| 3294 | 120 ## |
| 121 ## This file is part of Octave. | |
| 122 ## | |
| 123 ## Octave is free software; you can redistribute it and/or | |
| 124 ## modify it under the terms of the GNU General Public | |
| 125 ## License as published by the Free Software Foundation; | |
| 7081 | 126 ## either version 3 of the License, or (at your option) any |
| 127 ## later version. | |
| 3294 | 128 ## |
| 129 ## Octave is distributed in the hope that it will be useful, | |
| 130 ## but WITHOUT ANY WARRANTY; without even the implied | |
| 131 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR | |
| 132 ## PURPOSE. See the GNU General Public License for more | |
| 133 ## details. | |
| 134 ## | |
| 135 ## You should have received a copy of the GNU General Public | |
| 136 ## License along with Octave; see the file COPYING. If not, | |
| 7016 | 137 ## see <http://www.gnu.org/licenses/>. |
| 3294 | 138 |
| 139 ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) | |
| 140 ## | |
| 141 ## Start a subprocess with two-way communication. COMMAND | |
| 142 ## specifies the name of the command to start. ARGS is an | |
| 143 ## array of strings containing options for COMMAND. IN and | |
| 144 ## OUT are the file ids of the input and streams for the | |
| 145 ## subprocess, and PID is the process id of the subprocess, | |
| 146 ## or -1 if COMMAND could not be executed. | |
| 147 ## | |
| 148 ## Example: | |
| 149 ## | |
| 150 ## [in, out, pid] = popen2 ("sort", "-nr"); | |
| 151 ## fputs (in, "these\nare\nsome\nstrings\n"); | |
| 152 ## fclose (in); | |
|
7768
a2d9f325b65a
Use isschar instead of deprecated isstr
Rafael Laboissiere <rafael@debian.org>
parents:
7345
diff
changeset
|
153 ## while (ischar (s = fgets (out))) |
| 3294 | 154 ## fputs (stdout, s); |
| 155 ## endwhile | |
| 156 ## fclose (out); | |
| 157 @end example | |
| 158 | |
| 159 Octave uses the first block of comments in a function file that do not | |
| 160 appear to be a copyright notice as the help text for the file. For | |
| 161 Octave to recognize the first comment block as a copyright notice, it | |
| 6530 | 162 must start with the word `Copyright' after stripping the leading |
| 163 comment characters. | |
| 3294 | 164 |
| 165 After the copyright notice and help text come several @dfn{header | |
| 166 comment} lines, each beginning with @samp{## @var{header-name}:}. For | |
| 167 example, | |
| 168 | |
| 169 @example | |
| 170 @group | |
| 171 ## Author: jwe | |
| 172 ## Keywords: subprocesses input-output | |
| 173 ## Maintainer: jwe | |
| 174 @end group | |
| 175 @end example | |
| 176 | |
| 177 Here is a table of the conventional possibilities for @var{header-name}: | |
| 178 | |
| 179 @table @samp | |
| 180 @item Author | |
| 181 This line states the name and net address of at least the principal | |
| 182 author of the library. | |
| 183 | |
| 6670 | 184 @example |
| 9322 | 185 ## Author: John W. Eaton <jwe@@octave.org> |
| 6670 | 186 @end example |
| 3294 | 187 |
| 188 @item Maintainer | |
| 189 This line should contain a single name/address as in the Author line, or | |
| 190 an address only, or the string @samp{jwe}. If there is no maintainer | |
| 191 line, the person(s) in the Author field are presumed to be the | |
| 192 maintainers. The example above is mildly bogus because the maintainer | |
| 193 line is redundant. | |
| 194 | |
| 195 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make | |
| 196 possible a function to ``send mail to the maintainer'' without | |
| 197 having to mine the name out by hand. | |
| 198 | |
| 199 Be sure to surround the network address with @samp{<@dots{}>} if | |
| 200 you include the person's full name as well as the network address. | |
| 201 | |
| 202 @item Created | |
| 203 This optional line gives the original creation date of the | |
| 204 file. For historical interest only. | |
| 205 | |
| 206 @item Version | |
| 207 If you wish to record version numbers for the individual Octave program, | |
| 208 put them in this line. | |
| 209 | |
| 210 @item Adapted-By | |
| 211 In this header line, place the name of the person who adapted the | |
| 212 library for installation (to make it fit the style conventions, for | |
| 213 example). | |
| 214 | |
| 215 @item Keywords | |
| 216 This line lists keywords. Eventually, it will be used by an apropos | |
| 217 command to allow people will find your package when they're looking for | |
| 218 things by topic area. To separate the keywords, you can use spaces, | |
| 219 commas, or both. | |
| 220 @end table | |
| 221 | |
| 222 Just about every Octave function ought to have the @samp{Author} and | |
| 223 @samp{Keywords} header comment lines. Use the others if they are | |
| 224 appropriate. You can also put in header lines with other header | |
| 225 names---they have no standard meanings, so they can't do any harm. | |
| 6574 | 226 |
| 227 @node Documentation Tips | |
| 228 @section Tips for Documentation Strings | |
| 229 | |
| 230 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
|
231 on an Octave function following the copyright statement. The help string |
| 7001 | 232 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
|
233 Octave. Here are some tips for the writing of documentation strings. |
| 6574 | 234 |
| 235 @itemize @bullet | |
| 236 @item | |
| 237 Every command, function, or variable intended for users to know about | |
| 238 should have a documentation string. | |
| 239 | |
| 240 @item | |
| 241 An internal variable or subroutine of an Octave program might as well have | |
| 242 a documentation string. | |
| 243 | |
| 244 @item | |
| 245 The first line of the documentation string should consist of one or two | |
| 246 complete sentences that stand on their own as a summary. | |
| 247 | |
| 248 The documentation string can have additional lines that expand on the | |
| 249 details of how to use the function or variable. The additional lines | |
| 250 should also be made up of complete sentences. | |
| 251 | |
| 252 @item | |
| 253 For consistency, phrase the verb in the first sentence of a | |
| 254 documentation string as an infinitive with ``to'' omitted. For | |
| 255 instance, use ``Return the frob of A and B.'' in preference to ``Returns | |
| 256 the frob of A and B@.'' Usually it looks good to do likewise for the | |
| 257 rest of the first paragraph. Subsequent paragraphs usually look better | |
| 258 if they have proper subjects. | |
| 259 | |
| 260 @item | |
| 261 Write documentation strings in the active voice, not the passive, and in | |
| 262 the present tense, not the future. For instance, use ``Return a list | |
| 263 containing A and B.'' instead of ``A list containing A and B will be | |
| 264 returned.'' | |
| 265 | |
| 266 @item | |
| 267 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
|
268 Instead of, ``Cause Octave to display text in boldface,'' just write |
| 6574 | 269 ``Display text in boldface.'' |
| 270 | |
| 271 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
272 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
|
273 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
|
274 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
|
275 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
|
276 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
277 @item |
| 6574 | 278 Do not start or end a documentation string with whitespace. |
| 279 | |
| 280 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
281 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
|
282 It is a good idea for most lines to be no wider than 60 characters. |
| 6574 | 283 |
| 284 However, rather than simply filling the entire documentation string, you | |
| 285 can make it much more readable by choosing line breaks with care. | |
| 286 Use blank lines between topics if the documentation string is long. | |
| 287 | |
| 288 @item | |
| 289 @strong{Do not} indent subsequent lines of a documentation string so | |
| 290 that the text is lined up in the source code with the text of the first | |
| 291 line. This looks nice in the source code, but looks bizarre when users | |
| 292 view the documentation. Remember that the indentation before the | |
| 293 starting double-quote is not part of the string! | |
| 294 | |
| 295 @item | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
296 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
|
297 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
298 @table @asis |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
299 @item |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
300 vectors : x,y,z,t,w |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
301 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
302 @item |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
303 matrices : A,B,M |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
304 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
305 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
306 strings : @nospell{str},s |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
307 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
308 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
309 filenames : @nospell{fname} |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
310 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
311 @item |
|
12576
a1e386b9ef4b
Spellcheck documentation for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
312 cells,@nospell{cellstrs} : c,@nospell{cstr} |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
313 @end table |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
314 |
|
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
315 @item |
| 6574 | 316 The documentation string for a variable that is a yes-or-no flag should |
| 317 start with words such as ``Nonzero means@dots{}'', to make it clear that | |
| 318 all nonzero values are equivalent and indicate explicitly what zero and | |
| 319 nonzero mean. | |
| 320 | |
| 321 @item | |
| 322 When a function's documentation string mentions the value of an argument | |
| 323 of the function, use the argument name in capital letters as if it were | |
| 324 a name for that value. Thus, the documentation string of the operator | |
| 325 @code{/} refers to its second argument as @samp{DIVISOR}, because the | |
| 326 actual argument name is @code{divisor}. | |
| 327 | |
| 328 Also use all caps for meta-syntactic variables, such as when you show | |
| 329 the decomposition of a list or vector into subunits, some of which may | |
| 330 vary. | |
| 331 @end itemize | |
| 332 | |
| 333 Octave also allows extensive formatting of the help string of functions | |
| 334 using Texinfo. The effect on the online documentation is relatively | |
| 335 small, but makes the help string of functions conform to the help of | |
| 336 Octave's own functions. However, the effect on the appearance of printed | |
| 337 or online documentation will be greatly improved. | |
| 338 | |
| 339 The fundamental building block of Texinfo documentation strings is the | |
| 340 Texinfo-macro @code{@@deftypefn}, which takes three arguments: The class | |
| 341 the function is in, its output arguments, and the function's | |
| 342 signature. Typical classes for functions include @code{Function File} | |
| 343 for standard Octave functions, and @code{Loadable Function} for | |
| 344 dynamically linked functions. A skeletal Texinfo documentation string | |
| 345 therefore looks like this | |
| 346 | |
| 347 @example | |
| 348 @group | |
| 349 -*- texinfo -*- | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
350 @@deftypefn@{Function File@} @{@@var@{ret@} =@} fn (@dots{}) |
| 6574 | 351 @@cindex index term |
| 7081 | 352 Help text in Texinfo format. Code samples should be marked |
| 353 like @@code@{sample of code@} and variables should be marked | |
| 354 as @@var@{variable@}. | |
| 355 @@seealso@{fn2@} | |
| 6574 | 356 @@end deftypefn |
| 357 @end group | |
| 358 @end example | |
| 359 | |
| 360 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
|
361 string of the @w{@code{DEFUN_DLD}} macro for dynamically loadable |
| 6574 | 362 functions. The important aspects of the documentation string are |
| 363 | |
| 364 @table @asis | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
365 @item -*- @nospell{texinfo} -*- |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7768
diff
changeset
|
366 This string signals Octave that the following text is in Texinfo format, |
| 6574 | 367 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
|
368 |
| 6574 | 369 @item @@deftypefn@{class@} @dots{} @@end deftypefn |
| 370 The entire help string should be enclosed within the block defined by | |
| 371 deftypefn. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
372 |
| 6574 | 373 @item @@cindex index term |
| 374 This generates an index entry, and can be useful when the function is | |
| 375 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
|
376 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
|
377 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
|
378 filed under different terms. |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
379 |
| 6574 | 380 @item @@var@{variable@} |
| 381 All variables should be marked with this macro. The markup of variables | |
| 382 is then changed appropriately for display. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
383 |
| 6574 | 384 @item @@code@{sample of code@} |
| 385 All samples of code should be marked with this macro for the same | |
| 386 reasons as the @@var macro. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
387 |
| 6574 | 388 @item @@seealso@{function2@} |
| 389 This is a comma separated list of function names that allows cross | |
| 390 referencing from one function documentation string to another. | |
| 391 @end table | |
| 392 | |
| 393 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
|
394 with text terminals as well as generating high-quality printed output. |
| 6574 | 395 To these ends, Texinfo has commands which control the diversion of parts |
| 396 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
|
397 of importance: info, HTML and @TeX{}. These are selected with |
| 6574 | 398 |
| 399 @example | |
| 400 @group | |
| 401 @@ifinfo | |
| 402 Text area for info only | |
| 403 @@end ifinfo | |
| 404 @end group | |
| 405 @end example | |
| 406 | |
| 407 @example | |
| 408 @group | |
| 409 @@ifhtml | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
410 Text area for HTML only |
| 6574 | 411 @@end ifhtml |
| 412 @end group | |
| 413 @end example | |
| 414 | |
| 415 @example | |
| 416 @group | |
| 417 @@tex | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
418 Text area for TeX only |
| 6574 | 419 @@end tex |
| 420 @end group | |
| 421 @end example | |
| 422 | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
423 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
|
424 the @code{@@ifhtml} blocks are unnecessary. If no specific output |
| 6574 | 425 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
|
426 processors. It is usual to have the above blocks in pairs to allow the |
| 6574 | 427 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
|
428 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
|
429 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
|
430 following construct is seen repeatedly. |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
431 |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
432 @example |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
433 @group |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
434 @@tex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
435 text for TeX only |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
436 @@end tex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
437 @@ifnottex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
438 text for info, HTML, plaintext |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
439 @@end ifnottex |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
440 @end group |
|
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
441 @end example |
| 6574 | 442 |
| 443 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
|
444 strings is the @code{@@example} environment. An example of its use is |
| 6574 | 445 |
| 446 @example | |
| 447 @group | |
| 448 @@example | |
| 449 @@group | |
| 450 @@code@{2 * 2@} | |
| 451 @@result@{@} 4 | |
| 452 @@end group | |
| 453 @@end example | |
| 454 @end group | |
| 455 @end example | |
| 456 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
457 @noindent |
| 6574 | 458 which produces |
| 459 | |
| 460 @example | |
| 461 @group | |
| 462 @code{2 * 2} | |
| 463 @result{} 4 | |
| 464 @end group | |
| 465 @end example | |
| 466 | |
| 467 The @code{@@group} block prevents the example from being split across a | |
| 468 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
|
469 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
|
470 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
|
471 can be calculated. |
| 6574 | 472 |
| 8828 | 473 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
|
474 and the @code{@@deftypefnx} macro can be used to give alternatives. For |
| 6574 | 475 example |
| 476 | |
| 477 @example | |
| 478 @group | |
| 479 -*- texinfo -*- | |
|
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
480 @@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
|
481 @@deftypefnx@{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{}) |
| 6574 | 482 Help text in Texinfo format. |
| 483 @@end deftypefn | |
| 484 @end group | |
| 485 @end example | |
| 486 | |
| 487 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
|
488 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
|
489 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
|
490 documentation string for @code{nchoosek} is |
| 6574 | 491 |
| 492 @example | |
| 493 -*- texinfo -*- | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
494 @@deftypefn @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{n@}, @@var@{k@}) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
495 @@deftypefnx @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{set@}, @@var@{k@}) |
| 6574 | 496 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
497 Compute the binomial coefficient or all combinations of a set of items. |
| 6574 | 498 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
499 If @@var@{n@} is a scalar then calculate the binomial coefficient |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
500 of @@var@{n@} and @@var@{k@} which is defined as |
| 6574 | 501 @@tex |
| 502 $$ | |
| 503 @{n \choose k@} = @{n (n-1) (n-2) \cdots (n-k+1) \over k!@} | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
504 = @{n! \over k! (n-k)!@} |
| 6574 | 505 $$ |
| 506 @@end tex | |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
507 @@ifnottex |
| 6574 | 508 |
| 509 @@example | |
| 510 @@group | |
| 511 / \ | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
512 | n | n (n-1) (n-2) @@dots@{@} (n-k+1) n! |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
513 | | = ------------------------- = --------- |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
514 | k | k! k! (n-k)! |
| 6574 | 515 \ / |
| 516 @@end group | |
| 517 @@end example | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
518 |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
519 @@end ifnottex |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
520 @@noindent |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
521 This is the number of combinations of @@var@{n@} items taken in groups of |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
522 size @@var@{k@}. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
523 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
524 If the first argument is a vector, @@var@{set@}, then generate all |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
525 combinations of the elements of @@var@{set@}, taken @@var@{k@} at a time, with |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
526 one row per combination. The result @@var@{c@} has @@var@{k@} columns and |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
527 @@w@{@@code@{nchoosek (length (@@var@{set@}), @@var@{k@})@}@} rows. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
528 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
529 For example: |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
530 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
531 How many ways can three items be grouped into pairs? |
| 6574 | 532 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
533 @@example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
534 @@group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
535 nchoosek (3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
536 @@result@{@} 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
537 @@end group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
538 @@end example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
539 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
540 What are the possible pairs? |
| 6574 | 541 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
542 @@example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
543 @@group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
544 nchoosek (1:3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
545 @@result@{@} 1 2 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
546 1 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
547 2 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
548 @@end group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
549 @@end example |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
550 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
551 @@code@{nchoosek@} works only for non-negative, integer arguments. Use |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
552 @@code@{bincoeff@} for non-integer and negative scalar arguments, or for |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
553 computing many binomial coefficients at once with vector inputs |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
554 for @@var@{n@} or @@var@{k@}. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
555 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
556 @@seealso@{bincoeff, perms@} |
| 6574 | 557 @@end deftypefn |
| 558 @end example | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
559 @noindent |
| 6574 | 560 which demonstrates most of the concepts discussed above. |
| 561 @iftex | |
| 562 This documentation string renders as | |
| 563 | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
564 @c Note: use the actual output of info below, rather than try and |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
565 @c reproduce it here to prevent it looking different from how it would |
| 6574 | 566 @c appear with info. |
| 567 @example | |
| 568 -- Function File: C = nchoosek (N, K) | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
569 -- Function File: C = nchoosek (SET, K) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
570 Compute the binomial coefficient or all combinations of a set of |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
571 items. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
572 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
573 If N is a scalar then calculate the binomial coefficient of N and |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
574 K which is defined as |
| 6574 | 575 |
| 576 / \ | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
577 | n | n (n-1) (n-2) ... (n-k+1) n! |
| 7081 | 578 | | = ------------------------- = --------- |
| 579 | k | k! k! (n-k)! | |
| 6574 | 580 \ / |
| 581 | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
582 This is the number of combinations of N items taken in groups of |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
583 size K. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
584 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
585 If the first argument is a vector, SET, then generate all |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
586 combinations of the elements of SET, taken K at a time, with one |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
587 row per combination. The result C has K columns and |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
588 `nchoosek (length (SET), K)' rows. |
| 6574 | 589 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
590 For example: |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
591 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
592 How many ways can three items be grouped into pairs? |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
593 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
594 nchoosek (3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
595 => 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
596 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
597 What are the possible pairs? |
| 6574 | 598 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
599 nchoosek (1:3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
600 => 1 2 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
601 1 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
602 2 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
603 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
604 `nchoosek' works only for non-negative, integer arguments. Use |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
605 `bincoeff' for non-integer and negative scalar arguments, or for |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
606 computing many binomial coefficients at once with vector inputs |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
607 for N or K. |
| 6574 | 608 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
609 See also: bincoeff, perms |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
610 @end example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
611 @noindent |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
612 using info, whereas in a printed documentation using @TeX{} it will |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
613 appear as |
| 6574 | 614 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
615 @deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k}) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
616 @deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k}) |
| 6574 | 617 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
618 Compute the binomial coefficient or all combinations of a set of items. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
619 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
620 If @var{n} is a scalar then calculate the binomial coefficient |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
621 of @var{n} and @var{k} which is defined as |
| 6574 | 622 |
| 623 @tex | |
| 624 $$ | |
| 625 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
626 = {n! \over k! (n-k)!} |
| 6574 | 627 $$ |
| 628 @end tex | |
| 629 | |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
630 @noindent |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
631 This is the number of combinations of @var{n} items taken in groups of |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
632 size @var{k}. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
633 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
634 If the first argument is a vector, @var{set}, then generate all |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
635 combinations of the elements of @var{set}, taken @var{k} at a time, with |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
636 one row per combination. The result @var{c} has @var{k} columns and |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
637 @w{@code{nchoosek (length (@var{set}), @var{k})}} rows. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
638 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
639 For example: |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
640 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
641 How many ways can three items be grouped into pairs? |
| 6574 | 642 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
643 @example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
644 @group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
645 nchoosek (3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
646 @result{} 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
647 @end group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
648 @end example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
649 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
650 What are the possible pairs? |
|
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
651 |
|
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
652 @example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
653 @group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
654 nchoosek (1:3, 2) |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
655 @result{} 1 2 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
656 1 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
657 2 3 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
658 @end group |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
659 @end example |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
660 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
661 @code{nchoosek} works only for non-negative, integer arguments. Use |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
662 @code{bincoeff} for non-integer and negative scalar arguments, or for |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
663 computing many binomial coefficients at once with vector inputs for @var{n} |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
664 or @var{k}. |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
665 |
|
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
666 @seealso{bincoeff, perms} |
| 6574 | 667 @end deftypefn |
| 668 | |
| 669 @end iftex |