From octave-maintainers-request at bevo dot che dot wisc dot edu  Wed Oct 20 03:08:08 1999
Subject: Texinfo doc strings for Octave
From: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
To: octave-maintainers at bevo dot che dot wisc dot edu
Date: Wed, 20 Oct 1999 03:07:09 -0500

I've never been happy with the way that the on-line help was handled
in Octave.  Until now, there were two places for functions to be
documented.  One was in the source file itself, and the other was in
the Texinfo source for the manual.  Having the information in two
places meant that there were usually differences between the two
versions, and that it was less likely for the manual source to be
updated if the code changed.

For 2.1.18, I've tried to address that problem by allowing Texinfo
doc strings in the source files (.m and .cc) and to use those doc
strings to create the manual source files.  Texinfo doc strings must
begin with the special string `-*- texinfo -*-'.

For on-line display of the help text, if the doc string begins with
`-*- texinfo -*-', Octave's help command will pass it through makeinfo
before displaying it, so it will be neatly formatted.

To insert the doc strings in the manual, there are some new programs
and scripts that look through all the .m and .cc files and extract doc
strings.  Then another script processes the Texinfo source for the
manual, replacing any

   at DOCSTRING(function_name)

commands with the doc string for the named function.

This new method of documenting functions has the obvious advantage of
storing the information in only one place, close to the function
definition, where it can easily be updated if the code for the
function changes.  It also has the advantage of allowing Octave to
present more uniformly formatted help messages to the user.

I've already converted the system.texi file to use the new method.  It
took a little time, but was not too difficult.  I see no way to
automate the process, because differences in the doc strings and the
manual source need to be reconciled.  So, would anyone like to help
convert the other files?  If you are interested, please let me know so
I can coordinate the effort and we don't end up duplicating each
other's work.  I can also send you some information about exactly what
needs to be done.

Thanks,

jwe