[asdf-devel] documentation about ASDF configuration

[Attila Lendvai]

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!

-- 
 attila

ps: i know i should provide patches instead, so i quickly shut up now
because i don't know ASDF enough to confidently edit its
documentation.