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

[Ralf Wildenhues]

* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 02:23:56PM CET:
> 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?

Sure.

I have an intended use case where it might not be ideal that warnings
win over other options, by the way.  I hope to be able to finish the
gnu-make writeup tomorrow (where it happens).

> > > --- a/doc/automake.texi
> > > +++ b/doc/automake.texi

> > * Options generalities::        Semantics of Automake options
> >
> OK.
> 
> > Please also rerun emacs ^C ^U ^V before committing, thanks.
> >
> You mean ^C ^U ^A, right?

Yes, sorry.

> > > @@ -9023,8 +9030,16 @@ will now be rerun each time the version number is 
> > > bumped, when only

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

OK.

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

Hmm.  I would prefer to delay this decision until we have to cross that
bridge; i.e.:
- before we release 1.11.2, we should think about deprecation again,
- when we have a patch to change precedence, we can try to evaluate how
  disruptive it is, and then decide whether it can go in 1.12 or 1.13.

But anyway I don't want behavior that we want to change be documented
and thus set in stone in the manual now, if it previously hasn't been
documented.  So, can we please decouple these things from the patch
series we are discussing here?

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


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

Indeed.  I'll fix them in maint presently.

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

Yep.

Thanks!
Ralf