[RFC] document Cygwin native specific commands

[RFC] document Cygwin native specific commands

[Pierre Muller]

    Here is a third version of my patch to document 
Cygwin native specific commands.

2002-02-19  Pierre Muller  <muller@ics.u-strasbg.fr>

           * gdb.texinfo: Document Cygwin native specific commands.



Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.90
diff -u -r1.90 gdb.texinfo
--- gdb.texinfo 2002/02/15 19:06:33     1.90
+++ gdb.texinfo 2002/02/20 12:16:02
@@ -10487,6 +10487,7 @@
  * HP-UX::                       HP-UX
  * SVR4 Process Information::    SVR4 process information
  * DJGPP Native::                Features specific to the DJGPP port
+* Cygwin Native::              Features specific to the Cygwin port
  @end menu

  @node HP-UX
@@ -10683,6 +10684,92 @@
  mapped 1:1, i.e.@: the physical and linear addresses are identical.

  This command is supported only with some DPMI servers.
+@end table
+
+@node Cygwin Native
+@subsection Features for Debugging MS Windows PE executables
+@cindex MS Windows debugging
+@cindex native Cygwin debugging
+@cindex Cygwin-specific commands
+
+@value{GDBN} supports native debugging of MS Windows programs, and
+defines a few commands specific to the Cygwin port.  This
+subsection describes those commands.
+
+@table @code
+@kindex info w32
+@item info w32
+This is a prefix of MS Windows specific commands which print
+information about the target system and important OS structures.
+
+@item info w32 selector
+This command displays information returned by
+the Win32 API @code{GetThreadSelectorEntry} function.
+It takes an optional argument that is evaluated to
+a long value to give the information about this given selector.
+Without argument, this command displays information
+about the the six segment registers.
+
+@kindex info dll
+@item info dll
+This is a Cygwin specific alias of info shared.
+
+@kindex dll-symbols
+@item dll-symbols
+This command loads symbols from a dll similarly to
+add-sym command but without the need to specify a base address.
+
+@kindex set new-console
+@item set new-console @var{mode}
+If @var{mode} is @code{on} the debuggee will
+be started in a new console on next start.
+If @var{mode} is @code{off}i, the debuggee will
+be started in the same console as the debugger.
+
+@kindex show new-console
+@item show new-console
+Displays whether a new console is used
+when the debuggee is started.
+
+@kindex set new-group
+@item set new-group @var{mode}
+This boolean value controls whether the debuggee should
+start a new group or stay in the same group as the debugger.
+This affects the way the Windows OS handles
+Ctrl-C.
+
+@kindex show new-group
+@item show new-group
+Displays current value of new-group boolean.
+
+@kindex set debugevents
+@item set debugevents
+This boolean value adds debug output concerning events seen by the debugger.
+
+@kindex set debugexec
+@item set debugexec
+This boolean value adds debug output concerning execute events
+seen by the debugger.
+
+@kindex set debugexceptions
+@item set debugexceptions
+This boolean value adds debug ouptut concerning exception events
+seen by the debugger.
+
+@kindex set debugmemory
+@item set debugmemory
+This boolean value adds debug ouptut concerning memory events
+seen by the debugger.
+
+@kindex set shell
+@item set shell
+This boolean values specifies whether the debuggee is called
+via a shell or directly (default value is on).
+
+@kindex show shell
+@item show shell
+Displays if the debuggee will be started with a shell.
+
  @end table

  @node Embedded OS



Pierre Muller
Institut Charles Sadron
6,rue Boussingault
F 67083 STRASBOURG CEDEX (France)
mailto:muller@ics.u-strasbg.fr
Phone : (33)-3-88-41-40-07  Fax : (33)-3-88-41-40-99

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

On Wed, 20 Feb 2002, Pierre Muller wrote:

>     Here is a third version of my patch to document 
> Cygwin native specific commands.

Thanks, I'm happy now ;-)

Re: [RFC] document cygwin native specific commands

[Christopher Faylor]

On Wed, Feb 20, 2002 at 03:15:43PM +0200, Eli Zaretskii wrote:
>On Wed, 20 Feb 2002, Pierre Muller wrote:
>>     Here is a third version of my patch to document 
>> Cygwin native specific commands.
>
>Thanks, I'm happy now ;-)

