[asdf-devel] Partial patch for ASDF manual

[james anderson]

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.