[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
From: |
Michael Livshin |
Subject: |
Re: Documentation |
Date: |
28 Feb 2001 02:14:43 +0200 |
User-agent: |
Gnus/5.0807 (Gnus v5.8.7) XEmacs/21.1 (Crater Lake) |
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?
well, it always may be me. I thought you meant that sometimes it is
desirable to document a "name", so to speak. so you say something
like "one of the exports of the module (foo) is bar. it's supposed to
be bound to a list of widgets". you, thus, document the exported
binding whose name is `bar' and which is exported by the module `foo'.
you don't document the symbol `bar' itself, which is just an object.
ouch, the more I try to explain things, the more confusing they
seem. ;(
> Michael> one feature I like very much about the Lisp family of
> Michael> languages[1] is the syntactic flexibility. which means
> Michael> that you can't really know a lot about code if you only
> Michael> look at its printed representation (i.e. the source
> Michael> file).
>
> OK.
>
> Michael> which means that specifying tools which are
> Michael> external to the system proper whose purpose is to analyze
> Michael> printed representation of Lisp/Scheme code is, at best,
> Michael> kludgy.
>
> Agreed. (I'm not aware of having proposed anything like this - do you
> think that I have?
er, yes. that said, I'm actually having some trouble, at this point,
with associating different proposals and major/minor points with
people who made them, so I just address the points themselves. I can
see now it's not such a good strategy after all. sorry about that.
> 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?)
well, it's actually pretty conservative. but I'd like to make it
unneeded.
> I'm sorry if I appear to have been jumping between proposals - an
> unfortunate consequence, perhaps, of trying to take everyone's
> comments seriously.
it's very much appreciated. heck, I know someone whose snotty
comments all but beg "ignore me" at times. *blush*
> In detail... Everything in my Scheme docstring format proposal still
> stands. Several people have expressed support for (i) the
> documentation in comments approach, for various more or less
> `cosmetic' reasons, (ii) the idea of only loading docstrings into the
> system when they are needed, to reduce Guile's memory footprint.
all good things, and I want them too.
> On the other hand, other people have expressed support for the
> documentation in code approach, noted that docstrings should be
> associated with values rather than names, etc. as summarized in my
> last but one email.
there's no contradiction.
> 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.
this is where you lose me. hmmm. ah, I think I see. you think that
points (i) and (ii) are only addressable through snarfing, right?
> But what about the people who specifically _want_ documentation
> information to be lost when code is loaded?
would "sit in the database and don't fill up the memory until I ask
for you" be an adequate substitute for "get lost"? then I have this
concern in mind.
> Or those who find editing multiline Scheme strings significantly
> more awkward than comments?
this is addressable too, I believe.
I propose we introduce a new reader syntax for embedded documentation.
let's say #{...}#. (it's probably taken, but as I'm still in
handwaving mode...)
upon encountering this syntax, the reader will:
* store the text in the online database (dbm would do nicely).
* yield, as the read value, some lightweight ID which uniquely
identifies the stored string (a running counter would do nicely as
the key, I think). this ID is what the 'documentation object
property actually stores.
note that Martin already posted a dbm binding to guile-sources, so he
must be thinking along the same lines. ;)
the above takes care of the first problem. the second problem is
addressable by teaching Emacs to treat the #{...}# syntax like
comments, which shouldn't be very hard. the important point is that
it's not confused with the regular string syntax.
> I'm particularly keen to understand your point here, because the idea
> of `just using the module system' has occurred to me too, although
> probably in quite a different context. My idea is that we could use
> the module system to automatically track whether docstrings have
> already been loaded or not, and that the mechanism that we use to
> cause a module to be reloaded could be the same mechanism that we use
> to cause docstrings to be reloaded.
>
> So, for module (blah groop), the corresponding docstrings could be defined
> in module (blah groop documentation) as a sequence of document!
> expressions:
>
> (define-module (blah groop documentation)
> :use-module (blah groop))
>
> (document! blah-file "...")
> (document! blah-file-list "...")
> (document! blah-port "...")
>
> (Note that this file could be generated automatically as the result of
> snarfing docstring comments from the Scheme file for (blah groop).)
>
> This would be loaded by `(use-modules (blah groop documentation))',
> which automatically takes care of only loading the file once.
this looks like a very elegant solution to a problem that I'm trying
to avoid entirely. ;)
> What was your idea about using the module system?
well, as it organizes all the modules and bindings and objects in a
neat hierarchy, it seemed a good idea to use this hierarchy to
generate external documentation. like the reference manual. ;)
this does mean that in order to generate the chapter about, say,
regexps, you'll have to actually load the regexp module into Guile.
which may be a problem...
incoherently yours,
--mike
--
Make sure your code does nothing gracefully.