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

[Stefano Lattarini]

On Saturday 15 January 2011, Ralf Wildenhues wrote:
> * 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.
> 
OK, if we don't get through this patch today, I'll push the previous
patches to a public branch (after having fixed the dates in the ChangeLog
entries).

BTW, is the name 'warns-win-over-strictness' acceptable for that branch?

> > 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/:  /: /
>
Fixed (in commit message and in ChangeLog entry alike).

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

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

> Please also rerun emacs ^C ^U ^V before committing, thanks.
>
You mean ^C ^U ^A, right?

> > +* 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/
>
Fixed.

> > +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"?
>
I chose the name above only for consistency with the menu entries.
If you tell me this consistency is not needed, I heartily agree with
your proposed renaming, which makes things clearer IMHO.

> >  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.
>
Wait, IMVHO this fix cannot just be in the next automake release
without a clear deprecation of the older behaviour first.  The
backward-incompatibility would be too great and sharp otherwise.

The right thing to do (again IMVHO) is implement the fix in a proper
master-based branch, and merge it back into master only after automake
1.12 has been released.  WDYT?

> 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.
>
Before discussing about this any further, I'll wait for a reply to my
argumentation above.

> > +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).
>
Oh, sorry.  I just copied and pasted from some pre-existing code,
which lacks such spacing.

> More instances below.
>
Fixed those too.

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

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

> > address@hidden List of Automake options
> > address@hidden A comprehensive list of Automake options
> >
This @section should be renamed as "List of Automake options", right?

> >  @vindex AUTOMAKE_OPTIONS
> >  
> >  @table @asis
> 
> OK with all of those addressed.
> 
> Thanks,
> Ralf
> 

Thanks,
   Stefano