diff mbox

Grammatical edits to error reporting documentation.

Message ID 544B36BC.3080807@pacific.net
State Superseded
Headers show

Commit Message

Rical Jasan Oct. 25, 2014, 5:35 a.m. UTC
Addresses issues with grammar in the manual's Error Reporting chapter
for the sake of clarity and consistency.

    * manual/errno.texi: Edit grammar for clarity and consistency.

2014-10-24  Rical Jasan  <redacted>

	* manual/errno.texi (Error Reporting): Edit grammar for clarity
	and consistency.
diff mbox

Patch

diff --git a/manual/errno.texi b/manual/errno.texi
index 41d6639..eb9617e 100644
--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -104,7 +104,7 @@  happen on @gnuhurdsystems{}, we have saved space by not mentioning
 @code{EFAULT} in the descriptions of individual functions.
 
 In some Unix systems, many system calls can also return @code{EFAULT} if
-given as an argument a pointer into the stack, and the kernel for some
+given a pointer into the stack as an argument, and the kernel for some
 obscure reason fails in its attempt to extend the stack.  If this ever
 happens, you should probably try using statically or dynamically
 allocated memory instead of stack memory on that system.
@@ -168,7 +168,7 @@  Input/output error; usually used for physical read or write errors.
 @comment errno 6 @c DO NOT REMOVE
 No such device or address.  The system tried to use the device
 represented by a file you specified, and it couldn't find the device.
-This can mean that the device file was installed incorrectly, or that
+This can mean the device file was installed incorrectly, or
 the physical device is missing or not correctly attached to the
 computer.
 @end deftypevr
@@ -215,8 +215,8 @@  to manipulate.
 @comment errno 11 @c DO NOT REMOVE
 Deadlock avoided; allocating a system resource would have resulted in a
 deadlock situation.  The system does not guarantee that it will notice
-all such situations.  This error means you got lucky and the system
-noticed; it might just hang.  @xref{File Locks}, for an example.
+all such situations; this error means you got lucky and the system
+noticed it might just hang.  @xref{File Locks}, for an example.
 @end deftypevr
 
 @comment errno.h
@@ -718,7 +718,7 @@  this error occurs when you are trying to delete a directory.
 @comment BSD: Too many processes
 @deftypevr Macro int EPROCLIM
 @comment errno 67 @c DO NOT REMOVE
-This means that the per-user limit on new process would be exceeded by
+This means the per-user limit on new processes would be exceeded by
 an attempted @code{fork}.  @xref{Limits on Resources}, for details on
 the @code{RLIMIT_NPROC} limit.
 @end deftypevr
@@ -1318,17 +1318,17 @@  The @code{strerror_r} function works like @code{strerror} but instead of
 returning the error message in a statically allocated buffer shared by
 all threads in the process, it returns a private copy for the
 thread.  This might be either some permanent global data or a message
-string in the user supplied buffer starting at @var{buf} with the
+string in the user-supplied buffer starting at @var{buf} with the
 length of @var{n} bytes.
 
 At most @var{n} characters are written (including the NUL byte) so it is
-up to the user to select the buffer large enough.
+up to the user to select a buffer large enough.
 
 This function should always be used in multi-threaded programs since
 there is no way to guarantee the string returned by @code{strerror}
 really belongs to the last call of the current thread.
 
-This function @code{strerror_r} is a GNU extension and it is declared in
+The function @code{strerror_r} is a GNU extension and is declared in
 @file{string.h}.
 @end deftypefun
 
@@ -1401,8 +1401,8 @@  names yourself.  We added these extensions to make it possible to write
 self-contained error-reporting subroutines that require no explicit
 cooperation from @code{main}.
 
-Here is an example showing how to handle failure to open a file
-correctly.  The function @code{open_sesame} tries to open the named file
+Here is an example showing how to correctly handle failure to open a
+file.  The function @code{open_sesame} tries to open the named file
 for reading and returns a stream if successful.  The @code{fopen}
 library function returns a null pointer if it couldn't open the file for
 some reason.  In that situation, @code{open_sesame} constructs an
@@ -1468,15 +1468,15 @@  the problem mentioned above that the error reporting function must be
 called immediately after the function causing the error since otherwise
 @code{errno} might have a different value.
 
-The @code{error} prints first the program name.  If the application
-defined a global variable @code{error_print_progname} and points it to a
-function this function will be called to print the program name.
-Otherwise the string from the global variable @code{program_name} is
-used.  The program name is followed by a colon and a space which in turn
-is followed by the output produced by the format string.  If the
-@var{errnum} parameter is non-zero the format string output is followed
-by a colon and a space, followed by the error message for the error code
-@var{errnum}.  In any case is the output terminated with a newline.
+@code{error} first prints the program name.  If the application
+defined a global variable @code{error_print_progname} and points it to
+a function, that function will be called to print the program name;
+otherwise the string from the global variable @code{program_name} is
+used.  The program name is followed by a colon and a space, then the
+output produced by the format string.  If the @var{errnum} parameter
+is non-zero, the format string output is followed by a colon and a
+space, then the error message for the error code @var{errnum}.  In all
+cases the output is terminated with a newline.
 
 The output is directed to the @code{stderr} stream.  If the
 @code{stderr} wasn't oriented before the call it will be narrow-oriented
