[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
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/04
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/04
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/09
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/10
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/10
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/10
- Re: Writing 'help' functions as m-files,
John W. Eaton <=
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/10
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/10
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/11
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/11
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/11
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/12
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/12
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/12
- Re: Writing 'help' functions as m-files, John W. Eaton, 2009/02/12
- Re: Writing 'help' functions as m-files, Søren Hauberg, 2009/02/12