Mercurial > octave-nkf
annotate doc/interpreter/tips.txi @ 20595:c1a6c31ac29a
eliminate more simple uses of error_state
* ov-classdef.cc: Eliminate simple uses of error_state.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Tue, 06 Oct 2015 00:20:02 -0400 |
parents | 014edaafa3ad |
children |
rev | line source |
---|---|
19731
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
19630
diff
changeset
|
1 @c Copyright (C) 1996-2015 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. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
9 @c |
7018 | 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. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
14 @c |
7018 | 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; | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
126 ## either version 3 of the License, or (at your option) any |
7081 | 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 | |
20210
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
245 The first line of the documentation string should consist of a summary of |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
246 the function. |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
247 |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
248 Subsequent lines may expand the general nature of the function. |
6574 | 249 |
20210
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
250 After the introduction there should be paragraphs describing the meaning |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
251 and usage of each input, followed by the meaning and usage of each output. |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
252 |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
253 Finally, there may be more general information such as notes about the |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
254 algorithm used, references to scientific papers, notes about any |
014edaafa3ad
doc: Rewrite guidelines for crafting docstrings.
Rik <rik@octave.org>
parents:
19731
diff
changeset
|
255 incompatibilities with @sc{matlab}, etc. |
6574 | 256 |
257 @item | |
258 For consistency, phrase the verb in the first sentence of a | |
259 documentation string as an infinitive with ``to'' omitted. For | |
260 instance, use ``Return the frob of A and B.'' in preference to ``Returns | |
261 the frob of A and B@.'' Usually it looks good to do likewise for the | |
262 rest of the first paragraph. Subsequent paragraphs usually look better | |
263 if they have proper subjects. | |
264 | |
265 @item | |
266 Write documentation strings in the active voice, not the passive, and in | |
267 the present tense, not the future. For instance, use ``Return a list | |
268 containing A and B.'' instead of ``A list containing A and B will be | |
269 returned.'' | |
270 | |
271 @item | |
272 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
|
273 Instead of, ``Cause Octave to display text in boldface,'' just write |
6574 | 274 ``Display text in boldface.'' |
275 | |
276 @item | |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
277 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
|
278 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
|
279 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
|
280 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
|
281 |
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
282 @item |
6574 | 283 Do not start or end a documentation string with whitespace. |
284 | |
285 @item | |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
286 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
|
287 It is a good idea for most lines to be no wider than 60 characters. |
6574 | 288 |
289 However, rather than simply filling the entire documentation string, you | |
290 can make it much more readable by choosing line breaks with care. | |
291 Use blank lines between topics if the documentation string is long. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
292 |
6574 | 293 @item |
294 @strong{Do not} indent subsequent lines of a documentation string so | |
295 that the text is lined up in the source code with the text of the first | |
296 line. This looks nice in the source code, but looks bizarre when users | |
297 view the documentation. Remember that the indentation before the | |
298 starting double-quote is not part of the string! | |
299 | |
300 @item | |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
301 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
|
302 |
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
303 @table @asis |
16094
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
304 @item vectors : |
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
305 x,y,z,t,w |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
306 |
16094
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
307 @item matrices : |
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
308 A,B,M |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
309 |
16094
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
310 @item strings : |
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
311 @nospell{str},s |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
312 |
16094
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
313 @item filenames : |
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
314 @nospell{fname} |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
315 |
16094
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
316 @item cells,@nospell{cellstrs} : |
8899c785cc99
doc: Fix warnings associated with Texinfo 5.0 (bug #38392)
Rik <rik@octave.org>
parents:
14138
diff
changeset
|
317 c,@nospell{cstr} |
12546
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
318 @end table |
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
319 |
39ca02387a32
Improve docstrings for a number of functions.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
320 @item |
6574 | 321 The documentation string for a variable that is a yes-or-no flag should |
322 start with words such as ``Nonzero means@dots{}'', to make it clear that | |
323 all nonzero values are equivalent and indicate explicitly what zero and | |
324 nonzero mean. | |
325 | |
326 @item | |
327 When a function's documentation string mentions the value of an argument | |
328 of the function, use the argument name in capital letters as if it were | |
329 a name for that value. Thus, the documentation string of the operator | |
330 @code{/} refers to its second argument as @samp{DIVISOR}, because the | |
331 actual argument name is @code{divisor}. | |
332 | |
333 Also use all caps for meta-syntactic variables, such as when you show | |
334 the decomposition of a list or vector into subunits, some of which may | |
335 vary. | |
336 @end itemize | |
337 | |
338 Octave also allows extensive formatting of the help string of functions | |
339 using Texinfo. The effect on the online documentation is relatively | |
340 small, but makes the help string of functions conform to the help of | |
341 Octave's own functions. However, the effect on the appearance of printed | |
342 or online documentation will be greatly improved. | |
343 | |
344 The fundamental building block of Texinfo documentation strings is the | |
345 Texinfo-macro @code{@@deftypefn}, which takes three arguments: The class | |
346 the function is in, its output arguments, and the function's | |
347 signature. Typical classes for functions include @code{Function File} | |
348 for standard Octave functions, and @code{Loadable Function} for | |
349 dynamically linked functions. A skeletal Texinfo documentation string | |
350 therefore looks like this | |
351 | |
352 @example | |
353 @group | |
354 -*- texinfo -*- | |
16790
d21bf69e49b2
doc: Update some spacing in the Tips & Standards chapter.
Rik <rik@octave.org>
parents:
16094
diff
changeset
|
355 @@deftypefn @{Function File@} @{@@var@{ret@} =@} fn (@dots{}) |
6574 | 356 @@cindex index term |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
357 Help text in Texinfo format. Code samples should be marked |
7081 | 358 like @@code@{sample of code@} and variables should be marked |
359 as @@var@{variable@}. | |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
360 @@seealso@{fn2, fn3@} |
6574 | 361 @@end deftypefn |
362 @end group | |
363 @end example | |
364 | |
365 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
|
366 string of the @w{@code{DEFUN_DLD}} macro for dynamically loadable |
6574 | 367 functions. The important aspects of the documentation string are |
368 | |
369 @table @asis | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
370 @item -*- @nospell{texinfo} -*- |
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7768
diff
changeset
|
371 This string signals Octave that the following text is in Texinfo format, |
6574 | 372 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
|
373 |
16790
d21bf69e49b2
doc: Update some spacing in the Tips & Standards chapter.
Rik <rik@octave.org>
parents:
16094
diff
changeset
|
374 @item @@deftypefn @{class@} @dots{} @@end deftypefn |
6574 | 375 The entire help string should be enclosed within the block defined by |
376 deftypefn. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
377 |
6574 | 378 @item @@cindex index term |
379 This generates an index entry, and can be useful when the function is | |
380 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
|
381 within Octave's help viewer. Only one index term may appear per line |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
382 but multiple @@cindex lines are valid if the function should be |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
383 filed under different terms. |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
384 |
6574 | 385 @item @@var@{variable@} |
386 All variables should be marked with this macro. The markup of variables | |
387 is then changed appropriately for display. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
388 |
6574 | 389 @item @@code@{sample of code@} |
390 All samples of code should be marked with this macro for the same | |
391 reasons as the @@var macro. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10812
diff
changeset
|
392 |
17290
17be601bc783
doc: Periodic spellchecking of documentation.
Rik <rik@octave.org>
parents:
17289
diff
changeset
|
393 @item @nospell{@@qcode@{"sample_code"@}} |
17be601bc783
doc: Periodic spellchecking of documentation.
Rik <rik@octave.org>
parents:
17289
diff
changeset
|
394 @itemx @nospell{@@qcode@{'sample_code'@}} |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
395 All samples of code which are quoted should use this more specialized macro. |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
396 This happens frequently when discussing graphics properties such as "position" |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
397 or options such as "on"/"off". |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
398 |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
399 @item @@seealso@{function2, function3@} |
6574 | 400 This is a comma separated list of function names that allows cross |
401 referencing from one function documentation string to another. | |
402 @end table | |
403 | |
404 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
|
405 with text terminals as well as generating high-quality printed output. |
6574 | 406 To these ends, Texinfo has commands which control the diversion of parts |
407 of the document into a particular output processor. Three formats are | |
16790
d21bf69e49b2
doc: Update some spacing in the Tips & Standards chapter.
Rik <rik@octave.org>
parents:
16094
diff
changeset
|
408 of importance: info, HTML, and @TeX{}. These are selected with |
6574 | 409 |
410 @example | |
411 @group | |
412 @@ifinfo | |
413 Text area for info only | |
414 @@end ifinfo | |
415 @end group | |
416 @end example | |
417 | |
418 @example | |
419 @group | |
420 @@ifhtml | |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
421 Text area for HTML only |
6574 | 422 @@end ifhtml |
423 @end group | |
424 @end example | |
425 | |
426 @example | |
427 @group | |
428 @@tex | |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
429 Text area for TeX only |
6574 | 430 @@end tex |
431 @end group | |
432 @end example | |
433 | |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
10284
diff
changeset
|
434 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
|
435 the @code{@@ifhtml} blocks are unnecessary. If no specific output |
6574 | 436 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
|
437 processors. It is usual to have the above blocks in pairs to allow the |
6574 | 438 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
|
439 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
|
440 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
|
441 following construct is seen repeatedly. |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
442 |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
443 @example |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
444 @group |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
445 @@tex |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
446 text for TeX only |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
447 @@end tex |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
448 @@ifnottex |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
449 text for info, HTML, plaintext |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
450 @@end ifnottex |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
451 @end group |
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
452 @end example |
6574 | 453 |
454 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
|
455 strings is the @code{@@example} environment. An example of its use is |
6574 | 456 |
457 @example | |
458 @group | |
459 @@example | |
460 @@group | |
461 @@code@{2 * 2@} | |
462 @@result@{@} 4 | |
463 @@end group | |
464 @@end example | |
465 @end group | |
466 @end example | |
467 | |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
468 @noindent |
6574 | 469 which produces |
470 | |
471 @example | |
472 @group | |
473 @code{2 * 2} | |
474 @result{} 4 | |
475 @end group | |
476 @end example | |
477 | |
478 The @code{@@group} block prevents the example from being split across a | |
479 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
|
480 arrow signifying the result of a command. If your example is larger than |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
481 20 lines it is better @emph{NOT} to use grouping so that a reasonable page |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
16790
diff
changeset
|
482 boundary can be calculated. |
6574 | 483 |
8828 | 484 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
|
485 and the @code{@@deftypefnx} macro can be used to give alternatives. For |
6574 | 486 example |
487 | |
488 @example | |
489 @group | |
490 -*- texinfo -*- | |
16790
d21bf69e49b2
doc: Update some spacing in the Tips & Standards chapter.
Rik <rik@octave.org>
parents:
16094
diff
changeset
|
491 @@deftypefn @{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{}) |
d21bf69e49b2
doc: Update some spacing in the Tips & Standards chapter.
Rik <rik@octave.org>
parents:
16094
diff
changeset
|
492 @@deftypefnx @{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{}) |
6574 | 493 Help text in Texinfo format. |
494 @@end deftypefn | |
495 @end group | |
496 @end example | |
497 | |
498 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
|
499 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
|
500 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
|
501 documentation string for @code{nchoosek} is |
6574 | 502 |
503 @example | |
504 -*- texinfo -*- | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
505 @@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
|
506 @@deftypefnx @{Function File@} @{@@var@{c@} =@} nchoosek (@@var@{set@}, @@var@{k@}) |
6574 | 507 |
19093 | 508 Compute the binomial coefficient of @@var@{n@} or list all possible |
509 combinations of a @@var@{set@} of items. | |
6574 | 510 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
511 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
|
512 of @@var@{n@} and @@var@{k@} which is defined as |
6574 | 513 @@tex |
514 $$ | |
515 @{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
|
516 = @{n! \over k! (n-k)!@} |
6574 | 517 $$ |
518 @@end tex | |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
519 @@ifnottex |
6574 | 520 |
521 @@example | |
522 @@group | |
523 / \ | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
524 | 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
|
525 | | = ------------------------- = --------- |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
526 | k | k! k! (n-k)! |
6574 | 527 \ / |
528 @@end group | |
529 @@end example | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
530 |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
531 @@end ifnottex |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
532 @@noindent |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
533 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
|
534 size @@var@{k@}. |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
535 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
536 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
|
537 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
|
538 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
|
539 @@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
|
540 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
541 For example: |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
542 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
543 How many ways can three items be grouped into pairs? |
6574 | 544 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
545 @@example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
546 @@group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
547 nchoosek (3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
548 @@result@{@} 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
549 @@end group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
550 @@end example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
551 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
552 What are the possible pairs? |
6574 | 553 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
554 @@example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
555 @@group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
556 nchoosek (1:3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
557 @@result@{@} 1 2 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
558 1 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
559 2 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
560 @@end group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
561 @@end example |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
562 |
19093 | 563 Programming Note: When calculating the binomial coefficient @@code@{nchoosek@} |
564 works only for non-negative, integer arguments. Use @@code@{bincoeff@} for | |
565 non-integer and negative scalar arguments, or for computing many binomial | |
566 coefficients at once with vector inputs for @@var@{n@} or @@var@{k@}. | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
567 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
568 @@seealso@{bincoeff, perms@} |
6574 | 569 @@end deftypefn |
570 @end example | |
17289
4d7f95eb8bfe
doc: Miscellaneous small tweaks to documentation for consistency.
Rik <rik@octave.org>
parents:
17281
diff
changeset
|
571 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
572 @noindent |
6574 | 573 which demonstrates most of the concepts discussed above. |
574 @iftex | |
19093 | 575 This documentation string renders in Info format as |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
576 @c Note: use the actual output of info below, rather than try and |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
577 @c reproduce it here to prevent it looking different from how it would |
6574 | 578 @c appear with info. |
17289
4d7f95eb8bfe
doc: Miscellaneous small tweaks to documentation for consistency.
Rik <rik@octave.org>
parents:
17281
diff
changeset
|
579 |
6574 | 580 @example |
581 -- 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
|
582 -- Function File: C = nchoosek (SET, K) |
19093 | 583 Compute the binomial coefficient of N or list all possible |
584 combinations of a SET of items. | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
585 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
586 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
|
587 K which is defined as |
6574 | 588 |
589 / \ | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
590 | n | n (n-1) (n-2) ... (n-k+1) n! |
7081 | 591 | | = ------------------------- = --------- |
592 | k | k! k! (n-k)! | |
6574 | 593 \ / |
594 | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
595 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
|
596 size K. |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
597 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
598 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
|
599 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
|
600 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
|
601 `nchoosek (length (SET), K)' rows. |
6574 | 602 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
603 For example: |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
604 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
605 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
|
606 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
607 nchoosek (3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
608 => 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
609 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
610 What are the possible pairs? |
6574 | 611 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
612 nchoosek (1:3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
613 => 1 2 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
614 1 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
615 2 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
616 |
19093 | 617 Programming Note: When calculating the binomial coefficient |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
618 `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
|
619 `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
|
620 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
|
621 for N or K. |
6574 | 622 |
19093 | 623 See also: bincoeff, perms. |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
624 @end example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
625 @noindent |
19093 | 626 whereas in printed documentation using @TeX{} it will appear as |
6574 | 627 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
628 @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
|
629 @deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k}) |
6574 | 630 |
19093 | 631 Compute the binomial coefficient of @var{n} or list all possible |
632 combinations of a @var{set} of items. | |
14093
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 @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
|
635 of @var{n} and @var{k} which is defined as |
6574 | 636 @tex |
637 $$ | |
638 {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
|
639 = {n! \over k! (n-k)!} |
6574 | 640 $$ |
641 @end tex | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
642 @noindent |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
643 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
|
644 size @var{k}. |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
645 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
646 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
|
647 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
|
648 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
|
649 @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
|
650 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
651 For example: |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
652 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
653 How many ways can three items be grouped into pairs? |
6574 | 654 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
655 @example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
656 @group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
657 nchoosek (3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
658 @result{} 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
659 @end group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
660 @end example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
661 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
662 What are the possible pairs? |
9210
a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
Rik <rdrider0-list@yahoo.com>
parents:
9209
diff
changeset
|
663 |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
664 @example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
665 @group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
666 nchoosek (1:3, 2) |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
667 @result{} 1 2 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
668 1 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
669 2 3 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
670 @end group |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
671 @end example |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
672 |
19093 | 673 Programming Note: When calculating the binomial coefficient @code{nchoosek} |
674 works only for non-negative, integer arguments. Use @code{bincoeff} for | |
675 non-integer and negative scalar arguments, or for computing many binomial | |
676 coefficients at once with vector inputs for @var{n} or @var{k}. | |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
677 |
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12576
diff
changeset
|
678 @seealso{bincoeff, perms} |
6574 | 679 @end deftypefn |
680 | |
681 @end iftex |