RFA/doc: couple of small Obj-C documentation tweaks

RFA/doc: couple of small Obj-C documentation tweaks

[Jason Molenda]

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

Hi Eli & Adam,

I was looking at the gdb docs today and saw a couple of small problems 
with the Objective-C section.  OK to commit?


2004-01-06  Jason Molenda  (jmolenda@apple.com)

         * doc/gdb.texinfo (Objective-C): "methodName" typeo.
         Add @code markup around var names from examples.
         Minor cleanup to _NSPrintForDebugger explanation.


[-- Attachment #2: pa.txt --]
[-- Type: text/plain, Size: 1765 bytes --]

2004-01-06  Jason Molenda  (jmolenda@apple.com)

	* doc/gdb.texinfo (Objective-C): "methodName" typeo.
	Add @code markup around var names from examples.
	Minor cleanup to _NSPrintForDebugger explanation.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.185
diff -u -p -r1.185 gdb.texinfo
--- gdb.texinfo	28 Oct 2003 22:04:47 -0000	1.185
+++ gdb.texinfo	7 Jan 2004 01:01:33 -0000
@@ -8484,7 +8484,7 @@ A fully qualified Objective-C method nam
 
 where the minus sign is used to indicate an instance method and a plus
 sign (not shown) is used to indicate a class method. The
-class name @var{Class} and method name @var{methoName} are enclosed in
+class name @var{Class} and method name @var{methodName} are enclosed in
 brackets, similar to the way messages are specified in Objective-C source
 code. For example, to set a breakpoint at the @code{create} instance method of 
 class @code{Fruit} in the program currently being debugged, enter:
@@ -8532,12 +8532,12 @@ print -[object hash]
 @end smallexample
 
 @cindex print an Objective-C object description
-will tell gdb to send the -hash message to object and print the
+will tell gdb to send the @code{hash} message to @code{object} and print the
 result. Also an additional command has been added, @code{print-object}
 or @code{po} for short, which is meant to print the description of an
 object. However, this command may only work with certain Objective-C
-libraries that have a particular hook function, called
-@code{_NSPrintForDebugger} defined.
+libraries that have a particular hook function,
+@code{_NSPrintForDebugger}, defined.
 
 @node Modula-2,  , Objective-C, Support
 @subsection Modula-2

Re: RFA/doc: couple of small Obj-C documentation tweaks

[Adam Fedor]

On Tuesday, January 6, 2004, at 06:34 PM, Jason Molenda wrote:

> Hi Eli & Adam,
>
> I was looking at the gdb docs today and saw a couple of small problems 
> with the Objective-C section.  OK to commit?
>
>
> 2004-01-06  Jason Molenda  (jmolenda@apple.com)
>
>         * doc/gdb.texinfo (Objective-C): "methodName" typeo.
>         Add @code markup around var names from examples.
>         Minor cleanup to _NSPrintForDebugger explanation.
>
>
Yes. Looks OK to me.

Re: RFA/doc: couple of small Obj-C documentation tweaks

[Eli Zaretskii]

> From: Jason Molenda <jmolenda@apple.com>
> Date: Tue, 6 Jan 2004 17:34:21 -0800
> 
> I was looking at the gdb docs today and saw a couple of small problems
> with the Objective-C section.  OK to commit?

Yes, but please correct the following small gotchas while at that:

> @@ -8532,12 +8532,12 @@ print -[object hash]
>  @end smallexample
>  
>  @cindex print an Objective-C object description
> -will tell gdb to send the -hash message to object and print the
> +will tell gdb to send the @code{hash} message to @code{object} and print the

Instead of "gdb" we use "@value{GDBN}" in the manual (so that the
actual name that appears in the produced docs can be changed globally
with a single simple change to the value of GDBN defined at the
beginning of gdb.texinfo).

Also, I'd use @var{object} instead of @code, since "object" is a
placeholder, not a literal string (right?).  "object" in the @example
should also appear in @var.

>  result. Also an additional command has been added, @code{print-object}

There's a comma missing after "Also".  print-object and po need a
@kindex entry, since we index all the GDB commands.

>  or @code{po} for short, which is meant to print the description of an
>  object. However, this command may only work with certain Objective-C
> -libraries that have a particular hook function, called
> -@code{_NSPrintForDebugger} defined.
> +libraries that have a particular hook function,
> +@code{_NSPrintForDebugger}, defined.

I'd also add an index entry for _NSPrintForDebugger here, since
someone, some day might need to look it up.

Finally, it looks like each period that ends a sentence in this
section isn't followed by 2 spaces, as required by the GNU standards.
Could you please fix that as well?

Thanks!

Re: RFA/doc: couple of small Obj-C documentation tweaks

[Jason Molenda]

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

Hi Eli,

Thanks for spotting the additional corrections.  I'm inexperienced with 
texinfo so I want to run the patch past you before I commit.  makeinfo 
and texi2html don't give any warnings when processing this - I believe 
it to be correct.

I re-fmt(1)'ed a couple of paragraphs that got too wide so the diff 
looks larger than it really is.



[-- Attachment #2: pa.txt --]
[-- Type: text/plain, Size: 3582 bytes --]

2004-01-07  Jason Molenda  (jmolenda@apple.com)

	* doc/gdb.texinfo (Objective-C: "methodName" typeo.
	Add @code/@var markup around names, as needed.
	Minor syntax cleanup of _NSPrintForDebugger explanation.
	Two spaces after periods.  GDBN used instead of lit. "gdb".
	Index entries added for print-object and _NSPrintForDebugger.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.185
diff -u -p -r1.185 gdb.texinfo
--- gdb.texinfo	28 Oct 2003 22:04:47 -0000	1.185
+++ gdb.texinfo	7 Jan 2004 23:54:25 -0000
@@ -8482,12 +8482,13 @@ A fully qualified Objective-C method nam
 -[@var{Class} @var{methodName}]
 @end smallexample
 
-where the minus sign is used to indicate an instance method and a plus
-sign (not shown) is used to indicate a class method. The
-class name @var{Class} and method name @var{methoName} are enclosed in
-brackets, similar to the way messages are specified in Objective-C source
-code. For example, to set a breakpoint at the @code{create} instance method of 
-class @code{Fruit} in the program currently being debugged, enter:
+where the minus sign is used to indicate an instance method and a
+plus sign (not shown) is used to indicate a class method.  The class
+name @var{Class} and method name @var{methodName} are enclosed in
+brackets, similar to the way messages are specified in Objective-C
+source code.  For example, to set a breakpoint at the @code{create}
+instance method of class @code{Fruit} in the program currently being
+debugged, enter:
 
 @smallexample
 break -[Fruit create]
@@ -8500,10 +8501,10 @@ enter:
 list +[NSText initialize]
 @end smallexample
 
-In the current version of GDB, the plus or minus sign is required.  In
-future versions of GDB, the plus or minus sign will be optional, but you
-can use it to narrow the search.  It is also possible to specify just a
-method name:
+In the current version of @value{GDBN}, the plus or minus sign is
+required.  In future versions of @value{GDBN}, the plus or minus
+sign will be optional, but you can use it to narrow the search.  It
+is also possible to specify just a method name:
 
 @smallexample
 break create
@@ -8524,20 +8525,23 @@ clear -[NSWindow makeKeyAndOrderFront:]
 
 @node The Print Command with Objective-C
 @subsubsection The Print Command With Objective-C
+@kindex print-object
+@kindex po @r{(@code{print-object})}
+@kindex _NSPrintForDebugger
 
-The print command has also been extended to accept methods. For example:
+The print command has also been extended to accept methods.  For example:
 
 @smallexample
-print -[object hash]
+print -[@var{object} hash]
 @end smallexample
 
 @cindex print an Objective-C object description
-will tell gdb to send the -hash message to object and print the
-result. Also an additional command has been added, @code{print-object}
-or @code{po} for short, which is meant to print the description of an
-object. However, this command may only work with certain Objective-C
-libraries that have a particular hook function, called
-@code{_NSPrintForDebugger} defined.
+will tell @value{GDBN} to send the @code{hash} message to @var{object}
+and print the result.  Also, an additional command has been added,
+@code{print-object} or @code{po} for short, which is meant to print
+the description of an object.  However, this command may only work
+with certain Objective-C libraries that have a particular hook
+function, @code{_NSPrintForDebugger}, defined.
 
 @node Modula-2,  , Objective-C, Support
 @subsection Modula-2

Re: RFA/doc: couple of small Obj-C documentation tweaks

[Eli Zaretskii]

> From: Jason Molenda <jmolenda@apple.com>
> Date: Wed, 7 Jan 2004 15:57:35 -0800
> 
> Thanks for spotting the additional corrections.  I'm inexperienced with 
> texinfo so I want to run the patch past you before I commit.

Sure, feel free.

> makeinfo and texi2html don't give any warnings when processing this
> - I believe it to be correct.

The patch is okay, except for the following two very minor problems:

> +@kindex _NSPrintForDebugger

_NSPrintForDebugger is not a command, so @kindex isn't right here.
I'd suggest something like this:

  @cindex @code{_NSPrintForDebugger}, and printing Objective-C objects

> +The print command has also been extended to accept methods.  For example:
>  
>  @smallexample
> -print -[object hash]
> +print -[@var{object} hash]
>  @end smallexample
>  
>  @cindex print an Objective-C object description
> -will tell gdb to send the -hash message to object and print the
> -result. Also an additional command has been added, @code{print-object}
> -or @code{po} for short, which is meant to print the description of an
> -object. However, this command may only work with certain Objective-C
> -libraries that have a particular hook function, called
> -@code{_NSPrintForDebugger} defined.
> +will tell @value{GDBN} to send the @code{hash} message to @var{object}

This last line doesn't start a new paragraph, so you need a @noindent
(alone on a separate line) immediately before it, like this:

  @smallexample
  print -[@var{object} hash]
  @end smallexample
  
  @cindex print an Objective-C object description
  @noindent
  will tell @value{GDBN} to send the @code{hash} message to @var{object}

This is needed to prevent makeinfo and TeX from indenting the line as
if it were a beginning of a paragraph.  (Sorry for not catching this
when I first read the patch.)

Otherwise, please commit the patch.  Thanks.

[Committed] RFA/doc: couple of small Obj-C documentation tweaks

[Jason Molenda]

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

Thanks for the additional comments, Eli.  I checked this in:


[-- Attachment #2: pa.txt --]
[-- Type: text/plain, Size: 4868 bytes --]

2004-01-08  Jason Molenda  <jmolenda@apple.com>
            Eli Zaretskii  <eliz@is.elta.co.il>

        * gdb.texinfo: Update copyright.
        (Objective-C): "methodName" typeo fixed.  Add @code/@var markup   
        around names, as appropriate.  Minor syntax cleanup of
        _NSPrintForDebugger explanation.  Two spaces after periods.
        GDBN used instead of lit. "gdb".  Index entries added for
        print-object and _NSPrintForDebugger.  @noindent added in one spot.
        
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.185
retrieving revision 1.186
diff -u -p -r1.185 -r1.186
--- gdb.texinfo	28 Oct 2003 22:04:47 -0000	1.185
+++ gdb.texinfo	8 Jan 2004 22:47:00 -0000	1.186
@@ -1,6 +1,6 @@
 \input texinfo      @c -*-texinfo-*-
 @c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003
+@c 1999, 2000, 2001, 2002, 2003, 2004
 @c Free Software Foundation, Inc.
 @c
 @c %**start of header
@@ -52,7 +52,7 @@ This is the @value{EDITION} Edition, of 
 Version @value{GDBVN}.
 
 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
-              1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
+              1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -115,7 +115,7 @@ This file describes @value{GDBN}, the @s
 This is the @value{EDITION} Edition, for @value{GDBN} Version
 @value{GDBVN}.
 
-Copyright (C) 1988-2003 Free Software Foundation, Inc.
+Copyright (C) 1988-2004 Free Software Foundation, Inc.
 
 @menu
 * Summary::                     Summary of @value{GDBN}
@@ -8482,12 +8482,13 @@ A fully qualified Objective-C method nam
 -[@var{Class} @var{methodName}]
 @end smallexample
 
-where the minus sign is used to indicate an instance method and a plus
-sign (not shown) is used to indicate a class method. The
-class name @var{Class} and method name @var{methoName} are enclosed in
-brackets, similar to the way messages are specified in Objective-C source
-code. For example, to set a breakpoint at the @code{create} instance method of 
-class @code{Fruit} in the program currently being debugged, enter:
+where the minus sign is used to indicate an instance method and a
+plus sign (not shown) is used to indicate a class method.  The class
+name @var{Class} and method name @var{methodName} are enclosed in
+brackets, similar to the way messages are specified in Objective-C
+source code.  For example, to set a breakpoint at the @code{create}
+instance method of class @code{Fruit} in the program currently being
+debugged, enter:
 
 @smallexample
 break -[Fruit create]
@@ -8500,10 +8501,10 @@ enter:
 list +[NSText initialize]
 @end smallexample
 
-In the current version of GDB, the plus or minus sign is required.  In
-future versions of GDB, the plus or minus sign will be optional, but you
-can use it to narrow the search.  It is also possible to specify just a
-method name:
+In the current version of @value{GDBN}, the plus or minus sign is
+required.  In future versions of @value{GDBN}, the plus or minus
+sign will be optional, but you can use it to narrow the search.  It
+is also possible to specify just a method name:
 
 @smallexample
 break create
@@ -8524,20 +8525,24 @@ clear -[NSWindow makeKeyAndOrderFront:]
 
 @node The Print Command with Objective-C
 @subsubsection The Print Command With Objective-C
+@kindex print-object
+@kindex po @r{(@code{print-object})}
 
-The print command has also been extended to accept methods. For example:
+The print command has also been extended to accept methods.  For example:
 
 @smallexample
-print -[object hash]
+print -[@var{object} hash]
 @end smallexample
 
 @cindex print an Objective-C object description
-will tell gdb to send the -hash message to object and print the
-result. Also an additional command has been added, @code{print-object}
-or @code{po} for short, which is meant to print the description of an
-object. However, this command may only work with certain Objective-C
-libraries that have a particular hook function, called
-@code{_NSPrintForDebugger} defined.
+@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
+@noindent
+will tell @value{GDBN} to send the @code{hash} message to @var{object}
+and print the result.  Also, an additional command has been added,
+@code{print-object} or @code{po} for short, which is meant to print
+the description of an object.  However, this command may only work
+with certain Objective-C libraries that have a particular hook
+function, @code{_NSPrintForDebugger}, defined.
 
 @node Modula-2,  , Objective-C, Support
 @subsection Modula-2