[commit] Don't use @var at the beginning of a sentence
Eli Zaretskii
eliz@gnu.org
Sat May 24 10:17:00 GMT 2014
FYI: I've pushed to the master branch the below, to avoid using @var
at the beginning of a sentence, which looks bad in print (PDF) and
HTML formats.
Please avoid this gotcha in future submissions of patches for the GDB
documentation. The changes I made can be studied to see a few
standard tricks you could use to avoid the gotcha when it looks
"natural" to you.
Thanks.
commit 697aa1b7d399d80cf164f190d3743513085f1009
Author: Eli Zaretskii <eliz@gnu.org>
Date: Sat May 24 13:02:42 2014 +0300
Don't use @var at the beginning of a sentence in GDB documentation.
gdb/doc/guile.texi (Types In Guile, Basic Guile, Frames In Guile)
(Breakpoints In Guile, Guile Printing Module)
(Guile Exception Handling, Values From Inferior In Guile)
(Objfiles In Guile, Breakpoints In Guile, Memory Ports in Guile):
Don't use @var at the beginning of a sentence.
gdb/doc/gdb.texinfo (Frame Filter Management, Trace Files)
(C Operators, Ada Tasks, Calling, Bootstrapping, ARM)
(PowerPC Embedded, Define, Annotations for Running)
(IPA Protocol Commands, Packets, General Query Packets)
(Tracepoint Packets, Notification Packets, Environment)
(Inferiors and Programs, Set Breaks, Set Catchpoints)
(Continuing and Stepping, Signals, Thread-Specific Breakpoints)
(Frames, Backtrace, Selection, Expressions, Registers)
(Trace State Variables, Built-In Func/Proc, Signaling, Files)
(Numbers, GDB/MI Async Records, GDB/MI Data Manipulation)
(Source Annotations, Using JIT Debug Info Readers, Packets)
(Stop Reply Packets, Host I/O Packets)
(Target Description Format): Don't use @var at the beginning of a
sentence.
gdb/doc/python.texi (Basic Python, Types In Python)
(Commands In Python, Frames In Python, Line Tables In Python)
(Breakpoints In Python, gdb.printing, gdb.types)
(Type Printing API): Don't use @var at the beginning of a
sentence.
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 25bdc32..2d8b100 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,32 @@
+2014-05-24 Eli Zaretskii <eliz@gnu.org>
+
+ * guile.texi (Types In Guile, Basic Guile, Frames In Guile)
+ (Breakpoints In Guile, Guile Printing Module)
+ (Guile Exception Handling, Values From Inferior In Guile)
+ (Objfiles In Guile, Breakpoints In Guile, Memory Ports in Guile):
+ Don't use @var at the beginning of a sentence.
+
+ * gdb.texinfo (Frame Filter Management, Trace Files)
+ (C Operators, Ada Tasks, Calling, Bootstrapping, ARM)
+ (PowerPC Embedded, Define, Annotations for Running)
+ (IPA Protocol Commands, Packets, General Query Packets)
+ (Tracepoint Packets, Notification Packets, Environment)
+ (Inferiors and Programs, Set Breaks, Set Catchpoints)
+ (Continuing and Stepping, Signals, Thread-Specific Breakpoints)
+ (Frames, Backtrace, Selection, Expressions, Registers)
+ (Trace State Variables, Built-In Func/Proc, Signaling, Files)
+ (Numbers, GDB/MI Async Records, GDB/MI Data Manipulation)
+ (Source Annotations, Using JIT Debug Info Readers, Packets)
+ (Stop Reply Packets, Host I/O Packets)
+ (Target Description Format): Don't use @var at the beginning of a
+ sentence.
+
+ * python.texi (Basic Python, Types In Python)
+ (Commands In Python, Frames In Python, Line Tables In Python)
+ (Breakpoints In Python, gdb.printing, gdb.types)
+ (Type Printing API): Don't use @var at the beginning of a
+ sentence.
+
2014-05-23 Markus Metzger <markus.t.metzger@intel.com>
* gdb.texinfo (Process Record and Replay): Document "set/show btrace
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index cc188ae..1ee62e0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2334,7 +2334,7 @@ your program. You can abbreviate @code{environment} as @code{env}.
@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
changes for your program (and the shell @value{GDBN} uses to launch
-it), not for @value{GDBN} itself. @var{value} may be any string; the
+it), not for @value{GDBN} itself. The @var{value} may be any string; the
values of environment variables are just strings, and any
interpretation is supplied by your program itself. The @var{value}
parameter is optional; if it is eliminated, the variable is set to a
@@ -2644,7 +2644,7 @@ remove inferiors from the debugging session use the
@kindex add-inferior
@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
Adds @var{n} inferiors to be run using @var{executable} as the
-executable. @var{n} defaults to 1. If no executable is specified,
+executable; @var{n} defaults to 1. If no executable is specified,
the inferiors begins empty, with no program. You can still assign or
change the program assigned to the inferior at any time by using the
@code{file} command with the executable name as its argument.
@@ -2652,7 +2652,7 @@ change the program assigned to the inferior at any time by using the
@kindex clone-inferior
@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
Adds @var{n} inferiors ready to execute the same program as inferior
-@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
+@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the
number of the current inferior. This is a convenient command when you
want to run another instance of the inferior you are debugging.
@@ -2851,7 +2851,7 @@ program information from the perspective of the current thread.
@c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays
the target system's identification for the thread with a message in the
-form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
+form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier
whose form varies depending on the particular system. For example, on
@sc{gnu}/Linux, you might see
@@ -3543,7 +3543,7 @@ above (or no argument) specifying where to break. @xref{Conditions,
@kindex tbreak
@item tbreak @var{args}
-Set a breakpoint enabled only for one stop. @var{args} are the
+Set a breakpoint enabled only for one stop. The @var{args} are the
same as for the @code{break} command, and the breakpoint is set in the same
way, but the breakpoint is automatically deleted after the first time your
program stops there. @xref{Disabling, ,Disabling Breakpoints}.
@@ -3551,7 +3551,7 @@ program stops there. @xref{Disabling, ,Disabling Breakpoints}.
@kindex hbreak
@cindex hardware breakpoints
@item hbreak @var{args}
-Set a hardware-assisted breakpoint. @var{args} are the same as for the
+Set a hardware-assisted breakpoint. The @var{args} are the same as for the
@code{break} command and the breakpoint is set in the same way, but the
breakpoint requires hardware support and some target hardware may not
have this support. The main purpose of this is EPROM/ROM code
@@ -3572,7 +3572,7 @@ hardware-breakpoint-limit}.
@kindex thbreak
@item thbreak @var{args}
-Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
+Set a hardware-assisted breakpoint enabled only for one stop. The @var{args}
are the same as for the @code{hbreak} command and the breakpoint is set in
the same way. However, like the @code{tbreak} command,
the breakpoint is automatically deleted after the
@@ -4163,7 +4163,7 @@ shared library. Use the @code{catch} command to set a catchpoint.
@table @code
@kindex catch
@item catch @var{event}
-Stop when @var{event} occurs. @var{event} can be any of the following:
+Stop when @var{event} occurs. The @var{event} can be any of the following:
@table @code
@item throw @r{[}@var{regexp}@r{]}
@@ -5267,8 +5267,8 @@ argument.
@item until @var{location}
@itemx u @var{location}
-Continue running your program until either the specified location is
-reached, or the current stack frame returns. @var{location} is any of
+Continue running your program until either the specified @var{location} is
+reached, or the current stack frame returns. The location is any of
the forms described in @ref{Specify Location}.
This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
@@ -5516,7 +5516,7 @@ for details about this command.
@kindex handle
@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
-Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
+Change the way @value{GDBN} handles signal @var{signal}. The @var{signal}
can be the number of a signal or its name (with or without the
@samp{SIG} at the beginning); a list of signal numbers of the form
@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
@@ -5952,9 +5952,9 @@ specify some source line.
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint. @var{threadno} is one of the
-numeric thread identifiers assigned by @value{GDBN}, shown in the first
-column of the @samp{info threads} display.
+particular thread reaches this breakpoint. The @var{threadno} specifier
+is one of the numeric thread identifiers assigned by @value{GDBN}, shown
+in the first column of the @samp{info threads} display.
If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
@@ -6728,9 +6728,9 @@ no provision for frameless functions elsewhere in the stack.
@table @code
@kindex frame@r{, command}
@cindex current stack frame
-@item frame @var{args}
+@item frame @r{[}@var{framespec}@r{]}
The @code{frame} command allows you to move from one stack frame to another,
-and to print the stack frame you select. @var{args} may be either the
+and to print the stack frame you select. The @var{framespec} may be either the
address of the frame or the stack frame number. Without an argument,
@code{frame} prints the current stack frame.
@@ -6776,8 +6776,8 @@ Similar, but print only the outermost @var{n} frames.
@itemx bt full
@itemx bt full @var{n}
@itemx bt full -@var{n}
-Print the values of the local variables also. @var{n} specifies the
-number of frames to print, as described above.
+Print the values of the local variables also. As described above,
+@var{n} specifies the number of frames to print.
@item backtrace no-filters
@itemx bt no-filters
@@ -6961,11 +6961,11 @@ their name, priority and enabled status.
@anchor{disable frame-filter all}
@item disable frame-filter @var{filter-dictionary} @var{filter-name}
Disable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
-@code{progspace} or the name of the object file where the frame filter
+@code{progspace}, or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters
-across all dictionaries are disabled. @var{filter-name} is the name
+across all dictionaries are disabled. The @var{filter-name} is the name
of the frame filter and is used when @code{all} is not the option for
@var{filter-dictionary}. A disabled frame-filter is not deleted, it
may be enabled again later.
@@ -6973,11 +6973,11 @@ may be enabled again later.
@kindex enable frame-filter
@item enable frame-filter @var{filter-dictionary} @var{filter-name}
Enable a frame filter in the dictionary matching
-@var{filter-dictionary}, or @code{all}, and @var{filter-name}.
+@var{filter-dictionary} and @var{filter-name}. The
@var{filter-dictionary} may be @code{all}, @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides. When @code{all} is specified, all frame filters across
-all dictionaries are enabled. @var{filter-name} is the name of the frame
+all dictionaries are enabled. The @var{filter-name} is the name of the frame
filter and is used when @code{all} is not the option for
@var{filter-dictionary}.
@@ -7036,15 +7036,15 @@ objfile /build/test frame-filters:
@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority}
Set the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
-dictionary resides. @var{priority} is an integer.
+dictionary resides. The @var{priority} is an integer.
@kindex show frame-filter priority
@item show frame-filter priority @var{filter-dictionary} @var{filter-name}
Show the @var{priority} of a frame filter in the dictionary matching
@var{filter-dictionary}, and the frame filter name matching
-@var{filter-name}. @var{filter-dictionary} may be @code{global},
+@var{filter-name}. The @var{filter-dictionary} may be @code{global},
@code{progspace} or the name of the object file where the frame filter
dictionary resides.
@@ -7121,17 +7121,17 @@ pointer, a program counter, and a memory stack pointer.
@kindex up
@item up @var{n}
-Move @var{n} frames up the stack. For positive numbers @var{n}, this
-advances toward the outermost frame, to higher frame numbers, to frames
-that have existed longer. @var{n} defaults to one.
+Move @var{n} frames up the stack; @var{n} defaults to 1. For positive
+numbers @var{n}, this advances toward the outermost frame, to higher
+frame numbers, to frames that have existed longer.
@kindex down
@kindex do @r{(@code{down})}
@item down @var{n}
-Move @var{n} frames down the stack. For positive numbers @var{n}, this
-advances toward the innermost frame, to lower frame numbers, to frames
-that were created more recently. @var{n} defaults to one. You may
-abbreviate @code{down} as @code{do}.
+Move @var{n} frames down the stack; @var{n} defaults to 1. For
+positive numbers @var{n}, this advances toward the innermost frame, to
+lower frame numbers, to frames that were created more recently.
+You may abbreviate @code{down} as @code{do}.
@end table
All of these commands end by printing two lines of output describing the
@@ -8224,10 +8224,10 @@ function where it is defined. @xref{Variables, ,Program Variables}.
@cindex casts, to view memory
@item @{@var{type}@} @var{addr}
Refers to an object of type @var{type} stored at address @var{addr} in
-memory. @var{addr} may be any expression whose value is an integer or
-pointer (but parentheses are required around binary operators, just as in
-a cast). This construct is allowed regardless of what kind of data is
-normally supposed to reside at @var{addr}.
+memory. The address @var{addr} may be any expression whose value is
+an integer or pointer (but parentheses are required around binary
+operators, just as in a cast). This construct is allowed regardless
+of what kind of data is normally supposed to reside at @var{addr}.
@end table
@node Ambiguous Expressions
@@ -10151,7 +10151,7 @@ and vector registers (in the selected stack frame).
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
As discussed in detail below, register values are normally relative to
-the selected stack frame. @var{regname} may be any register name valid on
+the selected stack frame. The @var{regname} may be any register name valid on
the machine you are using, with or without the initial @samp{$}.
@end table
@@ -12040,7 +12040,7 @@ variable with the same name.
@kindex tvariable
The @code{tvariable} command creates a new trace state variable named
@code{$@var{name}}, and optionally gives it an initial value of
-@var{expression}. @var{expression} is evaluated when this command is
+@var{expression}. The @var{expression} is evaluated when this command is
entered; the result will be converted to an integer if possible,
otherwise @value{GDBN} will report an error. A subsequent
@code{tvariable} command specifying the same name does not create a
@@ -12902,7 +12902,7 @@ a source of trace data. Commands that examine data work as they do with
a live target, but it is not possible to run any new trace experiments.
@code{tstatus} will report the state of the trace run at the moment
the data was saved, as well as the current trace frame you are examining.
-@var{filename} or @var{dirname} must be on a filesystem accessible to
+Both @var{filename} and @var{dirname} must be on a filesystem accessible to
the host.
@smallexample
@@ -13753,14 +13753,14 @@ assigned. Defined on scalar types.
@item @var{op}=
Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
and translated to @w{@code{@var{a} = @var{a op b}}}.
-@w{@code{@var{op}=}} and @code{=} have the same precedence.
+@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator
@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
@item ?:
The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
-of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
-integral type.
+of as: if @var{a} then @var{b} else @var{c}. The argument @var{a}
+should be of an integral type.
@item ||
Logical @sc{or}. Defined on integral types.
@@ -14714,18 +14714,20 @@ Returns boolean TRUE if @var{i} is an odd number.
@item ORD(@var{x})
Returns the ordinal value of its argument. For example, the ordinal
-value of a character is its @sc{ascii} value (on machines supporting the
-@sc{ascii} character set). @var{x} must be of an ordered type, which include
-integral, character and enumerated types.
+value of a character is its @sc{ascii} value (on machines supporting
+the @sc{ascii} character set). The argument @var{x} must be of an
+ordered type, which include integral, character and enumerated types.
@item SIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item TRUNC(@var{r})
Returns the integral part of @var{r}.
@item TSIZE(@var{x})
-Returns the size of its argument. @var{x} can be a variable or a type.
+Returns the size of its argument. The argument @var{x} can be a
+variable or a type.
@item VAL(@var{t},@var{i})
Returns the member of the type @var{t} whose ordinal value is @var{i}.
@@ -15628,13 +15630,13 @@ from the current task to the given task.
@cindex task breakpoints, in Ada
@kindex break @dots{} task @var{taskno}@r{ (Ada)}
These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}).
-@var{linespec} specifies source lines, as described
+command (@pxref{Thread Stops}). The
+@var{linespec} argument specifies source lines, as described
in @ref{Specify Location}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
-particular Ada task reaches this breakpoint. @var{taskno} is one of the
+particular Ada task reaches this breakpoint. The @var{taskno} is one of the
numeric task identifiers assigned by @value{GDBN}, shown in the first
column of the @samp{info tasks} display.
@@ -16562,7 +16564,7 @@ detail.
@kindex signal
@item signal @var{signal}
Resume execution where your program stopped, but immediately give it the
-signal @var{signal}. @var{signal} can be the name or the number of a
+signal @var{signal}. The @var{signal} can be the name or the number of a
signal. For example, on many systems @code{signal 2} and @code{signal
SIGINT} are both ways of sending an interrupt signal.
@@ -16670,7 +16672,7 @@ Make selected stack frame return now? (y or n) y
@cindex inferior functions, calling
@item print @var{expr}
Evaluate the expression @var{expr} and display the resulting value.
-@var{expr} may include calls to functions in the program being
+The expression may include calls to functions in the program being
debugged.
@kindex call
@@ -16938,7 +16940,7 @@ the program is running. To do this, use the @code{kill} command
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. @var{address} should be the memory
+into the program that is running. The @var{address} should give the memory
address at which the file has been loaded; @value{GDBN} cannot figure
this out for itself. You can additionally specify an arbitrary number
of @samp{-s @var{section} @var{address}} pairs, to give an explicit
@@ -19446,7 +19448,7 @@ handling tables. You need to do this because the stub does not have any
way of knowing what the exception handling tables on your target system
are like (for example, the processor's table might be in @sc{rom},
containing entries which point to a table in @sc{ram}).
-@var{exception_number} is the exception number which should be changed;
+The @var{exception_number} specifies the exception which should be changed;
its meaning is architecture-dependent (for example, different numbers
might represent divide by zero, misaligned access, etc). When this
exception occurs, control should be transferred directly to
@@ -20470,7 +20472,7 @@ installed with the name @code{vxgdb}, to distinguish it from a
@item VxWorks-timeout @var{args}
@kindex vxworks-timeout
All VxWorks-based targets now support the option @code{vxworks-timeout}.
-This option is set by the user, and @var{args} represents the number of
+This option is set by the user, and @var{args} represents the number of
seconds @value{GDBN} waits for responses to rpc's. You might use this if
your VxWorks target is a slow software simulator or is on the far side
of a thin network line.
@@ -20779,7 +20781,7 @@ The @value{GDBN} ARM simulator accepts the following optional arguments.
@table @code
@item --swi-support=@var{type}
-Tell the simulator which SWI interfaces to support.
+Tell the simulator which SWI interfaces to support. The argument
@var{type} may be a comma separated list of the following values.
The default value is @code{all}.
@@ -21148,8 +21150,8 @@ use the @code{break-range} command.
@table @code
@kindex break-range
@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range.
-@var{start-location} and @var{end-location} can specify a function name,
+Set a breakpoint for an address range given by
+@var{start-location} and @var{end-location}, which can specify a function name,
a line number, an offset of lines from the current line or from the start
location, or an address of an instruction (see @ref{Specify Location},
for a list of all the possible ways to specify a @var{location}.)
@@ -21244,7 +21246,7 @@ both the Unix host and on the Sparclet target. The program
@item remotetimeout @var{args}
@kindex remotetimeout
@value{GDBN} supports the option @code{remotetimeout}.
-This option is set by the user, and @var{args} represents the number of
+This option is set by the user, and @var{args} represents the number of
seconds @value{GDBN} waits for responses.
@end table
@@ -22189,7 +22191,7 @@ both input and output with the commands described below.
@kindex set input-radix
@item set input-radix @var{base}
Set the default base for numeric input. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix; for
example, any of
@@ -22210,7 +22212,7 @@ change the radix.
@kindex set output-radix
@item set output-radix @var{base}
Set the default base for numeric display. Supported choices
-for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
+for @var{base} are decimal 8, 10, or 16. The base must itself be
specified either unambiguously or using the current input radix.
@kindex show input-radix
@@ -23171,7 +23173,7 @@ end
@item define @var{commandname}
Define a command named @var{commandname}. If there is already a command
by that name, you are asked to confirm that you want to redefine it.
-@var{commandname} may be a bare command name consisting of letters,
+The argument @var{commandname} may be a bare command name consisting of letters,
numbers, dashes, and underscores. It may also start with any predefined
prefix command. For example, @samp{define target my-target} creates
a user-defined @samp{target my-target} command.
@@ -25381,7 +25383,7 @@ contains process identifier, specific to the operating system.
A thread group is no longer associated with a running program,
either because the program has exited, or because it was detached
from. The @var{id} field contains the @value{GDBN} identifier of the
-thread group. @var{code} is the exit code of the inferior; it exists
+thread group. The @var{code} field is the exit code of the inferior; it exists
only when the inferior exited with some code.
@item =thread-created,id="@var{id}",group-id="@var{gid}"
@@ -29191,12 +29193,12 @@ For the PPC MBX board:
[ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*]
@end smallexample
-Display the registers' contents. @var{fmt} is the format according to
-which the registers' contents are to be returned, followed by an optional
-list of numbers specifying the registers to display. A missing list of
-numbers indicates that the contents of all the registers must be
-returned. The @code{--skip-unavailable} option indicates that only
-the available registers are to be returned.
+Display the registers' contents. The format according to which the
+registers' contents are to be returned is given by @var{fmt}, followed
+by an optional list of numbers specifying the registers to display. A
+missing list of numbers indicates that the contents of all the
+registers must be returned. The @code{--skip-unavailable} option
+indicates that only the available registers are to be returned.
Allowed formats for @var{fmt} are:
@@ -31773,7 +31775,7 @@ annotation continues:
@noindent
where @var{name} is the name of the signal, such as @code{SIGILL} or
@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
-as @code{Illegal Instruction} or @code{Segmentation fault}.
+as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments
@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
user's benefit and have no particular format.
@@ -31811,7 +31813,7 @@ debug formats this will necessarily point to the beginning of a line),
@var{middle} is @samp{middle} if @var{addr} is in the middle of the
line, or @samp{beg} if @var{addr} is at the beginning of the line, and
@var{addr} is the address in the target program associated with the
-source which is being displayed. @var{addr} is in the form @samp{0x}
+source which is being displayed. The @var{addr} is in the form @samp{0x}
followed by one or more lowercase hex digits (note that this does not
depend on the language).
@@ -31984,7 +31986,7 @@ and @code{jit-reader-unload} commands.
@table @code
@item jit-reader-load @var{reader}
-Load the JIT reader named @var{reader}. @var{reader} is a shared
+Load the JIT reader named @var{reader}, which is a shared
object specified as either an absolute or a relative file name. In
the latter case, @value{GDBN} will try to load the reader from a
pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX
@@ -32239,7 +32241,7 @@ specification. They don't exist in real commands.
@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head}
Installs a new fast tracepoint described by @var{tracepoint_object}
-(@pxref{tracepoint object}). @var{gdb_jump_pad_head}, 8-byte long, is the
+(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the
head of @dfn{jumppad}, which is used to jump to data collection routine
in IPA finally.
@@ -32247,10 +32249,10 @@ Replies:
@table @samp
@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump}
@var{target_address} is address of tracepoint in the inferior.
-@var{gdb_jump_pad_head} is updated head of jumppad. Both of
+The @var{gdb_jump_pad_head} is updated head of jumppad. Both of
@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long.
-@var{fjump} contains a sequence of instructions jump to jumppad entry.
-@var{fjump_size}, 4-byte long, is the size of @var{fjump}.
+The @var{fjump} contains a sequence of instructions jump to jumppad entry.
+The @var{fjump_size}, 4-byte long, is the size of @var{fjump}.
@item E @var{NN}
for an error
@@ -33916,8 +33918,8 @@ Reply:
@item c @r{[}@var{addr}@r{]}
@cindex @samp{c} packet
-Continue. @var{addr} is address to resume. If @var{addr} is omitted,
-resume at current address.
+Continue at @var{addr}, which is the address to resume. If @var{addr}
+is omitted, resume at current address.
This packet is deprecated for multi-threading support. @xref{vCont
packet}.
@@ -34018,10 +34020,10 @@ for an error
@item H @var{op} @var{thread-id}
@cindex @samp{H} packet
Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
-@samp{G}, et.al.). @var{op} depends on the operation to be performed:
-it should be @samp{c} for step and continue operations (note that this
+@samp{G}, et.al.). Depending on the operation to be performed, @var{op}
+should be @samp{c} for step and continue operations (note that this
is deprecated, supporting the @samp{vCont} command is a better
-option), @samp{g} for other operations. The thread designator
+option), and @samp{g} for other operations. The thread designator
@var{thread-id} has the format and interpretation described in
@ref{thread-id syntax}.
@@ -34111,7 +34113,7 @@ server was able to read only part of the region of memory.
@item M @var{addr},@var{length}:@var{XX@dots{}}
@cindex @samp{M} packet
Write @var{length} bytes of memory starting at address @var{addr}.
-@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
+The data is given by @var{XX@dots{}}; each byte is transmitted as a two-digit
hexadecimal number.
Reply:
@@ -34169,14 +34171,14 @@ Don't use this packet; use the @samp{R} packet instead.
@item R @var{XX}
@cindex @samp{R} packet
-Restart the program being debugged. @var{XX}, while needed, is ignored.
+Restart the program being debugged. The @var{XX}, while needed, is ignored.
This packet is only available in extended mode (@pxref{extended mode}).
The @samp{R} packet has no reply.
@item s @r{[}@var{addr}@r{]}
@cindex @samp{s} packet
-Single step. @var{addr} is the address at which to resume. If
+Single step, resuming at @var{addr}. If
@var{addr} is omitted, resume at same address.
This packet is deprecated for multi-threading support. @xref{vCont
@@ -34200,8 +34202,8 @@ Reply:
@item t @var{addr}:@var{PP},@var{MM}
@cindex @samp{t} packet
Search backwards starting at address @var{addr} for a match with pattern
-@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
-@var{addr} must be at least 3 digits.
+@var{PP} and mask @var{MM}, both of which are are 4 byte long.
+There must be at least 3 digits in @var{addr}.
@item T @var{thread-id}
@cindex @samp{T} packet
@@ -34385,7 +34387,7 @@ request is completed.
@item vKill;@var{pid}
@cindex @samp{vKill} packet
@anchor{vKill packet}
-Kill the process with the specified process ID. @var{pid} is a
+Kill the process with the specified process ID @var{pid}, which is a
hexadecimal integer identifying the process. This packet is used in
preference to @samp{k} when multiprocess protocol extensions are
supported; see @ref{multiprocess extensions}.
@@ -34426,7 +34428,7 @@ for success (@pxref{Stop Reply Packets})
@anchor{X packet}
@cindex @samp{X} packet
Write data to memory, where the data is transmitted in binary.
-@var{addr} is address, @var{length} is number of bytes,
+Memory is specified by its address @var{addr} and number of bytes @var{length};
@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
Reply:
@@ -34525,7 +34527,7 @@ Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
address @var{addr}.
A hardware breakpoint is implemented using a mechanism that is not
-dependant on being able to modify the target's memory. @var{kind}
+dependant on being able to modify the target's memory. The @var{kind}
and @var{cond_list} have the same meaning as in @samp{Z0} packets.
@emph{Implementation note: A hardware breakpoint is not affected by code
@@ -34546,7 +34548,7 @@ for an error
@cindex @samp{z2} packet
@cindex @samp{Z2} packet
Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@@ -34563,7 +34565,7 @@ for an error
@cindex @samp{z3} packet
@cindex @samp{Z3} packet
Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@@ -34580,7 +34582,7 @@ for an error
@cindex @samp{z4} packet
@cindex @samp{Z4} packet
Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
-@var{kind} is interpreted as the number of bytes to watch.
+The number of bytes to watch is specified by @var{kind}.
Reply:
@table @samp
@@ -34630,7 +34632,7 @@ this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
@itemize @bullet
@item
If @var{n} is a hexadecimal number, it is a register number, and the
-corresponding @var{r} gives that register's value. @var{r} is a
+corresponding @var{r} gives that register's value. The data @var{r} is a
series of bytes in target byte order, with each byte given by a
two-digit hex number.
@@ -34645,7 +34647,7 @@ the core on which the stop event was detected.
@item
If @var{n} is a recognized @dfn{stop reason}, it describes a more
specific event that stopped the target. The currently defined stop
-reasons are listed below. @var{aa} should be @samp{05}, the trap
+reasons are listed below. The @var{aa} should be @samp{05}, the trap
signal. At most one stop reason should be present.
@item
@@ -34667,7 +34669,7 @@ hex.
@item library
The packet indicates that the loaded libraries have changed.
@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
-list of loaded libraries. @var{r} is ignored.
+list of loaded libraries. The @var{r} part is ignored.
@cindex replay log events, remote reply
@item replaylog
@@ -34847,7 +34849,7 @@ Reply:
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QDisableRandomization} is not supported
@@ -34924,7 +34926,7 @@ Hex encoded (big endian) bytes representing the address of the thread
local storage requested.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
@@ -34968,8 +34970,8 @@ Where: @var{count} (two hex digits) is the number of threads being
returned; @var{done} (one hex digit) is zero to indicate more threads
and one indicates no further threads; @var{argthreadid} (eight hex
digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
-is a sequence of thread IDs from the target. @var{threadid} (eight hex
-digits). See @code{remote.c:parse_threadlist_response()}.
+is a sequence of thread IDs, @var{threadid} (eight hex
+digits), from the target. See @code{remote.c:parse_threadlist_response()}.
@end table
@item qOffsets
@@ -35028,7 +35030,7 @@ Reply:
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QNonStop} is not supported by
@@ -35060,7 +35062,7 @@ Reply:
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QPassSignals} is not supported by
@@ -35102,7 +35104,7 @@ Reply:
The request succeeded.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that @samp{QProgramSignals} is not supported
@@ -35149,8 +35151,8 @@ packets.)
@cindex @samp{qSearch memory} packet
@anchor{qSearch memory}
Search @var{length} bytes at @var{address} for @var{search-pattern}.
-@var{address} and @var{length} are encoded in hex.
-@var{search-pattern} is a sequence of bytes, hex encoded.
+Both @var{address} and @var{length} are encoded in hex;
+@var{search-pattern} is a sequence of bytes, also hex encoded.
Reply:
@table @samp
@@ -35706,9 +35708,9 @@ encoded). @value{GDBN} will continue to supply the values of symbols
@item qThreadExtraInfo,@var{thread-id}
@cindex thread attributes info, remote request
@cindex @samp{qThreadExtraInfo} packet
-Obtain a printable string description of a thread's attributes from
-the target OS. @var{thread-id} is a thread ID;
-see @ref{thread-id syntax}. This
+Obtain from the target OS a printable string description of thread
+attributes for the thread @var{thread-id}; see @ref{thread-id syntax},
+for the forms of @var{thread-id}. This
string may contain anything that the target OS thinks is interesting
for @value{GDBN} to tell the user about the thread. The string is
displayed in @value{GDBN}'s @code{info threads} display. Some
@@ -35938,7 +35940,7 @@ by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@item qXfer:osdata:read::@var{offset},@var{length}
@anchor{qXfer osdata read}
-Access the target's @dfn{operating system information}.
+Access the target's @dfn{operating system information}.
@xref{Operating System Information}.
@end table
@@ -35950,13 +35952,13 @@ Data @var{data} (@pxref{Binary Data}) has been read from the
target. There may be more data at a higher address (although
it is permitted to return @samp{m} even for the last valid
block of data, as long as at least one byte of data was read).
-@var{data} may have fewer bytes than the @var{length} in the
+It is possible for @var{data} to have fewer bytes than the @var{length} in the
request.
@item l @var{data}
Data @var{data} (@pxref{Binary Data}) has been read from the target.
-There is no more data to be read. @var{data} may have fewer bytes
-than the @var{length} in the request.
+There is no more data to be read. It is possible for @var{data} to
+have fewer bytes than the @var{length} in the request.
@item l
The @var{offset} in the request is at the end of the data.
@@ -35967,7 +35969,7 @@ The request was malformed, or @var{annex} was invalid.
@item E @var{nn}
The offset was invalid, or there was an error encountered reading the data.
-@var{nn} is a hex-encoded @code{errno} value.
+The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
An empty reply indicates the @var{object} string was not recognized by
@@ -35979,8 +35981,8 @@ the stub, or that the object does not support reading.
@anchor{qXfer write}
Write uninterpreted bytes into the target's special data area
identified by the keyword @var{object}, starting at @var{offset} bytes
-into the data. @var{data}@dots{} is the binary-encoded data
-(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
+into the data. The binary-encoded data (@pxref{Binary Data}) to be
+written is given by @var{data}@dots{}. The content and encoding of @var{annex}
is specific to @var{object}; it can supply additional details about what data
to access.
@@ -36022,7 +36024,7 @@ The request was malformed, or @var{annex} was invalid.
@item E @var{nn}
The offset was invalid, or there was an error encountered writing the data.
-@var{nn} is a hex-encoded @code{errno} value.
+The @var{nn} part is a hex-encoded @code{errno} value.
@item @w{}
An empty reply indicates the @var{object} string was not
@@ -36190,8 +36192,8 @@ tracepoints (@pxref{Tracepoints}).
@cindex @samp{QTDP} packet
Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
-the tracepoint is disabled. @var{step} is the tracepoint's step
-count, and @var{pass} is its pass count. If an @samp{F} is present,
+the tracepoint is disabled. The @var{step} gives the tracepoint's step
+count, and @var{pass} gives its pass count. If an @samp{F} is present,
then the tracepoint is to be a fast tracepoint, and the @var{flen} is
the number of bytes that the target should copy elsewhere to make room
for the tracepoint. If an @samp{X} is present, it introduces a
@@ -36212,7 +36214,7 @@ The packet was not recognized.
@end table
@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
-Define actions to be taken when a tracepoint is hit. @var{n} and
+Define actions to be taken when a tracepoint is hit. The @var{n} and
@var{addr} must be the same as in the initial @samp{QTDP} packet for
this tracepoint. This packet may only be sent immediately after
another @samp{QTDP} packet that ended with a @samp{-}. If the
@@ -36234,7 +36236,7 @@ following forms:
@table @samp
@item R @var{mask}
-Collect the registers whose bits are set in @var{mask}. @var{mask} is
+Collect the registers whose bits are set in @var{mask},
a hexadecimal number whose @var{i}'th bit is set if register number
@var{i} should be collected. (The least significant bit is numbered
zero.) Note that @var{mask} may be any number of digits long; it may
@@ -36250,7 +36252,7 @@ values (the @samp{-1} value for @var{basereg} is a special case).
@item X @var{len},@var{expr}
Evaluate @var{expr}, whose length is @var{len}, and collect memory as
-it directs. @var{expr} is an agent expression, as described in
+it directs. The agent expression @var{expr} is as described in
@ref{Agent Expressions}. Each byte of the expression is encoded as a
two-digit hex number in the packet; @var{len} is the number of bytes
in the expression (and thus one-half the number of hex digits in the
@@ -36281,7 +36283,7 @@ The packet was not recognized.
@cindex @samp{QTDPsrc} packet
Specify a source string of tracepoint @var{n} at address @var{addr}.
This is useful to get accurate reproduction of the tracepoints
-originally downloaded at the beginning of the trace run. @var{type}
+originally downloaded at the beginning of the trace run. The @var{type}
is the name of the tracepoint part, such as @samp{cond} for the
tracepoint's conditional expression (see below for a list of types), while
@var{bytes} is the string, encoded in hexadecimal.
@@ -36380,9 +36382,10 @@ Replies:
@item 0
The minimum instruction length is currently unknown.
@item @var{length}
-The minimum instruction length is @var{length}, where @var{length} is greater
-or equal to 1. @var{length} is a hexadecimal number. A reply of 1 means
-that a fast tracepoint may be placed on any instruction regardless of size.
+The minimum instruction length is @var{length}, where @var{length}
+is a hexadecimal number greater or equal to 1. A reply
+of 1 means that a fast tracepoint may be placed on any instruction
+regardless of size.
@item E
An error has occurred.
@item @w{}
@@ -36477,8 +36480,8 @@ The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
@item terror:@var{text}:@var{tpnum}
The trace stopped because tracepoint @var{tpnum} had an error. The
string @var{text} is available to describe the nature of the error
-(for instance, a divide by zero in the condition expression).
-@var{text} is hex encoded.
+(for instance, a divide by zero in the condition expression); it
+is hex encoded.
@item tunknown:0
The trace stopped for some other reason.
@@ -36596,13 +36599,13 @@ a comma-separated list of markers
@item l
(lower case letter @samp{L}) denotes end of list.
@item E @var{nn}
-An error occurred. @var{nn} are hex digits.
+An error occurred. The error number @var{nn} is given as hex digits.
@item @w{}
An empty reply indicates that the request is not supported by the
stub.
@end table
-@var{address} is encoded in hex.
+The @var{address} is encoded in hex;
@var{id} and @var{extra} are strings encoded in hex.
In response to each query, the target will reply with a list of one or
@@ -36622,7 +36625,7 @@ tracepoint markers.
@item QTSave:@var{filename}
@cindex @samp{QTSave} packet
This packet directs the target to save trace data to the file name
-@var{filename} in the target's filesystem. @var{filename} is encoded
+@var{filename} in the target's filesystem. The @var{filename} is encoded
as a hex string; the interpretation of the file name (relative vs
absolute, wild cards, etc) is up to the target.
@@ -36686,7 +36689,7 @@ memory starting at @var{to}.
Replies:
@table @samp
@item qRelocInsn:@var{adjusted_size}
-Informs the stub the relocation is complete. @var{adjusted_size} is
+Informs the stub the relocation is complete. The @var{adjusted_size} is
the length in bytes of resulting relocated instruction sequence.
@item E @var{NN}
A badly formed request was detected, or an error was encountered while
@@ -36733,7 +36736,7 @@ The valid responses to Host I/O packets are:
@item F @var{result} [, @var{errno}] [; @var{attachment}]
@var{result} is the integer value returned by this operation, usually
non-negative for success and -1 for errors. If an error has occured,
-@var{errno} will be included in the result. @var{errno} will have a
+@var{errno} will be included in the result specifying a
value defined by the File-I/O protocol (@pxref{Errno Values}). For
operations which return data, @var{attachment} supplies the data as a
binary buffer. Binary buffers in response packets are escaped in the
@@ -36749,9 +36752,9 @@ An empty response indicates that this operation is not recognized.
These are the supported Host I/O operations:
@table @samp
-@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
-Open a file at @var{pathname} and return a file descriptor for it, or
-return -1 if an error occurs. @var{pathname} is a string,
+@item vFile:open: @var{filename}, @var{flags}, @var{mode}
+Open a file at @var{filename} and return a file descriptor for it, or
+return -1 if an error occurs. The @var{filename} is a string,
@var{flags} is an integer indicating a mask of open flags
(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
of mode bits to use if the file is created (@pxref{mode_t Values}).
@@ -36785,9 +36788,9 @@ packet is used. @samp{vFile:write} returns the number of bytes written,
which may be shorter than the length of @var{data}, or -1 if an
error occurred.
-@item vFile:unlink: @var{pathname}
-Delete the file at @var{pathname} on the target. Return 0,
-or -1 if an error occurs. @var{pathname} is a string.
+@item vFile:unlink: @var{filename}
+Delete the file at @var{filename} on the target. Return 0,
+or -1 if an error occurs. The @var{filename} is a string.
@item vFile:readlink: @var{filename}
Read value of symbolic link @var{filename} on the target. Return
@@ -36888,8 +36891,8 @@ Each notification is comprised of three parts:
@item @var{name}:@var{event}
The notification packet is sent by the side that initiates the
exchange (currently, only the stub does that), with @var{event}
-carrying the specific information about the notification.
-@var{name} is the name of the notification.
+carrying the specific information about the notification, and
+@var{name} specifying the name of the notification.
@item @var{ack}
The acknowledge sent by the other side, usually @value{GDBN}, to
acknowledge the exchange and request the event.
@@ -38953,7 +38956,7 @@ some system control registers; this is not related to the target's
ABI.
@item type
-The type of the register. @var{type} may be a predefined type, a type
+The type of the register. It may be a predefined type, a type
defined in the current feature, or one of the special types @code{int}
and @code{float}. @code{int} is an integer type of the correct size
for @var{bitsize}, and @code{float} is a floating point type (in the
@@ -38961,7 +38964,7 @@ architecture's normal floating point format) of the correct size for
@var{bitsize}. The default is @code{int}.
@item group
-The register group to which this register belongs. @var{group} must
+The register group to which this register belongs. It must
be either @code{general}, @code{float}, or @code{vector}. If no
@var{group} is specified, @value{GDBN} will not display the register
in @code{info registers}.
diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 56d817e..be41f36 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -260,7 +260,7 @@ and height, and its pagination will be disabled; @pxref{Screen Size}.
@deffn {Scheme Procedure} history-ref number
Return a value from @value{GDBN}'s value history (@pxref{Value
-History}). @var{number} indicates which history element to return.
+History}). The @var{number} argument indicates which history element to return.
If @var{number} is negative, then @value{GDBN} will take its absolute value
and count backward from the last element (i.e., the most recent element) to
find the value to return. If @var{number} is zero, then @value{GDBN} will
@@ -290,7 +290,7 @@ facilities.
@deffn {Scheme Procedure} parse-and-eval expression
Parse @var{expression} as an expression in the current language,
evaluate it, and return the result as a @code{<gdb:value>}.
-@var{expression} must be a string.
+The @var{expression} must be a string.
This function is useful when computing values.
For example, it is the only way to get the value of a
@@ -541,10 +541,10 @@ The following exception-related procedures are provided by the
@code{(gdb)} module.
@deffn {Scheme Procedure} make-exception key args
-Return a @code{<gdb:exception>} object.
-@var{key} and @var{args} are the standard Guile parameters of an exception.
-See the Guile documentation for more information
-(@pxref{Exceptions,,, guile, GNU Guile Reference Manual}).
+Return a @code{<gdb:exception>} object given by its @var{key} and
+@var{args}, which are the standard Guile parameters of an exception.
+See the Guile documentation for more information (@pxref{Exceptions,,,
+guile, GNU Guile Reference Manual}).
@end deffn
@deffn {Scheme Procedure} exception? object
@@ -821,7 +821,7 @@ Return field @var{field-name} from @code{<gdb:value>} object @var{value}.
@deffn {Scheme Procedure} value-subscript value index
Return the value of array @var{value} at index @var{index}.
-@var{value} must be a subscriptable @code{<gdb:value>} object.
+The @var{value} argument must be a subscriptable @code{<gdb:value>} object.
@end deffn
@deffn {Scheme Procedure} value-call value arg-list
@@ -922,24 +922,25 @@ The length must be a Scheme integer and not a @code{<gdb:value>} integer.
@deffn {Scheme Procedure} value-lazy? value
Return @code{#t} if @var{value} has not yet been fetched
-from the inferior.
+from the inferior.
Otherwise return @code{#f}.
-@value{GDBN} does not fetch values until necessary, for efficiency.
+@value{GDBN} does not fetch values until necessary, for efficiency.
For example:
@smallexample
(define myval (parse-and-eval "somevar"))
@end smallexample
-The value of @code{somevar} is not fetched at this time. It will be
+The value of @code{somevar} is not fetched at this time. It will be
fetched when the value is needed, or when the @code{fetch-lazy}
-procedure is invoked.
+procedure is invoked.
@end deffn
@deffn {Scheme Procedure} make-lazy-value type address
-Return a @code{<gdb:value>} that will be lazily fetched from the target.
-@var{type} is an object of type @code{<gdb:type>} and @var{address} is
-a Scheme integer of the address of the object in target memory.
+Return a @code{<gdb:value>} that will be lazily fetched from the
+target. The object of type @code{<gdb:type>} whose value to fetch is
+specified by its @var{type} and its target memory @var{address}, which
+is a Scheme integer.
@end deffn
@deffn {Scheme Procedure} value-fetch-lazy! value
@@ -1064,8 +1065,7 @@ Otherwise return @code{#f}.
@end deffn
@deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]}
-This function looks up a type by name. @var{name} is the name of the
-type to look up. It must be a string.
+This function looks up a type by its @var{name}, which must be a string.
If @var{block} is given, it is an object of type @code{<gdb:block>},
and @var{name} is looked up in that scope.
@@ -1728,7 +1728,7 @@ Return the list of registered @code{<gdb:pretty-printer>} objects for
@deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list
Set the list of registered @code{<gdb:pretty-printer>} objects for
-@var{objfile} to @var{printer-list}.
+@var{objfile} to @var{printer-list}. The
@var{printer-list} must be a list of @code{<gdb:pretty-printer>} objects.
@xref{Guile Pretty Printing API}, for more information.
@end deffn
@@ -1903,9 +1903,9 @@ Return the frame's @code{<gdb:sal>} (symtab and line) object.
Return the value of @var{variable} in @var{frame}. If the optional
argument @var{block} is provided, search for the variable from that
block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter). @var{variable}
-must be a string or a @code{<gdb:symbol>} object. @var{block} must be a
-@code{<gdb:block>} object.
+determined by the frame's current program counter). The
+@var{variable} must be given as a string or a @code{<gdb:symbol>}
+object, and @var{block} must be a @code{<gdb:block>} object.
@end deffn
@deffn {Scheme Procedure} frame-select frame
@@ -2397,14 +2397,14 @@ The following breakpoint-related procedures are provided by the
@c TODO: line length
@deffn {Scheme Procedure} create-breakpoint! location @r{[}#:type type@r{]} @r{[}#:wp-class wp-class@r{]} @r{[}#:internal internal@r{]}
-Create a new breakpoint. @var{spec} is a string naming the
+Create a new breakpoint according to @var{spec}, a string naming the
location of the breakpoint, or an expression that defines a watchpoint.
The contents can be any location recognized by the @code{break} command,
or in the case of a watchpoint, by the @code{watch} command.
The optional @var{type} denotes the breakpoint to create.
-This argument can be either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}.
-@var{type} defaults to @code{BP_BREAKPOINT}.
+This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT},
+and defaults to @code{BP_BREAKPOINT}.
The optional @var{wp-class} argument defines the class of watchpoint to
create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is
@@ -2594,7 +2594,7 @@ See @code{set-breakpoint-stop!} below in this section.
@end deffn
@deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f
-Set the stop predicate of @var{breakpoint}.
+Set the stop predicate of @var{breakpoint}. The predicate
@var{procedure} takes one argument: the <gdb:breakpoint> object.
If this predicate is set to a procedure then it is invoked whenever
the inferior reaches this breakpoint. If it returns @code{#t},
@@ -2953,11 +2953,12 @@ returns a port object. One can then read/write memory using that object.
@deffn {Scheme Procedure} open-memory @r{[}#:mode mode{]} @r{[}#:start address{]} @r{[}#:size size{]}
Return a port object that can be used for reading and writing memory.
-@var{mode} is the standard mode argument to Guile port open routines,
-except that it is restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}.
-For compatibility @samp{"b"} (binary) may also be present,
-but we ignore it: memory ports are binary only.
-The default is @samp{"r"}, read-only.
+The port will be open according to @var{mode}, which is the standard
+mode argument to Guile port open routines, except that it is
+restricted to one of @samp{"r"}, @samp{"w"}, or @samp{"r+"}. For
+compatibility @samp{"b"} (binary) may also be present, but we ignore
+it: memory ports are binary only. The default is @samp{"r"},
+read-only.
The chunk of memory that can be accessed can be bounded.
If both @var{start} and @var{size} are unspecified, all of memory can be
@@ -3223,14 +3224,14 @@ Usage:
@deffn {Scheme Procedure} prepend-pretty-printer! object printer
Add @var{printer} to the front of the list of pretty-printers for
-@var{object}. @var{object} must either be a @code{<gdb:objfile>} object
+@var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
or @code{#f} in which case @var{printer} is added to the global list of
printers.
@end deffn
@deffn {Scheme Procecure} append-pretty-printer! object printer
Add @var{printer} to the end of the list of pretty-printers for
-@var{object}. @var{object} must either be a @code{<gdb:objfile>} object
+@var{object}. The @var{object} must either be a @code{<gdb:objfile>} object,
or @code{#f} in which case @var{printer} is added to the global list of
printers.
@end deffn
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index ba0a7fd..ce8ec78 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -215,7 +215,7 @@ Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
If a GDB exception happens while @var{command} runs, it is
translated as described in @ref{Exception Handling,,Exception Handling}.
-@var{from_tty} specifies whether @value{GDBN} ought to consider this
+The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this
command as having originated from the user invoking it interactively.
It must be a boolean value. If omitted, it defaults to @code{False}.
@@ -237,10 +237,10 @@ Return a sequence holding all of @value{GDBN}'s breakpoints.
@findex gdb.parameter
@defun gdb.parameter (parameter)
-Return the value of a @value{GDBN} parameter. @var{parameter} is a
-string naming the parameter to look up; @var{parameter} may contain
-spaces if the parameter has a multi-part name. For example,
-@samp{print object} is a valid parameter name.
+Return the value of a @value{GDBN} @var{parameter} given by its name,
+a string; the parameter name string may contain spaces if the parameter has a
+multi-part name. For example, @samp{print object} is a valid
+parameter name.
If the named parameter does not exist, this function throws a
@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the
@@ -251,7 +251,7 @@ type, and returned.
@findex gdb.history
@defun gdb.history (number)
Return a value from @value{GDBN}'s value history (@pxref{Value
-History}). @var{number} indicates which history element to return.
+History}). The @var{number} argument indicates which history element to return.
If @var{number} is negative, then @value{GDBN} will take its absolute value
and count backward from the last element (i.e., the most recent element) to
find the value to return. If @var{number} is zero, then @value{GDBN} will
@@ -265,9 +265,9 @@ If no exception is raised, the return value is always an instance of
@findex gdb.parse_and_eval
@defun gdb.parse_and_eval (expression)
-Parse @var{expression} as an expression in the current language,
-evaluate it, and return the result as a @code{gdb.Value}.
-@var{expression} must be a string.
+Parse @var{expression}, which must be a string, as an expression in
+the current language, evaluate it, and return the result as a
+@code{gdb.Value}.
This function can be useful when implementing a new command
(@pxref{Commands In Python}), as it provides a way to parse the
@@ -871,8 +871,7 @@ module:
@findex gdb.lookup_type
@defun gdb.lookup_type (name @r{[}, block@r{]})
-This function looks up a type by name. @var{name} is the name of the
-type to look up. It must be a string.
+This function looks up a type by its @var{name}, which must be a string.
If @var{block} is given, then @var{name} is looked up in that scope.
Otherwise, it is searched for globally.
@@ -1533,8 +1532,8 @@ The recognition function is defined as:
@defmethod type_recognizer recognize (self, type)
If @var{type} is not recognized, return @code{None}. Otherwise,
return a string which is to be printed as the name of @var{type}.
-@var{type} will be an instance of @code{gdb.Type} (@pxref{Types In
-Python}).
+The @var{type} argument will be an instance of @code{gdb.Type}
+(@pxref{Types In Python}).
@end defmethod
@value{GDBN} uses this two-pass approach so that type printers can
@@ -2540,8 +2539,8 @@ this method, that is, the @key{TAB} and @key{M-?} key bindings
(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
complete}).
-The arguments @var{text} and @var{word} are both strings. @var{text}
-holds the complete command line up to the cursor's location.
+The arguments @var{text} and @var{word} are both strings; @var{text}
+holds the complete command line up to the cursor's location, while
@var{word} holds the last word of the command line; this is computed
using a word-breaking heuristic.
@@ -3246,8 +3245,8 @@ Return the frame's symtab and line object.
Return the value of @var{variable} in this frame. If the optional
argument @var{block} is provided, search for the variable from that
block; otherwise start at the frame's current block (which is
-determined by the frame's current program counter). @var{variable}
-must be a string or a @code{gdb.Symbol} object. @var{block} must be a
+determined by the frame's current program counter). The @var{variable}
+argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a
@code{gdb.Block} object.
@end defun
@@ -3777,8 +3776,8 @@ has the following direct access methods:
@defun LineTable.line (line)
Return a Python @code{Tuple} of @code{LineTableEntry} objects for any
-entries in the line table for the given @var{line}. @var{line} refers
-to the source code line. If there are no entries for that source code
+entries in the line table for the given @var{line}, which specifies
+the source code line. If there are no entries for that source code
@var{line}, the Python @code{None} is returned.
@end defun
@@ -3805,13 +3804,13 @@ Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
class.
@defun Breakpoint.__init__ (spec @r{[}, type @r{[}, wp_class @r{[},internal @r{[},temporary@r{]]]]})
-Create a new breakpoint. @var{spec} is a string naming the location
-of the breakpoint, or an expression that defines a watchpoint. The
-contents can be any location recognized by the @code{break} command,
-or in the case of a watchpoint, by the @code{watch} command. The
-optional @var{type} denotes the breakpoint to create from the types
-defined later in this chapter. This argument can be either:
-@code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}. @var{type}
+Create a new breakpoint according to @var{spec}, which is a string
+naming the location of the breakpoint, or an expression that defines a
+watchpoint. The contents can be any location recognized by the
+@code{break} command, or in the case of a watchpoint, by the
+@code{watch} command. The optional @var{type} denotes the breakpoint
+to create from the types defined later in this chapter. This argument
+can be either @code{gdb.BP_BREAKPOINT} or @code{gdb.BP_WATCHPOINT}; it
defaults to @code{gdb.BP_BREAKPOINT}. The optional @var{internal}
argument allows the breakpoint to become invisible to the user. The
breakpoint will neither be reported when created, nor will it be
@@ -4261,8 +4260,8 @@ regular expressions.
A pretty-printer which handles printing of @code{enum} values. Unlike
@value{GDBN}'s built-in @code{enum} printing, this printer attempts to
work properly when there is some overlap between the enumeration
-constants. @var{name} is the name of the printer and also the name of
-the @code{enum} type to look up.
+constants. The argument @var{name} is the name of the printer and
+also the name of the @code{enum} type to look up.
@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False)
Register @var{printer} with the pretty-printer list of @var{obj}.
@@ -4350,13 +4349,12 @@ string. Otherwise, return @code{None}. This is called by
API}).
@item register_type_printer (locus, printer)
-This is a convenience function to register a type printer.
-@var{printer} is the type printer to register. It must implement the
-type printer protocol. @var{locus} is either a @code{gdb.Objfile}, in
-which case the printer is registered with that objfile; a
-@code{gdb.Progspace}, in which case the printer is registered with
-that progspace; or @code{None}, in which case the printer is
-registered globally.
+This is a convenience function to register a type printer
+@var{printer}. The printer must implement the type printer protocol.
+The @var{locus} argument is either a @code{gdb.Objfile}, in which case
+the printer is registered with that objfile; a @code{gdb.Progspace},
+in which case the printer is registered with that progspace; or
+@code{None}, in which case the printer is registered globally.
@item TypePrinter
This is a base class that implements the type printer protocol. Type
More information about the Gdb-patches
mailing list