Re: Writing 'help' functions as m-files

[Søren Hauberg]

tir, 10 02 2009 kl. 17:16 -0500, skrev John W. Eaton:
> On 10-Feb-2009, Soren Hauberg wrote:
> 
> | Yeah, that is better. Something similar is also needed for 'help.m',
> | when handling 'Contents.m' files.
> 
> Since the contents.m files are supposed to just contain comments with
> the help text, shouldn't we just be able to easily grab the docstring
> from that file without having to parse it like a function or script?

Yeah, I guess that makes sense.

> | This sounds like a good idea to me. Just one comment, though: would it
> | be better to only have one cache instead of one per directory?
> 
> Sure, we can do that.  I was thinking that by splitting up the
> DOCSTRINGS files we could make rebuilding Octave a little faster if
> just one .m file changed.  But splitting them up also introduces some
> other complications, so for now I think it would be OK to leave the
> DOCSTRINGS creation as it is now, and then generate a single DOC
> from the src/DOCSTRINGS and scripts/DOCSTRINGS files.
> 
> OK, I thought about this some more and checked in the following
> changeset:
> 
>   http://hg.savannah.gnu.org/hgweb/octave/rev/80910b37d855
> 
> I decided to just go with an uncompressed text file for
> now.  It is less than 1MB.  It takes about 2 minutes to generate the
> DOC file from the src/DOCSTRINGS and scripts/DOCSTRINGS file on my
> system (~2GHz AMD64).  Maybe it would be faster if we didn't have to
> 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.

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

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

>   * 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.
What the current code does is to first remove all lines from the texinfo
code that begins with '@def', since that removes '@deftypefn',
'@defvar', etc., and then run 'makeinfo' on the text, which gives you
something that is quite simple to parse. The downside is that you have
to call 'makeinfo' twice, but the resulting code is much much more
simple, and in general seems to work better. So, I wouldn't change this,
unless you can come up with some clever trick.

>   * I noticed that help function now prints a list of all functions
>     together instead of grouping them by directory.  Is that
>     intentional?  I thought the previous output format was more
>     helpful.  What do others think?

Hmm, I thought I actually fixed that, but apparently I didn't.
Personally, I would actually prefer neither of the two options. I think
just typing 'help' provides waay too much output. I think it would be
better to simply print something like (very much written off the top of
my head):

  This is the GNU Octave prompt.

  To run a script saved in the file 'myscript.m', type

    myscript

  and press ENTER.

  To get help with individual commands and functions type

    help name

  where you should replace 'name' with the name of the command or
  function you would like to learn more about.

  For a more detailed introduction to GNU Octave, please consult the
  manual. To read this from the prompt type

    doc

  Enjoy GNU Octave! If you have questions, feel free to join the GNU
  Octave community. See http://www.octave.org for details.

Or something like that.

Soren