[RFA] Doc for "maint info sections" command

[RFA] Doc for "maint info sections" command

[Michael Snyder]

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

Michael

2001-12-26  Michael Snyder  <msnyder@redhat.com>

	* gdb.texinfo (maint info sections): Document.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.59
diff -c -3 -p -r1.59 gdb.texinfo
*** gdb.texinfo	2001/11/30 23:03:09	1.59
--- gdb.texinfo	2001/12/26 19:05:14
*************** use by @value{GDBN}, and the files from 
*** 9347,9352 ****
--- 9347,9376 ----
  command @code{help target} lists all possible targets rather than
  current ones.
  
+ @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
+ @item ALLOBJ
+ Display sections for all loaded object files, including shared libraries.
+ @kindex maint info sections @samp{<section name(s)>}
+ @item @samp{<section name(s)>}
+ Display info only for section(s) matching the listed name(s).
+ @kindex maint info sections @samp{<section flag(s)>}
+ @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
+ 
  @end table
  
  All file-specifying commands allow both absolute and relative file names

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

[Eli Zaretskii]

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

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

[Michael Snyder]

[-- Attachment #1: Type: text/plain, Size: 417 bytes --]

Eli Zaretskii wrote:
> 
> 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:

Great, thanks for the suggestions.  How's this?

[-- Attachment #2: allobj2.patch --]
[-- Type: text/plain, Size: 2446 bytes --]

2001-12-26  Michael Snyder  <msnyder@redhat.com>

	* gdb.texinfo (maint info sections): Document.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.60
diff -c -3 -p -r1.60 gdb.texinfo
*** gdb.texinfo	2001/12/27 18:41:40	1.60
--- gdb.texinfo	2001/12/27 18:59:21
*************** use by @value{GDBN}, and the files from 
*** 9347,9352 ****
--- 9347,9399 ----
  command @code{help target} lists all possible targets rather than
  current ones.
  
+ @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
+ @item ALLOBJ
+ Display sections for all loaded object files, including shared libraries.
+ @item @var{sections}
+ Display info only for named var{sections}.
+ @item @var{section-flags}
+ Display info only for sections for which @var{section-flags} are true.
+ The section flags that @value{GDBN} currently knows about are:
+ @table @code
+ @item ALLOC
+ Section will have space allocated in the process when loaded.
+ Set for all sections except those containing debug information.
+ @item LOAD
+ Section will be loaded from the file into the child process memory.
+ Set for pre-initialized code and data, clear for .bss sections.
+ @item RELOC
+ Section needs to be relocated before loading.
+ @item READONLY
+ Section cannot be modified by the child process.
+ @item CODE
+ Section contains executable code only.
+ @tem DATA
+ Section contains data only (no executable code).
+ @item ROM
+ Section will reside in ROM.
+ @item CONSTRUCTOR
+ Section contains data for constructor/destructor lists.
+ @item HAS_CONTENTS
+ Section is not empty.
+ @item NEVER_LOAD
+ An instruction to the linker to not output the section.
+ @item COFF_SHARED_LIBRARY
+ A notification to the linker that the section contains
+ COFF shared library information.
+ @item IS_COMMON
+ Section contains common symbols.
+ @end table
+ @end table
  @end table
  
  All file-specifying commands allow both absolute and relative file names

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

[Eli Zaretskii]

> Date: Thu, 27 Dec 2001 10:56:32 -0800
> From: Michael Snyder <msnyder@redhat.com>
> 
> Great, thanks for the suggestions.  How's this?

Approved, thanks.  Please make .bss have the @code markup, and this
can go in.

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

[Michael Snyder]

Eli Zaretskii wrote:
> 
> > Date: Thu, 27 Dec 2001 10:56:32 -0800
> > From: Michael Snyder <msnyder@redhat.com>
> >
> > Great, thanks for the suggestions.  How's this?
> 
> Approved, thanks.  Please make .bss have the @code markup, and this
> can go in.

Committed.