Re: Scheme file docstring format

[Neil Jerram]

>>>>> "thi" == thi  <address@hidden> writes:

    thi> this is reasonable.  then, the requirement becomes: docstring
    thi> snarfing should preserve export status of the definition (so
    thi> that presentation filters can do their job).

I don't follow your point here (and the subsequent details) at all,
I'm afraid.

The way I see it, identifier visibility, as managed by the module
system to resolve references in code, automatically determines the
visibility of the corresponding docstring.

So, `(help acons)' displays the docstring for the object that is the
evaluation of `acons' in the current environment, and `(help "acons")'
displays docstrings for all visible identifiers in the current
environment whose names match the regexp "acons".

`help' (and similarly `apropos') already do lookups like this.  I
don't see the need for anything clever at the snarfing stage.

    thi> if docstrings are stored/accessed using the same mechanisms
    thi> to resolve module references, maybe the `define-module' form
    thi> and the value of applying `module-public-interface' should be
    thi> considered food for the snarfer as well.  (an
    thi> interface-oriented snarfer would be immediately useful for
    thi> GUMM [he says selfishly].... :-)

I really don't understand; I'd like to, though, especially as you say
it would be useful for GUMM.  Please explain in more detail.

    thi> most useful would be some flexibility in what constitutes
    thi> snarfable input.  certainly we can mandate files distributed
    thi> w/ guile to have a certain format, but it would be nice to be
    thi> able to snarf other formats which may be regular in their own
    thi> way albeit not strictly conforming.  the nice hack would be
    thi> to heuristically determine which snarfing method to use given
    thi> a large-enough set of never-before-seen modules...  anyway,
    thi> for an indexing framework implementation, check out imenu.el
    thi> in your local emacs installation.

Ditto.

Best regards,

        Neil