octave-maintainers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Writing 'help' functions as m-files


From: Søren Hauberg
Subject: Re: Writing 'help' functions as m-files
Date: Tue, 10 Feb 2009 09:58:57 +0100

man, 09 02 2009 kl. 22:58 -0500, skrev John W. Eaton:
> OK, I looked at the current gen_doc_cache and I have a few comments

Thanks for taking the time to look into this. I apologize for not being
more active here.

>   * I noticed that
> 
>       gen_doc_cache (".")
> 
>     doesn't work because
> 
>       idx = find (p == pathsep ());
> 
>     returns an empty matrix if P has only one element.

See below.

>   * 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've changed this. I didn't do this at first, since I wasn't sure what
would happen if Octave was built without support for compression. Will
the call to 'save' fail, or will it simply skip the compression?

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

OK.

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

I agree. The only problem I see, is what if we distribute compressed
caches, and the user doesn't link to to 'zlib' (or whatever we use).

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

The attached changeset does this. The change also fixes the bug you
mentioned when doing 'gen_doc_cache (".")'.

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

I think your suggestion makes sense.

One thing to consider is where to put the cache for builtin stuff
(operators, keywords, ...). With the attached patch this is stored in
the file

  fullfile (octave_config_info.datadir, "DOC-builtin.gz");

(see 'lookfor.m' at line 58). Is that the right position/name?

Soren

Attachment: gen_doc_cache.changeset
Description: Text document


reply via email to

[Prev in Thread] Current Thread [Next in Thread]