Octave Function Reference Manual?

[John W. Eaton]

On 19-Jan-2007, David Bateman wrote:

| One thing I don't like about the current octave manual is that I don't
| believe that it is in fact a manual but rather a collection of the help
| strings and in many ways is closer to a reference manual.

It was never intended to be just a collection of docstrings, but it
has unfortunately evolved that way.

| So why not
| have a real reference manual and rewrite the manual itself to go beyond
| the scope of what the reference manual itself gives.
| 
| We have most of the tools to do this automatically already in
| octave-forge in the form of the admin/make_index script and the
| main/INDEX file. Taking the make_index script as a starting point I
| wrote the attached script.. This, together with the patch for the
| texinfo syntax errors in octave I just sent (
| https://www.cae.wisc.edu/pipermail/bug-octave/2007-January/001488.html),
| can be used to automatically create a texinfo reference manual for
| octave. The INDEX file probably needs a little work and the reference
| manual could be reformatted a bit, but the basic idea is there. To use
| this script do something like
| 
| cd octave
| ../make_funref ../octave-forge/main/INDEX funref.texi
| texi2dvi funref.texi
| dvipdf funref.dvi
| 
| after having applied the above patch and rebuilt octave. If you what to
| see what the resulting pdf file looks like check
| 
| http://www.dbateman.org/octave/funref.pdf
| 
| What are your thoughts on the idea of splitting the manual into a
| function reference manual and real manual?

I don't object to having a separate reference manual if people find
that useful.

My preference would be to omit all internal and deprecated/obsolete
functions from the list.

Also, I think the perl script could probably be simplified
considerably.  We already have tools to generate Texinfo source files
from the DOCSTRING files and input files that look like this:

  @DOCSTRING(all)

  @DOCSTRING(any)

  ...

so it seems that it would be simpler to reuse that script and just
have yours emit @DOCSTRING(name) lines (have your script generate a
.txi file and add a few dependencies and rules in
doc/interpreter/Makefile.in, and I think you are done).

For proper formatting, we should be parsing the Texinfo to extract the
parts we need instead of running makeinfo.  I think your lookfor
function already does something close to what is needed to generate
the brief description for the categorical list.  To really make this
work well, we will either need to enforce some discipline for writing
the first line of any docstring, or we will need to introduce another
(perhaps optional) command in the docstring like @synopsis{...} that
could be used for this purpose.  We might also consider an optional
@category{} command that could be used when automatic determination of
the category fails.

jwe