[asdf-devel] Partial patch for ASDF manual

[Robert Goldman]

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.

BTW, line 1319 of asdf.lisp seems to be someone's debugging statement
left around.  Shouldn't it be excised?
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: docpatch.diff
URL: <https://mailman.common-lisp.net/pipermail/asdf-devel/attachments/20090720/720fa2d5/attachment.ksh>