Re: Writing 'help' functions as m-files

[Søren Hauberg]

tir, 10 02 2009 kl. 11:34 -0500, skrev John W. Eaton:
> | >   * What is the slow part?  Running makeinfo?  If so, then I don't see
> | >     much we can do about that.  Or is it extracting the first sentence
> | >     of the doc string?
> | 
> | I haven't done any profiling, but I'm guessing it's the many calls to
> | 'makeinfo'. The algorithm for generating caches are in many ways similar
> | to the 'lookfor' code. When I moved 'lookfor' from C++ to an m-file, I
> | didn't really see any significant speed changes, so from that I
> | concluded (a bit hasty) that the slow part was 'makeinfo'.
> 
> I suspect there is also some time spent parsing the files to extract
> the docstrings.  Instead of just looking for the docstrings, your
> function is parsing them.

Yeah, I guess that adds some more work.

> Also, we are currently finding the functions in the path, and doing
> 
>   if (!dir_in_path)
>     addpath (directory);
>   endif
> 
>   ...
> 
>   if (!dir_in_path)
>     rmpath (directory);
>   endif
> 
> which has some problems.  First, there's no unwind_protect here, so
> you can end up modifying the global path if this function is
> interrupted.  Second, the current directory is still searched before
> the added path, so you could end up witn the wrong docstring in the
> DOC.gz file.  I think it would be better to temporarily cd to the
> directory, do the work, then cd back (using unwind_protect to ensure
> the change is temporary).

Yeah, that is better. Something similar is also needed for 'help.m',
when handling 'Contents.m' files.

> It occurred to me that in the process of building Octave, we already
> generate DOCSTRING files that contain the raw Texinfo docstrings.  I
> think we should be taking advantage of that.  The new function could
> still be useful for generating a DOC.gz file later, but I'm not sure
> it is the best thing to use during the build process.
> 
> How about making the following changes to the build process:
> 
>   * generate a DOCSTRINGS file for each directory in the source tree
>     that contains .m files or C++ files with DEFUNs.  We'll read these
>     files to generate the .texi files for the manual, same as we do
>     now for the two DOCSTRINGS files that we currently generate.  I
>     can do this part.
> 
>   * use the DOCSTRINGS files to generate the DOC.gz files.  It should
>     be much faster to read the DOCSTRINGS files than it is to parse
>     all the .m files in Octave.  We need to pass each docstring in a
>     DOCSTRINGS file through makeinfo and then extract the first
>     sentence.

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? We would
need a function to determine if a given function was part of Octave, or
somehow provided by the user. I guess this would make 'lookfor' even
faster as it then doesn't have to traverse all directories that comes
with Octave, to search a bunch of caches. It also might make cache
generation more simple. We should still support caches in individual
directories as that would be useful for packages.

Soren