Re: [RFA, doc RFA]: New printing module and info/disable/enable commands

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 31 Oct 2010 19:47:04 -0700 (PDT)
> From: dje@google.com (Doug Evans)
> 
> This patch adds two things: A new python module to assist in writing
> pretty-printers (mostly to formalize some of the administrivia aspects
> to support the new commands), and three new commands:
> info|enable|disable pretty-printer.

Thanks.

> +  ** Module gdb.printing has been added.
> +     It contains utilities for writing and registering pretty-printers.
> +     New classes: PrettyPrinter,  SubPrettyPrinter,
> +     RegexpCollectionPrettyPrinter.
> +     New function: register_pretty_printer.
> +
> +  ** New commands "info pretty-printers", "enable pretty-printer" and
> +     "disable pretty-printer" have been added.

This is okay.

> +Pretty-printers are normally named.  This makes them easy to manage.
> +For example, the @samp{info pretty-printer} command will list all the
> +installed pretty-printers.

It's not clear how "info pretty-printers" is an example of giving
names to pretty-printers.  How about

  The @samp{info pretty-printer} command will list all the installed
  pretty-printers with their names.

> +For pretty-printers that handle multiple types, we call the printer
> +of each individual type a @code{subprinter}, and each subprinter is named.

Suggest to rephrase:

  If a pretty-printer can handle multiple data types, then its
  @dfn{subprinters} are the printers for the individual data types.
  Each such subprinter has its own name.

> +The format of the name is @samp{printer-name}:@samp{subprinter-name}.

Please use @var here, not @code, since both of these stand for
something else, they are not literal symbols.

> +Pretty-printers are installed by @samp{registering} them with @value{GDBN}.
                                    ^^^^^^^^^^^^^^^^^^
@dfn, not @samp.  You are defining new terminology.

> +@node Pretty-Printer Commands
> +@subsection Pretty-Printer Commands

A @cindex entry here would be good.

> +@var{object-regexp} is a regular expression matching the objects to list.

"Objects to list" or "objects whose pretty-printers to list"?

> +Objects are @code{global}, the program space's file
   ^^^^^^^^^^^
"Objects can be ...", perhaps?

> +@item disable pretty-printer @var{object-regexp} @var{name-regexp}
> +Disable the pretty-printer matching @var{object-regexp} and @var{name-regexp}.
   ^^^^^^^^^^^^^^^^^^^^^^^^^^
"Disable pretty-printers", in plural.

> +@item enable pretty-printer @var{object-regexp} @var{name-regexp}
> +Enable the pretty-printer matching @var{object-regexp} and @var{name-regexp}.
   ^^^^^^^^^^^^^^^^^^^^^^^^^
Ditto.

> +Note that for @code{bar} the entire printer can be disabled,
> +as can each individual @code{subprinter}.

Why is "subprinter" in @code here?

> +When a printer handles several types we call the printer for each type
> +a @code{subprinter}.

@dfn, and I suggest to rephrase as above.

> +@node gdb.printing
> +@subsubsection gdb.printing

An index entry here, please.

Thanks.