Re: more M4sh documentation

[Ralf Wildenhues]

Hi Eric, Paul,

Thanks to both of you for the reviews!

* Eric Blake wrote on Tue, Mar 21, 2006 at 12:43:56AM CET:
> >  
> > 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.).

Hehe, you may have noticed that I did not write this paragraph at all,
just moved it.  That was intentional.  ;-)
But it's good to fix that while we're at it.  I took your suggestion
above, ..

> The AS_SET_CATFILE macro also fails when presented non-portable
> filenames [...]

 .. and added a note to this end.

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

Yes, it does.  No, I'm not volunteering for that sweep.

> > address@hidden AS_TMPDIR (@var{prefix}, @dvar{directory, $TMPDIR})

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

Yes, definitely.  I even thought of writing it, and documenting both it
and AS_EXIT.  My thinking currently is that it may be good to add them,
but then wait (until the release after that) with documenting them, so
they can have a time to stablilize.  After all, AS_TMPDIR took several
iterations, and the trap handling, too.

To explain this a bit more verbosely, in case someone would like a bit
more rationale: currently, there is this race: after the directory is
created, but before its name is assigned to $tmp, a signal may cause it
to be leftover.  Maybe this could be fixed by temporarily ignoring some
signals; but I'm pretty sure code to fix that will again take a while to
stabilize.

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

Exactly: let's not document interfaces now that later turn out to be not
portable.

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

Oops.

* Paul Eggert wrote on Tue, Mar 21, 2006 at 08:19:30AM CET:
> Ralf Wildenhues <address@hidden> writes:
> 
> > +This macro should be followed by @samp{dnl}.
> 
> This phrase occurs in several places, unexplained, and gives me the
> willies.  Why is dnl required?

