[asdf-devel] The Manual

[Dave Penton]

Greetings. I am writing regarding a post from R. Goldman last year on this mailing list. (I just today subscribed to the list.)

My question may already have been canvassed elsewhere. If so point me to the appropriate thread. I am not very adept at picking through the list archives, or maybe I'm just lazy....

Here is the relevant quotefrom the earlier post:

> Alas, the manual does not seem to clarify this.  This, I think is a
> problem with the manual's design.  In the discussion of DEFSYSTEM we
> have two example pages, and then we have the grammar.  The grammar
> specifies the /syntax/ of defsystem, but there really isn't any way to
> specify the /semantics/ of bits of defsystem.  Note that the operations
> (object model) bit of the manual does /not/ serve this purpose.  It
> would be OK for us to specify the semantics in terms of those
> operations, but we do not do so.  If we were to do so we would need to
> add a section that bridges from the syntax to the object model by
> specifying how the syntax gets rewritten into the object model.

I was thrilled to find this comment - it addresses my concern directly.
My question is: Has anyone followed up on this? A manual section on the semantics of defsystem is sorely needed. I am fairly new to Common Lisp (one year). Like most developers I need some kind of system definition facility but find myself a bit exasperated learning to use asdf.
My opinion (expressed with gratitude for the efforts of developers and documenters of asdf) is that Chapter 5 talks all around the thing that I most want to know, viz. "What does defsystem do?"
After a couple of examples, probably the manual should then contain an informal description of defsystem semantics. I know, of course, that it means to allow one to define a "system." But how? What is the strategy, and how do the bits of the defsystem form implement that strategy?
To illustrate my point, I stopped reading and started to grind my teeth a little when I hit this sentence in section 5.3:
"The method-form tokens need explaining...." 
Probably they do need explaining. But at that point the manual has given no context in which to understand an explanation. The next few lines do not actually constitute an explanation in any case. (Or maybe they do. I can be dense sometimes :-) Why is it that I should want to :perform something or :explain something :after? Maybe I also want to :deep-fry something :before or :exchange-mana :around something? (Ok, now I'm being snotty...sorry.)
If I were not a relative beginner to Common Lisp I might try to contribute some draft manual sections for consideration by the maintainers. However, I fear that my efforts would only increase the turbidity level.
So: Has anyone followed up on this, or does someone intend to do so?
Best,
- Dave -

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/asdf-devel/attachments/20101003/a1f02ac5/attachment.html>