dirlist (Was: Re: automake/338: AM_GNU_GETTEXT([external]) support)

[Alexandre Duret-Lutz]

>>> "Chuck" == Chuck Wilson <address@hidden> writes:

[...]

 Chuck> I hope the attached patch and ChangeLog address 1, 2, and 3.  I'll
 Chuck> take care of #4 soon.

That seems good.  The lengthy documentation is really great.  
Here are some comments.

[...]

 Chuck> +    $default_dirlist="$acdir/dirlist"
 Chuck> +       if ! ($acdir eq $default_acdir);

                if $acdir ne $default_acdir;

[...]

 Chuck> +By default, @command{aclocal} searches for @file{.m4} files in the 
following
 Chuck> +directories, in this order:
 Chuck> +
 Chuck> address@hidden @code
 Chuck> address@hidden @var{acdir}
 Chuck> +This directory is intended for third party @file{.m4} files, and is
 Chuck> +configured when @command{automake} itself is built.  This is 
 Chuck> address@hidden@@datadir@@/aclocal/}, which typically 
 Chuck> +expands to @address@hidden@}/share/aclocal/}.  To find the compiled-in 
 Chuck> +value of @var{acdir}, use the @code{--print-ac-dir} option 
 Chuck> +(@pxref{aclocal options}).
 Chuck> +
 Chuck> address@hidden @var{acdir-APIVERSION}
 Chuck> +This is where the @file{.m4} macros distributed with automake itself
 Chuck> +are stored.  @var{APIVERSION} depends on the automake release used; 
 Chuck> +for automake 1.6.x, @var{APIVERSION} = @code{1.6}.  
 Chuck> +
 Chuck> address@hidden table

acdir-APIVERSION is searched *before* acdir (because acdir may contain
macros from old Automake versions, and these should not supersede those
from acdir-APIVERSION).

See also: http://sources.redhat.com/ml/automake/2002-04/msg00279.html

 Chuck> +
 Chuck> +As an example, suppose that automake-1.6.2 was configured with
 Chuck> address@hidden/usr/local}.  Then, the search path would be:
 Chuck> +
 Chuck> address@hidden
 Chuck> address@hidden @file{/usr/local/share/aclocal/}
 Chuck> address@hidden @file{/usr/local/share/aclocal-1.6/}
 Chuck> address@hidden enumerate

Ditto.  This inversion also plagues other examples below.

 Chuck> +
 Chuck> +As explained in (@pxref{aclocal options}), there are several options 
that
 Chuck> +can be used to change or extend this search path.
 Chuck> +
 Chuck> address@hidden Modifying the macro search path: @code{--acdir}
 Chuck> +
 Chuck> +The most obvious option to modify the search path is 
 Chuck> address@hidden@address@hidden, which changes default directory and

@address@hidden

 Chuck> +drops the @var{APIVERSION} directory.  For example, if one specifies 
 Chuck> address@hidden/opt/private/}, then the search path becomes:
 Chuck> +
 Chuck> address@hidden
 Chuck> address@hidden @file{/opt/private/}
 Chuck> address@hidden enumerate

I'm leery of documenting things like --acdir here.  Users should
never use `--acdir'.  They only need `-I'.

 Chuck> +
 Chuck> address@hidden Modifying the macro search path: @code{-I} @var{dir}
 Chuck> +
 Chuck> +Any extra directories specified using @code{-I} options 
 Chuck> +(@pxref{aclocal options}) are @emph{prepended} to this search list.  
Thus,
 Chuck> address@hidden -I /home/special} results in the following search path:
 Chuck> +
 Chuck> address@hidden
 Chuck> address@hidden @file{/home/special}
 Chuck> address@hidden @var{acdir}
 Chuck> address@hidden @address@hidden
 Chuck> address@hidden enumerate

Although it's unrelated to your patch, it might be good to use
an example with more `-I'.  E.g. `aclocal -I /foo -I /bar' gives

  @item @file{/foo}
  @item @file{/bar}
  @item @address@hidden
  @item @var{acdir}

[...]

 Chuck> address@hidden is useful in the following situation: suppose that 
 Chuck> address@hidden version @code{1.6.2} is installed with 
 Chuck> +$prefix=/usr/local.  Thus, the default search directories are 

I think it's more common that Automake gets installed in /usr
(e.g. because it comes packaged by the distribution), and that
people manually install other packages in /usr/local.

Then they want aclocal to search /usr/local/share/aclocal/ 
in addition to other standard directories, and fill bug reports
like http://bugs.debian.org/98825

 Chuck> +++ automake-1.6.2/m4/dirlist   2002-07-19 15:31:22.000000000 -0400
 Chuck> @@ -0,0 +1 @@
 Chuck> +./dirlist-test

Since comments are allowed in this file, it seems wise to
explain it is used by the test suite (and similarly note in
dirlist.test that it relies on m4/dirlist).  This is no obvious
out of the context of this patch.

[...]
-- 
Alexandre Duret-Lutz