Re: Documentation

[Neil Jerram]

>>>>> "Michael" == Michael Livshin <address@hidden> writes:

    Michael> Neil Jerram <address@hidden> writes:
    >> I mean that I don't immediately see how one can make the
    >> distinction between applying to a symbol and applying to a
    >> particular binding.  With the current module system and with
    >> Scheme in general.  But I'm probably just missing something -
    >> am I?

    Michael> well, it always may be me.  I thought you meant that
    Michael> sometimes it is desirable to document a "name", so to
    Michael> speak.  so you say something like "one of the exports of
    Michael> the module (foo) is bar.  it's supposed to be bound to a
    Michael> list of widgets".  you, thus, document the exported
    Michael> binding whose name is `bar' and which is exported by the
    Michael> module `foo'.  you don't document the symbol `bar'
    Michael> itself, which is just an object.

I can see the need for documenting a particular binding rather than a
symbol, I'm just not sure how one can implement this.

    >> The only external tool that I have proposed is limited to
    >> looking at comments.  Er... OK, plus `(define ...)'
    >> expressions starting in column 0 - are you saying that even
    >> this very basic level of analysis would be too much, IYO?)

    Michael> well, it's actually pretty conservative.  but I'd like to
    Michael> make it unneeded.

Fine, if we can do that (make it unneeded).

    >> I think we can support both approaches, and don't see the need
    >> to decide between them.  The way to do this - as per my second
    >> proposal - is to say that the "documentation in code" approach
    >> is primary, and that snarfing tools are free to generate any
    >> code or data that can be used in some way by the documentation
    >> code.

    Michael> this is where you lose me.  hmmm.  ah, I think I see.
    Michael> you think that points (i) and (ii) are only addressable
    Michael> through snarfing, right?

Yes.  That is what I assumed.  But I see now that I may have been
wrong...

    Michael> I propose we introduce a new reader syntax for embedded
    Michael> documentation.  let's say #{...}#. (it's probably taken,
    Michael> but as I'm still in handwaving mode...)

    Michael> upon encountering this syntax, the reader will:

    Michael> * store the text in the online database (dbm would do
    Michael> nicely).  * yield, as the read value, some lightweight ID
    Michael> which uniquely identifies the stored string (a running
    Michael> counter would do nicely as the key, I think).  this ID is
    Michael> what the 'documentation object property actually stores.

This sounds pretty good to me.  Can you make the idea a little more
concrete, though, by giving an example of the use of #{...}# and
indicating what this read syntax would expand to?

    Michael> the above takes care of the first problem.  the second
    Michael> problem is addressable by teaching Emacs to treat the
    Michael> #{...}# syntax like comments, which shouldn't be very
    Michael> hard.  the important point is that it's not confused with
    Michael> the regular string syntax.

Right.

    >> What was your idea about using the module system?

    Michael> well, as it organizes all the modules and bindings and
    Michael> objects in a neat hierarchy, it seemed a good idea to use
    Michael> this hierarchy to generate external documentation.  like
    Michael> the reference manual. ;)

    Michael> this does mean that in order to generate the chapter
    Michael> about, say, regexps, you'll have to actually load the
    Michael> regexp module into Guile.  which may be a problem...

Not a problem IMO.

Best regards,

        Neil