[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
From: |
Neil Jerram |
Subject: |
Re: Documentation |
Date: |
01 Mar 2001 21:54:28 +0000 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.5 |
>>>>> "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
- Re: Documentation,
Neil Jerram <=
Re: Documentation, Jorgen 'forcer' Schaefer, 2001/03/01