Re: warnings with cvs texinfo version

[Patrice Dumas]

On Thu, Jun 21, 2012 at 10:51:16PM +0300, Eli Zaretskii wrote:
> 
> That demand would be satisfied by an optional warning.  E.g., like
> with GCC's -Wfoo switches.
> 
> > As to whether this means that the manual is in bad shape, I would be
> > tempted to say that it is the case.
> 
> Here's the output that "empty" table produces:
>
> ...
> 
> Do you see anything "bad shape" here?  I don't.

You missed my point.  The manual is formatted fine, but since it uses an
undocummented Texinfo feature it is in a bad shape Texinfo-wise and the
formatting could change in the future, more or less drastically.

> If you make such backwards incompatible changes in behavior, people
> will complain, and rightly so.

Not rightly.  Undocumented features should not be counted on.
 
> How is an empty argument to @w any better than an empty @item?  One
> day someone might even decide that such empty arguments to @w "don't
> make sense", and will produce a warning for that, too.

Sure, unless the fact that an empty @item is wrong but an @item with an
empty @w{} is correct is documented in the manual, in which case it
becomes 'set in stone' that this is a correct construct.

> The GDB manual has been using this form for a very long time now.  So
> long that it could definitely be considered an established de-facto
> practice.

I don't think so.  It instead shows that we need to state precisely if
it is correct or not.

> > Should that be documented?
> 
> Not sure what you suggest to document.

I suggest to document the correct constructs, such that expectations are
precise on what should lead to a warning or not.

> A user-friendly tool lets users do whatever they want, so long as the
> result is to users' liking.  If I learned anything from the days back
> when I was hacking makeinfo, it's that users will use the tools in
> every imaginable way and some unimaginable ones.  Restricting them or
> annoying them with gratuitous messages, without a very good reason, is
> just annoyance.

I interpret your point in the exact opposite direction.  To me, the fact
that 'users will use the tools in every imaginable way and some
unimaginable ones' means that users should only have expectations on the
documented features, and that we may want to precise the right ways
at any time.

> > I am not sure, as the output may not be what the writer intended.
> 
> It is today.

For you in Info.  But not necessarily for everybody in every format.
For instance, the docbook produced is invalid.  It is not clear to me
that what comes before the first item should be indented or not.

> > Again, the empty @item line could either be ignored, or be considered as
> > an empty line depending on the formatter.
> 
> makeinfo never did such things, and IMO it never should.

If changes are relevant, for constructs that were previously
undocumented, makeinfo may change its output.
 
> > This has changed, now the text is:
> > 
> >  Both contents commands should be written on a line by themselves, and
> >  placed near the beginning of the file, after the @code{@@end
> >  titlepage} (@pxref{titlepage,,@code{@@titlepage}}), before any
> >  sectioning command.  The contents commands automatically generate a
> >  chapter-like heading at the top of the first table of contents page,
> >  so don't include any sectioning command such as @code{@@unnumbered}
> >  before them.
> > 
> > Maybe this could be clearer?
> 
> This is clear enough, but it's still doesn't contradict having
> @contents after @top, because @top is not a sectioning command.

For me, it is.  Maybe that could be clearer.

> Again, limitations should have a good reason.  What harm will having
> @contents after @top do?  If there's no harm, then please don't annoy
> users by warnings that don't have a solid reason.

In TeX it doesn't work.  If you look at the manual, the @top is in an
@ifnottex block, but the idea is that the rule about @contents should
not depend on the output format.

> > There is a balance between having more warnings to warn users that have
> > made mistakes and having less warnings to let the user have more
> > freedom, and where the cursor is is mostly arbitrary: you'll always 
> > help some users and piss off others.  Nowadays, there are more and more 
> > warnings added.  Personnally, I don't care much, Karl is the one
> > deciding on that in general.
> 
> Well, I surely hope Karl will reconsider.  Because I think this policy
> will bring nothing but complaints and aggravation.

I think that it depends whether there is a way to get things right or
not.  For @contents, it is rather easy, as it may be moved before
sections in any format -- although the output in html and plaintext will
be different.

For the empty @item issue, using @w{} or something like that may be a
possible solution.

For the indentation provided by an empty @table, I have no idea for now.

-- 
Pat