On Mon, 23 Nov 2009, Raymond Toy wrote:
< Leo Butler wrote:
< > I'd like to propose a modest addition to the source-code documentation.
< > It consists of the following bits:
< >
< > 1-a bash script that generates TAGS files for both src and share
< > mac and lisp files, extracting variables/functions/macros defined
< > using
< >
< Just curious. Now you have this huge TAGS file, what information can
< you get out of it? Based on your description, you just have a huge list
< of symbols without any kind of description.
The TAGS file centralizes the location information about all
variables/functions/macros used in the Maxima source. It's valuable for
the same reason a map is valuable. Of course, each of us can cobble
together a map of the code, through memory, clever grep searches, etc.
but it's a waste of time. I don't know if you use TAGS in your own code,
but I was surprised how much faster I could move between source files
when I needed to remind myself of a definition.
It is possible to alter the regexps so that the lisp docstrings are
included, where they exist, so documentation in the source code could
also be centralized (if there are concerns about docstrings bloating the
binary, then we can put in comments where the docstrings should be).
More importantly, the TAGS file needs to be used in conjunction with
some other tool to make it useful. Emacs has good support for it, so
that is one tool. Another tool would be to filter the information in the
TAGS file and auto-generate the 'maxima-font-lock.el' and
'builtins-list.txt' files. And another tool would be to auto-generate a
location lookup table that's accessible from within Maxima's online
help.
< And if you're really
< looking through the src lisp files and grabbing all symbols defined
< using def*, won't there be a huge number of symbols that are totally
< irrelevant to even developers?
Actually, the 'irrelevant' symbols are likely the most important ones to
be catalogued. I don't use a map to get to the grocery store, but I do
use a map when travelling to parts unknown.
<
< I'd rather have each share directory/package include it's own info file
< that we can parse and integrate into maxima's info. This is more work
< but, I think, far more beneficial for everyone since it can be focussed
< on the important aspects of the package without listing all of the
< internal stuff that most users and developers won't need. The info file
< would be a description of the package, not a list of every symbol used
< in the package.
I don't disagree with this, but you are counterposing apples and
oranges. Or, you are counterposing the book and its index.
Leo
--
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.