autoconf-archive-maintainers | |
[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Discrimination
From: |
Dustin J. Mitchell |
Subject: |
Re: Discrimination |
Date: |
Sat, 1 Aug 2009 22:06:52 -0400 |
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