Comment on: FAQ chapter for the manual

[Bruce Korb]

> Why doesn't Automake support wildcards?
> =======================================
> 
>    Developers are lazy.  People often they would like to use wildcards
> in `Makefile.am's so they don't need to remember they have to update
> `Makefile.am's every time they add, delete, or rename a file.
> 
>    There are several objections to this:
>    * When using CVS (or similar) developers need to remember they have
>      to run `cvs add' or `cvs rm' anyway.....
> 
>    * Using wildcards makes easy to distribute files by mistake.....
>    
>    * Using wildcards it's easy to omit some files by mistake.....
> 
>    * Listing files, you control *exactly* what you distribute.....
> 
>    * Finally it's really hard to `forget' adding a file.....

You left out an argument in favor:  the add-on files are self
contained.  I, in fact, intentionally make it very simple to
add expression files to AutoGen.  :-)  You add a file named
``exprMumble.c'' to the agen5 directory and it is automatically
incorporated into autogen, but for the fact you also have to
edit Makefile.am to add it to the list.  If they don't want to
distribute it, then omit it.  It gets dropped automatically,
but for the fact it is now listed in Makefile.am.  :-)
There ought to be a way to say, "I understand all your
philosophical objections, but I don't care.  Glob this expression
and insert the result into Makefile.in and please don't tell me you
know how to do my business better than me."  We have philosophical
differences.


> Files left in build directory after distclean
> =============================================
> 
>    This is a diagnostic you might encounter while running `make
> distcheck'.
> ....
>    This diagnostic really covers two kinds of errors.
> 
>    * files that are forgotten by distclean;
> 
>    * distributed files that are erroneously rebuilt.
> 
>    The former left-over files are not distributed, ....
> 
>    The latter bug is not always easy to understand and fix, so let's
> proceed with an example.  Suppose our package contains a program for
> which we want to build a man page using `help2man'.  GNU `help2man'
> produces simple manual pages from the `--help' and `--version' output
> of other commands (*note Overview: (help2man)Top.).  Because we don't
> want our users to install `help2man', we decide to distribute the
> generated man page using the following setup.
> 
>      # This Makefile.am is bogus.
>      bin_PROGRAMS = foo
>      foo_SOURCES = foo.c
>      dist_man_MANS = foo.1
>      
>      foo.1: foo$(EXEEXT)
>         help2man --output=foo.1 ./foo$(EXEEXT)

This example is too simplistic.  There are a number of packages
that derive documentation from the sources.  Mine is "special"
in that I distribute the piece that does the extraction, but
anyone deriving a .texi file from javadoc comments will have
essentially the same difficulty.  Do you distribute trivially
extracted text or not?  I say, "not" and if not you have this
dilemma.  Various pieces of documentation will depend upon the
extracted .texi file, even if you distribute these docs.  The
result is your clients will always have their builds attempting
to rebuild distributed docs and the distcheck will choke.  After
years of arguing this, I did finally win my point and it ought
to be in the FAQ.  :-)

BTW, the problem gets much worse if the product distributes with
no .texi files because the texi rules know that if there are no
texi files, then there can be no texi documentation.  This is
a mistake.  I've been told that the texi rules come from the texi
folks, so it's not Automake's job to fix it.  It's still a problem.