Mercurial > hg > octave-nkf
changeset 9210:a7a9eecc07b5
Change recommendation for writing documentation to favor @tex
rather than @iftex construction.
author | Rik <rdrider0-list@yahoo.com> |
---|---|
date | Sun, 17 May 2009 14:17:32 -0700 |
parents | 923c7cb7f13f |
children | f0c3d3fc4903 |
files | doc/ChangeLog doc/interpreter/tips.txi scripts/specfun/nchoosek.m |
diffstat | 3 files changed, 46 insertions(+), 18 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2009-05-17 Rik <rdrider0-list@yahoo.com> + + * interpreter/tips.txi: Change recommendation to use @tex rather than + @iftex construction. + 2009-05-17 Rik <rdrider0-list@yahoo.com> * interpreter/*.txi: Simplify TeXinfo files by eliminating redundant @iftex
--- a/doc/interpreter/tips.txi +++ b/doc/interpreter/tips.txi @@ -383,7 +383,7 @@ @example @group -*- texinfo -*- -@@deftypefn@{Function File@} @{@@var@{ret@} = @} fn (@dots{}) +@@deftypefn@{Function File@} @{@@var@{ret@} =@} fn (@dots{}) @@cindex index term Help text in Texinfo format. Code samples should be marked like @@code@{sample of code@} and variables should be marked @@ -407,7 +407,9 @@ @item @@cindex index term This generates an index entry, and can be useful when the function is included as part of a larger piece of documentation. It is ignored -within Octave's help viewer. +within Octave's help viewer. Only one index term may appear per line +but multiple @@cindex lines are valid if the function should be +filed under different terms. @item @@var@{variable@} All variables should be marked with this macro. The markup of variables is then changed appropriately for display. @@ -420,7 +422,7 @@ @end table Texinfo format has been designed to generate output for online viewing -with text-terminals as well as generating high-quality printed output. +with text terminals as well as generating high-quality printed output. To these ends, Texinfo has commands which control the diversion of parts of the document into a particular output processor. Three formats are of importance: info, html and @TeX{}. These are selected with @@ -436,18 +438,16 @@ @example @group @@ifhtml -Text area for html only +Text area for HTML only @@end ifhtml @end group @end example @example @group -@@iftex @@tex -text for TeX only +Text area for TeX only @@end tex -@@end iftex @end group @end example @@ -456,7 +456,20 @@ processor is chosen, by default, the text goes into all output processors. It is usual to have the above blocks in pairs to allow the same information to be conveyed in all output formats, but with a -different markup. +different markup. Currently, most Octave documentation only makes a +distinction between @TeX{} and all other formats. Therefore, the +following construct is seen repeatedly. + +@example +@group +@@tex +text for TeX only +@@end tex +@@ifnottex +text for info, HTML, plaintext +@@end ifnottex +@end group +@end example Another important feature of Texinfo that is often used in Octave help strings is the @code{@@example} environment. An example of its use is @@ -483,7 +496,9 @@ The @code{@@group} block prevents the example from being split across a page boundary, while the @code{@@result@{@}} macro produces a right -arrow signifying the result of a command. +arrow signifying the result of a command. If your example is larger than +20 lines it is better NOT to use grouping so that a reasonable page boundary +can be calculated. In many cases a function has multiple ways in which it can be called, and the @code{@@deftypefnx} macro can be used to give alternatives. For @@ -492,8 +507,8 @@ @example @group -*- texinfo -*- -@@deftypefn@{Function File@} @{@@var@{a@} = @} fn (@@var@{x@}, @dots{}) -@@deftypefnx@{Function File@} @{@@var@{a@} = @} fn (@@var@{y@}, @dots{}) +@@deftypefn@{Function File@} @{@@var@{a@} =@} fn (@@var@{x@}, @dots{}) +@@deftypefnx@{Function File@} @{@@var@{a@} =@} fn (@@var@{y@}, @dots{}) Help text in Texinfo format. @@end deftypefn @end group @@ -502,7 +517,7 @@ Many complete examples of Texinfo documentation can be taken from the help strings for the Octave functions themselves. A relatively complete example of which is the @code{nchoosek} function. The Texinfo -documentation string of @code{nchoosek} is +documentation string for @code{nchoosek} is @example -*- texinfo -*- @@ -512,14 +527,12 @@ @@var@{n@}. If @@var@{n@} is a scalar then, calculate the binomial coefficient of @@var@{n@} and @@var@{k@}, defined as -@@iftex @@tex $$ @{n \choose k@} = @{n (n-1) (n-2) \cdots (n-k+1) \over k!@} $$ @@end tex -@@end iftex -@@ifinfo +@@ifnottex @@example @@group @@ -530,13 +543,17 @@ \ / @@end group @@end example -@@end ifinfo +@@end ifnottex If @@var@{n@} is a vector, this generates all combinations of the elements of @@var@{n@}, taken @@var@{k@} at a time, one row per combination. The resulting @@var@{c@} has size @@code@{[nchoosek (length (@@var@{n@}),@@var@{k@}), @@var@{k@}]@}. +@@code@{nchoosek@} works only for non-negative integer arguments; use +@@code@{bincoeff@} for non-integer scalar arguments and for using vector +arguments to compute many coefficients at once. + @@seealso@{bincoeff@} @@end deftypefn @end example @@ -566,6 +583,10 @@ combination. The resulting C has size `[nchoosek (length (N), K), K]'. + `nchoosek' works only for non-negative integer + arguments; use `bincoeff' for non-integer scalar + arguments and for using vector arguments to compute + many coefficients at once. See also: bincoeff. @end group @@ -591,6 +612,10 @@ resulting @var{c} has size @code{[nchoosek (length (@var{n}), @var{k}), @var{k}]}. +@code{nchoosek} works only for non-negative integer arguments; use +@code{bincoeff} for non-integer scalar arguments and for using vector +arguments to compute many coefficients at once. + @seealso{bincoeff} @end deftypefn
--- a/scripts/specfun/nchoosek.m +++ b/scripts/specfun/nchoosek.m @@ -24,14 +24,12 @@ ## If @var{n} is a scalar then, calculate the binomial coefficient ## of @var{n} and @var{k}, defined as ## -## @iftex ## @tex ## $$ ## {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} ## = {n! \over k! (n-k)!} ## $$ ## @end tex -## @end iftex ## @ifnottex ## ## @example