Re: Writing 'help' functions as m-files

[John W. Eaton]

I have no objection to writing the help functions as .m files.

I'd like to consider the following change as well.

The DEFUN macro in Octave is patterned after the one used in Emacs.
Originally, Emacs also had the doc string as an argument to the
macro.  The Emacs build procss extracted the doc strings and placed
them in a separate file that was indexed for quick lookup.  This also
avoided storing relatively large amounts of infrequently used data in
the Emacs binary itself (I know it may be hard to believe that there
was a concern for space efficiency, in Emacs, but there it is!).  More
recently, the Emacs sources have been changed to look like this:

  DEFUN ("setq", Fsetq, Ssetq, 0, UNEVALLED, 0,
         doc: /* Set each SYM to the value of its VAL.
  The symbols SYM are variables; they are literal (not evaluated).
  The values VAL are expressions; they are evaluated.
  Thus, (setq x (1+ y)) sets `x' to the value of `(1+ y)'.
  The second VAL is not computed until after the first SYM is set, and so on;
  each VAL can use the new value of variables set earlier in the `setq'.
  The return value of the `setq' form is the value of the last VAL.
  usage: (setq [SYM VAL]...)  */)
       (args)
       Lisp_Object args;
  {

so that the doc string is just a comment.  It is still extracted by the
build process and stored in a separate file that is indexed for quick
lookup.  Having the doc string as a comment has several advantages. It
would no longer be necessary to insert \n\ or other
quoted characters.  Since there would be no C character escapes, we
wouldn't need to use the mkgendoc script to generate the C++ program
that we compile to strip them out.  And we would also avoid any
character string length limits imposed by a C++ compiler (though that
may be rare these days).  The only disadvantage I can see (other than 
the work needed for the implementation) is that inserting "*/" in a
doc string would require special treatment, but I don't think we need
that.

Should we make a change Like this?

Should the doc strings for the built-in functions be placed in a
single indexed file?

Should the doc strings for functions defined in .oct files be
installed in individual .m files alongside the .oct files?

Additionally, the list of items for 3.1 includes "handle block
comments" (for the scripting language).  Given that, we could also
write doc strings in .m files using

#{
-*- texinfo -*-
@deftypefn {Function File} address@hidden =} convn (@var{a}, @var{b}, 
@var{shape})
@math{N}-dimensional convolution of matrices @var{a} and @var{b}.

The size of the output is determined by the @var{shape} argument.
This can be any of the following character strings:

@table @asis
@item "full"
The full convolution result is returned. The size out of the output is
@code{size (@var{a}) + size (@var{b})-1}. This is the default behaviour.
@item "same"
The central part of the convolution result is returned. The size out of the
output is the same as @var{a}.
@item "valid"
The valid part of the convolution is returned. The size of the result is
@code{max (size (@var{a}) - size (@var{b})+1, 0)}.
@end table

@seealso{conv, conv2}
@end deftypefn
#}

and avoid the need for prefixing every line with "##".  Would that be
helpful when writing the doc strings?  I suppose that with a decent
editor it is easy enough to strip the comment characters out, edit the
doc string, and then replace the comment characters, but using block
comments would still simplify the process.

jwe