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: John W. Eaton
Subject: Re: Writing 'help' functions as m-files
Date: Tue, 10 Feb 2009 17:16:58 -0500

On 10-Feb-2009, Søren 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?

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

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

| We should still support caches in individual
| directories as that would be useful for packages.

Yes.

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.

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

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

Thanks,

jwe



reply via email to

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