* Re: [PATCH] fix hyphenation and matters of style in docs
2007-04-10 19:22 ` Eli Zaretskii
@ 2007-04-11 18:52 ` Bob Wilson
0 siblings, 0 replies; 4+ messages in thread
From: Bob Wilson @ 2007-04-11 18:52 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Daniel Jacobowitz, gdb-patches
[-- Attachment #1: Type: text/plain, Size: 2152 bytes --]
On Apr 10, 2007, at 12:21 PM, Eli Zaretskii wrote:
>
> Either I didn't see or somehow managed to delete it inadvertently,
> since I don't have it in my INBOX. Sorry for that.
No problem.
>
> Reviewing it now, I agree with the suggested changes, but have a few
> questions/requests:
>
> . Please replace "@code{configure}" with "@file{configure}" or
> "@command{configure}".
OK. There were quite a few other instances of this, so I went ahead
and changed them all to @file{configure}.
>
> . I don't understand this change:
>
> -@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call
> specific attachment}
> +@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call
> specific
> +attachment}
>
> Maybe you wanted to say "call-specific attachment"? if so, I agree.
Hmm. I think you're right -- I must have intended to add the hyphen,
and regardless, that seems like the right thing to do.
>
> . Since this patch was posted, the section names were rewritten to
> use a consistent capitalization, but this one doesn't:
>
> +@subsection Protocol-specific representation of datatypes
Right.
>
> With these gotchas taken care of, Bob, please commit the patch, and
> thanks.
OK, thanks. I've committed the revised patch attached below.
>
> And thanks to Daniel for the heads-up.
Yes, thanks, Daniel!
gdb/doc/
* gdb.texinfo (Contributors, Continuing and Stepping)
(Fortran Defaults, HPPA, TUI, TUI Commands, Configure Options)
(General Query Packets, File-I/O Remote Protocol Extension)
(Protocol Basics, The F Reply Packet, Write)
(Protocol-specific Representation of Datatypes, Memory
Transfer):
Fix hyphenation, punctuation and grammar problems.
(Cygwin Native): Likewise. Also fix misuse of @pxref and use
'section' instead of 'subsection' in the text.
(Non-debug DLL Symbols): Avoid 'subsubsection' in the text.
(i386): Remove period from section name.
(Installing GDB, Requirements, Running Configure, Separate
Objdir)
(Config Names, Configure Options): Use @file{configure}.
[-- Attachment #2: gdb-doc-style.patch --]
[-- Type: application/octet-stream, Size: 18256 bytes --]
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.399
diff -u -r1.399 gdb.texinfo
--- gdb.texinfo 2 Apr 2007 17:31:40 -0000 1.399
+++ gdb.texinfo 11 Apr 2007 18:33:32 -0000
@@ -491,7 +491,7 @@
frame IDs, independent frame sniffers, and the sentinel frame. Mark
Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
-trad unwinders. The architecture specific changes, each involving a
+trad unwinders. The architecture-specific changes, each involving a
complete rewrite of the architecture's frame code, were carried out by
Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
@@ -4097,7 +4097,7 @@
implies that @code{until} can be used to skip over recursive function
invocations. For instance in the code below, if the current location is
line @code{96}, issuing @code{until 99} will execute the program up to
-line @code{99} in the same invocation of factorial, i.e. after the inner
+line @code{99} in the same invocation of factorial, i.e., after the inner
invocations have returned.
@smallexample
@@ -9628,8 +9628,8 @@
@cindex Special Fortran commands
-@value{GDBN} had some commands to support Fortran specific feature,
-such as common block displaying.
+@value{GDBN} has some commands to support Fortran-specific features,
+such as displaying common blocks.
@table @code
@cindex @code{COMMON} blocks, Fortran
@@ -13643,16 +13643,15 @@
@cindex Cygwin-specific commands
@value{GDBN} supports native debugging of MS Windows programs, including
-DLLs with and without symbolic debugging information. There are various
-additional Cygwin-specific commands, described in this subsection. The
-subsubsection @pxref{Non-debug DLL Symbols} describes working with DLLs
-that have no debugging symbols.
-
+DLLs with and without symbolic debugging information. There are various
+additional Cygwin-specific commands, described in this section.
+Working with DLLs that have no debugging symbols is described in
+@ref{Non-debug DLL Symbols}.
@table @code
@kindex info w32
@item info w32
-This is a prefix of MS Windows specific commands which print
+This is a prefix of MS Windows-specific commands which print
information about the target system and important OS structures.
@item info w32 selector
@@ -13665,7 +13664,7 @@
@kindex info dll
@item info dll
-This is a Cygwin specific alias of info shared.
+This is a Cygwin-specific alias of @code{info shared}.
@kindex dll-symbols
@item dll-symbols
@@ -13757,19 +13756,19 @@
Very often on windows, some of the DLLs that your program relies on do
not include symbolic debugging information (for example,
-@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
+@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
symbols in a DLL, it relies on the minimal amount of symbolic
-information contained in the DLL's export table. This subsubsection
+information contained in the DLL's export table. This section
describes working with such symbols, known internally to @value{GDBN} as
``minimal symbols''.
Note that before the debugged program has started execution, no DLLs
-will have been loaded. The easiest way around this problem is simply to
+will have been loaded. The easiest way around this problem is simply to
start the program --- either by setting a breakpoint or letting the
-program run once to completion. It is also possible to force
+program run once to completion. It is also possible to force
@value{GDBN} to load a particular DLL before starting the executable ---
see the shared library information in @ref{Files}, or the
-@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
+@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
explicitly loading symbols from a DLL with no debugging information will
cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
which may adversely affect symbol lookup performance.
@@ -15406,7 +15405,7 @@
@end menu
@node i386
-@subsection x86 Architecture-specific Issues.
+@subsection x86 Architecture-specific Issues
@table @code
@item set struct-convention @var{mode}
@@ -15596,7 +15595,7 @@
@table @code
@item set debug hppa
@kindex set debug hppa
-This command determines whether HPPA architecture specific debugging
+This command determines whether HPPA architecture-specific debugging
messages are to be displayed.
@item show debug hppa
@@ -16686,7 +16685,7 @@
* TUI Overview:: TUI overview
* TUI Keys:: TUI key bindings
* TUI Single Key Mode:: TUI single key mode
-* TUI Commands:: TUI specific commands
+* TUI Commands:: TUI-specific commands
* TUI Configuration:: TUI configuration variables
@end menu
@@ -16980,7 +16979,7 @@
@node TUI Commands
-@section TUI Specific Commands
+@section TUI-specific Commands
@cindex TUI commands
The TUI has specific commands to control the text windows.
@@ -22104,7 +22103,7 @@
@menu
* Requirements:: Requirements for building @value{GDBN}
-* Running Configure:: Invoking the @value{GDBN} @code{configure} script
+* Running Configure:: Invoking the @value{GDBN} @file{configure} script
* Separate Objdir:: Compiling @value{GDBN} in another directory
* Config Names:: Specifying names for hosts and targets
* Configure Options:: Summary of options for configure
@@ -22132,7 +22131,7 @@
@value{GDBN} can use the Expat XML parsing library. This library may be
included with your operating system distribution; if it is not, you
can get the latest version from @url{http://expat.sourceforge.net}.
-The @code{configure} script will search for this library in several
+The @file{configure} script will search for this library in several
standard locations; if it is installed in an unusual path, you can
use the @option{--with-libexpat-prefix} option to specify its location.
@@ -22142,9 +22141,9 @@
@end table
@node Running Configure
-@section Invoking the @value{GDBN} @code{configure} Script
+@section Invoking the @value{GDBN} @file{configure} Script
@cindex configuring @value{GDBN}
-@value{GDBN} comes with a @code{configure} script that automates the process
+@value{GDBN} comes with a @file{configure} script that automates the process
of preparing @value{GDBN} for installation; you can then use @code{make} to
build the @code{gdb} program.
@iftex
@@ -22190,12 +22189,12 @@
source for the @sc{gnu} memory-mapped malloc package
@end table
-The simplest way to configure and build @value{GDBN} is to run @code{configure}
+The simplest way to configure and build @value{GDBN} is to run @file{configure}
from the @file{gdb-@var{version-number}} source directory, which in
this example is the @file{gdb-@value{GDBVN}} directory.
First switch to the @file{gdb-@var{version-number}} source directory
-if you are not already in it; then run @code{configure}. Pass the
+if you are not already in it; then run @file{configure}. Pass the
identifier for the platform on which @value{GDBN} will run as an
argument.
@@ -22210,7 +22209,7 @@
@noindent
where @var{host} is an identifier such as @samp{sun4} or
@samp{decstation}, that identifies the platform where @value{GDBN} will run.
-(You can often leave off @var{host}; @code{configure} tries to guess the
+(You can often leave off @var{host}; @file{configure} tries to guess the
correct value by examining your system.)
Running @samp{configure @var{host}} and then running @code{make} builds the
@@ -22219,7 +22218,7 @@
binaries, are left in the corresponding source directories.
@need 750
-@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
+@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
system does not recognize this automatically when you run a different
shell, you may need to run @code{sh} on it explicitly:
@@ -22227,17 +22226,18 @@
sh configure @var{host}
@end smallexample
-If you run @code{configure} from a directory that contains source
+If you run @file{configure} from a directory that contains source
directories for multiple libraries or programs, such as the
-@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
+@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN},
+@file{configure}
creates configuration files for every directory level underneath (unless
you tell it not to, with the @samp{--norecursion} option).
-You should run the @code{configure} script from the top directory in the
+You should run the @file{configure} script from the top directory in the
source tree, the @file{gdb-@var{version-number}} directory. If you run
-@code{configure} from one of the subdirectories, you will configure only
+@file{configure} from one of the subdirectories, you will configure only
that subdirectory. That is usually not what you want. In particular,
-if you run the first @code{configure} from the @file{gdb} subdirectory
+if you run the first @file{configure} from the @file{gdb} subdirectory
of the @file{gdb-@var{version-number}} directory, you will omit the
configuration of @file{bfd}, @file{readline}, and other sibling
directories of the @file{gdb} subdirectory. This leads to build errors
@@ -22254,17 +22254,17 @@
If you want to run @value{GDBN} versions for several host or target machines,
you need a different @code{gdb} compiled for each combination of
-host and target. @code{configure} is designed to make this easy by
+host and target. @file{configure} is designed to make this easy by
allowing you to generate each configuration in a separate subdirectory,
rather than in the source directory. If your @code{make} program
handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
@code{make} in each of these directories builds the @code{gdb}
program specified there.
-To build @code{gdb} in a separate directory, run @code{configure}
+To build @code{gdb} in a separate directory, run @file{configure}
with the @samp{--srcdir} option to specify where to find the source.
-(You also need to specify a path to find @code{configure}
-itself from your working directory. If the path to @code{configure}
+(You also need to specify a path to find @file{configure}
+itself from your working directory. If the path to @file{configure}
would be the same as the argument to @samp{--srcdir}, you can leave out
the @samp{--srcdir} option; it is assumed.)
@@ -22281,7 +22281,7 @@
@end group
@end smallexample
-When @code{configure} builds a configuration using a remote source
+When @file{configure} builds a configuration using a remote source
directory, it creates a tree for the binaries with the same structure
(and using the same names) as the tree under the source directory. In
the example, you'd find the Sun 4 library @file{libiberty.a} in the
@@ -22299,13 +22299,13 @@
@value{GDBN} runs on one machine---the @dfn{host}---while debugging
programs that run on another machine---the @dfn{target}).
You specify a cross-debugging target by
-giving the @samp{--target=@var{target}} option to @code{configure}.
+giving the @samp{--target=@var{target}} option to @file{configure}.
When you run @code{make} to build a program or library, you must run
it in a configured directory---whatever directory you were in when you
-called @code{configure} (or one of its subdirectories).
+called @file{configure} (or one of its subdirectories).
-The @code{Makefile} that @code{configure} generates in each source
+The @code{Makefile} that @file{configure} generates in each source
directory also runs recursively. If you type @code{make} in a source
directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
@@ -22319,7 +22319,7 @@
@node Config Names
@section Specifying Names for Hosts and Targets
-The specifications used for hosts and targets in the @code{configure}
+The specifications used for hosts and targets in the @file{configure}
script are based on a three-part naming scheme, but some short predefined
aliases are also supported. The full naming scheme encodes three pieces
of information in the following pattern:
@@ -22332,9 +22332,9 @@
or as the value for @var{target} in a @code{--target=@var{target}}
option. The equivalent full name is @samp{sparc-sun-sunos4}.
-The @code{configure} script accompanying @value{GDBN} does not provide
+The @file{configure} script accompanying @value{GDBN} does not provide
any query facility to list all supported host and target names or
-aliases. @code{configure} calls the Bourne shell script
+aliases. @file{configure} calls the Bourne shell script
@code{config.sub} to map abbreviations to full names; you can read the
script, if you wish, or you can use it to test your guesses on
abbreviations---for example:
@@ -22359,12 +22359,12 @@
directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
@node Configure Options
-@section @code{configure} Options
+@section @file{configure} Options
-Here is a summary of the @code{configure} options and arguments that
-are most often useful for building @value{GDBN}. @code{configure} also has
+Here is a summary of the @file{configure} options and arguments that
+are most often useful for building @value{GDBN}. @file{configure} also has
several other options not listed here. @inforef{What Configure
-Does,,configure.info}, for a full explanation of @code{configure}.
+Does,,configure.info}, for a full explanation of @file{configure}.
@smallexample
configure @r{[}--help@r{]}
@@ -22383,7 +22383,7 @@
@table @code
@item --help
-Display a quick summary of how to invoke @code{configure}.
+Display a quick summary of how to invoke @file{configure}.
@item --prefix=@var{dir}
Configure the source to install programs and files under directory
@@ -22401,14 +22401,14 @@
Use this option to make configurations in directories separate from the
@value{GDBN} source directories. Among other things, you can use this to
build (or maintain) several configurations simultaneously, in separate
-directories. @code{configure} writes configuration specific files in
+directories. @file{configure} writes configuration-specific files in
the current directory, but arranges for them to use the source in the
-directory @var{dirname}. @code{configure} creates directories under
+directory @var{dirname}. @file{configure} creates directories under
the working directory in parallel to the source directories below
@var{dirname}.
@item --norecursion
-Configure only the directory level where @code{configure} is executed; do not
+Configure only the directory level where @file{configure} is executed; do not
propagate configuration to subdirectories.
@item --target=@var{target}
@@ -23647,7 +23647,7 @@
thread local variable. (This offset is obtained from the debug
information associated with the variable.)
-@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the
the load module associated with the thread local storage. For example,
a @sc{gnu}/Linux system will pass the link map address of the shared
object associated with the thread local storage under consideration.
@@ -24382,7 +24382,7 @@
* The Ctrl-C Message::
* Console I/O::
* List of Supported Calls::
-* Protocol Specific Representation of Datatypes::
+* Protocol-specific Representation of Datatypes::
* Constants::
* File-I/O Examples::
@end menu
@@ -24452,7 +24452,7 @@
All parameters to the system call. Pointers are given as addresses
in the target memory address space. Pointers to strings are given as
pointer/length pair. Numerical values are given as they are.
-Numerical control flags are given in a protocol specific representation.
+Numerical control flags are given in a protocol-specific representation.
@end itemize
@@ -24537,11 +24537,13 @@
@table @samp
-@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment}
+@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific
+attachment}
@var{retcode} is the return code of the system call as hexadecimal value.
-@var{errno} is the @code{errno} set by the call, in protocol specific representation.
+@var{errno} is the @code{errno} set by the call, in protocol-specific
+representation.
This parameter can be omitted if the call was successful.
@var{Ctrl-C flag} is only sent if the user requested a break. In this
@@ -24560,7 +24562,7 @@
@end smallexample
@noindent
-assuming 4 is the protocol specific representation of @code{EINTR}.
+assuming 4 is the protocol-specific representation of @code{EINTR}.
@end table
@@ -24872,7 +24874,7 @@
@item EFBIG
An attempt was made to write a file that exceeds the
-host specific maximum file size allowed.
+host-specific maximum file size allowed.
@item ENOSPC
No space on device to write the data.
@@ -25210,9 +25212,9 @@
protocol.
@end table
-@node Protocol Specific Representation of Datatypes
-@subsection Protocol Specific Representation of Datatypes
-@cindex protocol specific representation of datatypes, in file-i/o protocol
+@node Protocol-specific Representation of Datatypes
+@subsection Protocol-specific Representation of Datatypes
+@cindex protocol-specific representation of datatypes, in file-i/o protocol
@menu
* Integral Datatypes::
@@ -25272,7 +25274,7 @@
@cindex memory transfer, in file-i/o protocol
Structured data which is transferred using a memory read or write (for
-example, a @code{struct stat}) is expected to be in a protocol specific format
+example, a @code{struct stat}) is expected to be in a protocol-specific format
with all scalar multibyte datatypes being big endian. Translation to
this representation needs to be done both by the target before the @code{F}
packet is sent, and by @value{GDBN} before
^ permalink raw reply [flat|nested] 4+ messages in thread