@@ -1485,7 +1485,7 @@  afterwards.
 The function will return unless the @var{status} parameter has a
 non-zero value.  In this case the function will call @code{exit} with
 the @var{status} value for its parameter and therefore never return.  If
-@code{error} returns the global variable @code{error_message_count} is
+@code{error} returns, the global variable @code{error_message_count} is
 incremented by one to keep track of the number of errors reported.
 @end deftypefun
 
@@ -1503,43 +1503,44 @@  incremented by one to keep track of the number of errors reported.
 @c like error.
 
 The @code{error_at_line} function is very similar to the @code{error}
-function.  The only difference are the additional parameters @var{fname}
+function---the only difference is the additional parameters @var{fname}
 and @var{lineno}.  The handling of the other parameters is identical to
 that of @code{error} except that between the program name and the string
-generated by the format string additional text is inserted.
+generated by the format string, additional text is inserted.
 
-Directly following the program name a colon, followed by the file name
-pointer to by @var{fname}, another colon, and a value of @var{lineno} is
-printed.
-
-This additional output of course is meant to be used to locate an error
-in an input file (like a programming language source code file etc).
+Directly following the program name, a colon, followed by the file name
+pointed to by @code{fname}, another colon, and the value of
+@code{lineno} is printed.  This additional output is meant to help
+locate an error in an input file (e.g., a programming language source
+code file).
 
 If the global variable @code{error_one_per_line} is set to a non-zero
-value @code{error_at_line} will avoid printing consecutive messages for
-the same file and line.  Repetition which are not directly following
-each other are not caught.
+value, @code{error_at_line} will avoid printing consecutive messages for
+the same file and line.
 
-Just like @code{error} this function only returned if @var{status} is
-zero.  Otherwise @code{exit} is called with the non-zero value.  If
-@code{error} returns the global variable @code{error_message_count} is
-incremented by one to keep track of the number of errors reported.
+Just like @code{error}, this function only returns if @var{status} is
+zero; otherwise @code{exit} is called with the non-zero value.  If
+@code{error} returns, the global variable @code{error_message_count}
+is incremented by one to keep track of the number of errors reported.
 @end deftypefun
 
-As mentioned above the @code{error} and @code{error_at_line} functions
-can be customized by defining a variable named
+As mentioned above, the @code{error} and @code{error_at_line}
+functions can be customized by defining a variable named
 @code{error_print_progname}.
 
 @comment error.h
 @comment GNU
 @deftypevar {void (*error_print_progname)} (void)
 If the @code{error_print_progname} variable is defined to a non-zero
-value the function pointed to is called by @code{error} or
+value, the function pointed to is called by @code{error} or
 @code{error_at_line}.  It is expected to print the program name or do
 something similarly useful.
 
-The function is expected to be print to the @code{stderr} stream and
-must be able to handle whatever orientation the stream has.
+The function is expected to print to the @code{stderr} stream and
+must be able to handle whatever orientation the stream has.  To
+preserve the format of @code{error} and @code{error_at_line}, the
+function should append a colon and space, without a newline, to its
+output.
 
 The variable is global and shared by all threads.
 @end deftypevar
@@ -1555,18 +1556,18 @@  variable is global and shared by all threads.
 @comment error.h
 @comment GNU
 @deftypevar int error_one_per_line
-The @code{error_one_per_line} variable influences only
-@code{error_at_line}.  Normally the @code{error_at_line} function
-creates output for every invocation.  If @code{error_one_per_line} is
-set to a non-zero value @code{error_at_line} keeps track of the last
-file name and line number for which an error was reported and avoid
-directly following messages for the same file and line.  This variable
-is global and shared by all threads.
+The @code{error_one_per_line} variable influences
+@code{error_at_line}, which normally creates output for every
+invocation.  If @code{error_one_per_line} is set to a non-zero value,
+@code{error_at_line} keeps track of the last file name and line number
+for which an error was reported and avoids printing consecutive
+messages for the same file and line.  The variable is global and
+shared by all threads.
 @end deftypevar
 
 @noindent
