Re: Names in libguile

[Mikael Djurfeldt <mdj at mdj dot nada dot kth dot se>]

Maciej Stachowiak <mjs@eazel.com> writes:

> IMO, every document that is relevant to a user of Guile should be
> distributed, although not if it is so incomplete or out of date as to
> be misleading.

Yes, this is one reason why I don't like everything to be put into the
distribution.  While developers know how to interpret the documents
and in which state they are in, it could be truly confusing for users.

> Documents that are only relevant to development of Guile (various
> policies) only need to be in CVS and not in the distributions. I don't
> think it is possile to usefully hack Guile at this point without using
> anoncvs (when I finish setting snapshots back up); it's changing fast
> enough that patches to a stable release are unlikely to apply cleanly
> to the latest sources anyway.
> 
> And the goal of documentation is not to provide as much information as
> possible, but to provide relevant information in a well-organized
> way. Too much documentation can make it harder for the user to find
> the information her or she is actually looking for.

Exactly.

> Addressing the more specific issue, I think the naming policy is
> useful as end-user documentation, especially if we state that it is
> both the required naming policy for Guile itself, and our recommeneded
> policy for Guile extensions and applications. This will give users
> guidance on the logic behind the naming schemes and help them be
> consistent in their own code.

New suggestion:

We introduce the new directory devel/ which is not distributed.
Then we put documentation which is useful for the application writer
under doc/.

OK?