[PATCH] fix hyphenation and matters of style in docs

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH] fix hyphenation and matters of style in docs

Bob Wilson
I've got a few more doc patches left.  This one gets into some things that are a
little bit more a matter of style, at least in regard to the best way to fix the
problems.  I've been trying to make fairly minimal changes here (although I did
add some whitespace fixes to this patch after seeing Eli's request for that),
but in some cases I wondered whether more substantial changes would be better,
e.g., to avoid use of hyphenated adjectives.  Personally, I think this patch is
fine, so I guess I'm just trying to explain why I split out these changes into a
separate patch -- they seemed more likely to generate some comments.

2007-03-26  Bob Wilson  <[hidden email]>
       
        * 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.


Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.394
diff -u -r1.394 gdb.texinfo
--- gdb.texinfo 26 Mar 2007 15:51:17 -0000 1.394
+++ gdb.texinfo 26 Mar 2007 16:46:10 -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
@@ -4120,7 +4120,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
@@ -9651,8 +9651,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
@@ -13664,16 +13664,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
@@ -13686,7 +13685,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
@@ -13778,19 +13777,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.
@@ -15540,7 +15539,7 @@
 @end menu
 
 @node i386
-@subsection x86 Architecture-specific issues.
+@subsection x86 Architecture-specific issues
 
 @table @code
 @item set struct-convention @var{mode}
@@ -15730,7 +15729,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
@@ -16820,7 +16819,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
 
@@ -17114,7 +17113,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.
@@ -22535,7 +22534,7 @@
 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.  @code{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
 the working directory in parallel to the source directories below
@@ -23781,7 +23780,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.
@@ -24516,7 +24515,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
@@ -24586,7 +24585,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
 
@@ -24671,11 +24670,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
@@ -24694,7 +24695,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
 
@@ -25006,7 +25007,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.
@@ -25344,9 +25345,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::
@@ -25406,7 +25407,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
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] fix hyphenation and matters of style in docs

Daniel Jacobowitz-2
On Mon, Mar 26, 2007 at 10:08:32AM -0700, Bob Wilson wrote:

> I've got a few more doc patches left.  This one gets into some things that are
> a little bit more a matter of style, at least in regard to the best way to fix
> the problems.  I've been trying to make fairly minimal changes here (although I
> did add some whitespace fixes to this patch after seeing Eli's request for
> that), but in some cases I wondered whether more substantial changes would be
> better, e.g., to avoid use of hyphenated adjectives.  Personally, I think this
> patch is fine, so I guess I'm just trying to explain why I split out these
> changes into a separate patch -- they seemed more likely to generate some
> comments.
>
> 2007-03-26  Bob Wilson  <[hidden email]>
>
> * 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.

Eli, did you see this patch?  I'm only asking because you're normally
so quick to respond :-)


--
Daniel Jacobowitz
CodeSourcery
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] fix hyphenation and matters of style in docs

Eli Zaretskii
> >
> > 2007-03-26  Bob Wilson  <[hidden email]>
> >
> > * 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.
>
> Eli, did you see this patch?

Either I didn't see or somehow managed to delete it inadvertently,
since I don't have it in my INBOX.  Sorry for that.

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}".

 . 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.

 . 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

With these gotchas taken care of, Bob, please commit the patch, and
thanks.

And thanks to Daniel for the heads-up.
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] fix hyphenation and matters of style in docs

Bob Wilson

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}.


gdb-doc-style.patch (18K) Download Attachment