Re: more M4sh documentation

[Eric Blake]

> The M4sh macros are quite useful also outside of Autoconf.
> OK to apply this to document some of them?

Mostly good, but see nits below...

>  
> address@hidden AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
> address@hidden
> +Set the shell variable @var{var} to @var{dir}/@var{file}, but
> +optimizing the common cases (@var{dir} or @var{file} is @samp{.},
> address@hidden is absolute, etc.).
> address@hidden defmac

When file is absolute, dir/file is not the same as file.  I would reword
this paragraph as:

Set the shell variable @var{var} to the location of pathname
@var{file} from the perspective of directory @var{dir}, optimizing
for common cases (@var{dir} or @var{file} is @samp{.}, @var{file}
is absolute, etc.).

Doesn't etc. need special texinfo handling, since it is an abbreviation
(but this would mean a sweep through the entire .texi file, not just
your patch).

The AS_SET_CATFILE macro also fails when presented non-portable
filenames (for example, the Unix box relative path "a:\\b" looks like
a Windows drive letter and will be treated as absolute on Unix; the
pathname "1:/" will be treated as absolute even though on cygwin
it is relative; the pathname a:foo is treated as relative even though
on cygwin it is absolute).  But I don't know whether it is worth
making it the macro more robust, or just documenting the limitation
that AS_SET_CATFILE expects portable filenames to be useful, along
with recognition that it recognizes \ as an alternate spelling of / and
recognizes drive letters.

>  
> address@hidden AS_TMPDIR (@var{prefix}, @dvar{directory, $TMPDIR})
> address@hidden
> +Create a temporary directory in @var{directory}, as safely as possible
> +(@pxref{Limitations of Usual Tools}).
> address@hidden defaults to @env{TMPDIR}, which is defaulted to
> address@hidden/tmp}.  The @var{prefix} should be up to 4 characters long and
> +indicate the script responsible for the directory.  If successful,
> +set @env{tmp} to the name of the newly created directory, otherwise
> +terminate the script.  No provision for the removal of @samp{$tmp} is
> +made.
> address@hidden defmac

Should we be providing a macro that expands portably into the proper
trap commands for removing $tmp on exit?  Or at least an example
usage of how the user might write such a trap command?

Hmm, is there a portable way to add commands to an existing trap?  It
seems like an AS_TRAP command might be useful for portably adding/
extending an exit trap to remove the tmpdir, but it seems like a rather
difficult task to define a useful interface for AS_TRAP that can be
portably implemented across the various shells.

> address@hidden AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, 
> @ovar{action-if-less}, @ovar{action-if-greater}, @ovar{action-if-greater})

action-if-greater appears twice.

-- 
Eric Blake