Leo Butler wrote:
> 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.
>
Ok, the TAGS file itself is fine. (I stopped using TAGS long ago,
because it was never up-to-date for any sources I used. With Lisp, I
usually use describe with cmucl to tell me where the source file is. Of
course that doesn't work for Maxima sources.) Also, I find my self
grepping more often for error messages than for function/variable names.
I guess it useful it needs to be built each time I build maxima so it's
up-to-date.
> 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.
>
>
I can see the utility of using ? to find such symbol, but my expectation
is that there is some useful documentation on what the symbol is. And
it might increase the number of false positives to wade through.
So, for me, TAGS is good. TAGS in describe is bad.
Ray