Me too.  Please check it in.

cgf

Re: [RFC] document cygwin native specific commands

[Pierre Muller]

At 16:58 20/02/2002 , vous avez écrit:
>On Wed, Feb 20, 2002 at 03:15:43PM +0200, Eli Zaretskii wrote:
> >On Wed, 20 Feb 2002, Pierre Muller wrote:
> >>     Here is a third version of my patch to document 
> >> Cygwin native specific commands.
> >
> >Thanks, I'm happy now ;-)
>
>Me too.  Please check it in.

Done, thanks.



Pierre Muller
Institut Charles Sadron
6,rue Boussingault
F 67083 STRASBOURG CEDEX (France)
mailto:muller@ics.u-strasbg.fr
Phone : (33)-3-88-41-40-07  Fax : (33)-3-88-41-40-99

[RFC] document Cygwin native specific commands

[Pierre Muller]

   Here is a second version of my patch to document 
Cygwin native specific commands.

I have no experience with texinfo ...
I still don't know what the difference between @kindex and @cindex is :(

2002-02-19  Pierre Muller  <muller@ics.u-strasbg.fr>

          * gdb.texinfo: Document Cygwin native specifc commands.



Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.90
diff -u -r1.90 gdb.texinfo
--- gdb.texinfo	2002/02/15 19:06:33	1.90
+++ gdb.texinfo	2002/02/19 09:27:41
@@ -10487,6 +10487,7 @@
  * HP-UX::                       HP-UX
  * SVR4 Process Information::    SVR4 process information
  * DJGPP Native::                Features specific to the DJGPP port
+* Cygwin Native::		Features specific to the Cygwin port
  @end menu
  
  @node HP-UX
@@ -10683,6 +10684,79 @@
  mapped 1:1, i.e.@: the physical and linear addresses are identical.
  
  This command is supported only with some DPMI servers.
+@end table
+
+@node Cygwin Native
+@subsection Features for Debugging @sc{win32} PE executables
+@cindex @sc{win32} debugging
+@cindex native Cygwin debugging
+@cindex Win32-specific commands
+
+@value{GDBN} supports native debugging of @sc{win32} programs, and
+defines a few commands specific to the Cygwin port.  This
+subsection describes those commands.
+
+@table @code
+@kindex info w32
+@item info w32
+This is a prefix of @sc{win32}-specific commands which print
+information about the target system and important OS structures.
+
+@kindex selector
+@cindex @sc{win32} selector info
+@item info w32 selector
+This command displays information returned by
+the Win32 API @code{GetThreadSelectorEntry} function.
+It takes an optional argument that is evaluated to
+a long value to give the information about this given selector.
+Without argument, this command displays information
+about the the six segment registers.
+
+@kindex dll
+@item info dll
+This is an alias of info shared.
+
+@kindex dll-symbols
+@item dll-symbols
+This command loads symbols from a dll similarly to
+add-sym command but without the need to specify a base address.
+
+@kindex new-console
+@item set new-console
+This boolean value controls whether the debuggee should
+be started in a new console or in the same console as the debugger.
+
+@kindex new-group
+@item set new-group
+This boolean value controls whether the debuggee should
+start a new group or stay in the same group as the debugger.
+This affects the way the Windows OS handles
+Ctrl-C.
+
+@kindex debugevents
+@item set debugevents
+This boolean value adds debug output concerning events seen by the debugger.
+
+@kindex debugexec
+@item set debugexec
+This boolean value adds debug output concerning execute events 
+seen by the debugger.
+
+@kindex debugexceptions
+@item set debugexceptions
+This boolean value adds debug ouptut concerning exception events 
+seen by the debugger.
+
+@kindex debugmemory
+@item set debugmemory
+This boolean value adds debug ouptut concerning memory events 
+seen by the debugger.
+
+@kindex shell
+@item set shell
+This boolean values specifies whether the debugge is called
+via a shell or directly.
+
  @end table
  
  @node Embedded OS



