Discrimination

[Reuben Thomas]

Contributions to autoconf-archive have exploded in the past year,
which is great. However, there are now far too many macros of dubious
utility.

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.

However, this is only part of the story. To be helpful rather than
overwhelming to the user, we need to be careful about the
proliferation of general-purpose macros. Special-purpose macros whose
purpose is indicated in the name are less of a problem, since they can
more easily be found by the user who will go looking for them. The
problem is general-purpose macros which are as likely to be found by a
user who didn't know that they exist or that they might be useful, and
hence is likely to find them by browsing the list of available macros.
Arguably further divisions might be useful e.g. for all the LaTeX
macros.

I have suggestions:

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.

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?

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.

Essentially, we should be able to achieve good results with
structuring, and leave little need for documentation beyond what is
written in each file, even if we allow it to be read in a more
convenient format.

-- 
http://rrt.sc3d.org