Re: Discrimination

[Dustin J. Mitchell]

On Sat, Aug 1, 2009 at 9:03 AM, Reuben Thomas<address@hidden> wrote:
> My renaming drive (to change them all to the same prefix) will help
> inspection of the list. Peter is working on documentation, which will
> also help, though I'm actually sceptical about the value of doing it:
> how will the documentation be kept consistent with the code? Will it
> be automatically generated from the code? If so, fine. Otherwise, I'm
> skeptical about both the value of the documentation and of the wisdom
> of spending time on it. If it's a one-off effort to provide texinfo
> documentation generated from the comments in the .m4 files, then fine.

I havea a different take on the documentation.  I would like to see
some very detailed guidelines as to how an acceptable macro should be
implemented -- the appropriate interface, appropriate use of other
macros, etc.

I feel like we need this documentation in place *before* we begin a
mark-and-sweep of the macros, as the rename is a perfect time to
change the interface.

As an example, AC_PROG_SWIG automatically sets SWIG if found (which is
pretty normal for an AC_PROG_xx), but sets it to something producing
an error message if it is not found.  It also doesn't have an
action-if-found nor an action-if-not-found.  As contrast,
AC_PROG_APACHE will error out if Apache is not found.  All of this
violates the principle of least surprise for users of the archive.

I'm interested in making a first cut of this documentation, but it
could easily devolve into a bikeshed discussion, so we should probably
lay down some ground rules first, and perhaps Peter should make the
first cut and then we can adjust?  I don't know what Peter's
documentation plans are..

Dustin

-- 
Open Source Storage Engineer
http://www.zmanda.com