Pierre Muller
Institut Charles Sadron
6,rue Boussingault
F 67083 STRASBOURG CEDEX (France)
mailto:muller@ics.u-strasbg.fr
Phone : (33)-3-88-41-40-07  Fax : (33)-3-88-41-40-99

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

> Date: Tue, 19 Feb 2002 10:31:37 +0100
> From: Pierre Muller <muller@cerbere.u-strasbg.fr>
> 
> I have no experience with texinfo ...

Don't worry, that's what I'm here for ;-)

> I still don't know what the difference between @kindex and @cindex is :(

The GDB manual uses @kindex to put all the GDB commands into a
separate index, while @cindex entries go into the Concept Index.
Right now, this line near the beginning of gdb.texinfo:

    @syncodeindex ky cp

causes the @kindex entries to be printed together with the @cindex
entries.  But it is enough to remove that line to cause them to be in
2 different indices.

So whenever you want to add an index entry for a command, please
always put it into @kindex.

> +@node Cygwin Native
> +@subsection Features for Debugging @sc{win32} PE executables
> +@cindex @sc{win32} debugging
> +@cindex native Cygwin debugging
> +@cindex Win32-specific commands

As I said earlier, I'd really prefer that you say "Windows
applications" or "native Windows debugging", instead of using
"win32".

Otherwise, this can go in, as far as I'm concerned.

Re: [RFC] document Cygwin native specific commands

[Andrew Cagney]

> 
> As I said earlier, I'd really prefer that you say "Windows
> applications" or "native Windows debugging", instead of using
> "win32".
> 

Yes, Eli is correct here.  It is like using ``GNU/Linux'' or ``Linux 
kernel'' in documentation and comments.

Andrew

Re: [RFC] document Cygwin native specific commands

[Andrew Cagney]

> 
> The GDB manual uses @kindex to put all the GDB commands into a
> separate index, while @cindex entries go into the Concept Index.
> Right now, this line near the beginning of gdb.texinfo:
> 
>     @syncodeindex ky cp
> 
> causes the @kindex entries to be printed together with the @cindex
> entries.  But it is enough to remove that line to cause them to be in
> 2 different indices.

Hmm.  Given a dump of all of GDB's commands, should there be a kindex 
for each?  What about the reverse?

I think we might have just stumbled across something that is feasible 
for the ARI to check.

enjoy,
Andrew

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

> Date: Tue, 19 Feb 2002 11:37:35 -0500
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> Hmm.  Given a dump of all of GDB's commands, should there be a kindex 
> for each?

Yes, each command described in the manual should be indexed.  That
way, all users need to type to find the documentation of any given
command CMD is "i CMD <RET>", once they are in an Info reader.

The issue of undocumented commands came up several times in the past,
with Stan reminding us, time and again, a threat to remove any
undocumented commands from the code ;-)

> What about the reverse?

I don't understand the question, sorry.

> I think we might have just stumbled across something that is feasible 
> for the ARI to check.

A good idea, IMHO.  Perhaps it could also comment out any command
that doesn't have documentation ;-)

Re: [RFC] document Cygwin native specific commands

[Andrew Cagney]

> Date: Tue, 19 Feb 2002 11:37:35 -0500
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> Hmm.  Given a dump of all of GDB's commands, should there be a kindex 
>> for each?
> 
> 
> Yes, each command described in the manual should be indexed.  That
> way, all users need to type to find the documentation of any given
> command CMD is "i CMD <RET>", once they are in an Info reader.
> 
> The issue of undocumented commands came up several times in the past,
> with Stan reminding us, time and again, a threat to remove any
> undocumented commands from the code ;-)

I've now got something tangable to work with ...

>> What about the reverse?
> 
> 
> I don't understand the question, sorry.


Should, for every @kindex, there be a corresponding command?  I suspect 
this is half correct.  A quick grep came up with things like ``@kindex 
PageUp''.  So that not only undocumented commands but also commands that 
have been removed can be detected - remember the discovery MichaelS made 
with

>> I think we might have just stumbled across something that is feasible 
>> for the ARI to check.
> 
> 
> A good idea, IMHO.  Perhaps it could also comment out any command
> that doesn't have documentation ;-)

