Re: [ENHANCEMENT]Autoconfig.pdf

[Eric Blake]

On 06/30/2014 03:25 PM, Arthur Schwarz wrote:
> (Of course, [ENHANCEMENT] is in the eyes of the beholder.
> 
> I'm reading Section 3 of the Autoconf.pdf manual (for version 2.69, 24 April
> 2012) and wonder if the following suggestion might gain some traction. The

First, realize that the pdf you are looking at may have different
pagination than what other people are looking at; it's better to point
to actual text you want improved, and/or point to links to the online
manual, instead of assuming that everyone will be looking at the pdf as
you.  As 2.69 is the most recent release, this should be the same
contents as what you were reading:
https://www.gnu.org/software/autoconf/manual/autoconf.html

[and yes, I really need to find some free time to release 2.70]

> request is for a formal, linguistic, definition collected into a single
> introductory section with formal definitions of syntax.

You're welcome to write a patch with any of these suggestions -
sometimes, a patch goes a lot further than broad overviews of what you
want changed but without wording to back up the changes.

> 
> 1: A formal description of the autoconfig language. Something like
>    Alphabet a-zA-z0-9
>    Special characters ,$@
>    Digraphs: '$@', '$*', '$%', '$f', '$1' 
>    Naming conventions, eg., are all autoconf supplied macros capitalized and
> must the user capitalize their macros.
>    Etc.

The problem is that there is no formal definition of the 'autoconf' (not
'autoconfig') language - it is really an amalgamation of anything that
is legal shell, plus anything that is legal m4 wrapping that shell,
within the bounds of the m4 macros that are already present.  The
autoconf code did not write its own parser, but is merely borrowing the
existing m4 parser to macro-expand text into what is hopefully valid
code that can be parsed by /bin/sh.

As for naming conventions, the manual DOES make some suggestions on
common conventions (anything starting with AC_ is reserved for use by
autoconf; user-defined m4 macros are typically all uppercase with a
prefix to minimize clashes of other packages defining macros with
similar names but different contents).  Does this section of the mnanual
not go into enough details?
https://www.gnu.org/software/autoconf/manual/autoconf.html#Macro-Names

Or are you asking for a reference to that section to occur earlier in
the manual?

> 2: A formal description of the command line input interface

Is this section of the manual not already sufficient?

https://www.gnu.org/software/autoconf/manual/autoconf.html#autoconf-Invocation

> 3: Specific formal statements (if true) that:
>    a. autoconfig.ac, aclocal.m4, acsite.m4 consists exclusively of m4 macros
> and comments.

Or rather, that these files will be macro-expanded by m4, and the result
of macro-expanding them must then be a valid shell file.

