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:
- 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).
- 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.