On 11 March 2010 18:48, Robert Goldman rpgoldman@sift.info wrote:
The section 8/9 merge was easy. The section 7 (where does asdf write its files?) one is going to be more difficult.
It turns out that this stuff is discussed in THREE locations:
The "configuring ASDF chapter;
Section 7
README.asdf-output-translations.
Getting those three merged sensibly is going to be a bit more work than I'd hoped.
I'm inclined to start by having the configuration chapter just crossref to section 7, and merge all the stuff into section 7. Then we can figure out how to reorganize things.
I think we should probably update this to restore some one-paragraph "here's how you turn it on with a minimum of fuss" introduction. Regrettably, I don't see how that's possible with the full, heavyweight new configuration procedure.
Current section 7 should be mostly deleted and replaced with the current contents of README.asdf-output-translations. Some good bits from current section 7 can be salvaged as minor appendix sections of the new section 7. I'd keep the configuring ASDF mostly intact, as a summary of "getting there quick in the common case", with cross-reference to the new section 7 for more information; any advanced bits should be moved there.
The idea is that a newbie should have to read as little as possible to get started, and it should be very clear which sections he needs to read and which he doesn't.
[ François-René ÐVB Rideau | Reflection&Cybernethics | http://fare.tunes.org ] Alliance, n.: In international politics, the union of two thieves who have their hands so deeply inserted in each other's pocket that they cannot separately plunder a third. — Ambrose Bierce, "The Devil's Dictionary"