[patch] doc-python: Pretty Printing split user / developer

[patch] doc-python: Pretty Printing split user / developer

[Jan Kratochvil]

Hi,

There has been accepted:
	RFA: update `print' docs
	http://sourceware.org/ml/gdb-patches/2010-03/msg00236.html

but still it got a user comment:

[ info '(./gdb.info)Pretty Printing' ]
# ... the target for the xref needs to be something more user oriented targeted
# at the C/C++/Fortran programmer rather something that goes to part of the
# manual discussing the Python API. 
# 
# That section is fine right up until you get to:
# 
# A pretty-printer is just an object that holds a value and implements a
# specific interface, defined here.
# 
# That is more targeted at the pretty printer developer. 

which I try to address by the attachment.  Is it OK this way?

(the "smallexample" parts sure have not been changed at all)


Thanks,
Jan


gdb/doc/
2010-04-21  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (Data): New @menu reference to Pretty Printing.
	(Python API): Change the reference to Pretty Printing API.
	(Pretty Printing): Move the user part under the Data node.  Create
	a new reference to Pretty Printing API.  Rename the API part ...
	(Pretty Printing API): To a new node name.
	(Selecting Pretty-Printers, Progspaces In Python, Objfiles In Python)
	(GDB/MI Variable Objects): Change references to Pretty Printing API.

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6731,6 +6731,7 @@ Table}.
 * Memory::                      Examining memory
 * Auto Display::                Automatic display
 * Print Settings::              Print settings
+* Pretty Printing::             Python pretty printing
 * Value History::               Value history
 * Convenience Vars::            Convenience variables
 * Registers::                   Registers
@@ -7901,6 +7902,39 @@ Do not pretty print C@t{++} virtual function tables.
 Show whether C@t{++} virtual function tables are pretty printed, or not.
 @end table
 
+@node Pretty Printing
+@section Pretty Printing
+
+@value{GDBN} provides a mechanism to allow pretty-printing of values using
+Python code.  It greatly simplifies the display of complex objects.  This
+mechanism works for both MI and the CLI.
+
+For example, here is how a C@t{++} @code{std::string} looks without a
+pretty-printer:
+
+@smallexample
+(@value{GDBP}) print s
+$1 = @{
+  static npos = 4294967295, 
+  _M_dataplus = @{
+    <std::allocator<char>> = @{
+      <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@}, 
+    members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider: 
+    _M_p = 0x804a014 "abcd"
+  @}
+@}
+@end smallexample
+
+With a pretty-printer for @code{std::string} only the contents are printed:
+
+@smallexample
+(@value{GDBP}) print s
+$2 = "abcd"
+@end smallexample
+
+For implementing pretty printers for new types you should read the Python API
+details (@pxref{Pretty Printing API}).
+
 @node Value History
 @section Value History
 
@@ -19765,7 +19799,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 * Auto-loading::                Automatically loading Python code.
 * Values From Inferior::
 * Types In Python::		Python representation of types.
-* Pretty Printing::		Pretty-printing values.
+* Pretty Printing API::		Pretty-printing values.
 * Selecting Pretty-Printers::   How GDB chooses a pretty-printer.
 * Commands In Python::          Implementing new commands in Python.
 * Functions In Python::         Writing new convenience functions.
@@ -20392,37 +20426,13 @@ A function internal to @value{GDBN}.  This is the type used to represent
 convenience functions.
 @end table
 
-@node Pretty Printing
-@subsubsection Pretty Printing
-
-@value{GDBN} provides a mechanism to allow pretty-printing of values
-using Python code.  The pretty-printer API allows application-specific
-code to greatly simplify the display of complex objects.  This
-mechanism works for both MI and the CLI.
-
-For example, here is how a C@t{++} @code{std::string} looks without a
-pretty-printer:
+@node Pretty Printing API
+@subsubsection Pretty Printing API
 
-@smallexample
-(@value{GDBP}) print s
-$1 = @{
-  static npos = 4294967295, 
-  _M_dataplus = @{
-    <std::allocator<char>> = @{
-      <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@}, 
-    members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider: 
-    _M_p = 0x804a014 "abcd"
-  @}
-@}
-@end smallexample
-
-After a pretty-printer for @code{std::string} has been installed, only
-the contents are printed:
-
-@smallexample
-(@value{GDBP}) print s
-$2 = "abcd"
-@end smallexample
+@value{GDBN} provides a mechanism to allow pretty-printing of values using
+Python code.  The pretty-printer API allows application-specific code to
+greatly simplify the display of complex objects.  An example output is provided
+(@pxref{Pretty Printing}).
 
 A pretty-printer is just an object that holds a value and implements a
 specific interface, defined here.
@@ -20514,7 +20524,7 @@ attribute.
 
 A function on one of these lists is passed a single @code{gdb.Value}
 argument and should return a pretty-printer object conforming to the
-interface definition above (@pxref{Pretty Printing}).  If a function
+interface definition above (@pxref{Pretty Printing API}).  If a function
 cannot create a pretty-printer for the value, it should return
 @code{None}.
 
@@ -20595,7 +20605,7 @@ printers with a specific objfile, @value{GDBN} will find the correct
 printers for the specific version of the library used by each
 inferior.
 
-To continue the @code{std::string} example (@pxref{Pretty Printing}),
+To continue the @code{std::string} example (@pxref{Pretty Printing API}),
 this code might appear in @code{gdb.libstdcxx.v6}:
 
 @smallexample
@@ -20961,7 +20971,7 @@ The @code{pretty_printers} attribute is a list of functions.  It is
 used to look up pretty-printers.  A @code{Value} is passed to each
 function in order; if the function returns @code{None}, then the
 search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing}, for more
+which is used to format the value.  @xref{Pretty Printing API}, for more
 information.
 @end defivar
 
@@ -21006,7 +21016,7 @@ The @code{pretty_printers} attribute is a list of functions.  It is
 used to look up pretty-printers.  A @code{Value} is passed to each
 function in order; if the function returns @code{None}, then the
 search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing}, for more
+which is used to format the value.  @xref{Pretty Printing API}, for more
 information.
 @end defivar
 
@@ -25263,7 +25273,7 @@ then this attribute will not be present.
 @item displayhint
 A dynamic varobj can supply a display hint to the front end.  The
 value comes directly from the Python pretty-printer object's
-@code{display_hint} method.  @xref{Pretty Printing}.
+@code{display_hint} method.  @xref{Pretty Printing API}.
 @end table
 
 Typical output will look like this:
@@ -25435,7 +25445,7 @@ The result may have its own attributes:
 @item displayhint
 A dynamic varobj can supply a display hint to the front end.  The
 value comes directly from the Python pretty-printer object's
-@code{display_hint} method.  @xref{Pretty Printing}.
+@code{display_hint} method.  @xref{Pretty Printing API}.
 
 @item has_more
 This is an integer attribute which is nonzero if there are children
@@ -25799,7 +25809,7 @@ single argument.  @value{GDBN} will call this object with the value of
 the varobj @var{name} as an argument (this is done so that the same
 Python pretty-printing code can be used for both the CLI and MI).
 When called, this object must return an object which conforms to the
-pretty-printing interface (@pxref{Pretty Printing}).
+pretty-printing interface (@pxref{Pretty Printing API}).
 
 The pre-defined function @code{gdb.default_visualizer} may be used to
 select a visualizer by following the built-in process

Re: [patch] doc-python: Pretty Printing split user / developer

[Eli Zaretskii]

> Date: Wed, 21 Apr 2010 22:50:46 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> which I try to address by the attachment.  Is it OK this way?

Thanks.

> +@smallexample
> +(@value{GDBP}) print s
> +$1 = @{
> +  static npos = 4294967295, 
> +  _M_dataplus = @{
> +    <std::allocator<char>> = @{
> +      <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@}, 
> +    members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider: 
> +    _M_p = 0x804a014 "abcd"
> +  @}
> +@}
> +@end smallexample

The long lines here need to be wrapped, to become shorter than 72
characters.

>  * Auto-loading::                Automatically loading Python code.
>  * Values From Inferior::
>  * Types In Python::		Python representation of types.
> -* Pretty Printing::		Pretty-printing values.
> +* Pretty Printing API::		Pretty-printing values.
>  * Selecting Pretty-Printers::   How GDB chooses a pretty-printer.
>  * Commands In Python::          Implementing new commands in Python.
>  * Functions In Python::         Writing new convenience functions.

This menu uses TAB characters.  Please convert all of them to spaces
("M-x untabify" in Emacs).  Using TABs in a Texinfo file is a no-no,
because it causes line misalignment in the Info output.

> +@value{GDBN} provides a mechanism to allow pretty-printing of values using
> +Python code.  The pretty-printer API allows application-specific code to
> +greatly simplify the display of complex objects.

This repeats what you just said in the "Pretty Printing" section.  I
don't think we need to repeat that.

Okay with these changes.

Re: [patch] doc-python: Pretty Printing split user / developer

[Jan Kratochvil]

On Thu, 22 Apr 2010 05:18:45 +0200, Eli Zaretskii wrote:
> The long lines here need to be wrapped, to become shorter than 72
> characters.

Fixed.


> This menu uses TAB characters.  Please convert all of them to spaces

Fixed.

> Using TABs in a Texinfo file is a no-no,

There are more of them, though.


> > +@value{GDBN} provides a mechanism to allow pretty-printing of values using
> > +Python code.  The pretty-printer API allows application-specific code to
> > +greatly simplify the display of complex objects.
> 
> This repeats what you just said in the "Pretty Printing" section.  I
> don't think we need to repeat that.

It now looks this way but that's probably OK:

# File: gdb.info,  Node: Pretty Printing API,  Next: Selecting Pretty-Printers,
# Prev: Types In Python,  Up: Python API
# 
# 23.2.2.6 Pretty Printing API
# ............................
# 
# An example output is provided (*note Pretty Printing::).
# 
#    A pretty-printer is just an object that holds a value and implements
# a specific interface, defined here.


Checked-in.


Thanks,
Jan


http://sourceware.org/ml/gdb-cvs/2010-04/msg00221.html

--- src/gdb/doc/ChangeLog	2010/04/22 04:09:25	1.1053
+++ src/gdb/doc/ChangeLog	2010/04/22 16:32:43	1.1054
@@ -1,3 +1,14 @@
+2010-04-22  Jan Kratochvil  <jan.kratochvil@redhat.com>
+
+	* gdb.texinfo (Data): New @menu reference to Pretty Printing.
+	(Python API): Change the reference to Pretty Printing API.
+	(Pretty Printing): Move the user part under the Data node.  Reformat
+	the sample output to 72 columns.  Create a new reference to Pretty
+	Printing API.  Rename the API part ...
+	(Pretty Printing API): To a new node name.
+	(Selecting Pretty-Printers, Progspaces In Python, Objfiles In Python)
+	(GDB/MI Variable Objects): Change references to Pretty Printing API.
+
 2010-04-21  Stan Shebs  <stan@codesourcery.com>
 
 	* gdb.texinfo (Tracepoint Actions): Mention synonymy of actions
--- src/gdb/doc/gdb.texinfo	2010/04/22 04:09:25	1.710
+++ src/gdb/doc/gdb.texinfo	2010/04/22 16:32:43	1.711
@@ -6731,6 +6731,7 @@
 * Memory::                      Examining memory
 * Auto Display::                Automatic display
 * Print Settings::              Print settings
+* Pretty Printing::             Python pretty printing
 * Value History::               Value history
 * Convenience Vars::            Convenience variables
 * Registers::                   Registers
@@ -7909,6 +7910,42 @@
 Show whether C@t{++} virtual function tables are pretty printed, or not.
 @end table
 
+@node Pretty Printing
+@section Pretty Printing
+
+@value{GDBN} provides a mechanism to allow pretty-printing of values using
+Python code.  It greatly simplifies the display of complex objects.  This
+mechanism works for both MI and the CLI.
+
+For example, here is how a C@t{++} @code{std::string} looks without a
+pretty-printer:
+
+@smallexample
+(@value{GDBP}) print s
+$1 = @{
+  static npos = 4294967295, 
+  _M_dataplus = @{
+    <std::allocator<char>> = @{
+      <__gnu_cxx::new_allocator<char>> = @{
+        <No data fields>@}, <No data fields>
+      @},
+    members of std::basic_string<char, std::char_traits<char>,
+      std::allocator<char> >::_Alloc_hider:
+    _M_p = 0x804a014 "abcd"
+  @}
+@}
+@end smallexample
+
+With a pretty-printer for @code{std::string} only the contents are printed:
+
+@smallexample
+(@value{GDBP}) print s
+$2 = "abcd"
+@end smallexample
+
+For implementing pretty printers for new types you should read the Python API
+details (@pxref{Pretty Printing API}).
+
 @node Value History
 @section Value History
 
@@ -19770,8 +19807,8 @@
 * Exception Handling::
 * Auto-loading::                Automatically loading Python code.
 * Values From Inferior::
-* Types In Python::		Python representation of types.
-* Pretty Printing::		Pretty-printing values.
+* Types In Python::             Python representation of types.
+* Pretty Printing API::         Pretty-printing values.
 * Selecting Pretty-Printers::   How GDB chooses a pretty-printer.
 * Commands In Python::          Implementing new commands in Python.
 * Functions In Python::         Writing new convenience functions.
@@ -20398,37 +20435,10 @@
 convenience functions.
 @end table
 
-@node Pretty Printing
-@subsubsection Pretty Printing
-
-@value{GDBN} provides a mechanism to allow pretty-printing of values
-using Python code.  The pretty-printer API allows application-specific
-code to greatly simplify the display of complex objects.  This
-mechanism works for both MI and the CLI.
-
-For example, here is how a C@t{++} @code{std::string} looks without a
-pretty-printer:
+@node Pretty Printing API
+@subsubsection Pretty Printing API
 
-@smallexample
-(@value{GDBP}) print s
-$1 = @{
-  static npos = 4294967295, 
-  _M_dataplus = @{
-    <std::allocator<char>> = @{
-      <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@}, 
-    members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider: 
-    _M_p = 0x804a014 "abcd"
-  @}
-@}
-@end smallexample
-
-After a pretty-printer for @code{std::string} has been installed, only
-the contents are printed:
-
-@smallexample
-(@value{GDBP}) print s
-$2 = "abcd"
-@end smallexample
+An example output is provided (@pxref{Pretty Printing}).
 
 A pretty-printer is just an object that holds a value and implements a
 specific interface, defined here.
@@ -20520,7 +20530,7 @@
 
 A function on one of these lists is passed a single @code{gdb.Value}
 argument and should return a pretty-printer object conforming to the
-interface definition above (@pxref{Pretty Printing}).  If a function
+interface definition above (@pxref{Pretty Printing API}).  If a function
 cannot create a pretty-printer for the value, it should return
 @code{None}.
 
@@ -20601,7 +20611,7 @@
 printers for the specific version of the library used by each
 inferior.
 
-To continue the @code{std::string} example (@pxref{Pretty Printing}),
+To continue the @code{std::string} example (@pxref{Pretty Printing API}),
 this code might appear in @code{gdb.libstdcxx.v6}:
 
 @smallexample
@@ -20967,7 +20977,7 @@
 used to look up pretty-printers.  A @code{Value} is passed to each
 function in order; if the function returns @code{None}, then the
 search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing}, for more
+which is used to format the value.  @xref{Pretty Printing API}, for more
 information.
 @end defivar
 
@@ -21012,7 +21022,7 @@
 used to look up pretty-printers.  A @code{Value} is passed to each
 function in order; if the function returns @code{None}, then the
 search continues.  Otherwise, the return value should be an object
-which is used to format the value.  @xref{Pretty Printing}, for more
+which is used to format the value.  @xref{Pretty Printing API}, for more
 information.
 @end defivar
 
@@ -25269,7 +25279,7 @@
 @item displayhint
 A dynamic varobj can supply a display hint to the front end.  The
 value comes directly from the Python pretty-printer object's
-@code{display_hint} method.  @xref{Pretty Printing}.
+@code{display_hint} method.  @xref{Pretty Printing API}.
 @end table
 
 Typical output will look like this:
@@ -25441,7 +25451,7 @@
 @item displayhint
 A dynamic varobj can supply a display hint to the front end.  The
 value comes directly from the Python pretty-printer object's
-@code{display_hint} method.  @xref{Pretty Printing}.
+@code{display_hint} method.  @xref{Pretty Printing API}.
 
 @item has_more
 This is an integer attribute which is nonzero if there are children
@@ -25805,7 +25815,7 @@
 the varobj @var{name} as an argument (this is done so that the same
 Python pretty-printing code can be used for both the CLI and MI).
 When called, this object must return an object which conforms to the
-pretty-printing interface (@pxref{Pretty Printing}).
+pretty-printing interface (@pxref{Pretty Printing API}).
 
 The pre-defined function @code{gdb.default_visualizer} may be used to
 select a visualizer by following the built-in process