How about I make them disabled but allow the user to re-enable them once 
the've entered documentation at a prompt? :-)
	
Andrew

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

On Tue, 19 Feb 2002, Andrew Cagney wrote:

> Should, for every @kindex, there be a corresponding command?

Yes.

> I suspect 
> this is half correct.  A quick grep came up with things like ``@kindex 
> PageUp''.

PageUp is not necessarily a Bad Thing: it's something you type when you 
interact with GDB.  But other things, like getDebugChar, should not be in 
@kindex.

Re: [RFC] document Cygwin native specific commands

[Pierre Muller]

At 18:26 19/02/2002 , Eli Zaretskii a écrit:
> > Date: Tue, 19 Feb 2002 11:37:35 -0500
> > From: Andrew Cagney <ac131313@cygnus.com>
> > 
> > Hmm.  Given a dump of all of GDB's commands, should there be a kindex 
> > for each?
>
>Yes, each command described in the manual should be indexed.  That
>way, all users need to type to find the documentation of any given
>command CMD is "i CMD <RET>", once they are in an Info reader.

Sorrry, Eli, but I don't really understand what I should do here.

Thus I looked at the subsection above concerning DJGPP
specific commands, but there I find a kindex entry
for :
   "info dos" 
"sysinfo"
but nothing for ldt gdt idt  dos subcommands....
Shouldn't there be
@kindex info dos
...
@kindex info dos sysinfo
...
@kindex info dos ldt
@kindex info dos gdt
@kindex info dos idt
?????

In my code I added a 
@kindex shell
but there is a 
"shell" command
and I was documenting 
"set shell" Cygwin specifc command....

So 
  -- should I use 
  @kindex set shell
?
-- shouldn't in be a w32 subcommand ?
but is this possible for set/show commands ?



Pierre Muller
Institut Charles Sadron
6,rue Boussingault
F 67083 STRASBOURG CEDEX (France)
mailto:muller@ics.u-strasbg.fr
Phone : (33)-3-88-41-40-07  Fax : (33)-3-88-41-40-99

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

On Wed, 20 Feb 2002, Pierre Muller wrote:

> Thus I looked at the subsection above concerning DJGPP
> specific commands, but there I find a kindex entry
> for :
>    "info dos" 
> "sysinfo"
> but nothing for ldt gdt idt  dos subcommands....
> Shouldn't there be
> @kindex info dos
> ...
> @kindex info dos sysinfo
> ...
> @kindex info dos ldt
> @kindex info dos gdt
> @kindex info dos idt
> ?????

I didn't include the subcommands on purpose.  The reason is that it is 
not useful to have several index entries that all begin with the same 
string and point to the same page in the manual.  That is why I only 
indexed "info dos".

So I guess my assertion about ``every command'' should have been 
qualified by this exception.  Sorry for confusion.

> So 
>   -- should I use 
>   @kindex set shell
> ?

Yes.  That is how all "set ..." commands are indexed in the manual, 
AFAICS.

> -- shouldn't in be a w32 subcommand ?

Sorry, I don't understand: the command is "set shell", not "set w32 shell", 
right?  If so, you should have "@kindex set shell".

> but is this possible for set/show commands ?

Is what possible?

Re: [RFC] document Cygwin native specific commands

[Pierre Muller]

At 12:18 20/02/2002 , Eli Zaretskii a écrit:

>On Wed, 20 Feb 2002, Pierre Muller wrote:
>
> > Thus I looked at the subsection above concerning DJGPP
> > specific commands, but there I find a kindex entry
> > for :
> >    "info dos" 
> > "sysinfo"
> > but nothing for ldt gdt idt  dos subcommands....
> > Shouldn't there be
> > @kindex info dos
> > ...
> > @kindex info dos sysinfo
> > ...
> > @kindex info dos ldt
> > @kindex info dos gdt
> > @kindex info dos idt
> > ?????
>
>I didn't include the subcommands on purpose.  The reason is that it is 
>not useful to have several index entries that all begin with the same 
>string and point to the same page in the manual.  That is why I only 
>indexed "info dos".
>
>So I guess my assertion about ``every command'' should have been 
>qualified by this exception.  Sorry for confusion.

