[asdf-devel] Partial patch for ASDF manual

[Robert Goldman]

james anderson wrote:
> On 2009-07-20, at 20:49 , Robert Goldman wrote:
> 
>> The existing manual doesn't document ASDF's :weakly-depends-on, an  
>> issue
>> which this patch addresses.
>>
>> Two notes about this patch, which characterize it as interim:
>>
>> 1.  It would help if I had a better example of the use of
>> :weakly-depends-on.  I believe I have the semantics right, but I don't
>> have a good use case (a simple textual discussion is enough of a use
>> case).  It's not so much how to use the feature as how people write
>> systems that use the feature.  For example, would you write a piece of
>> code that weakly depended on system foo, set up system foo so that it
>> pushed :foo on the *features* and then sprinkle "#+ foo" around your
>> code?  It almost seems like we'd want a corresponding construct that
>> would load a file only if some feature was present at system operate
>> time (NOT at the time when the ASDF system definition was read).
>>
>> 2.  I found that documenting this exposed a weakness in the ASDF
>> manual's structure.  The manual provides a section that documents the
>> grammar, and a section that documents the ASDF object model.  There
>> isn't really a section that gives a semantic counterpart to the  
>> syntax.
>>  One might think that the object model documentation would fill this
>> need, but it doesn't really.  :weakly-depends-on is a good example of
>> this hole, because weakly-depends-on is translated either into a
>> component dependency or into nothing, so it has meaning only as  
>> part of
>> a defsystem form.  We can't describe its semantics in the section  
>> on the
>> object model, because there is no object model component that
>> corresponds directly to the weakly-depends-on argument.
> 
> i sent a message back in may, to call attention to a missing use case  
> which is related to this. (look for things on 18.05).
> it set out the permutations among presence and processing. of which i  
> recognized three use cases.
> [upon re-reading, i think the third table should indicate that both  
> 'a' and 'b' are to be processed when both are present.]
> 
> in order to make things clear, the documentation should break out the  
> state of the system model and the effect of the expression with  
> sufficient detail that, if nothing else, the reader can construct  
> such a state table on their own.

I am inclined to agree (see my email, which crossed with yours, about
that table).  But one point I was trying to make was that there's no
place in the existing manual's table of contents to put something like
your table.

I'm willing to contribute text to the manual, but not willing to jump in
and restructure it, at least not now.

Best,
r