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

[Ralf Wildenhues]

* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 12:41:16PM CET:
> 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,

No problem.  Let's see if we can get through it quickly.

I think you should not let the remainder of the patch series have to
wait for this, though.

> 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

s/:  /: /

> "List of Automake options".   Fix typo (colon instead of full

s/   /  /

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

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

info output should not exceed 80 characters (probably not 79, haven't
checked), this line is too long.  How about this instead?

* Options generalities::        Semantics of Automake options

Please also rerun emacs ^C ^U ^V before committing, thanks.

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

s/the @samp{\(.*\)}/\1/

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

Karl recommends section names to be identical to node names in general.
How about just naming this "Option generalities"?

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

OK until here.

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

No.  We already agreed to fixing this, so we should not document the
broken behavior.  We should fix it instead.  Can we just omit this for
the moment?  Maybe with a
 @comment FIXME: document interaction with command-line args when fixed.

if you prefer that.

> +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:

s/an usage like//
(but see below)

> address@hidden
> +AUTOMAKE_OPTIONS = -Wportability foreign
> address@hidden example
> address@hidden
> +will end up being enabling those portability warnings.

s/being //

Empty lines before @example and after @end example, and before
@noindent (the last two should be collapsed to just one).
More instances below.

In this particular case, I'd just move the half-sentence up between
"this" and ":" above.

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

The last sentence should be deleted.  Everything that is documented is
not an accident by default, unless noted otherwise.  You'd have to add
thousands of such notes to the manual.

> address@hidden List of Automake options
> address@hidden A comprehensive list of Automake options
> +
>  @vindex AUTOMAKE_OPTIONS
>  
>  @table @asis

OK with all of those addressed.

Thanks,
Ralf