RE: Docstring question

["John W. Eaton" <jwe at bevo dot che dot wisc dot edu>]

On  8-Dec-1999, Daschbach, John L <John.Daschbach@pnl.gov> wrote:

| Octave with guile scripting would be out of this world.

That's the reason I subscribed to this list.  Unfortunately, I've had
to give up on any use of guile in Octave, at least temporarily.

| The guile maintainers might want to look at the Octave manual and
| the built in documentation delivered by the interpretter.  Also the
| structure of the Matlab/Octave .m files with document extraction is
| really quite slick, although I think this only works with the
| internal interpretter documentation system, not texinfo.

I'm not sure what you mean by that.  In the current CVS sources (which
is the only version of Octave that uses the documentation extraction
method that I outlined in my previous post) .m files may include
Texinfo doc strings similar to what is used in the C++ sources.  There
is a separate doc string extraction script that works on .m files.  So
the documentation works about the same way for any function, whether
it is written in C++ or Octave's own extension language.

| 	Perhaps this is not really necessary.  Here is what I'm currently using
| 	in the Octave sources (interpreter code and manual).  In the
| 	interpreter sources, I declare functions like this:
| 
| 	  DEFUN (fprintf, args, ,
| 	    "-*- texinfo -*-\n\
| 	  @deftypefn {Built-in Function} {} fprintf (@var{fid}, @var{template},
| @dots{})\n\
| 	  This function is just like @code{printf}, except that the output is\n\
| 	  written to the stream @var{fid} instead of @code{stdout}.\n\
| 	  @end deftypefn")
| 	  {
| 	    ... function body stuff ...
| 	  }
| 
| This is quite good.  Two limitations are that long examples and the
| like would, IMHO, clutter the code a great deal.  For instance I
| recall there is a good example for using lsode in Octave.  Wouldn't
| this take a good deal of space in the C++ source file?

I think most extended examples are currently in the manual source itself
instead of embedded in the source code, but it doesn't matter much to
me where they go.  I just checked, and doc strings currently require
about 150k of space.  I don't think that is too much for a program as
large as Octave in 1999.  To me, it is much more important to only
have to maintain one set of doc strings (instead of one for the manual
and one for the on-line help) and to have the doc strings close to the
function definition.

If the size of the doc strings does get to be too much to carry around
in the executable, it would be easy to modify Octave to use a method
similar to GNU Emacs, which I believe doesn't actually include the
docstrings in the compiled code, but stores them in a separate file,
which can be easily searched at run time.

jwe

-- 
In the beginning, Ken Thompson | Octave: http://www.che.wisc.edu/octave
wrote the searching tool grep. |     Me: http://www.che.wisc.edu/~jwe
       -- A. Hume, SP&E (1988) |