>    b. The M4 syntax requires that no space separate a macro name from its
> opening
>       parentheses, as in NAME(.

The manual is already very clear on this point:
https://www.gnu.org/software/autoconf/manual/autoconf.html#Autoconf-Language

>    c. That within a macro, spaces are ignored.

Not quite true - rather, within a macro, unquoted leading space is
ignored (this is inherited from m4).  But again, already mentioned.

>    d. That within a quoted string, spaces are not ignored.
>    e. That the M4 quote symbol can be '[', ']'.

Already mentioned.

>    f. That the M4 quote symbol can be '"' text '"', as in page 18 echo "Hard
> rock was here! --AC""_DC", and what the difference is between double quotes
> and square brackets.

No. Absolutely wrong.  You do NOT want to set the m4 quote symbols to
"".  It is almost always best to leave them as [ and ].  What you are
getting confused at is that "" is shell quoting, and the result of
calling autoconf is to turn a configure.ac script that contains plain
text and m4 macros into a shell script.  Anything that does not result
in an m4 macro must result in shell code.  The example about how to
quote AC_DC was intended to demonstrate how to produce shell code that
contains what would normally look like an autoconf macro name, but which
must survive unchanged through m4 expansion to be used literally in the
shell.

But if you have ideas on how to clarify the text in that section
(https://www.gnu.org/software/autoconf/manual/autoconf.html#Autoconf-Language),
let us know.

>    g. The exact rules for macro expansion (see page 18). What is given are
> inexact rules in that there is no strong indication of the sequence of
> events and their consequences. What is given is a verbal description which
> is not quite as clear as it could be.

Again, a problem with assuming pdf page numbers; I'm not sure what text
you are referring to.  What do you propose that would be more exact?
Basically, a macro is expanded if m4 thinks it is a macro name (and m4
does not require () to designate a macro call).

> 4: page 18. The following example should be explained. What is wrong?
>     The following example is wrong and dangerous, as it is underquoted:
>         AC_CHECK_HEADER(stdio.h,
>         AC_DEFINE(HAVE_STDIO_H, 1,
>         Define to 1 if you have <stdio.h>.),
>         AC_MSG_ERROR([sorry, can't do anything for you]))
>    Exactly how is it underquoted? Why is it dangerous.

It is underquoted compared to the version displayed a few lines earlier:

     AC_CHECK_HEADER([stdio.h],
                     [AC_DEFINE([HAVE_STDIO_H], 1,
                        [Define to 1 if you have <stdio.h>.])],
                     [AC_MSG_ERROR([sorry, can't do anything for you])])

and can cause autoconf to completely botch the file, if the expansion of
the AC_DEFINE (or any other underquoted macro) contains commas which
then cause the AC_CHECK_HEADER macro to be called with a different
number of arguments than what you thought you were passing.

The manual goes into a more in-depth discussion of quoting pitfalls:
https://www.gnu.org/software/autoconf/manual/autoconf.html#M4-Quotation

but we are trying to keep the introduction short and concise.  However,
I agree that adding a bit more wording to this part of the manual might
be helpful; do you have a sentence or two that would have helped you?

> 5: If M4 macros and non-macro's can be intermixed

Yes

>    a. Is the syntax the same?

Anything that is not recognized as a macro name is not a macro, and is
output verbatim, so it better be valid shell at that point.

>    b. Where is there a reference to the non-M4 macro's.

Any good shell reference manual.

>    c. Is echo a non-M4 macro.

It is not (normally) a macro, therefore it is output literally into the
shell script, and had better be valid shell (which it is).  (Paranoid
script writers could try to write a script that assumes that even 'echo'
may have been defined as an m4 macro, and try to quote it so that it
will not be expanded by m4; but this tends to add a lot of work for not
much gain)

> 6: page 22. The -W command line input seems to contain more than 'all',
> 'none', 'error', 'no-category' In seems to include 'syntax', 'obsolete'.
> Should these be part of the -W description? And you mention that $WARNINGS
> is an environment variable which autoconf makes explicit use of if present.
> What purpose does it serve to provide an explicit use on the command line?

Those are the special warnings that are not categories; all other
arguments to -W are normal category arguments.  Yes, the manual could
probably mention a way to get autoconf to display its current list of
known warning categories.  (Hint: 'autoconf --help' gives such a list;
for autoconf, the normal categories are 'cross', 'obsolete', and
'syntax').  Any unrecognized categories are ignored; this is so that the
idea of $WARNINGS is generic across several GNU programs (automake being
another program that uses it; automake also understands the 'gnu',
'override', 'portability', 'extra-portability', and 'unsupported'
categories, but lacks the 'cross' category).  By setting your
environment variable, maybe to WARNINGS='cross gnu', then you can get
both autoconf and automake to turn on particular warnings categories,
and without making either program complaining about the category that
only the other understands.

> 7: Section 3 seems to contain forward references to language elements which
> are not explained in part or fully at the point of use. This makes the
> description confusing. This occurs, eg., onpage 18 for autom4te and page 23
> for @, $@, $*, $%.

Are you proposing adding forward definition links to some of these
constructs?  The $% autom4te construct is explained in more detail at
https://www.gnu.org/software/autoconf/manual/autoconf.html#autom4te-Invocation

> 8: pagae 13: What are bin_PROGRAMS. hello_SOURCES and VPATH. No description
> is provided.

These are automake terms.  As this is the autoconf manual, not the
automake manual, the best we can do is point you to the automake manual
if you want to learn more about typical Makefile.am constructs.

> 9: The figures on page 15 are confusing and (I think) don't correctly
> display the context and separation between data and program. For example, 
> 
>     your source files --> [autoscan*] --> [configure.scan] --> configure.ac
> 
> seems to show an optional execution of autoscan generating an optional
> congifure.scan file resulting in a configure.ac file. Removing all the
> optional reference yields:
> 
>    your source files --> configure.ac
> 
> and this must certainly be incorrect. Perhaps you mean (I'mm just guessing)
> 
>   your source files --> autoscan* --> configure.scan
> 
>   configure.scan --> editor --> configure.ac

Sure, adding [*$EDITOR] into the mix might make it easier to understand.
 [To be honest, autoscan is very seldom used these days]

> 
> [local macros] seems ambiguous. Do mean a user created file of any name
> containing user defined local marros?

Any file mentioned in an include statement in acinclude.m4 counts as a
local macro file.

> 
> What purpose does Makefile.in serve? It has no generators and no users in
> its first instance and is used only in its second.

When preparing a tarball without using automake, you must hand-write a
Makefile.in and ship it as-is.  It IS used, just not during package
preparation time.  Remember, the point of autoconf is to help define a
clear delineation between two phases of development:

Phase 1: developer chooses what goes into the tarball, and has access to
autoconf but no to the end user's machine
Phase 2: end user builds the tarball, and has access to machine details
but not necessarily autoconf

The goal is to make phase 1 easier on the developer (configure.ac is a
lot more compact than open-coding an entire configure script; and
everything in the tarball must be machine-independent - use of perl and
m4 makes it possible for a fairly concise configure.ac of a few thousand
bytes expand into a configure shell script which is well over a million
bytes long), while phase 2 must make life easier for the end user (the
configure script must take the machine-independent sources and customize
them to the end user's machine, without relying on anything not
sanctioned by the GNU Coding Standards as being portable, which means no
perl or m4).  Until you wrap your head around the dichotomy of execution
(the developer runs autoconf which is based on m4, the end user runs
configure which is shell, and configure.ac contains constructs that must
feed both invocations), the autoconf language is very difficult to
grasp.  But once you DO understand that separation of execution, a lot
of the rest of the manual makes sense in a new light.

> 
> Config.status seems to be a generated file but there is no generator.

config.status is generated by configure (the arrows are awkward there:
configure generates up to three things: config.cache, config.log, and
config.status; it then executes config.status, and config.status
generates config.h and Makefile).  Suggestions on drawing anything
better, or turning it into a vector graphic diagram instead of ascii-art
while still fitting in the constrants of what the 'info' reader can
display, are welcome.

> 
> None of the files are described and none of the files have forward
> references to defintions.
> 
> Now I absolutely know that this is all a bore and distraction. But I'm
> trying to make some sense of all the pieces and having a ferocious
> difficulty. 
> 
> Please don't take this as a criticism (or even a request if that suits your
> purpose) but only as a list of things that confuse me or that I think might
> need some clarification. You have an excellent (and at points, quite funny)
> manual, and I appreciate it and the effort required to make it.

Thanks for your feedback as a new reader.  Sometimes, many of the
contributors are such long-time users that we forget how hard it was to
initially learn things.  But without actual patches (or at least
proposed wording changes), it's hard to see what would have made it
easier for you to understand, and still keep the manual concise in the
introduction for sections that are further developed later on.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature