help as m-files

[John W. Eaton]

On 29-Oct-2008, Søren Hauberg wrote:

| Hi All,
|   Attached is a fairly large changeset (hence the need for compressing
| it) that re-implements the help system as m-files. This is pretty much a
| fresh implementation, so there will be bugs (although I've removed those
| I've been able to find). So, why would we want to re-implement this as
| m-files, when we have something that's already functional?
| 
|   * It simplifies the code quite a bit, which should make it easier for
|     new people to hack on. Especially, the 'lookfor' implementation is
|     a lot more simple.
| 
|   * It provides some new functionality to Octave. Specifically, it is
|     now quite easy to get the help text of a function, and run it
|     through 'makeinfo'. This makes it fairly simple to generate html
|     versions of the help texts.
| 
|   * 'lookfor' is now very fast. The new implementation of 'lookfor' can
|     use cached help texts, which makes it very fast. For me, a call to
|     'lookfor' usually takes less than a second (compared ~1 minute
|     before).
| 
| The patch is, however, not entirely complete. To generate caches for
| 'lookfor', you need to run the 'gen_doc_cache' function. Basically,
| 'gen_doc_cache' traverses the current path, and creates a cache file in
| each directory. This should either happen during 'make' or 'make
| install'. I'm not sure which is better, so I'd appreciate some help
| here. Also, this should happen during 'pkg install' such that the user
| can search package help texts fast.

OK, I'm generally in favor of this change as I'd like to see more
things implemented in .m files if possible.

Is lookfor faster only because of the switch to using a cache?  If
there is no cache, is it still slow?

Could we just check to ensure that the cache is up to date when adding
directories to the load path?  I'm assuming you could do this by
comparing the mtime of the cache file with the mtimes of .m files in the
directory.  I think we already call stat on every file in each load
path directory when we add the directory to the load path, so this
additional check should not add much to Octave's startup time.

Then later, when running lookfor, would you also want to ensure that the
cache files are up to date, or would you just assume that they are?
It seems it would be best to check timestamps, but that could slow
things down again

| I also have the following on my outstanding-issues-list:
| 
|   * Perhaps move internal variables (eg 'makeinfo_program') to m-files?

Yes, I think that would be good to do.

|   * how should 'private' directories be treated in Makefiles ?

I'm not sure, but we do need to do something for this since there are
other places where we could use private functions.

|   * Fix XXX's in code (nothing major).

Please use FIXME instead of XXX as people have complained in the past
about patches/mail with XXX being flagged as spam.

jwe