[asdf-devel] revising asdf manual

[Faré]

On 11 March 2010 18:48, Robert Goldman <rpgoldman at 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:
>
> 1.  The "configuring ASDF chapter;
>
> 2.  Section 7
>
> 3.  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"