[PATCH 5/5] gdb/python: implement the print_insn extension language hook

[Eli Zaretskii]

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Date: Wed, 13 Oct 2021 22:59:10 +0100
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index d001a03145d..fd1952a2f59 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -32,6 +32,12 @@ maint show internal-warning backtrace
>    internal-error, or an internal-warning.  This is on by default for
>    internal-error and off by default for internal-warning.
>  
> +set style disassembly on|off
> +show style disassembly
> +  If GDB is compiled with Python support, and the Python pygments
> +  module is available, then, when this setting is on, disassembler
> +  output will have styling applied.

If this requires Python with a module that is not available by
default, I think a general style name like "disassembly" would be
misleading.  I suggest "pygment-disassembly" instead.

> +@item set style disassembly @samp{on|off}
> +Enable or disable disassembly styling.  This affects whether
> +disassembly output, such as the output of the @code{disassemble}
> +command, is styled.  The default is @samp{on}.  Note that disassembly
> +styling only works if styling in general is enabled, and if a source
> +highlighting library is available to @value{GDBN}.
> +
> +To highlight disassembly output @value{GDBN} must be compiled with
> +Python support, and the Python Pygments package must be available,

So what does the default ON setting mean if pygments module is not
available, or if GDB was not compiled with Python support?
> +@node Disassembly In Python
> +@cindex Python Instruction Disassembly

Index entries should begin with a lower-case letter, so that sorting
of the entries in the produced manual would not depend on the locale.

> +@defivar DisassembleInfo can_emit_style_escapes
> +This is @code{True} if the output stream that the disassembler is
> +currently printing too can support escape sequences use for colors,
                      ^^^
Should be "to".

> +otherwise this attribute is @code{False}.

Not sure why you are talking about escape sequences: we support
styling with colors also on terminals without escape sequences.  Does
this mean this feature _must_ have actual escape sequence support?

> +@defmethod DisassembleInfo memory_error (offset)
> +This method marks the @code{DisassembleInfo} as having experienced a
> +@code{gdb.MemoryError} when trying to access memory of @var{offset}
> +bytes from @code{DisassembleInfo.address}.

Should this text have a cross-reference to where MemoryError is
described?

> +The optional @var{architecture} is either a string, or the value
> +@code{None}.  If it is a string, then it should be the name of an
> +architecture known to @value{GDBN}, as returned either from
> +@code{gdb.Architecture.name()}
> +(@pxref{gdbpy_architecture_name,,gdb.Architecture.name}), or from
> +@code{gdb.architecture_names()}
> +(@pxref{gdb_architecture_names,,gdb.architecture_names}).

Please remove the parentheses from the references to these methods.

> +@defun format_address (architecture, address)
> +Returns @var{address} formatted as a string, in a style suitable for
> +including in the disassembly output of an instruction, for example a
> +formatted address might look like:
> +
> +@smallexample
> +0x00001042 <symbol+16>
> +@end smallexample
> +
> +@var{architecture} is a @code{gdb.Architecture} (@pxref{Architectures
> +In Python}), which is required to format the addresses correctly.
> +This can be obtained from @code{DisassembleInfo.architecture}.

This last paragraph should have @noindent before it, since it's a
continuation the description of format_address.

> +After calling this function the result in @var{info} @emph{might} have
> +been updated to include syntax highlighting escape sequences.  If
> +syntax highlighting is disabled in @value{GDBN}, or the output stream
> +doesn't support syntax highlighting, then this function will leave
> +@var{info} unchanged.

I suggest a cross-reference to commands that enable syntax
highlighting where you mention it.

> +This function should return a Python object that supports the buffer
> +protocol, i.e. a string, an array, or the object returned from

Please add @: after i.e., to prevent TeX from typesetting that as an
end of a sentence.

Thanks.