Re: warnings with cvs texinfo version

[Eli Zaretskii]

> Date: Thu, 21 Jun 2012 15:50:29 +0200
> From: Patrice Dumas <address@hidden>
> Cc: address@hidden, address@hidden
> 
> On Thu, Jun 21, 2012 at 05:52:55AM +0300, Eli Zaretskii wrote:
> > 
> > > ./gdb.texinfo:22939: warning: @table has text but no @item
> > 
> > Why is this warning needed?
> 
> This one is clear to me.  A @table without @item does not make sense.  A
> @table specifies a series of headings and associated texts, so a @table 
> without @item has no reason to be.  I don't think this warning should be
> ignored.  Maybe use @group?  Or @quotation?

IMO, this is wrong in principle.  It is not makeinfo's business to
force style on the author of the manual.  Warnings should only be
emitted when the produced manual is in bad shape.  This isn't such a
case, so the warning is IMO gratuitous.  If you want a pedantic mode
(which could be a useful feature), please make it optional.

> What are you searching for with those empty tables?

Indentation and consistent format of describing GDB features.

> > > ./gdb.texinfo:35330: warning: @item missing argument
> > 
> > And this one?
> 
> @table is for a succession of headings and text.  An empty item means
> no heading and thus is not suitable.

It doesn't come out empty in the output.  Did you look at that?  It
produces this:

  `'

which stands for an empty response.  If you know of any other way of
getting the same in a @samp typeface, please tell.

> I agree that it may make sense as a separator, to control the
> presentation, but the general idea is that Texinfo should not be
> used as a presentational markup, but instead as a descriptive
> markup, hence this warning.

Again, this is wrong philosophy.  This warning should at least be
turned off by default.

> You can always ignore that warning, though.

Extra noise runs the risk of obscuring real problems.

> > > ./gdb.texinfo:190: warning: @contents should only appear at beginning or 
> > > end of document
> > 
> > That @contents _is_ at the beginning.  What's the issue here?
> 
> It is not at the very beginning, instead, it appears at the end of the 
> top node and element.  At the beginning would mean before 
> @node Top

But the Texinfo manual documents no such restriction.  It says only
this:

    Both contents commands should be written on a line by themselves, and
  are best placed near the beginning of the file, after the address@hidden
  titlepage' (*note titlepage::).

This is clearly an advisory, not a requirement.  So I don't think a
warning is called for.

> You can ignore this warning, though.

I don't want to ignore warnings.  Please don't introduce warnings that
should be ignored.