RE: Docstring question

["Daschbach, John L" <John dot Daschbach at pnl dot gov>]

	JWE>
	Thanks!  :-)  The Octave manual owes a lot to the organization of the
	Emacs Lisp manual, as well as the Gawk and Emacs manuals.  I think
	I've seen RMS write that a good manual must be more than just a
	laundry list of functions.  I tried hard to follow that advice by
	writing a description of a topic with reference-manual information
	mixed in.  I think I've partially succeeded, but there is still much
	work to be done.

Good to see you here!  (an Octave with guile scripting would be out of this
world.  My Octave is always a bit kludgy when I have to do things it wasn't
designed to do, like massaging input data etc..  The work around is usually to
have Octave call some Perl scripts which works pretty well.)

(editorial:  Octave, GNU Emacs, gcc, and Perl, are the open source tools I
depend on for most of what I do.  All are excellent.  I'd like to add guile to
this list, replacing some uses of Perl and gcc, but I'm not quite there.  A
great deal of the reason is documentation, or lack there of.)

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.

	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?  


	To manage the insertion of the doc strings in the manual, I have
	things like this in the ultimate manual sources:

	  @node Formatted Output
	  @subsection Formatted Output


	  This section describes how to call @code{printf} and related
functions.

	  The following functions are available for formatted output.  They are
	  modelled after the C language functions of the same name, but they
	  interpret the format template differently in order to improve the
	  performance of printing vector and matrix values.

	  @DOCSTRING(printf)

Yes, this is what I had in mind, markers in the texinfo source where extracted
information is inserted.  In a very slick system it would be possible to say
something like 
@DOCCLASS(socket)
and have all the functions declared with the class socket to be documented in
alpha order at this point.  As manual writing progressed, these would be
replaced with explicit references in a hand organized system like the one you
describe. 
	  

	-- 
	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) |