It's not.  That was a recommendation I took from comments in the code.
Thinking about it, it is not necessary and should not even be here; it
probably was recommended for in-Autoconf macros to prevent additional
newlines in the output.  I just deleted the phrase now, but kept the
`dnl's in the example; that should be sufficient.

Updated patch below.  I'd be happy to apply if you are comfortable with
making all of these public.  IOW: the real question is one of commitment
to these interfaces.

Other issues fixed in this version: do not use TABs in .texi files
(could that be checked, say, in Makefile.maint?), bogus address@hidden'
for AS_COPYRIGHT, a couple of fixed tenses.

Cheers,
Ralf

        * doc/autoconf.texi (Programming in M4sh): Move documentation of
        AS_SET_CATFILE.  Document AS_COPYRIGHT, AS_EXECUTABLE_P,
        AS_LITERAL_IF, AS_LN_S, AS_TMPDIR, AS_VERSION_COMPARE,
        AS_VAR_GET, AS_VAR_SET, AS_VAR_SET_IF, AS_VAR_TEST_SET,
        AS_VAR_PUSHDEF, AS_VAR_POPDEF.  Add AC_CHECK_FUNC implementation
        as example for variable accessor usage.  Fix tense in AS_CASE
        description.
        (Limitations of Usual Tools) <mktemp>: Refer to AS_TMPDIR.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.970
diff -u -r1.970 autoconf.texi
--- doc/autoconf.texi   20 Mar 2006 20:28:56 -0000      1.970
+++ doc/autoconf.texi   21 Mar 2006 18:44:57 -0000
@@ -9391,7 +9389,18 @@
 @asindex{CASE}
 Expand into a shell @samp{case} statement, where @var{word} is matched
 against one or more patterns.  @var{if-matched} is run if the
-corresponding pattern matched @var{word}, else @var{default} is run.
+corresponding pattern matches @var{word}, else @var{default} is run.
address@hidden defmac
+
address@hidden AS_COPYRIGHT (@var{copyright-notice})
address@hidden
address@hidden Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the M4sh macros, parts of your script are covered by
address@hidden
+
+The @var{copyright-notice} will show up in both the head of
+the generated script and in its @samp{--version} output.
 @end defmac
 
 @defmac AS_DIRNAME (@var{file-name})
@@ -9402,6 +9411,12 @@
 @command{dirname} command.
 @end defmac
 
address@hidden AS_EXECUTABLE_P (@var{file-name})
address@hidden
+Check whether @file{file-name} is executable (@pxref{Limitations of
+Builtins}).
address@hidden defmac
+
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
 @asindex{IF}
 Run shell code @var{test1}.  If @var{test1} exits with a zero status then
@@ -9421,6 +9436,24 @@
 be expanded before the first test.
 @end defmac
 
address@hidden AS_LITERAL_IF (@var{expression}, @var{if-literal}, 
@var{if-not-literal})
address@hidden
+If @var{expression} contains shell indirections such as parameter
+expansion @samp{$var} or command substitution @samp{`command`}, expand
+to @var{if-not-literal}, else expand to @var{if-literal}.  The macro
+only approximates the answer, as some literals will not be recognized as
+such.  It may be used to create macros that are polymorphic to M4 and
+shell arguments, or to cope with variables both without and with
+indirection, such as @samp{ac_cv_$var}.
address@hidden defmac
+
address@hidden AS_LN_S (@var{file}, @var{link})
address@hidden
+Link @file{file} to @file{link} using @samp{ln -s} if the operating
+system and file system support symbolic links, otherwise using @samp{ln}
+if that works, otherwise using @samp{cp -p}.
address@hidden defmac
+
 @defmac AS_MKDIR_P (@var{file-name})
 @asindex{MKDIR_P}
 Make the directory @var{file-name}, including intervening directories
@@ -9432,6 +9465,15 @@
 succeed in that case.
 @end defmac
 
address@hidden AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
address@hidden
+Set the shell variable @var{var} to the location of path name
address@hidden from the perspective of directory @var{dir}, optimizing
+for common cases (@var{dir} or @var{file} is @samp{.}, @var{file}
+is absolute).  This macro expects portable path names (@pxref{File
+System Conventions}).
address@hidden defmac
+
 @defmac AS_SHELL_SANITIZE
 @asindex{SHELL_SANITIZE}
 Initialize the shell suitably for @code{configure} scripts.  This has
@@ -9441,6 +9483,18 @@
 @xref{Special Shell Variables}.
 @end defmac
 
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
+
 @defmac AS_TR_CPP (@var{expression})
 @asindex{TR_CPP}
 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
@@ -9465,13 +9519,70 @@
 @end example
 @end defmac
 
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 AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, 
@ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater})
address@hidden
+Compare two version strings @var{version-1} and @var{version-2} in a way
+compatible with glibc strverscmp (@pxref{String/Array Comparison, , ,
+libc, @acronym{GNU} libc})
 @end defmac
 
+With the help of @samp{AS_LITERAL_IF}, it is possible to unify the
+handling of M4 and shell variables together with indirections to some
+extent.  M4sh offers a few helper macros to this end:
+
address@hidden AS_VAR_GET (@var{variable})
address@hidden
+Get the value of shell variable @var{variable}.
address@hidden defmac
+
address@hidden AS_VAR_SET (@var{variable}, @var{value})
address@hidden
+Set the shell variable @var{variable} to @var{value}.
address@hidden defmac
+
address@hidden AS_VAR_SET_IF (@var{variable}, @var{if-true}, @var{if-false})
address@hidden
+If the shell variable accessed by @var{variable} is set, expand
address@hidden, else expand @var{if-false}.
address@hidden defmac
+
address@hidden AS_VAR_TEST_SET (@var{variable})
address@hidden
+Expand into the @command{test} expression which determines whether
address@hidden is set.
address@hidden defmac
+
address@hidden AS_VAR_PUSHDEF (@var{varname}, @var{value})
address@hidden
+Define a M4 variable @var{varname} as an accessor to the shell variable
address@hidden, including indirections.  @var{varname} should be accessed
+with the @samp{AS_VAR_*} macros described above, and needs to be
+undefined with @samp{AS_VAR_POPDEF} at the end of the block.
address@hidden defmac
+
address@hidden AS_VAR_POPDEF (@var{varname})
address@hidden
+Undefine the M4 variable @var{varname} previously defined by
address@hidden
address@hidden defmac
+
address@hidden
+A possible implementation of @samp{AC_CHECK_FUNC} demonstrates the use
+of these accessor macros.  Note that it allows both literals and shell
+variables in the first argument:
+
address@hidden
+AC_DEFUN([AC_CHECK_FUNC],
+[AS_VAR_PUSHDEF([ac_var], [ac_cv_func_$1])dnl
+AC_CACHE_CHECK([for $1], ac_var,
+[AC_LINK_IFELSE([AC_LANG_FUNC_LINK_TRY([$1])],
+                [AS_VAR_SET(ac_var, yes)],
+                [AS_VAR_SET(ac_var, no)])])
+AS_IF([test AS_VAR_GET(ac_var) = yes], [$2], [$3])dnl
+AS_VAR_POPDEF([ac_var])dnl
+])
address@hidden example
+
 
 @node File Descriptor Macros
 @section File Descriptor Macros
@@ -12691,7 +12802,8 @@
 gaining control, though @command{mktemp} is far less likely to fail
 gratuitously under attack.
 
-Here is sample code to create a new temporary directory safely:
+Here is sample code to create a new temporary directory safely; it
+corresponds to @code{AS_TMPDIR} (@pxref{Programming in M4sh}):
 
 @example
 # Create a temporary directory $tmp in $TMPDIR (default /tmp).