dear list,

the issue of ASDF configuration came up on sbcl-devel. it's already documented at: http://common-lisp.net/project/asdf/asdf.html#Configuring-ASDF

i've found it too verbose compared to what it's all about, or at least too much written in the form of prose. as if it was written for people who first meet the concept of system definitions and library loading itself.

imho, the usefulness of a documentation is determined by two things:

- how quickly readers find an answer for a specific question

- how much the documentation is structured so that it helps reading a topic in different levels of detail. like: - getting a bird's view (e.g. only reading the sub-chapter titles) - reading the first paragraph of each chapter - reading a whole chapter of interest

also note that the readers of the ASDF documentation (and ASDF users) are 90+% experienced programmers.

so, i suggest to seriously shorten the configuration chapter, or to split the documentation into a verbose one for newcomers, and a highly structured one for people who have an idea what they are dealing with, just don't know which knob to turn in which direction. if we don't split, then at least focus on the latter.

these are based on my personal experience reading the doc.

and a specific suggestion: the inherit-configuration feature was not obvious and i misunderstood it. the two possible interpretation: - insert here the rest of what is defined in the standard configuration files (the right one)

- insert here the current value of the source-registry. IOW, let me append or prefix some configuration entries (the way i misunderstood it)

but ASDF2 is definitely a great improvement, thanks a whole lot for the work!