Port of texinfo help string documentation from Coda

[David Bateman]

Attached you'll a patch for tips.txi that is liberally based on the
section of Coda for texinfo help strings, though it is completely
rewritten to include things like @seealso, @deftypefnx, etc and to use
Octave's internal functions as the examples.

Regards
David

-- 
David Bateman                                address@hidden
Motorola Labs - Paris                        +33 1 69 35 48 04 (Ph) 
Parc Les Algorithmes, Commune de St Aubin    +33 6 72 01 06 33 (Mob) 
91193 Gif-Sur-Yvette FRANCE                  +33 1 69 35 77 01 (Fax) 

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary

*** ./doc/interpreter/tips.txi.orig12   2007-04-25 11:59:33.800864916 +0200
--- ./doc/interpreter/tips.txi  2007-04-25 12:33:08.117908522 +0200
***************
*** 15,23 ****
  @menu
  * Style Tips::                  Writing clean and robust programs.
  * Coding Tips::                 Making code run faster.
- * Documentation Tips::          Writing readable documentation strings.
  * Comment Tips::                Conventions for writing comments.
  * Function Headers::            Standard headers for functions.
  @end menu
  
  @node Style Tips
--- 15,23 ----
  @menu
  * Style Tips::                  Writing clean and robust programs.
  * Coding Tips::                 Making code run faster.
  * Comment Tips::                Conventions for writing comments.
  * Function Headers::            Standard headers for functions.
+ * Documentation Tips::          Writing readable documentation strings.
  @end menu
  
  @node Style Tips
***************
*** 121,204 ****
  files.
  @end itemize
  
- @node Documentation Tips
- @section Tips for Documentation Strings
- 
- Here are some tips for the writing of documentation strings.
- 
- @itemize @bullet
- @item
- Every command, function, or variable intended for users to know about
- should have a documentation string.
- 
- @item
- An internal variable or subroutine of an Octave program might as well have
- a documentation string.
- 
- @item
- The first line of the documentation string should consist of one or two
- complete sentences that stand on their own as a summary.
- 
- The documentation string can have additional lines that expand on the
- details of how to use the function or variable.  The additional lines
- should also be made up of complete sentences.
- 
- @item
- For consistency, phrase the verb in the first sentence of a
- documentation string as an infinitive with ``to'' omitted.  For
- instance, use ``Return the frob of A and B.'' in preference to ``Returns
- the frob of A and address@hidden''  Usually it looks good to do likewise for 
the
- rest of the first paragraph.  Subsequent paragraphs usually look better
- if they have proper subjects.
- 
- @item
- Write documentation strings in the active voice, not the passive, and in
- the present tense, not the future.  For instance, use ``Return a list
- containing A and B.'' instead of ``A list containing A and B will be
- returned.''
- 
- @item
- Avoid using the word ``cause'' (or its equivalents) unnecessarily.
- Instead of, ``Cause Octave to display text in boldface,'' write just
- ``Display text in boldface.''
- 
- @item
- Do not start or end a documentation string with whitespace.
- 
- @item
- Format the documentation string so that it fits in an Emacs window on an
- 80-column screen.  It is a good idea for most lines to be no wider than
- 60 characters.
- 
- However, rather than simply filling the entire documentation string, you
- can make it much more readable by choosing line breaks with care.
- Use blank lines between topics if the documentation string is long.
-  
- @item
- @strong{Do not} indent subsequent lines of a documentation string so
- that the text is lined up in the source code with the text of the first
- line.  This looks nice in the source code, but looks bizarre when users
- view the documentation.  Remember that the indentation before the
- starting double-quote is not part of the string!
- 
- @item
- The documentation string for a variable that is a yes-or-no flag should
- start with words such as ``Nonzero address@hidden'', to make it clear that
- all nonzero values are equivalent and indicate explicitly what zero and
- nonzero mean.
- 
- @item
- When a function's documentation string mentions the value of an argument
- of the function, use the argument name in capital letters as if it were
- a name for that value.  Thus, the documentation string of the operator
- @code{/} refers to its second argument as @samp{DIVISOR}, because the
- actual argument name is @code{divisor}.
- 
- Also use all caps for meta-syntactic variables, such as when you show
- the decomposition of a list or vector into subunits, some of which may
- vary.
- @end itemize
- 
  @node Comment Tips
  @section Tips on Writing Comments
  
--- 121,126 ----
***************
*** 347,349 ****
--- 269,583 ----
  @samp{Keywords} header comment lines.  Use the others if they are
  appropriate.  You can also put in header lines with other header
  names---they have no standard meanings, so they can't do any harm.
