Re: [RFA] Doc for "maint info sections" command

[Eli Zaretskii <eliz@is.elta.co.il>]

On Wed, 26 Dec 2001, Michael Snyder wrote:

> I haven't tested this, and I'm not sure whether the @table operator
> can be nested?

Yes, @table can be nested.

> 2001-12-26  Michael Snyder  <msnyder@redhat.com>
> 
> 	* gdb.texinfo (maint info sections): Document.

Thanks for writing this up.  I have a few comments:

> + @kindex maint info sections
> + @item maint info sections
> + Another command that can give you extra information about program sections
> + is @code{maint info sections}.  In addition to the section information
> + displayed by @code{info files}, this command displays the flags and file
> + offset of each section in the executable and core dump files.  In addition,
> + @code{maint info sections} provides the following command options (which
> + may be arbitrarily combined):
> + 
> + @table @code
> + @kindex maint info sections ALLOBJ

It is not useful to have several index entries that are so close to
one another and all begin with the same string.  What this produces in
the printed manual is several successive entries in the index that all
point to the same page.

So please leave only the one @kindex maint info sections" above, and
delete the others, which say "kindex maint info sections SOMETHING".

> + @item @samp{<section name(s)>}

Here, "<section name(s)>" is a ``metasyntactic variable'', something
that should be replaced by specific strings from some set of possible
strings.  Metasyntactic variables should have the @var markup in
Texinfo (which upcases them in the Info manual, and produces cursive
font in the printed version).  So here's how I'd suggest to rewrite
the above @item:

  @item @var{sections}

> + Display info only for section(s) matching the listed name(s).

...and then you can refer to @var{sections} in the text, like this:

  Display info only for named @var{sections}.

> + @item @samp{<section flag(s)>}
> + Display info only for sections for which @samp{<section flag(s)>} are true.
> + The section flags that @value{GDBN} currently knows about are @code{ALLOC,
> + LOAD, RELOC, READONLY, CODE, DATA, ROM, CONSTRUCTOR, HAS_CONTENTS, 
> + NEVER_LOAD, COFF_SHARED_LIBRARY,} and @code{IS_COMMON}.
> + @end table

Same here: @var{section-flags} in the @item, and then use
@var{section-flags} in the text.

Also, you will get a warning from makeinfo if you have commas inside
@code; you should do it the hard way: @code{ALLOC}, @code{LOAD}, etc.

Actually, I'd suggest to make the list of flags another @table, and
perhaps explain some of them (ALLOC, CONSTRUCTOR, and HAS_CONTENTS
are those which would leave me wondering, for example).