Re: warnings with cvs texinfo version

[Eli Zaretskii]

> Date: Thu, 21 Jun 2012 19:18:19 +0200
> From: Patrice Dumas <address@hidden>
> Cc: address@hidden, address@hidden
> 
> On Thu, Jun 21, 2012 at 07:15:47PM +0300, Eli Zaretskii wrote:
> > > 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.
> 
> This warning was primarily done to help writers avoid mistakes, after a
> user demand (if I recall well).

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:

   The following attributes are provided:

      -- Variable: Value.address
          If this object is addressable, this read-only attribute holds
          a `gdb.Value' object representing the address.  Otherwise,
          this attribute holds `None'.

      -- Variable: Value.is_optimized_out
          This read-only boolean attribute is true if the compiler
          optimized out this value, thus it is not available for
          fetching from the inferior.

      -- Variable: Value.type
          The type of this `gdb.Value'.  The value of this attribute is
          a `gdb.Type' object (*note Types In Python::).

Do you see anything "bad shape" here?  I don't.

> The presentation of the text appearing before the first @item could
> be formatted differently from the text appearing after the first @item,
> so you cannot rely on having the presentation you want in the future.
> It could even be discarded, be considered as a 'meta-data' (the table
> title?).  This is left unspecified for now in the manual such that we 
> can give any meaning to this text in the future.

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

> > It doesn't come out empty in the output.  Did you look at that?  It
> > produces this:
> > 
> >   `'
> 
> Indeed, I missed it.
>  
> > which stands for an empty response.  If you know of any other way of
> > getting the same in a @samp typeface, please tell.
> 
> There is, for example:
> 
>   @item @w{}

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.

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.

> However if the table is formatted with @asis, there is no output.

That's true, but this is not an @asis table.  If you want to limit
this warning to @asis, I'd be fine with that.

> Should that be documented?

Not sure what you suggest to document.

> > > 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 is not a wrong philosophy, in my opinion this is the philosophy 
> behind Texinfo.

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.

> > This warning should at least be turned off by default.
> 
> I am not sure, as the output may not be what the writer intended.

It is today.

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

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

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.

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