[PATCH] Update docs w.r.t. warning and strictness options.

[Stefano Lattarini]

And here finally is the promised documentation patch, which should
conclude the patch series (this time for good, I hope!).

Thanks, and sorry for the delay,
   Stefano

From 2d902e81c6b2fbb939c8b6a3d1c744dfbf03655c Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Fri, 14 Jan 2011 15:18:36 +0100
Subject: [PATCH] Update docs w.r.t. warning and strictness options.

* doc/automake.texi (Strictness): Document that some warnings are
turned off by default in `foreign' strictness.
(Options):  Divide into new sections "Options generalities" and
"List of Automake options".   Fix typo (colon instead of full
stop).  Document option precedence (AUTOMAKE_OPTIONS wins over
AM_INIT_AUTOMAKE which wins over command line).  Also document
interactions between options specifying strictness and those
specifying warnings.
---
 ChangeLog         |   12 +++++++++++
 doc/automake.texi |   58 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 751f1a9..bdb3228 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-01-02  Stefano Lattarini  <address@hidden>
 
+       Update docs w.r.t. warning and strictness options.
+       * doc/automake.texi (Strictness): Document that some warnings are
+       turned off by default in `foreign' strictness.
+       (Options):  Divide into new sections "Options generalities" and
+       "List of Automake options".   Fix typo (colon instead of full
+       stop).  Document option precedence (AUTOMAKE_OPTIONS wins over
+       AM_INIT_AUTOMAKE which wins over command line).  Also document
+       interactions between options specifying strictness and those
+       specifying warnings.
+
+2011-01-02  Stefano Lattarini  <address@hidden>
+
        More checks on warnings/strictness precedence.
        * tests/warning-groups-win-over-strictness.test: New test, similar
        to `warnings-win-over-strictness.test', but checking the explicit
diff --git a/doc/automake.texi b/doc/automake.texi
index 8c98ce8..3e41966 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -320,6 +320,11 @@ Support for test suites
 * DejaGnu Tests::               Interfacing with the external testing framework
 * Install Tests::               Running tests on installed packages
 
+Changing Automake's Behavior
+
+* Options generalities::        Automake options, strictness, and their 
precedence
+* List of Automake options::    A comprehensive list of Automake options
+
 Miscellaneous Rules
 
 * Tags::                        Interfacing to cscope, etags and mkid
@@ -1899,7 +1904,9 @@ The valid strictness levels are:
 Automake will check for only those things that are absolutely
 required for proper operations.  For instance, whereas GNU standards
 dictate the existence of a @file{NEWS} file, it will not be required in
-this mode.  The name comes from the fact that Automake is intended to be
+this mode.  This strictness will also turn off some warnings by default
+(among them, the @samp{portability} warnings).
+The name comes from the fact that Automake is intended to be
 used for GNU programs; these relaxed rules are not the standard mode of
 operation.
 
@@ -9023,8 +9030,16 @@ will now be rerun each time the version number is 
bumped, when only
 @node Options
 @chapter Changing Automake's Behavior
 
address@hidden
+* Options generalities::        Automake options, strictness, and their 
precedence
+* List of Automake options::    A comprehensive list of Automake options
address@hidden menu
+
address@hidden Options generalities
address@hidden Automake options, strictness, and their precedence
+
 Various features of Automake can be controlled by options.  Except where
-noted otherwise, options can be specified in one of several ways: Most
+noted otherwise, options can be specified in one of several ways.  Most
 options can be applied on a address@hidden basis when listed in a
 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}.  Some
 of these options only make sense when specified in the toplevel
@@ -9034,7 +9049,44 @@ of these options only make sense when specified in the 
toplevel
 require changes to the @command{configure} script can only be specified
 there.  These are annotated below.
 
-Currently understood options are:
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
+turn take precedence over those specified on the command address@hidden
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed.  It might be fixed
+in a future Automake version though, so try not to rely on it.}.
+
+Also, some care must be taken about the interactions among strictness
+level and warning categories.  As a general rule, strictness-implied
+warnings are overridden by those specified by explicit options.  For
+example, even if @samp{portability} warnings are disabled by default
+in @option{foreign} strictness, an usage like this:
address@hidden
+AUTOMAKE_OPTIONS = -Wportability foreign
address@hidden example
address@hidden
+will end up being enabling those portability warnings.
+
+However, a strictness level specified in a higher-priority context
+will override all the explicit warnings specified in a lower-priority
+context.  For example, if @file{configure.ac} contains:
address@hidden
+AM_INIT_AUTOMAKE([-Wportability])
address@hidden example
address@hidden
+and @file{Makefile.am} contains:
address@hidden
+AUTOMAKE_OPTIONS = foreign
address@hidden example
address@hidden
+then @samp{portability} warnings will be @emph{disabled} in
address@hidden  This is not an implementation accident,
+but a conscious design choice.
+
address@hidden List of Automake options
address@hidden A comprehensive list of Automake options
+
 @vindex AUTOMAKE_OPTIONS
 
 @table @asis
-- 
1.7.2.3