Re: Writing 'help' functions as m-files

[John W. Eaton]

On 10-Feb-2009, Søren Hauberg wrote:

| tir, 10 02 2009 kl. 17:16 -0500, skrev John W. Eaton:
|
| > start makeinfo for each docstring, but instead processed them all at
| > once, then split them up again.  I'll try to make that work and see if
| > it helps.
| 
| Yeah, I think that would probably speed up building. It's fairly easy to
| just insert
| 
|   #########################
| 
| between individual functions, and then split things apart after running
| makeinfo.

The DOCSTRINGS files already use ascii 31 for this, and it passes
through makeinfo fine, so I just used that.

My latest version is checked in.  It

  reads the contents of all the DOCSTRINGS files into memory

  replaces @seealso{fcn-list} with "See also: fcn-list."

  strips the "-*- texinfo -*-" tags

  runs makeinfo on the result (using system, not the Octave makeinfo
  function, since the extra processing of that function is not needed
  now)

  finds the separator characters in the output from makeinfo to work
  on each docstring

  splits the function name and doc string (the function name appears
  just after the separator character, same as in the DOCSTRINGS files)

  finds the first sentence, stripping extra spaces and newline characters

  stores the symbol name, docstring, and first sentence in a cell
  array

  saves the cell array

I parsed the output by noting that each formatted docstring should
begin with

 " -- Function File: ..."

or similar. The key is that the " -- " at the beginning of a line
should only appear as the tag of a header like this, so I just look
for the end of the last line containing one of those, and assume the
first sentence begins just after that.

| > | We would
| > | need a function to determine if a given function was part of Octave, or
| > | somehow provided by the user.
| > 
| > Why?  Is the DOC file used for anything other than lookfor?
| 
| 'lookfor' should also search files that aren't cached. So you would need
| some way of determining if we should search all functions in a given
| directory.

OK.

| > Some other thoughts:
| > 
| >   * The name of the makeinfo function might lead to some confusion
| >     since it doesn't run makeinfo, but performs a specialized task
| >     just for the help functions in Octave.  It might be better to
| >     rename it to __makeinfo__.m  and consider it an internal
| >     function.
| 
| Well, it does run the makeinfo program... But you're right that it does
| more than this. I don't mind renaming it, but I don't think it should be
| a "hidden" function (or whatever we call functions that begin with
| "__"). I use the function quite a bit for generating web pages for
| Octave-Forge, so I'd at least appreciate if its API was fairly stable. 

I don't think the API would change much. It's just that it seems to me
that it is the wrong name for such a specialized function, and I don't
think very many users will need it.

| >   * It looks like your gen_doc_cache function is running makeinfo
| >     twice.  First to generate the formatted help text, then again from
| >     the get_first_help_sentence function.  I think it would be better
| >     to simply pass the formatted help tect to
| >     get_first_help_sentence.  Maybe that should also be an internal
| >     function.
| 
| The problem is that it is not trivial to extract the first sentence. If
| you run 'makeinfo' on the entire help message you get something like
| 
|    -- Function File: [RETVAL, STATUS] = makeinfo (TEXT, OUTPUT_TYPE)
|    -- Function File: [RETVAL, STATUS] = makeinfo (TEXT, OUTPUT_TYPE,
|             SEE_ALSO)
|        Run `makeinfo' on a given text.
| 
| which you then have to parse. The old code in 'lookfor' did this, and it
| was very complicated, yet I don't think it handled all corner-cases.

See above.  Does it really need to be complicated?

Next, I'll try to fix the Makefile to install the DOC file somewhere.

jwe