Re: Writing 'help' functions as m-files

[John W. Eaton]

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

| tir, 27 01 2009 kl. 11:48 -0500, skrev John W. Eaton:
| > On 23-Jan-2009, Søren Hauberg wrote:
| > | > Is there more to do?  I remember some discussion about cache files and
| > | > needing to generate those when Octave is installed.  Am I remembering
| > | > correctly?  Can you do that, or explain what needs to be done?
| > | 
| > | Basically, we need to call 'gen_doc_cache ()' at some point. This
| > | function traverses the 'path ()' and generates a cache in each
| > | directory. A cache is just a simple '.mat' file that contains the help
| > | texts of the files in the directory. I am not sure when it is best to do
| > | this
| > | 
| > |   * when Octave is built, or
| > |   * when Octave is installed.
| > | 
| > | I'm guessing both will work. I'm guessing that the easiest solution is
| > | to run 'octave --eval gen_doc_cache ()' at the end of the installation.
| > 
| > I think it should be done at build time so that running Octave in
| > place will work.  Then the generated files can be installed.
| 
| First of all, sorry about the late reply...
| 
| So, I'd like to run 'gen_doc_cache' when Octave is built, which I guess
| boils down to
| 
|   ./run-octave --eval gen_doc_cache
| 
| But I fear this won't work. The 'gen_doc_cache' function simply
| traverses the current path and creates a cache for each directory in the
| path. The problem is that the path seems to be different when running
| './run-octave', than when running an installed octave. Specifically, in
| './run-octave' we have
| 
|   /home/sh/Dokumenter/octave/octave-hg/upstream/src
|   /home/sh/Dokumenter/octave/octave-hg/upstream/src/OPERATORS
|   /home/sh/Dokumenter/octave/octave-hg/upstream/src/TEMPLATE-INST
|   /home/sh/Dokumenter/octave/octave-hg/upstream/src/DLD-FUNCTIONS
|   /home/sh/Dokumenter/octave/octave-hg/upstream/src/pic
| 
| in the path, whereas in an installed Octave we have
| 
|   /home/sh/Programmer//libexec/octave/3.1.51+/site/oct/i686-pc-linux-gnu
|   /home/sh/Programmer//libexec/octave/site/oct/api-v33
| +/i686-pc-linux-gnu
|   /home/sh/Programmer//libexec/octave/site/oct/i686-pc-linux-gnu
|   /home/sh/Programmer//share/octave/3.1.51+/site/m
|   /home/sh/Programmer//share/octave/site/api-v33+/m
| 
| in the path. So, if I run 'gen_doc_cache' via './run-octave' the path
| I'll be traversing won't correspond to the path that's available when
| Octave is installed.
| 
| Any thoughts or comments?

OK, I looked at the current gen_doc_cache and I have a few comments

  * I noticed that

      gen_doc_cache (".")

    doesn't work because

      idx = find (p == pathsep ());

    returns an empty matrix if P has only one element.

  * Since all the data are character strings, using a binary format
    doesn't save much space.  Compression would help, so maybe using
    -text -z as options for save would be better than just using
    binary.

  * I think I'd prefer a simple name like DOC.gz in each directory
    instead of help_cache.mat.  Also, generally I think we try to
    prefer using - instead of _ for file names in Octave, unless they
    are .m files, which have to have names that are also valid
    symbol names in the scripting language.

  * Running the funtion takes some time, so I think it would be best
    to run it at build time.  It looks like most of the files will not
    need to change when Octave is built, so it probably also makes
    sense to distribute these files with the tar.gz files.

  * 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 propose making gen_doc_cache take two arguments.  The first argument
names the output file.  The second names the directory to work on.  If
only one argument is given, generate the DOC.gz file for for keywords,
operators, etc.

By doing that, it will be easy to write a rule for Make that will
create the DOC file if it is out of date compared to any of the
corresponding source files.

Write Makefile rules to generate a DOC.gz file in each subdirectory of
scripts the src directory.

Add the DOC.gz files to the list of files that we distribute.

Fix the install rules to install them.

Since it takes some time to run, make the function verbose, so that
there is some indication of progress.

Does this sound OK?  If you agree, I can do most of this work.

jwe