But why did you kindex sysinfo and not the other ones?

> > So 
> >   -- should I use 
> >   @kindex set shell
> > ?
>
>Yes.  That is how all "set ..." commands are indexed in the manual, 
>AFAICS.

OK!

> > -- shouldn't in be a w32 subcommand ?
>
>Sorry, I don't understand: the command is "set shell", not "set w32 shell", 
>right?  If so, you should have "@kindex set shell".

No I was asking if this "set shell " command
should not be replaced by a "set w32 shell" command.
But I am not sure how this could be done...
because add_show_from_set and add_set_cmd are
special functions.




Pierre Muller
Institut Charles Sadron
6,rue Boussingault
F 67083 STRASBOURG CEDEX (France)
mailto:muller@ics.u-strasbg.fr
Phone : (33)-3-88-41-40-07  Fax : (33)-3-88-41-40-99

Re: [RFC] document Cygwin native specific commands

[Eli Zaretskii]

On Wed, 20 Feb 2002, Pierre Muller wrote:

> But why did you kindex sysinfo and not the other ones?

Because `sysinfo' is a term people might look up in the index.  There are 
programs by that name on various DOS/Windows systems.  In other words, it 
is simply a word I thought someone could look for.
> No I was asking if this "set shell " command
> should not be replaced by a "set w32 shell" command.

Maybe, I don't know.  It's something Christopher should decide, I think.

Re: [RFC] document cygwin native specific commands

[Christopher Faylor]

On Wed, Feb 20, 2002 at 03:15:06PM +0200, Eli Zaretskii wrote:
>
>On Wed, 20 Feb 2002, Pierre Muller wrote:
>
>> But why did you kindex sysinfo and not the other ones?
>
>Because `sysinfo' is a term people might look up in the index.  There are 
>programs by that name on various DOS/Windows systems.  In other words, it 
>is simply a word I thought someone could look for.
>> No I was asking if this "set shell " command
>> should not be replaced by a "set w32 shell" command.
>
>Maybe, I don't know.  It's something Christopher should decide, I think.

Sorry.  I missed the question.

No.  It shouldn't be a "w32" command.  I approved the w32 sub-part
because I thought it had a distinct meaning.  In your use you were
providing info on data that came straight from Windows.  The "set shell"
command has nothing specifically to do with "w32".

If we were going to be really pedantic about it, we could add a "set cygwin ..."
command, I suppose.  I don't see any reason to impose that extra level
of keywords on a user.  If we did that then presumably all of cygwin gdb's
extra commands should go under "set cygwin ...".

cgf

Re: [RFC] document cygwin native specific commands

[Eli Zaretskii]

> Date: Wed, 20 Feb 2002 10:57:40 -0500
> From: Christopher Faylor <cgf@redhat.com>
> 
> I don't see any reason to impose that extra level of keywords on a
> user.

Yes, I agree.

Re: [RFC] document cygwin native specific commands

[Christopher Faylor]

On Tue, Feb 19, 2002 at 03:22:16PM +0200, Eli Zaretskii wrote:
>> +@node Cygwin Native
>> +@subsection Features for Debugging @sc{win32} PE executables
>> +@cindex @sc{win32} debugging
>> +@cindex native Cygwin debugging
>> +@cindex Win32-specific commands
>
>As I said earlier, I'd really prefer that you say "Windows
>applications" or "native Windows debugging", instead of using
>"win32".

How about MS Windows, just to be clear?  It's always bugged me
that MS abrogated the name Windows for their own use.

>Otherwise, this can go in, as far as I'm concerned.

Ditto.  As always, thanks very much for doing this, Pierre.

cgf

Re: [RFC] document cygwin native specific commands

[Eli Zaretskii]

> Date: Tue, 19 Feb 2002 12:10:19 -0500
> From: Christopher Faylor <cgf@redhat.com>
> >
> >As I said earlier, I'd really prefer that you say "Windows
> >applications" or "native Windows debugging", instead of using
> >"win32".
> 
> How about MS Windows, just to be clear?

Sure, that's good.