-A program which read some input file and reports errors in it could look
-like this:
+A program which reads some input file and reports errors in it could
+look like this:
 
 @smallexample
 @{
@@ -1608,13 +1609,13 @@  are included only for compatibility.
 @deftypefun void warn (const char *@var{format}, @dots{})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Just calls vwarn with the va_list.
-The @code{warn} function is roughly equivalent to a call like
+The @code{warn} function is roughly equivalent to a call like:
 @smallexample
-  error (0, errno, format, @r{the parameters})
+error (0, errno, format, @r{the parameters})
 @end smallexample
 @noindent
-except that the global variables @code{error} respects and modifies
-are not used.
+except the global variables @code{error} respects and modifies are not
+used.
 @end deftypefun
 
 @comment err.h
@@ -1625,9 +1626,9 @@  are not used.
 @c given message, and the error string with fw?printf's %m.  When the
 @c stream is wide, convert_and_print converts the format string to an
 @c alloca/malloc-created buffer using mbsrtowcs and then calls fwprintf.
-The @code{vwarn} function is just like @code{warn} except that the
-parameters for the handling of the format string @var{format} are passed
-in as a value of type @code{va_list}.
+The @code{vwarn} function is just like @code{warn} except the
+parameters for the handling of the format string @var{format} are
+passed in as a value of type @code{va_list}.
 @end deftypefun
 
 @comment err.h
@@ -1635,14 +1636,14 @@  in as a value of type @code{va_list}.
 @deftypefun void warnx (const char *@var{format}, @dots{})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as warn, but without the strerror translation issues.
-The @code{warnx} function is roughly equivalent to a call like
+The @code{warnx} function is roughly equivalent to a call like:
 @smallexample
-  error (0, 0, format, @r{the parameters})
+error (0, 0, format, @r{the parameters})
 @end smallexample
 @noindent
-except that the global variables @code{error} respects and modifies
-are not used.  The difference to @code{warn} is that no error number
-string is printed.
+except the global variables @code{error} respects and modifies are not
+used.  The difference to @code{warn} is that no error number string is
+printed.
 @end deftypefun
 
 @comment err.h
@@ -1650,9 +1651,9 @@  string is printed.
 @deftypefun void vwarnx (const char *@var{format}, va_list @var{ap})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as vwarn, but without the strerror translation issues.
-The @code{vwarnx} function is just like @code{warnx} except that the
-parameters for the handling of the format string @var{format} are passed
-in as a value of type @code{va_list}.
+The @code{vwarnx} function is just like @code{warnx} except the
+parameters for the handling of the format string @var{format} are
+passed in as a value of type @code{va_list}.
 @end deftypefun
 
 @comment err.h
@@ -1660,13 +1661,13 @@  in as a value of type @code{va_list}.
 @deftypefun void err (int @var{status}, const char *@var{format}, @dots{})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as warn followed by exit.
-The @code{err} function is roughly equivalent to a call like
+The @code{err} function is roughly equivalent to a call like:
 @smallexample
-  error (status, errno, format, @r{the parameters})
+error (status, errno, format, @r{the parameters})
 @end smallexample
 @noindent
-except that the global variables @code{error} respects and modifies
-are not used and that the program is exited even if @var{status} is zero.
+except the global variables @code{error} respects and modifies are not
+used and the program is exited even if @var{status} is zero.
 @end deftypefun
 
 @comment err.h
@@ -1674,9 +1675,9 @@  are not used and that the program is exited even if @var{status} is zero.
 @deftypefun void verr (int @var{status}, const char *@var{format}, va_list @var{ap})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascuintl{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as vwarn followed by exit.
-The @code{verr} function is just like @code{err} except that the
-parameters for the handling of the format string @var{format} are passed
-in as a value of type @code{va_list}.
+The @code{verr} function is just like @code{err} except the parameters
+for the handling of the format string @var{format} are passed in as a
+value of type @code{va_list}.
 @end deftypefun
 
 @comment err.h
@@ -1684,15 +1685,14 @@  in as a value of type @code{va_list}.
 @deftypefun void errx (int @var{status}, const char *@var{format}, @dots{})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as warnx followed by exit.
-The @code{errx} function is roughly equivalent to a call like
+The @code{errx} function is roughly equivalent to a call like:
 @smallexample
-  error (status, 0, format, @r{the parameters})
+error (status, 0, format, @r{the parameters})
 @end smallexample
 @noindent
-except that the global variables @code{error} respects and modifies
-are not used and that the program is exited even if @var{status}
-is zero.  The difference to @code{err} is that no error number
-string is printed.
+except the global variables @code{error} respects and modifies are not
+used and the program is exited even if @var{status} is zero.  The
+difference to @code{err} is that no error number string is printed.
 @end deftypefun
 
 @comment err.h
@@ -1700,7 +1700,7 @@  string is printed.
 @deftypefun void verrx (int @var{status}, const char *@var{format}, va_list @var{ap})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
 @c Same as vwarnx followed by exit.
-The @code{verrx} function is just like @code{errx} except that the
-parameters for the handling of the format string @var{format} are passed
-in as a value of type @code{va_list}.
+The @code{verrx} function is just like @code{errx} except the
+parameters for the handling of the format string @var{format} are
+passed in as a value of type @code{va_list}.
 @end deftypefun