> Date: Thu, 21 Jun 2012 19:18:19 +0200 > From: Patrice Dumas <pertu...@free.fr> > Cc: bug-gdb@gnu.org, k...@freefriends.org > > 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 `@end > > 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. _______________________________________________ bug-gdb mailing list bug-gdb@gnu.org https://lists.gnu.org/mailman/listinfo/bug-gdb