[ENHANCEMENT]Autoconfig.pdf

[Arthur Schwarz]

(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
request is for a formal, linguistic, definition collected into a single
introductory section with formal definitions of syntax.

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.
2: A formal description of the command line input interface
3: Specific formal statements (if true) that:
   a. autoconfig.ac, aclocal.m4, acsite.m4 consists exclusively of m4 macros
and comments.
   b. The M4 syntax requires that no space separate a macro name from its
opening
      parentheses, as in NAME(.
   c. That within a macro, spaces are ignored.
   d. That within a quoted string, spaces are not ignored.
   e. That the M4 quote symbol can be '[', ']'.
   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.
   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.
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.
5: If M4 macros and non-macro's can be intermixed
   a. Is the syntax the same?
   b. Where is there a reference to the non-M4 macro's.
   c. Is echo a non-M4 macro.
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?
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 @, $@, $*, $%.
8: pagae 13: What are bin_PROGRAMS. hello_SOURCES and VPATH. No description
is provided.
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

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

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

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

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
art