Re: Discrimination

[Peter Simons]

Reuben Thomas wrote:

 > There are now far too many macros of dubious utility.

Yes, this is true. A couple of years ago, it was important for the
Archive to reach a certain critical mass in order to be noticed. These
days, however, quality is far more important than quantity.


 > Will [the texinfo documentation] be automatically generated from the
 > code?

Yes. The maint branch contains a script 'macro2texi.py' that's used to
convert each macro's comment section into a texinfo file. All files are
then tied together by 'autoconf-archive.texi' (which is edited
manually). The generated output is reasonable, but it's not of
particularly high quality. Eventually, we should come up with something
better. Ideas and suggestions are welcome, of course.


 > Special-purpose vs. general-purpose macros

Yes, this is a useful distinction indeed. General-purpose macros like
AX_COMPARE_VERSION lay foundations for other macros to build on, which
means that bugs in those macros tend to affect a lot of other code. It's
a good idea, IMHO, to put those macros under some additional scrutiny.


 > 1. Separate the macros into two groups, those which are
 > single-purpose (broadly speaking, those which don't take arguments),
 > and those which are general purpose. This makes the search problem
 > easier.

Yes, this is a good idea. When someone looks for a way to detect Python,
she'll just enter the terms "python autoconf macro" into Google, and
that will quickly lead her to the right place. You cannot easily find
AX_COMPARE_VERSION or AX_PREFIX_CONFIG_H that way, though, because there
aren't any obvious keywords that describe the macro's purpose. These
general-purpose macros would benefit greatly from an categorization
scheme.


 > 2. Be more demanding when new general-purpose macros are submitted:
 > are they necessary? can the functionality be added to an existing
 > macro? For special-purpose macros: why is a special-purpose macro
 > needed? What's the audience?

I completely agree. IMHO, the central issues here are time and effort.
Someone has to make those decisions about new submissions in a timely
fashion. It would help a lot if we'd have some document that describes
our expectations.


 > 3. Refactoring. There are quite a few macros whose functionality
 > overlap (I'm working on one of these too) and others that are very
 > thin wrappers, like all the acltx_prog_* and acltx_package_* macros,
 > which look as though they ought to be compressed into single macros,
 > perhaps, in the case of acltx_prog_*, a macro which knows a list of
 > binary names to try for each of a list of program names (associative
 > arrays in m4?). For acltx_package_*, it's far from obvious to me why
 > kpathsea is not used to find package files.

You are right. IMHO, there are two sides to this issue that need to be
weighed and balanced. A macro like AX_WITH_PERL is trivial, if you know
about AX_WITH_PROG. However, a lot of people don't know about
AX_WITH_PROG. For them, AX_WITH_PERL is useful because that macro is
fairly easy to find.

I feel that we can delete macros like AX_WITH_PERL (or most of the LaTeX
macros, for that matter), if we ensure that the underlying
general-purpose macros are easy to find and easy to use.


Dustin J. Mitchell wrote:

 > 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 would very much like to have that document, too!


 > 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.

Maybe we can combine those tasks? Good submission guidelines would stem
from real-life experience. As it happens, we have that real-life
experience in the form of 500+ macros in our repository. We could go
through those macros, review them, and write down all problems and
inconsistencies that we discover. The resulting list would probably be a
great step into the direction that we want go.

Generally speaking, I think it's fine to perform all kinds of wild
changes in the Git repository. It's okay for our users to expect stable
*releases*, but they shouldn't expect that from the 'master' branch. The
notion of renaming files and breaking interfaces doesn't bother me at
all. We can do all that, we just need to clean up a little before
compiling a release tarball. ;-)


 > Perhaps Peter should make the first cut and then we can adjust?

I can try to provide a starting point based on my experiences so far. I
won't be able to do that quickly though, so if someone else would like
to work on that subject, please go right ahead. The README-maint file
feels like a good place to keep preliminary documentation, and so does
the autoconf-archive.texi file in 'maint'. Frankly, a plain ASCII text
that's posted to this mailing list is fine too. We shouldn't worry about
formatting etc. right now, the contents of the submissions guidelines is
more important than the presentation.


 > I don't know what Peter's documentation plans are.

Currently, I'm setting up an automated procedure that complies the
individual macro's documentation into a single texinfo file. Gnulib's
maintainer makefile has rather fancy support for those tasks, but it's a
bit of an effort to figure out how all that works.

I've also compiled a list of a few other minor subjects that need to be
documented in 'TODO'. Beyond that, I don't have any other plans at this
point.

Take care,
Peter