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 `@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? > > 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 _______________________________________________ bug-gdb mailing list bug-gdb@gnu.org https://lists.gnu.org/mailman/listinfo/bug-gdb