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

[Doug Evans <dje at google dot com>]

On Sun, Oct 31, 2010 at 9:07 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> 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.

Thanks.  This applies all your suggestions.

And I still need approval for the code part.

2010-11-02  Doug Evans  <dje@google.com>

        New python module gdb.printing, and new commands info pretty-printer,
        enable pretty-printer, disable pretty-printer.
        * NEWS: Mention them.
        * data-directory/Makefile.in (PYTHON_FILES): Add gdb/printing.py,
        gdb/command/__init__.py, gdb/command/pretty_printers.py.
        * python/lib/gdb/__init__.py: Install pretty-printer commands.
        * python/lib/gdb/printing.py: New file.
        * python/lib/gdb/command/__init__.py: New file.
        * python/lib/gdb/command/pretty_printers.py: New file.

        doc/
        * gdb.texinfo (Pretty Printing): Expand into three sections,
        introduction, example, and commands.
        (Python API): Delete section Disabling Pretty-Printers, merge into
        Selecting Pretty-Printers.
        (Writing a Pretty-Printer): New section.  Move the pretty-printer
        example here, and reformat to match python coding style.  Add a second
        example using the gdb.printing module.
        (Python modules): Add gdb.printing.

        testsuite/
        * gdb.python/py-pp-maint.c: New file.
        * gdb.python/py-pp-maint.exp: New file.
        * gdb.python/py-pp-maint.py: New file.

Attachment: gdb-101102-pp-maint-3.patch.txt
Description: Text document