Re: Documentation

[Michael Livshin]

Neil Jerram <address@hidden> writes:

>     moi> the intention is to document a binding, right?  so the
>     moi> above will document the binding in the current module
>     moi> named by 'case-fold-search, and not the symbol
>     moi> 'case-fold-search?
> 
> Good point - I have no idea whether/how this would work.

do you mean how this would work with the current module system or how
this would work in general?  because in general (i.e. theoretically),
I don't see any problem.

>     moi> here's a mini-proposal:
> 
>     moi> what do we really want when we say "documentation for
>     moi> module foo"?  I think we really are saying "documentation
>     moi> for all the bindings of module foo".
> 
>     moi> so the natural (well, probably not, as it occured to me
>     moi> only now) thought is: let's use the module system.
> 
>     moi> (define (snarf-docs module-name) (let ((module
>     moi> (resolve-module module-name))) (for-each-exported-binding
>     moi> (lambda (b) (filter-docs b)) module)))
> 
> This is the main thing that I don't get.  Could you explain a little
> more?  Who and when would call `snarf-docs',

I think it would be prudent to explain my motivation at this point.

one feature I like very much about the Lisp family of languages[1] is
the syntactic flexibility.  which means that you can't really know a
lot about code if you only look at its printed representation
(i.e. the source file).  which means that specifying tools which are
external to the system proper whose purpose is to analyze printed
representation of Lisp/Scheme code is, at best, kludgy.  it would only
work through convention.  having tools that work only through
convention is probably acceptable in practice, but I'd rather avoid
that if it's possible.  and I happen to think it _is_ possible.

problem is, I don't really know any more whether you agree with this
or not.  I _assumed_ you don't agree, thus I wrote up the above sloppy
mini-proposal, so that you would see that if documentation information
isn't lost when code is loaded, then there's no need at all to _guess_
things about printed representation of said code -- we could just
interrogate the module system and find things out for sure.

so perhaps the mini-proposal might have not been called for.  in that
case, sorry.  I hope that's clearer now.

> and what would `filter-docs' do in this proposal?

that's a good question.  I suspect I didn't understand the purpose of
`filter-docs' properly.


Footnotes: 
[1]  folks over at comp.lang.lisp argue that Scheme is not Lisp, but
     the current Guile is certainly lispier than many Schemes out
     there, and definitely lispier than the language specified by
     R5RS.  please don't ask me to explain. ;)

-- 
This program posts news to billions of machines throughout the galaxy.  Your
message will cost the net enough to bankrupt your entire planet.  As a result
your species will be sold into slavery.  Be sure you know what you are doing.
Are you absolutely sure you want to do this? [yn] y