Re: warnings with cvs texinfo version

[Patrice Dumas]

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).  As to whether this means that the
manual is in bad shape, I would be tempted to say that it is the case.
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.  Such text should not 
be used in the mean time, in my opinion.

That being said, I agree with you that there is no easy way to have a
consistent presentation as @quotation that would be more logical, at
least in TeX leads to different left margin.  Any idea, Karl?

> Indentation and consistent format of describing GDB features.

Ok.

> 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{}

However if the table is formatted with @asis, there is no output.  In 
that case, using, for instance, @w{ }, leads to a line passed.  Having
this difference may not be optimal, though.

Should that be documented?

> > 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.  I found that in the history of Texinfo (by chance):

   A bit of history: in the 1970's at CMU, Brian Reid developed a program
 and format named Scribe to mark up documents for printing.  It used the
 `@' character to introduce commands, as Texinfo does.  Much more
 consequentially, it strove to describe document contents rather than
 formatting, an idea wholeheartedly adopted by Texinfo.

> This warning should at least be turned off by default.

I am not sure, as the output may not be what the writer intended.
Again, the empty @item line could either be ignored, or be considered as
an empty line depending on the formatter.  The fact that empty @item 
lines should not be used is not said in the manual, though.

> > You can always ignore that warning, though.
> 
> Extra noise runs the risk of obscuring real problems.

Agreed.

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

> > You can ignore this warning, though.
> 
> I don't want to ignore warnings.  Please don't introduce warnings that
> should be ignored.

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.

-- 
Pat