Re: more M4sh documentation

[Stepan Kasal]

Hello Ralf,
  thank you very much for writing this documentation.

On Tue, Mar 21, 2006 at 07:44:37PM +0100, Ralf Wildenhues wrote:
> the real question is one of commitment to these interfaces.

Exactly.

First, the question of _AS_PREPARE.  I agree this hack shall not be
documented---the right thing would be to implement the following:

cat >"$CONFIG_LT" <<\_LTEOF
AS_SUBSCRIPT_INIT
AS_FOO
AS_BAR
...
AS_SUBSCRIPT_END
_LTEOF

And all the AS_REQUIREs and AS_PREPAREs from AS_FOO, AS_BAR, etc. would
go right after AS_SUBSCRIPT_INIT, not to the global M4SH-INIT diversion.

Second, I think you should remove the description of AS_VAR_TEST_SET
from the docs.  it's not used anywhere, only in AS_VAR_SET_IF.
Actually, I think we should rename it to _AS_VAR_TEST_SET after 2.60.
Please place a FIXME there to remind us.

> * Eric Blake wrote on Tue, Mar 21, 2006 at 12:43:56AM CET:
> > > address@hidden AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
...
> > Set the shell variable @var{var} to the location of pathname
> > @var{file} from the perspective of directory @var{dir}, [...]

I read (the new version) of the patch today.  I wasn't able to grasp
what Eric's description means.  I had to look at the m4sh.m4 to see
what the macro does.  Learning from this experience, I'd suggest:

@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
@asindex{SET_CATFILE}
If @var{file} is an absolute pathname, set the shell variable @var{var}
to @var{file}.  Otherwise set @var{var} to @address@hidden/@var{file}},
optimizing the cases when @var{dir} or @var{file} is @samp{.}.
The parameters @var{dir} and @var{file} shall be portable path names
(@pxref{File System Conventions}),
given as shell words, properly quoted, with possible variable expansions.
@end defmac

Well, perhaps the last line can be improved, perhaps an example could
be added.  I meant you can use '/bin/sh', "dir/file", "$tmp/$filename"
"$dir" and such.

Another issue:

The AS_VAR_* descriptions are not self-content, I'm afraid.
The example helps a lot, but one has to be careful to notice that
the `ac_var' parameter is not quoted in most cases.

I think the whole system should be explained in a new node; and it might
help to invent some new terms and use them consistently:

All the macros take a `handler' which is a generalized variable name.

At the beginning, you have to call AS_VAR_PUSHDEF to create the handler.
Then you access the macro by AS_VAR_SET, AS_VAR_GET, etc.  Please note that
these macos take the `handler' as the first parameter, not the
handler macro name.  So it is necessary to leave the handler macro
unquoted, so that /the expansion of the macro/ is passed as the parameter.
When you are done, you should free the handler macro by AS_VAR_POPDEF.

As an example, here is a possible implementation of @samp{AC_CHECK_FUNC};
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

@defmac AS_VAR_PUSHDEF (@var{handler-macro-name}, @var{name-word})
Creates a handler for shell variable whose name is derived from `name-word'.
An m4 macro `handler-macro-name' is defined, which expands to the handler.
`name-word' may be any text; if it contains shell variable expansion, the
actual variable name will be computed at the time the shell script is
executed.

@defmac AS_VAR_POPDEF (@var{handler-macro-name})

@defmac AS_VAR_SET (@var{handler}, @var{value})
@asindex{VAR_SET}
Set the shell variable defined by @var{handler} to @var{value}.
@var{handler} is a handler created by AS_VAR_PUSHDEF.
In other words, AS_VAR_SET takes _the expansion of_ the macro defined by
AS_VAR_POPDEF.
@end defmac

@defmac AS_VAR_GET (@var{handler})
...

@defmac AS_VAR_SET_IF (@var{handler}, @var{if-set}, @var{if-not-set})
...

[AS_VAR_TEST_SET deleted]

Ralf, will you be so kind to incorporate (some of) these ideas to the
next incarnation of your patch?
(Not only that I'm lazy, but many of the ideas sketched above are a bit
hazy, so I'll be glad if you sort them out.)

Have a nice day,
        Stepan