+ 
+ @node Documentation Tips
+ @section Tips for Documentation Strings
+ 
+ As noted above, documentation is typically in a commented header block
+ on an Octave function following the copyright statement. The help string
+ shown above is an unformated stringed and will be displayed as is by
+ Octave. Here are some tips for the writing of documentation strings.
+ 
+ @itemize @bullet
+ @item
+ Every command, function, or variable intended for users to know about
+ should have a documentation string.
+ 
+ @item
+ An internal variable or subroutine of an Octave program might as well have
+ a documentation string.
+ 
+ @item
+ The first line of the documentation string should consist of one or two
+ complete sentences that stand on their own as a summary.
+ 
+ The documentation string can have additional lines that expand on the
+ details of how to use the function or variable.  The additional lines
+ should also be made up of complete sentences.
+ 
+ @item
+ For consistency, phrase the verb in the first sentence of a
+ documentation string as an infinitive with ``to'' omitted.  For
+ instance, use ``Return the frob of A and B.'' in preference to ``Returns
+ the frob of A and address@hidden''  Usually it looks good to do likewise for 
the
+ rest of the first paragraph.  Subsequent paragraphs usually look better
+ if they have proper subjects.
+ 
+ @item
+ Write documentation strings in the active voice, not the passive, and in
+ the present tense, not the future.  For instance, use ``Return a list
+ containing A and B.'' instead of ``A list containing A and B will be
+ returned.''
+ 
+ @item
+ Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+ Instead of, ``Cause Octave to display text in boldface,'' write just
+ ``Display text in boldface.''
+ 
+ @item
+ Do not start or end a documentation string with whitespace.
+ 
+ @item
+ Format the documentation string so that it fits in an Emacs window on an
+ 80-column screen.  It is a good idea for most lines to be no wider than
+ 60 characters.
+ 
+ However, rather than simply filling the entire documentation string, you
+ can make it much more readable by choosing line breaks with care.
+ Use blank lines between topics if the documentation string is long.
+  
+ @item
+ @strong{Do not} indent subsequent lines of a documentation string so
+ that the text is lined up in the source code with the text of the first
+ line.  This looks nice in the source code, but looks bizarre when users
+ view the documentation.  Remember that the indentation before the
+ starting double-quote is not part of the string!
+ 
+ @item
+ The documentation string for a variable that is a yes-or-no flag should
+ start with words such as ``Nonzero address@hidden'', to make it clear that
+ all nonzero values are equivalent and indicate explicitly what zero and
+ nonzero mean.
+ 
+ @item
+ When a function's documentation string mentions the value of an argument
+ of the function, use the argument name in capital letters as if it were
+ a name for that value.  Thus, the documentation string of the operator
+ @code{/} refers to its second argument as @samp{DIVISOR}, because the
+ actual argument name is @code{divisor}.
+ 
+ Also use all caps for meta-syntactic variables, such as when you show
+ the decomposition of a list or vector into subunits, some of which may
+ vary.
+ @end itemize
+ 
+ Octave also allows extensive formatting of the help string of functions
+ using Texinfo.  The effect on the online documentation is relatively
+ small, but makes the help string of functions conform to the help of
+ Octave's own functions.  However, the effect on the appearance of printed
+ or online documentation will be greatly improved.
+ 
+ The fundamental building block of Texinfo documentation strings is the
+ Texinfo-macro @code{@@deftypefn}, which takes three arguments: The class
+ the function is in, its output arguments, and the function's
+ signature.  Typical classes for functions include @code{Function File}
+ for standard Octave functions, and @code{Loadable Function} for
+ dynamically linked functions.  A skeletal Texinfo documentation string
+ therefore looks like this
+ 
+ @example
+ @group
+ -*- texinfo -*-
+ @@address@hidden address@hidden @{@@address@hidden@} = @} function_name 
(@dots{})
+ @@cindex index term
+ Help text in Texinfo format.  Code samples should be marked like
+ @@address@hidden of address@hidden and variables should be marked as
+ @@address@hidden@}.
+ @@address@hidden@}
+ @@end deftypefn
+ @end group
+ @end example
+ 
+ This help string must be commented in user functions, or in the help
+ string of the @code{DEFUN_DLD} macro for dynamically loadable
+ functions.  The important aspects of the documentation string are
+ 
+ @table @asis
+ @item -*- texinfo -*-
+ This string signals Octave that the follow text is in Texinfo format,
+ and should be the first part of any help string in Texinfo format.
+ @item @@address@hidden@} @dots{} @@end deftypefn
+ The entire help string should be enclosed within the block defined by
+ deftypefn.
+ @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.
+ @item @@address@hidden@}
+ All variables should be marked with this macro.  The markup of variables
+ is then changed appropriately for display.
+ @item @@address@hidden of address@hidden
+ All samples of code should be marked with this macro for the same
+ reasons as the @@var macro.
+ @item @@address@hidden@}
+ This is a comma separated list of function names that allows cross
+ referencing from one function documentation string to another.
+ @end table
+ 
+ Texinfo format has been designed to generate output for online viewing
+ 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
+ 
+ @example
+ @group
+ @@ifinfo
+ Text area for info only
+ @@end ifinfo
+ @end group
+ @end example
+ 
+ @example
+ @group
+ @@ifhtml
+ Text area for html only
+ @@end ifhtml
+ @end group
+ @end example
+ 
+ @example
+ @group
+ @@iftex
+ @@tex
+ text for TeX only
+ @@end tex
+ @@end iftex
+ @end group
+ @end example
+ 
+ Note that often TeX output can be used in html documents and so often
+ the @code{@@ifhtml} blocks are unnecessary. If no specific output
+ 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.
+ 
+ Another important feature of Texinfo that is often used in Octave help
+ strings is the @code{@@example} environment. An example of its use is
+ 
+ @example
+ @group
+ @@example
+ @@group
+ @@address@hidden * address@hidden
+ @@address@hidden@} 4
+ @@end group
+ @@end example
+ @end group
+ @end example
+ 
+ which produces
+ 
+ @example
+ @group
+ @code{2 * 2}
+ @result{} 4
+ @end group
+ @end example
+ 
+ The @code{@@group} block prevents the example from being split across a
+ page boundary, while the @code{@@address@hidden@}} macro produces a right
+ arrow signifying the result of a command. 
+ 
+ In many cases a function has multiple means in which it can be called,
+ and the @code{@@deftypefnx} macro can be used to give alternatives. For
+ example
+ 
+ @example
+ @group
+ -*- texinfo -*-
+ @@address@hidden address@hidden @{@@address@hidden@} = @} function_name 
(@@address@hidden@}, @dots{})
+ @@address@hidden address@hidden @{@@address@hidden@} = @} function_name 
(@@address@hidden@}, @dots{})
+ Help text in Texinfo format.
+ @@end deftypefn
+ @end group
+ @end example
+ 
+ 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
+ 
+ @example
+ @group
+ -*- texinfo -*-
+ @@deftypefn @{Function address@hidden @{@@address@hidden@} address@hidden 
nchoosek (@@address@hidden@}, @@address@hidden@})
+ 
+ Compute the binomial coefficient or all combinations of @@address@hidden@}.
+ If @@address@hidden@} is a scalar then, calculate the binomial coefficient
+ of @@address@hidden@} and @@address@hidden@}, defined as
+ 
+ @@iftex
+ @@tex
+ $$
+  @{n \choose address@hidden = @{n (n-1) (n-2) \cdots (n-k+1) \over 
address@hidden
+ $$
+ @@end tex
+ @@end iftex
+ @@ifinfo
+ 
+ @@example
+ @@group
+  /   \
+  | n |    n (n-1) (n-2) ... (n-k+1)
+  |   |  = -------------------------
+  | k |               k!
+  \   /
+ @@end group
+ @@end example
+ @@end ifinfo
+ 
+ If @@address@hidden@} is a vector generate all combinations of the elements
+ of @@address@hidden@}, taken @@address@hidden@} at a time, one row per 
combination. The 
+ resulting @@address@hidden@} has size @@address@hidden (length 
(@@address@hidden@}), 
+ @@address@hidden@}), @@address@hidden@address@hidden
+ 
+ @@address@hidden@}
+ @@end deftypefn
+ @end group
+ @end example
+ 
+ which demonstrates most of the concepts discussed above.
+ @iftex
+ This documentation string renders as
+ 
+ @c Note actually use the output of info below rather than try and 
+ @c reproduce it here to prevent it looking different than how it would
+ @c appear with info.
+ @example
+ @group
+  -- Function File: C = nchoosek (N, K)
+      Compute the binomial coefficient or all combinations of N.  If N
+      is a scalar then, calculate the binomial coefficient of N and K,
+      defined as
+ 
+            /   \
+            | n |    n (n-1) (n-2) ... (n-k+1)
+            |   |  = -------------------------
+            | k |               k!
+            \   /
+ 
+      If N is a vector generate all combinations of the elements of N,
+      taken K at a time, one row per combination. The resulting C has
+      size `[nchoosek (length (N), K), K]'.
+ 
+ 
+      See also: bincoeff.
+ @end group
+ @end example
+ 
+ using info, whereas in a printed documentation using TeX it will appear
+ as
+ 
+ @deftypefn {Function File} address@hidden =} nchoosek (@var{n}, @var{k})
+ 
+ Compute the binomial coeeficient or all combinations of @var{n}.
+ If @var{n} is a scalar then, calculate the binomial coefficient
+ of @var{n} and @var{k}, defined as
+ 
+ @tex
+ $$
+  {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
+ $$
+ @end tex
+ 
+ If @var{n} is a vector generate 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}]}.
+ 
+ @seealso{bincoeff}
+ @end deftypefn
+ 
+ @end iftex