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 > > > > +@menu > > +* Options generalities:: Automake options, strictness, and their > > precedence > > +* List of Automake options:: A comprehensive list of Automake options > > +@end menu > > + > > +@node Options generalities > > +@section 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 per-@file{Makefile} 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 line@footnote{ > > +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) > > > +@example > > +AUTOMAKE_OPTIONS = -Wportability foreign > > +@end example > > +@noindent > > +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: > > +@example > > +AM_INIT_AUTOMAKE([-Wportability]) > > +@end example > > +@noindent > > +and @file{Makefile.am} contains: > > +@example > > +AUTOMAKE_OPTIONS = foreign > > +@end example > > +@noindent > > +then @samp{portability} warnings will be @emph{disabled} in > > +@file{Makefile.am}. 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. > > +@node List of Automake options > > +@section 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