[asdf-devel] The Manual

[Robert Goldman]

On 10/3/10 Oct 3 -4:18 PM, Dave Penton wrote:
> 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?
> 

In short, no one has followed up on this.  I would say that I have the
intention of doing so, but that intention is likely to be postponed
repeatedly.  The works is substantially thankless and unremunerative,
thus must queue behind work that is more remunerative and fun.

The problem here is exacerbated by the fact that in order to fit a
discussion of the semantics into the manual, one would have to
substantially restructure the whole thing, which is an extra bonus
helping of drudgery and thanklessness.

I see that sentence (now in section 5.2).  What needs to happen in the
short term is that this needs to simply point to a section of the
documentation later where the methods are actually addressed, since the
only piece of information here is that this provides a shorthand for
method definition.

The bad news for the long term is that there is no place where the
object model is comprehensively addressed, and there is unlikely to be
in the near future.

I have pushed a marginal improvement of that example corresponding to my
"short term" answer above.

best,
r