Merge branch 'master' into non-fatal-io-2

1 files changed, 234 insertions, 195 deletions

diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 1e833fe2..c466abff 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -1297,7 +1297,7 @@ October 2014
       <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation>
       <affiliation><jobtitle>Israel</jobtitle></affiliation>
     </author>
-    <date>December 2014</date>
+    <date>February 2015</date>
    </prefaceinfo>
 @end docbook
 
@@ -2253,14 +2253,14 @@ which they raised and educated me.
 Finally, I also must acknowledge my gratitude to G-d, for the many opportunities
 He has sent my way, as well as for the gifts He has given me with which to
 take advantage of those opportunities.
-@iftex
+@ifnotdocbook
 @sp 2
 @noindent
 Arnold Robbins @*
 Nof Ayalon @*
 Israel @*
-December 2014
-@end iftex
+February 2015
+@end ifnotdocbook
 
 @ifnotinfo
 @part @value{PART1}The @command{awk} Language
@@ -12560,6 +12560,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list}
 
 @cindex regexp constants, as patterns
 @cindex patterns, regexp constants as
+A regexp constant as a pattern is also a special case of an expression
 pattern.  The expression @code{/li/} has the value one if @samp{li}
 appears in the current input record. Thus, as a pattern, @code{/li/}
 matches any record containing @samp{li}.
@@ -29337,7 +29338,7 @@ paper and pencil (and/or a calculator). In theory, numbers can have an
 arbitrary number of digits on either side (or both sides) of the decimal
 point, and the results of a computation are always exact.
 
-Some modern system can do decimal arithmetic in hardware, but usually you
+Some modern systems can do decimal arithmetic in hardware, but usually you
 need a special software library to provide access to these instructions.
 There are also libraries that do decimal arithmetic entirely in software.
 
@@ -29393,8 +29394,34 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}.
 @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295
 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807
 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615
-@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38}
-@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308}
+@iftex
+@item Single-precision floating point (approximate) @tab @math{1.175494^{-38}} @tab @math{3.402823^{38}}
+@item Double-precision floating point (approximate) @tab @math{2.225074^{-308}} @tab @math{1.797693^{308}}
+@end iftex
+@ifnottex
+@ifnotdocbook
+@item Single-precision floating point (approximate) @tab 1.175494e-38 @tab 3.402823e38
+@item Double-precision floating point (approximate) @tab 2.225074e-308 @tab 1.797693e308
+@end ifnotdocbook
+@end ifnottex
+@ifdocbook
+@item Single-precision floating point (approximate) @tab
+@docbook
+1.175494<superscript>-38</superscript>
+@end docbook
+@tab
+@docbook
+3.402823<superscript>38</superscript>
+@end docbook
+@item Double-precision floating point (approximate) @tab
+@docbook
+2.225074<superscript>-308</superscript>
+@end docbook
+@tab
+@docbook
+1.797693<superscript>308</superscript>
+@end docbook
+@end ifdocbook
 @end multitable
 @end float
 
@@ -29403,7 +29430,7 @@ signed. The possible ranges of values are shown in @ref{table-numeric-ranges}.
 
 The rest of this @value{CHAPTER} uses a number of terms. Here are some
 informal definitions that should help you work your way through the material
-here.
+here:
 
 @table @dfn
 @item Accuracy
@@ -29424,7 +29451,7 @@ A special value representing infinity. Operations involving another
 number and infinity produce infinity.
 
 @item NaN
-``Not A Number.''@footnote{Thanks to Michael Brennan for this description,
+``Not a number.''@footnote{Thanks to Michael Brennan for this description,
 which we have paraphrased, and for the examples.} A special value that
 results from attempting a calculation that has no answer as a real number.
 In such a case, programs can either receive a floating-point exception,
@@ -29467,8 +29494,8 @@ formula:
 @end display
 
 @noindent
-Here, @var{prec} denotes the binary precision
-(measured in bits) and @var{dps} (short for decimal places)
+Here, @emph{prec} denotes the binary precision
+(measured in bits) and @emph{dps} (short for decimal places)
 is the decimal digits.
 
 @item Rounding mode
@@ -29476,7 +29503,7 @@ How numbers are rounded up or down when necessary.
 More details are provided later.
 
 @item Significand
-A floating-point value consists the significand multiplied by 10
+A floating-point value consists of the significand multiplied by 10
 to the power of the exponent. For example, in @code{1.2345e67},
 the significand is @code{1.2345}.
 
@@ -29500,7 +29527,7 @@ to allow greater precisions and larger exponent ranges.
 (@command{awk} uses only the 64-bit double-precision format.)
 
 @ref{table-ieee-formats} lists the precision and exponent
-field values for the basic IEEE 754 binary formats:
+field values for the basic IEEE 754 binary formats.
 
 @float Table,table-ieee-formats
 @caption{Basic IEEE format values}
@@ -29564,12 +29591,12 @@ for more information.
 @author Teen Talk Barbie, July 1992
 @end quotation
 
-This @value{SECTION} provides a high level overview of the issues
+This @value{SECTION} provides a high-level overview of the issues
 involved when doing lots of floating-point arithmetic.@footnote{There
 is a very nice @uref{http://www.validlab.com/goldberg/paper.pdf,
 paper on floating-point arithmetic} by David Goldberg, ``What Every
-Computer Scientist Should Know About Floating-point Arithmetic,''
-@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), 5-48.  This is
+Computer Scientist Should Know About Floating-Point Arithmetic,''
+@cite{ACM Computing Surveys} @strong{23}, 1 (1991-03): 5-48.  This is
 worth reading if you are interested in the details, but it does require
 a background in computer science.}
 The discussion applies to both hardware and arbitrary-precision
@@ -29638,7 +29665,7 @@ $ @kbd{gawk 'BEGIN @{ x = 0.875; y = 0.425}
 
 Often the error is so small you do not even notice it, and if you do,
 you can always specify how much precision you would like in your output.
-Usually this is a format string like @code{"%.15g"}, which when
+Usually this is a format string like @code{"%.15g"}, which, when
 used in the previous example, produces an output identical to the input.
 
 @node Comparing FP Values
@@ -29677,7 +29704,7 @@ else
 
 The loss of accuracy during a single computation with floating-point
 numbers usually isn't enough to worry about. However, if you compute a
-value which is the result of a sequence of floating-point operations,
+value that is the result of a sequence of floating-point operations,
 the error can accumulate and greatly affect the computation itself.
 Here is an attempt to compute the value of @value{PI} using one of its
 many series representations:
@@ -29730,7 +29757,7 @@ no easy answers. The standard rules of algebra often do not apply
 when using floating-point arithmetic.
 Among other things, the distributive and associative laws
 do not hold completely, and order of operation may be important
-for your computation. Rounding error, cumulative precision loss
+for your computation. Rounding error, cumulative precision loss,
 and underflow are often troublesome.
 
 When @command{gawk} tests the expressions @samp{0.1 + 12.2} and
@@ -29770,7 +29797,8 @@ by our earlier attempt to compute the value of @value{PI}.
 Extra precision can greatly enhance the stability and the accuracy
 of your computation in such cases.
 
-Repeated addition is not necessarily equivalent to multiplication
+Additionally, you should understand that
+repeated addition is not necessarily equivalent to multiplication
 in floating-point arithmetic. In the example in
 @ref{Errors accumulate}:
 
@@ -29833,7 +29861,7 @@ to emulate an IEEE 754 binary format.
 @float Table,table-predefined-precision-strings
 @caption{Predefined precision strings for @code{PREC}}
 @multitable {@code{"double"}} {12345678901234567890123456789012345}
-@headitem @code{PREC} @tab IEEE 754 Binary Format
+@headitem @code{PREC} @tab IEEE 754 binary format
 @item @code{"half"} @tab 16-bit half-precision
 @item @code{"single"} @tab Basic 32-bit single precision
 @item @code{"double"} @tab Basic 64-bit double precision
@@ -29865,7 +29893,6 @@ than the default and cannot use a command-line assignment to @code{PREC},
 you should either specify the constant as a string, or as a rational
 number, whenever possible. The following example illustrates the
 differences among various ways to print a floating-point constant:
-@end quotation
 
 @example
 $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'}
@@ -29877,22 +29904,23 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'}
 $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'}
 @print{} 0.1000000000000000000000000
 @end example
+@end quotation
 
 @node Setting the rounding mode
 @subsection Setting the Rounding Mode
 
 The @code{ROUNDMODE} variable provides
-program level control over the rounding mode.
+program-level control over the rounding mode.
 The correspondence between @code{ROUNDMODE} and the IEEE
 rounding modes is shown in @ref{table-gawk-rounding-modes}.
 
 @float Table,table-gawk-rounding-modes
 @caption{@command{gawk} rounding modes}
 @multitable @columnfractions .45 .30 .25
-@headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE}
+@headitem Rounding mode @tab IEEE name @tab @code{ROUNDMODE}
 @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"}
-@item Round toward plus Infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"}
-@item Round toward negative Infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"}
+@item Round toward positive infinity @tab @code{roundTowardPositive} @tab @code{"U"} or @code{"u"}
+@item Round toward negative infinity @tab @code{roundTowardNegative} @tab @code{"D"} or @code{"d"}
 @item Round toward zero @tab @code{roundTowardZero} @tab @code{"Z"} or @code{"z"}
 @item Round to nearest, ties away from zero @tab @code{roundTiesToAway} @tab @code{"A"} or @code{"a"}
 @end multitable
@@ -29953,8 +29981,8 @@ distributes upward and downward rounds of exact halves, which might
 cause any accumulating round-off error to cancel itself out. This is the
 default rounding mode for IEEE 754 computing functions and operators.
 
-The other rounding modes are rarely used.  Round toward positive infinity
-(@code{roundTowardPositive}) and round toward negative infinity
+The other rounding modes are rarely used.  Rounding toward positive infinity
+(@code{roundTowardPositive}) and toward negative infinity
 (@code{roundTowardNegative}) are often used to implement interval
 arithmetic, where you adjust the rounding mode to calculate upper and
 lower bounds for the range of output. The @code{roundTowardZero} mode can
@@ -30011,17 +30039,17 @@ If instead you were to compute the same value using arbitrary-precision
 floating-point values, the precision needed for correct output (using
 the formula
 @iftex
-@math{prec = 3.322 @cdot dps}),
+@math{prec = 3.322 @cdot dps})
 would be @math{3.322 @cdot 183231},
 @end iftex
 @ifnottex
 @ifnotdocbook
-@samp{prec = 3.322 * dps}),
+@samp{prec = 3.322 * dps})
 would be 3.322 x 183231,
 @end ifnotdocbook
 @end ifnottex
 @docbook
-<emphasis>prec</emphasis> = 3.322 &sdot; <emphasis>dps</emphasis>),
+<emphasis>prec</emphasis> = 3.322 &sdot; <emphasis>dps</emphasis>)
 would be
 <emphasis>prec</emphasis> = 3.322 &sdot; 183231, @c
 @end docbook
@@ -30059,7 +30087,7 @@ interface to process arbitrary-precision integers or mixed-mode numbers
 as needed by an operation or function.  In such a case, the precision is
 set to the minimum value necessary for exact conversion, and the working
 precision is not used for this purpose.  If this is not what you need or
-want, you can employ a subterfuge, and convert the integer to floating
+want, you can employ a subterfuge and convert the integer to floating
 point first, like this:
 
 @example
@@ -30196,7 +30224,7 @@ word sizes. See
 @node POSIX Floating Point Problems
 @section Standards Versus Existing Practice
 
-Historically, @command{awk} has converted any non-numeric looking string
+Historically, @command{awk} has converted any nonnumeric-looking string
 to the numeric value zero, when required.  Furthermore, the original
 definition of the language and the original POSIX standards specified that
 @command{awk} only understands decimal numbers (base 10), and not octal
@@ -30213,8 +30241,8 @@ notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not}
 source code constants.)
 
 @item
-Support for the special IEEE 754 floating-point values ``Not A Number''
-(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf'').
+Support for the special IEEE 754 floating-point values ``not a number''
+(NaN), positive infinity (``inf''), and negative infinity (``@minus{}inf'').
 In particular, the format for these values is as specified by the ISO 1999
 C standard, which ignores case and can allow implementation-dependent additional
 characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}.
@@ -30235,21 +30263,21 @@ values is also a very severe departure from historical practice.
 @end itemize
 
 The second problem is that the @command{gawk} maintainer feels that this
-interpretation of the standard, which requires a certain amount of
+interpretation of the standard, which required a certain amount of
 ``language lawyering'' to arrive at in the first place, was not even
-intended by the standard developers.  In other words, ``we see how you
+intended by the standard developers.  In other words, ``We see how you
 got where you are, but we don't think that that's where you want to be.''
 
 Recognizing these issues, but attempting to provide compatibility
 with the earlier versions of the standard,
 the 2008 POSIX standard added explicit wording to allow, but not require,
 that @command{awk} support hexadecimal floating-point values and
-special values for ``Not A Number'' and infinity.
+special values for ``not a number'' and infinity.
 
 Although the @command{gawk} maintainer continues to feel that
 providing those features is inadvisable,
 nevertheless, on systems that support IEEE floating point, it seems
-reasonable to provide @emph{some} way to support NaN and Infinity values.
+reasonable to provide @emph{some} way to support NaN and infinity values.
 The solution implemented in @command{gawk} is as follows:
 
 @itemize @value{BULLET}
@@ -30269,7 +30297,7 @@ $ @kbd{echo 0xDeadBeef | gawk --posix '@{ print $1 + 0 @}'}
 @end example
 
 @item
-Without @option{--posix}, @command{gawk} interprets the four strings
+Without @option{--posix}, @command{gawk} interprets the four string values
 @samp{+inf},
 @samp{-inf},
 @samp{+nan},
@@ -30291,7 +30319,7 @@ $ @kbd{echo 0xDeadBeef | gawk '@{ print $1 + 0 @}'}
 @end example
 
 @command{gawk} ignores case in the four special values.
-Thus @samp{+nan} and @samp{+NaN} are the same.
+Thus, @samp{+nan} and @samp{+NaN} are the same.
 @end itemize
 
 @node Floating point summary
@@ -30304,9 +30332,9 @@ values.  Standard @command{awk} uses double-precision
 floating-point values.
 
 @item
-In the early 1990s, Barbie mistakenly said ``Math class is tough!''
+In the early 1990s Barbie mistakenly said, ``Math class is tough!''
 Although math isn't tough, floating-point arithmetic isn't the same
-as pencil and paper math, and care must be taken:
+as pencil-and-paper math, and care must be taken:
 
 @c nested list
 @itemize @value{MINUS}
@@ -30339,7 +30367,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and
 @item
 With @option{-M}, @command{gawk} performs
 arbitrary-precision integer arithmetic using the GMP library.
-This is faster and more space efficient than using MPFR for
+This is faster and more space-efficient than using MPFR for
 the same calculations.
 
 @item
@@ -30351,7 +30379,7 @@ It pays to be aware of them.
 Overall, there is no need to be unduly suspicious about the results from
 floating-point arithmetic. The lesson to remember is that floating-point
 arithmetic is always more complex than arithmetic using pencil and
-paper. In order to take advantage of the power of computer floating point,
+paper. In order to take advantage of the power of floating-point arithmetic,
 you need to know its limitations and work within them. For most casual
 use of floating-point arithmetic, you will often get the expected result
 if you simply round the display of your final results to the correct number
@@ -30412,7 +30440,7 @@ Extensions are useful because they allow you (of course) to extend
 @command{gawk}'s functionality. For example, they can provide access to
 system calls (such as @code{chdir()} to change directory) and to other
 C library routines that could be of use.  As with most software,
-``the sky is the limit;'' if you can imagine something that you might
+``the sky is the limit''; if you can imagine something that you might
 want to do and can write in C or C++, you can write an extension to do it!
 
 Extensions are written in C or C++, using the @dfn{application programming
@@ -30420,7 +30448,7 @@ interface} (API) defined for this purpose by the @command{gawk}
 developers.  The rest of this @value{CHAPTER} explains
 the facilities that the API provides and how to use
 them, and presents a small example extension.  In addition, it documents
-the sample extensions included in the @command{gawk} distribution,
+the sample extensions included in the @command{gawk} distribution
 and describes the @code{gawkextlib} project.
 @ifclear FOR_PRINT
 @xref{Extension Design}, for a discussion of the extension mechanism
@@ -30573,7 +30601,7 @@ Some other bits and pieces:
 @itemize @value{BULLET}
 @item
 The API provides access to @command{gawk}'s @code{do_@var{xxx}} values,
-reflecting command-line options, like @code{do_lint}, @code{do_profiling}
+reflecting command-line options, like @code{do_lint}, @code{do_profiling},
 and so on (@pxref{Extension API Variables}).
 These are informational: an extension cannot affect their values
 inside @command{gawk}.  In addition, attempting to assign to them
@@ -30617,7 +30645,7 @@ This (rather large) @value{SECTION} describes the API in detail.
 @node Extension API Functions Introduction
 @subsection Introduction
 
-Access to facilities within @command{gawk} are made available
+Access to facilities within @command{gawk} is achieved
 by calling through function pointers passed into your extension.
 
 API function pointers are provided for the following kinds of operations:
@@ -30645,7 +30673,7 @@ Output wrappers
 Two-way processors
 @end itemize
 
-All of these are discussed in detail, later in this @value{CHAPTER}.
+All of these are discussed in detail later in this @value{CHAPTER}.
 
 @item
 Printing fatal, warning, and ``lint'' warning messages.
@@ -30683,7 +30711,7 @@ Creating a new array
 Clearing an array
 
 @item
-Flattening an array for easy C style looping over all its indices and elements
+Flattening an array for easy C-style looping over all its indices and elements
 @end itemize
 @end itemize
 
@@ -30695,8 +30723,9 @@ The following types, macros, and/or functions are referenced
 in @file{gawkapi.h}.  For correct use, you must therefore include the
 corresponding standard header file @emph{before} including @file{gawkapi.h}:
 
+@c FIXME: Make this is a float at some point.
 @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}}
-@headitem C Entity @tab Header File
+@headitem C entity @tab Header file
 @item @code{EOF} @tab @code{<stdio.h>}
 @item Values for @code{errno} @tab @code{<errno.h>}
 @item @code{FILE} @tab @code{<stdio.h>}
@@ -30722,7 +30751,7 @@ Doing so, however, is poor coding practice.
 Although the API only uses ISO C 90 features, there is an exception; the
 ``constructor'' functions use the @code{inline} keyword. If your compiler
 does not support this keyword, you should either place
-@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a
+@samp{-Dinline=''} on your command line or use the GNU Autotools and include a
 @file{config.h} file in your extensions.
 
 @item
@@ -30730,7 +30759,7 @@ All pointers filled in by @command{gawk} point to memory
 managed by @command{gawk} and should be treated by the extension as
 read-only.  Memory for @emph{all} strings passed into @command{gawk}
 from the extension @emph{must} come from calling one of
-@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()},
+@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()},
 and is managed by @command{gawk} from then on.
 
 @item
@@ -30744,7 +30773,7 @@ characters are allowed.
 By intent, strings are maintained using the current multibyte encoding (as
 defined by @env{LC_@var{xxx}} environment variables) and not using wide
 characters.  This matches how @command{gawk} stores strings internally
-and also how characters are likely to be input and output from files.
+and also how characters are likely to be input into and output from files.
 @end quotation
 
 @item
@@ -30789,6 +30818,8 @@ general-purpose use. Additional, more specialized, data structures are
 introduced in subsequent @value{SECTION}s, together with the functions
 that use them.
 
+The general-purpose types and structures are as follows:
+
 @table @code
 @item typedef void *awk_ext_id_t;
 A value of this type is received from @command{gawk} when an extension is loaded.
@@ -30805,7 +30836,7 @@ while allowing @command{gawk} to use them as it needs to.
 @itemx @ @ @ @ awk_false = 0,
 @itemx @ @ @ @ awk_true
 @itemx @} awk_bool_t;
-A simple boolean type.
+A simple Boolean type.
 
 @item typedef struct awk_string @{
 @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */
@@ -30851,7 +30882,7 @@ The @code{val_type} member indicates what kind of value the
 @itemx #define array_cookie@ @ @ u.a
 @itemx #define scalar_cookie@ @ u.scl
 @itemx #define value_cookie@ @ @ u.vc
-These macros make accessing the fields of the @code{awk_value_t} more
+Using these macros makes accessing the fields of the @code{awk_value_t} more
 readable.
 
 @item typedef void *awk_scalar_t;
@@ -30874,7 +30905,7 @@ indicates what is in the @code{union}.
 Representing numbers is easy---the API uses a C @code{double}.  Strings
 require more work. Because @command{gawk} allows embedded @sc{nul} bytes
 in string values, a string must be represented as a pair containing a
-data-pointer and length. This is the @code{awk_string_t} type.
+data pointer and length. This is the @code{awk_string_t} type.
 
 Identifiers (i.e., the names of global variables) can be associated
 with either scalar values or with arrays.  In addition, @command{gawk}
@@ -30887,12 +30918,12 @@ of the @code{union} as if they were fields in a @code{struct}; this
 is a common coding practice in C.  Such code is easier to write and to
 read, but it remains @emph{your} responsibility to make sure that
 the @code{val_type} member correctly reflects the type of the value in
-the @code{awk_value_t}.
+the @code{awk_value_t} struct.
 
 Conceptually, the first three members of the @code{union} (number, string,
 and array) are all that is needed for working with @command{awk} values.
 However, because the API provides routines for accessing and changing
-the value of global scalar variables only by using the variable's name,
+the value of a global scalar variable only by using the variable's name,
 there is a performance penalty: @command{gawk} must find the variable
 each time it is accessed and changed.  This turns out to be a real issue,
 not just a theoretical one.
@@ -30910,7 +30941,9 @@ See also the entry for ``Cookie'' in the @ref{Glossary}.
 object for that variable, and then use
 the cookie for getting the variable's value or for changing the variable's
 value.
-This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro.
+The @code{awk_scalar_t} type holds a scalar cookie, and the
+@code{scalar_cookie} macro provides access to the value of that type
+in the @code{awk_value_t} struct.
 Given a scalar cookie, @command{gawk} can directly retrieve or
 modify the value, as required, without having to find it first.
 
@@ -30919,8 +30952,8 @@ If you know that you wish to
 use the same numeric or string @emph{value} for one or more variables,
 you can create the value once, retaining a @dfn{value cookie} for it,
 and then pass in that value cookie whenever you wish to set the value of a
-variable.  This saves both storage space within the running @command{gawk}
-process as well as the time needed to create the value.
+variable.  This saves storage space within the running @command{gawk}
+process and reduces the time needed to create the value.
 
 @node Memory Allocation Functions
 @subsection Memory Allocation Functions and Convenience Macros
@@ -30948,13 +30981,13 @@ be passed to @command{gawk}.
 
 @item void gawk_free(void *ptr);
 Call the correct version of @code{free()} to release storage that was
-allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}.
+allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
 @end table
 
 The API has to provide these functions because it is possible
 for an extension to be compiled and linked against a different
 version of the C library than was used for the @command{gawk}
-executable.@footnote{This is more common on MS-Windows systems, but
+executable.@footnote{This is more common on MS-Windows systems, but it
 can happen on Unix-like systems as well.} If @command{gawk} were
 to use its version of @code{free()} when the memory came from an
 unrelated version of @code{malloc()}, unexpected behavior would
@@ -30964,7 +30997,7 @@ Two convenience macros may be used for allocating storage
 from @code{gawk_malloc()} and
 @code{gawk_realloc()}. If the allocation fails, they cause @command{gawk}
 to exit with a fatal error message.  They should be used as if they were
-procedure calls that do not return a value.
+procedure calls that do not return a value:
 
 @table @code
 @item #define emalloc(pointer, type, size, message) @dots{}
@@ -31001,7 +31034,7 @@ make_malloced_string(message, strlen(message), & result);
 @end example
 
 @item #define erealloc(pointer, type, size, message) @dots{}
-This is like @code{emalloc()}, but it calls @code{gawk_realloc()},
+This is like @code{emalloc()}, but it calls @code{gawk_realloc()}
 instead of @code{gawk_malloc()}.
 The arguments are the same as for the @code{emalloc()} macro.
 @end table
@@ -31026,7 +31059,7 @@ for storage in @code{result}. It returns @code{result}.
 @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result)
 This function creates a string value in the @code{awk_value_t} variable
 pointed to by @code{result}. It expects @code{string} to be a @samp{char *}
-value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here
+value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The idea here
 is that the data is passed directly to @command{gawk}, which assumes
 responsibility for it. It returns @code{result}.
 
@@ -31077,7 +31110,7 @@ The fields are:
 @table @code
 @item const char *name;
 The name of the new function.
-@command{awk} level code calls the function by this name.
+@command{awk}-level code calls the function by this name.
 This is a regular C string.
 
 Function names must obey the rules for @command{awk}
@@ -31091,7 +31124,7 @@ This is a pointer to the C function that provides the extension's
 functionality.
 The function must fill in @code{*result} with either a number
 or a string. @command{gawk} takes ownership of any string memory.
-As mentioned earlier, string memory @strong{must} come from one of
+As mentioned earlier, string memory @emph{must} come from one of
 @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
 
 The @code{num_actual_args} argument tells the C function how many
@@ -31143,20 +31176,20 @@ The @code{exit_status} parameter is the exit status value that
 @command{gawk} intends to pass to the @code{exit()} system call.
 
 @item arg0
-A pointer to private data which @command{gawk} saves in order to pass to
+A pointer to private data that @command{gawk} saves in order to pass to
 the function pointed to by @code{funcp}.
 @end table
 @end table
 
-Exit callback functions are called in last-in-first-out (LIFO)
+Exit callback functions are called in last-in, first-out (LIFO)
 order---that is, in the reverse order in which they are registered with
 @command{gawk}.
 
 @node Extension Version String
 @subsubsection Registering An Extension Version String
 
-You can register a version string which indicates the name and
-version of your extension, with @command{gawk}, as follows:
+You can register a version string that indicates the name and
+version of your extension with @command{gawk}, as follows:
 
 @table @code
 @item void register_ext_version(const char *version);
@@ -31178,7 +31211,7 @@ of @code{RS} to find the end of the record, and then uses @code{FS}
 Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}).
 
 If you want, you can provide your own custom input parser.  An input
-parser's job is to return a record to the @command{gawk} record processing
+parser's job is to return a record to the @command{gawk} record-processing
 code, along with indicators for the value and length of the data to be
 used for @code{RT}, if any.
 
@@ -31196,9 +31229,9 @@ It should not change any state (variable values, etc.) within @command{gawk}.
 @item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf);
 When @command{gawk} decides to hand control of the file over to the
 input parser, it calls this function.  This function in turn must fill
-in certain fields in the @code{awk_input_buf_t} structure, and ensure
+in certain fields in the @code{awk_input_buf_t} structure and ensure
 that certain conditions are true.  It should then return true. If an
-error of some kind occurs, it should not fill in any fields, and should
+error of some kind occurs, it should not fill in any fields and should
 return false; then @command{gawk} will not use the input parser.
 The details are presented shortly.
 @end table
@@ -31291,7 +31324,7 @@ in the @code{struct stat}, or any combination of these factors.
 
 Once @code{@var{XXX}_can_take_file()} has returned true, and
 @command{gawk} has decided to use your input parser, it calls
-@code{@var{XXX}_take_control_of()}.  That function then fills one of
+@code{@var{XXX}_take_control_of()}.  That function then fills
 either the @code{get_record} field or the @code{read_func} field in
 the @code{awk_input_buf_t}.  It must also ensure that @code{fd} is @emph{not}
 set to @code{INVALID_HANDLE}.  The following list describes the fields that
@@ -31313,21 +31346,21 @@ records.  Said function is the core of the input parser.  Its behavior
 is described in the text following this list.
 
 @item ssize_t (*read_func)();
-This function pointer should point to function that has the
+This function pointer should point to a function that has the
 same behavior as the standard POSIX @code{read()} system call.
 It is an alternative to the @code{get_record} pointer.  Its behavior
 is also described in the text following this list.
 
 @item void (*close_func)(struct awk_input *iobuf);
 This function pointer should point to a function that does
-the ``tear down.'' It should release any resources allocated by
+the ``teardown.'' It should release any resources allocated by
 @code{@var{XXX}_take_control_of()}.  It may also close the file. If it
 does so, it should set the @code{fd} field to @code{INVALID_HANDLE}.
 
 If @code{fd} is still not @code{INVALID_HANDLE} after the call to this
 function, @command{gawk} calls the regular @code{close()} system call.
 
-Having a ``tear down'' function is optional. If your input parser does
+Having a ``teardown'' function is optional. If your input parser does
 not need it, do not set this field.  Then, @command{gawk} calls the
 regular @code{close()} system call on the file descriptor, so it should
 be valid.
@@ -31338,7 +31371,7 @@ input records.  The parameters are as follows:
 
 @table @code
 @item char **out
-This is a pointer to a @code{char *} variable which is set to point
+This is a pointer to a @code{char *} variable that is set to point
 to the record.  @command{gawk} makes its own copy of the data, so
 the extension must manage this storage.
 
@@ -31391,17 +31424,17 @@ set this field explicitly.
 You must choose one method or the other: either a function that
 returns a record, or one that returns raw data.  In particular,
 if you supply a function to get a record, @command{gawk} will
-call it, and never call the raw read function.
+call it, and will never call the raw read function.
 @end quotation
 
 @command{gawk} ships with a sample extension that reads directories,
-returning records for each entry in the directory (@pxref{Extension
+returning records for each entry in a directory (@pxref{Extension
 Sample Readdir}).  You may wish to use that code as a guide for writing
 your own input parser.
 
 When writing an input parser, you should think about (and document)
 how it is expected to interact with @command{awk} code.  You may want
-it to always be called, and take effect as appropriate (as the
+it to always be called, and to take effect as appropriate (as the
 @code{readdir} extension does).  Or you may want it to take effect
 based upon the value of an @command{awk} variable, as the XML extension
 from the @code{gawkextlib} project does (@pxref{gawkextlib}).
@@ -31511,7 +31544,7 @@ a pointer to any private data associated with the file.
 These pointers should be set to point to functions that perform
 the equivalent function as the @code{<stdio.h>} functions do, if appropriate.
 @command{gawk} uses these function pointers for all output.
-@command{gawk} initializes the pointers to point to internal, ``pass through''
+@command{gawk} initializes the pointers to point to internal ``pass-through''
 functions that just call the regular @code{<stdio.h>} functions, so an
 extension only needs to redefine those functions that are appropriate for
 what it does.
@@ -31522,7 +31555,7 @@ upon the @code{name} and @code{mode} fields, and any additional state
 (such as @command{awk} variable values) that is appropriate.
 
 When @command{gawk} calls @code{@var{XXX}_take_control_of()}, that function should fill
-in the other fields, as appropriate, except for @code{fp}, which it should just
+in the other fields as appropriate, except for @code{fp}, which it should just
 use normally.
 
 You register your output wrapper with the following function:
@@ -31562,14 +31595,14 @@ The fields are as follows:
 The name of the two-way processor.
 
 @item awk_bool_t (*can_take_two_way)(const char *name);
-This function returns true if it wants to take over two-way I/O for this @value{FN}.
+The function pointed to by this field should return true if it wants to take over two-way I/O for this @value{FN}.
 It should not change any state (variable
 values, etc.) within @command{gawk}.
 
 @item awk_bool_t (*take_control_of)(const char *name,
 @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_input_buf_t *inbuf,
 @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_output_buf_t *outbuf);
-This function should fill in the @code{awk_input_buf_t} and
+The function pointed to by this field should fill in the @code{awk_input_buf_t} and
 @code{awk_outut_buf_t} structures pointed to by @code{inbuf} and
 @code{outbuf}, respectively.  These structures were described earlier.
 
@@ -31598,7 +31631,7 @@ Register the two-way processor pointed to by @code{two_way_processor} with
 
 You can print different kinds of warning messages from your
 extension, as described here.  Note that for these functions,
-you must pass in the extension id received from @command{gawk}
+you must pass in the extension ID received from @command{gawk}
 when the extension was loaded:@footnote{Because the API uses only ISO C 90
 features, it cannot make use of the ISO C 99 variadic macro feature to hide
 that parameter. More's the pity.}
@@ -31651,7 +31684,7 @@ matches what you requested, the function returns true and fills
 in the @code{awk_value_t} result.
 Otherwise, the function returns false, and the @code{val_type}
 member indicates the type of the actual value.  You may then
-print an error message, or reissue the request for the actual
+print an error message or reissue the request for the actual
 value type, as appropriate.  This behavior is summarized in
 @ref{table-value-types-returned}.
 
@@ -31684,32 +31717,32 @@ value type, as appropriate.  This behavior is summarized in
       <entry><para><emphasis role="bold">String</emphasis></para></entry>
       <entry><para>String</para></entry>
       <entry><para>String</para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para></entry>
     </row>
     <row>
       <entry></entry>
       <entry><para><emphasis role="bold">Number</emphasis></para></entry>
       <entry><para>Number if can be converted, else false</para></entry>
       <entry><para>Number</para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para></entry>
     </row>
     <row>
       <entry><para><emphasis role="bold">Type</emphasis></para></entry>
       <entry><para><emphasis role="bold">Array</emphasis></para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para></entry>
       <entry><para>Array</para></entry>
-      <entry><para>false</para></entry>
+      <entry><para>False</para></entry>
     </row>
     <row>
       <entry><para><emphasis role="bold">Requested</emphasis></para></entry>
       <entry><para><emphasis role="bold">Scalar</emphasis></para></entry>
       <entry><para>Scalar</para></entry>
       <entry><para>Scalar</para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para></entry>
     </row>
     <row>
       <entry></entry>
@@ -31721,11 +31754,11 @@ value type, as appropriate.  This behavior is summarized in
     </row>
     <row>
       <entry></entry>
-      <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para></entry>
-      <entry><para>false</para>
-      </entry><entry><para>false</para></entry>
+      <entry><para><emphasis role="bold">Value cookie</emphasis></para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para></entry>
+      <entry><para>False</para>
+      </entry><entry><para>False</para></entry>
     </row>
   </tbody>
 </tgroup>
@@ -31743,12 +31776,12 @@ value type, as appropriate.  This behavior is summarized in
 @end tex
 @multitable @columnfractions .166 .166 .198 .15 .15 .166
 @headitem @tab @tab String @tab Number @tab Array @tab Undefined
-@item @tab @b{String} @tab String @tab String @tab false @tab false
-@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false
-@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false
-@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false
+@item @tab @b{String} @tab String @tab String @tab False @tab False
+@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab False @tab False
+@item @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab False
+@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab False @tab False
 @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined
-@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false
+@item @tab @b{Value cookie} @tab False @tab False @tab False @tab False
 @end multitable
 @end ifnotdocbook
 @end ifnotplaintext
@@ -31759,21 +31792,21 @@ value type, as appropriate.  This behavior is summarized in
                         +------------+------------+-----------+-----------+
                         |   String   |   Number   | Array     | Undefined |
 +-----------+-----------+------------+------------+-----------+-----------+
-|           | String    |   String   |   String   | false     | false     |
+|           | String    |   String   |   String   | False     | False     |
 |           |-----------+------------+------------+-----------+-----------+
-|           | Number    | Number if  |   Number   | false     | false     |
+|           | Number    | Number if  |   Number   | False     | False     |
 |           |           | can be     |            |           |           |
 |           |           | converted, |            |           |           |
 |           |           | else false |            |           |           |
 |           |-----------+------------+------------+-----------+-----------+
-|   Type    | Array     |   false    |   false    | Array     | false     |
+|   Type    | Array     |   False    |   False    | Array     | False     |
 | Requested |-----------+------------+------------+-----------+-----------+
-|           | Scalar    |   Scalar   |   Scalar   | false     | false     |
+|           | Scalar    |   Scalar   |   Scalar   | False     | False     |
 |           |-----------+------------+------------+-----------+-----------+
 |           | Undefined |  String    |   Number   | Array     | Undefined |
 |           |-----------+------------+------------+-----------+-----------+
-|           | Value     |   false    |   false    | false     | false     |
-|           | Cookie    |            |            |           |           |
+|           | Value     |   False    |   False    | False     | False     |
+|           | cookie    |            |            |           |           |
 +-----------+-----------+------------+------------+-----------+-----------+
 @end example
 @end ifplaintext
@@ -31790,16 +31823,16 @@ passed to your extension function. They are:
 @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted,
 @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result);
 Fill in the @code{awk_value_t} structure pointed to by @code{result}
-with the @code{count}'th argument.  Return true if the actual
-type matches @code{wanted}, false otherwise.  In the latter
+with the @code{count}th argument.  Return true if the actual
+type matches @code{wanted}, and false otherwise.  In the latter
 case, @code{result@w{->}val_type} indicates the actual type
-(@pxref{table-value-types-returned}).  Counts are zero based---the first
+(@pxref{table-value-types-returned}).  Counts are zero-based---the first
 argument is numbered zero, the second one, and so on. @code{wanted}
 indicates the type of value expected.
 
 @item awk_bool_t set_argument(size_t count, awk_array_t array);
 Convert a parameter that was undefined into an array; this provides
-call-by-reference for arrays.  Return false if @code{count} is too big,
+call by reference for arrays.  Return false if @code{count} is too big,
 or if the argument's type is not undefined.  @DBXREF{Array Manipulation}
 for more information on creating arrays.
 @end table
@@ -31823,8 +31856,9 @@ allows you to create and release cached values.
 The following routines provide the ability to access and update
 global @command{awk}-level variables by name.  In compiler terminology,
 identifiers of different kinds are termed @dfn{symbols}, thus the ``sym''
-in the routines' names.  The data structure which stores information
+in the routines' names.  The data structure that stores information
 about symbols is termed a @dfn{symbol table}.
+The functions are as follows:
 
 @table @code
 @item awk_bool_t sym_lookup(const char *name,
@@ -31833,14 +31867,14 @@ about symbols is termed a @dfn{symbol table}.
 Fill in the @code{awk_value_t} structure pointed to by @code{result}
 with the value of the variable named by the string @code{name}, which is
 a regular C string.  @code{wanted} indicates the type of value expected.
-Return true if the actual type matches @code{wanted}, false otherwise.
+Return true if the actual type matches @code{wanted}, and false otherwise.
 In the latter case, @code{result->val_type} indicates the actual type
 (@pxref{table-value-types-returned}).
 
 @item awk_bool_t sym_update(const char *name, awk_value_t *value);
 Update the variable named by the string @code{name}, which is a regular
 C string.  The variable is added to @command{gawk}'s symbol table
-if it is not there.  Return true if everything worked, false otherwise.
+if it is not there.  Return true if everything worked, and false otherwise.
 
 Changing types (scalar to array or vice versa) of an existing variable
 is @emph{not} allowed, nor may this routine be used to update an array.
@@ -31865,7 +31899,7 @@ populate it.
 A @dfn{scalar cookie} is an opaque handle that provides access
 to a global variable or array. It is an optimization that
 avoids looking up variables in @command{gawk}'s symbol table every time
-access is needed. This was discussed earlier in @ref{General Data Types}.
+access is needed. This was discussed earlier, in @ref{General Data Types}.
 
 The following functions let you work with scalar cookies:
 
@@ -31981,7 +32015,7 @@ and carefully check the return values from the API functions.
 @subsubsection Creating and Using Cached Values
 
 The routines in this section allow you to create and release
-cached values.  As with scalar cookies, in theory, cached values
+cached values.  Like scalar cookies, in theory, cached values
 are not necessary. You can create numbers and strings using
 the functions in @ref{Constructor Functions}. You can then
 assign those values to variables using @code{sym_update()}
@@ -32059,7 +32093,7 @@ Using value cookies in this way saves considerable storage, as all of
 @code{VAR1} through @code{VAR100} share the same value.
 
 You might be wondering, ``Is this sharing problematic?
-What happens if @command{awk} code assigns a new value to @code{VAR1},
+What happens if @command{awk} code assigns a new value to @code{VAR1};
 are all the others changed too?''
 
 That's a great question. The answer is that no, it's not a problem.
@@ -32163,7 +32197,7 @@ modify them.
 @node Array Functions
 @subsubsection Array Functions
 
-The following functions relate to individual array elements.
+The following functions relate to individual array elements:
 
 @table @code
 @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);
@@ -32182,13 +32216,13 @@ Return false if @code{wanted} does not match the actual type or if
 @code{index} is not in the array (@pxref{table-value-types-returned}).
 
 The value for @code{index} can be numeric, in which case @command{gawk}
-converts it to a string. Using non-integral values is possible, but
+converts it to a string. Using nonintegral values is possible, but
 requires that you understand how such values are converted to strings
-(@pxref{Conversion}); thus using integral values is safest.
+(@pxref{Conversion}); thus, using integral values is safest.
 
 As with @emph{all} strings passed into @command{gawk} from an extension,
 the string value of @code{index} must come from @code{gawk_malloc()},
-@code{gawk_calloc()} or @code{gawk_realloc()}, and
+@code{gawk_calloc()}, or @code{gawk_realloc()}, and
 @command{gawk} releases the storage.
 
 @item awk_bool_t set_array_element(awk_array_t a_cookie,
@@ -32244,7 +32278,7 @@ flatten an array and work with it.
 @item awk_bool_t release_flattened_array(awk_array_t a_cookie,
 @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_flat_array_t *data);
 When done with a flattened array, release the storage using this function.
-You must pass in both the original array cookie, and the address of
+You must pass in both the original array cookie and the address of
 the created @code{awk_flat_array_t} structure.
 The function returns true upon success, false otherwise.
 @end table
@@ -32254,7 +32288,7 @@ The function returns true upon success, false otherwise.
 
 To @dfn{flatten} an array is to create a structure that
 represents the full array in a fashion that makes it easy
-for C code to traverse the entire array.  Test code
+for C code to traverse the entire array.  Some of the code
 in @file{extension/testext.c} does this, and also serves
 as a nice example showing how to use the APIs.
 
@@ -32311,9 +32345,9 @@ dump_array_and_delete(int nargs, awk_value_t *result)
 @end example
 
 The function then proceeds in steps, as follows. First, retrieve
-the name of the array, passed as the first argument. Then
-retrieve the array itself. If either operation fails, print
-error messages and return:
+the name of the array, passed as the first argument, followed by
+the array itself. If either operation fails, print an
+error message and return:
 
 @example
     /* get argument named array as flat array and print it */
@@ -32349,7 +32383,7 @@ and print it:
 @end example
 
 The third step is to actually flatten the array, and then
-to double check that the count in the @code{awk_flat_array_t}
+to double-check that the count in the @code{awk_flat_array_t}
 is the same as the count just retrieved:
 
 @example
@@ -32370,7 +32404,7 @@ is the same as the count just retrieved:
 The fourth step is to retrieve the index of the element
 to be deleted, which was passed as the second argument.
 Remember that argument counts passed to @code{get_argument()}
-are zero-based, thus the second argument is numbered one:
+are zero-based, and thus the second argument is numbered one:
 
 @example
     if (! get_argument(1, AWK_STRING, & value3)) @{
@@ -32385,7 +32419,7 @@ element values. In addition, upon finding the element with the
 index that is supposed to be deleted, the function sets the
 @code{AWK_ELEMENT_DELETE} bit in the @code{flags} field
 of the element.  When the array is released, @command{gawk}
-traverses the flattened array, and deletes any elements which
+traverses the flattened array, and deletes any elements that
 have this flag bit set:
 
 @example
@@ -32673,10 +32707,10 @@ The API versions are available at compile time as constants:
 
 @table @code
 @item GAWK_API_MAJOR_VERSION
-The major version of the API.
+The major version of the API
 
 @item GAWK_API_MINOR_VERSION
-The minor version of the API.
+The minor version of the API
 @end table
 
 The minor version increases when new functions are added to the API. Such
@@ -32694,14 +32728,14 @@ constant integers:
 
 @table @code
 @item api->major_version
-The major version of the running @command{gawk}.
+The major version of the running @command{gawk}
 
 @item api->minor_version
-The minor version of the running @command{gawk}.
+The minor version of the running @command{gawk}
 @end table
 
 It is up to the extension to decide if there are API incompatibilities.
-Typically a check like this is enough:
+Typically, a check like this is enough:
 
 @example
 if (api->major_version != GAWK_API_MAJOR_VERSION
@@ -32715,7 +32749,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION
 @end example
 
 Such code is included in the boilerplate @code{dl_load_func()} macro
-provided in @file{gawkapi.h} (discussed later, in
+provided in @file{gawkapi.h} (discussed in
 @ref{Extension API Boilerplate}).
 
 @node Extension API Informational Variables
@@ -32762,7 +32796,7 @@ as described here.  The boilerplate needed is also provided in comments
 in the @file{gawkapi.h} header file:
 
 @example
-/* Boiler plate code: */
+/* Boilerplate code: */
 int plugin_is_GPL_compatible;
 
 static gawk_api_t *const api;
@@ -32821,7 +32855,7 @@ to @code{NULL}, or to point to a string giving the name and version of
 your extension.
 
 @item static awk_ext_func_t func_table[] = @{ @dots{} @};
-This is an array of one or more @code{awk_ext_func_t} structures
+This is an array of one or more @code{awk_ext_func_t} structures,
 as described earlier (@pxref{Extension Functions}).
 It can then be looped over for multiple calls to
 @code{add_ext_func()}.
@@ -32952,7 +32986,7 @@ the @code{stat()} fails.  It fills in the following elements:
 
 @table @code
 @item "name"
-The name of the file that was @code{stat()}'ed.
+The name of the file that was @code{stat()}ed.
 
 @item "dev"
 @itemx "ino"
@@ -33008,7 +33042,7 @@ interprocess communications).
 The file is a directory.
 
 @item "fifo"
-The file is a named-pipe (also known as a FIFO).
+The file is a named pipe (also known as a FIFO).
 
 @item "file"
 The file is just a regular file.
@@ -33031,7 +33065,7 @@ For some other systems, @dfn{a priori} knowledge is used to provide
 a value. Where no value can be determined, it defaults to 512.
 @end table
 
-Several additional elements may be present depending upon the operating
+Several additional elements may be present, depending upon the operating
 system and the type of the file.  You can test for them in your @command{awk}
 program by using the @code{in} operator
 (@pxref{Reference to Elements}):
@@ -33061,7 +33095,7 @@ edited slightly for presentation.  See @file{extension/filefuncs.c}
 in the @command{gawk} distribution for the complete version.}
 
 The file includes a number of standard header files, and then includes
-the @file{gawkapi.h} header file which provides the API definitions.
+the @file{gawkapi.h} header file, which provides the API definitions.
 Those are followed by the necessary variable declarations
 to make use of the API macros and boilerplate code
 (@pxref{Extension API Boilerplate}):
@@ -33102,9 +33136,9 @@ int plugin_is_GPL_compatible;
 @cindex programming conventions, @command{gawk} extensions
 By convention, for an @command{awk} function @code{foo()}, the C function
 that implements it is called @code{do_foo()}.  The function should have
-two arguments: the first is an @code{int} usually called @code{nargs},
+two arguments. The first is an @code{int}, usually called @code{nargs},
 that represents the number of actual arguments for the function.
-The second is a pointer to an @code{awk_value_t}, usually named
+The second is a pointer to an @code{awk_value_t} structure, usually named
 @code{result}:
 
 @example
@@ -33150,7 +33184,7 @@ Finally, the function returns the return value to the @command{awk} level:
 
 The @code{stat()} extension is more involved.  First comes a function
 that turns a numeric mode into a printable representation
-(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
+(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for brevity:
 
 @example
 /* format_mode --- turn a stat mode field into something readable */
@@ -33206,9 +33240,9 @@ array_set_numeric(awk_array_t array, const char *sub, double num)
 
 The following function does most of the work to fill in
 the @code{awk_array_t} result array with values obtained
-from a valid @code{struct stat}. It is done in a separate function
+from a valid @code{struct stat}. This work is done in a separate function
 to support the @code{stat()} function for @command{gawk} and also
-to support the @code{fts()} extension which is included in
+to support the @code{fts()} extension, which is included in
 the same file but whose code is not shown here
 (@pxref{Extension Sample File Functions}).
 
@@ -33329,8 +33363,8 @@ the @code{stat()} system call instead of the @code{lstat()} system
 call.  This is done by using a function pointer: @code{statfunc}.
 @code{statfunc} is initialized to point to @code{lstat()} (instead
 of @code{stat()}) to get the file information, in case the file is a
-symbolic link. However, if there were three arguments, @code{statfunc}
-is set point to @code{stat()}, instead.
+symbolic link. However, if the third argument is included, @code{statfunc}
+is set to point to @code{stat()}, instead.
 
 Here is the @code{do_stat()} function, which starts with
 variable declarations and argument checking:
@@ -33386,7 +33420,7 @@ Next, it gets the information for the file.  If the called function
     /* always empty out the array */
     clear_array(array);
 
-    /* stat the file, if error, set ERRNO and return */
+    /* stat the file; if error, set ERRNO and return */
     ret = statfunc(name, & sbuf);
     if (ret < 0) @{
         update_ERRNO_int(errno);
@@ -33408,7 +33442,9 @@ Finally, it's necessary to provide the ``glue'' that loads the
 new function(s) into @command{gawk}.
 
 The @code{filefuncs} extension also provides an @code{fts()}
-function, which we omit here. For its sake there is an initialization
+function, which we omit here
+(@pxref{Extension Sample File Functions}).
+For its sake, there is an initialization
 function:
 
 @example
@@ -33533,9 +33569,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk}
 @section The Sample Extensions in the @command{gawk} Distribution
 @cindex extensions distributed with @command{gawk}
 
-This @value{SECTION} provides brief overviews of the sample extensions
+This @value{SECTION} provides a brief overview of the sample extensions
 that come in the @command{gawk} distribution. Some of them are intended
-for production use (e.g., the @code{filefuncs}, @code{readdir} and
+for production use (e.g., the @code{filefuncs}, @code{readdir}, and
 @code{inplace} extensions).  Others mainly provide example code that
 shows how to use the extension API.
 
@@ -33571,14 +33607,14 @@ This is how you load the extension.
 @item @code{result = chdir("/some/directory")}
 The @code{chdir()} function is a direct hook to the @code{chdir()}
 system call to change the current directory.  It returns zero
-upon success or less than zero upon error.  In the latter case, it updates
-@code{ERRNO}.
+upon success or a value less than zero upon error.
+In the latter case, it updates @code{ERRNO}.
 
 @cindex @code{stat()} extension function
 @item @code{result = stat("/some/path", statdata} [@code{, follow}]@code{)}
 The @code{stat()} function provides a hook into the
 @code{stat()} system call.
-It returns zero upon success or less than zero upon error.
+It returns zero upon success or a value less than zero upon error.
 In the latter case, it updates @code{ERRNO}.
 
 By default, it uses the @code{lstat()} system call.  However, if passed
@@ -33605,10 +33641,10 @@ array with information retrieved from the filesystem, as follows:
 @item @code{"major"} @tab @code{st_major} @tab Device files
 @item @code{"minor"} @tab @code{st_minor} @tab Device files
 @item @code{"blksize"} @tab @code{st_blksize} @tab All
-@item @code{"pmode"} @tab A human-readable version of the mode value, such as printed by
-@command{ls}.  For example, @code{"-rwxr-xr-x"} @tab All
+@item @code{"pmode"} @tab A human-readable version of the mode value, like that printed by
+@command{ls} (for example, @code{"-rwxr-xr-x"}) @tab All
 @item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links
-@item @code{"type"} @tab The type of the file as a string. One of
+@item @code{"type"} @tab The type of the file as a string---one of
 @code{"file"},
 @code{"blockdev"},
 @code{"chardev"},
@@ -33618,15 +33654,15 @@ array with information retrieved from the filesystem, as follows:
 @code{"symlink"},
 @code{"door"},
 or
-@code{"unknown"}.
-Not all systems support all file types. @tab All
+@code{"unknown"}
+(not all systems support all file types) @tab All
 @end multitable
 
 @cindex @code{fts()} extension function
 @item @code{flags = or(FTS_PHYSICAL, ...)}
 @itemx @code{result = fts(pathlist, flags, filedata)}
 Walk the file trees provided in @code{pathlist} and fill in the
-@code{filedata} array as described next.  @code{flags} is the bitwise
+@code{filedata} array, as described next.  @code{flags} is the bitwise
 OR of several predefined values, also described in a moment.
 Return zero if there were no errors, otherwise return @minus{}1.
 @end table
@@ -33682,7 +33718,8 @@ During a traversal, do not cross onto a different mounted filesystem.
 @end table
 
 @item filedata
-The @code{filedata} array is first cleared.  Then, @code{fts()} creates
+The @code{filedata} array holds the results.
+@code{fts()} first clears it.  Then it creates
 an element in @code{filedata} for every element in @code{pathlist}.
 The index is the name of the directory or file given in @code{pathlist}.
 The element for this index is itself an array.  There are two cases:
@@ -33724,7 +33761,7 @@ for a file: @code{"path"}, @code{"stat"}, and @code{"error"}.
 @end table
 
 The @code{fts()} function returns zero if there were no errors.
-Otherwise it returns @minus{}1.
+Otherwise, it returns @minus{}1.
 
 @quotation NOTE
 The @code{fts()} extension does not exactly mimic the
@@ -33766,14 +33803,14 @@ The arguments to @code{fnmatch()} are:
 
 @table @code
 @item pattern
-The @value{FN} wildcard to match.
+The @value{FN} wildcard to match
 
 @item string
-The @value{FN} string.
+The @value{FN} string
 
 @item flag
 Either zero, or the bitwise OR of one or more of the
-flags in the @code{FNM} array.
+flags in the @code{FNM} array
 @end table
 
 The flags are as follows:
@@ -33810,14 +33847,14 @@ This is how you load the extension.
 @cindex @code{fork()} extension function
 @item pid = fork()
 This function creates a new process. The return value is zero in the
-child and the process-ID number of the child in the parent, or @minus{}1
+child and the process ID number of the child in the parent, or @minus{}1
 upon error. In the latter case, @code{ERRNO} indicates the problem.
 In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are
 updated to reflect the correct values.
 
 @cindex @code{waitpid()} extension function
 @item ret = waitpid(pid)
-This function takes a numeric argument, which is the process-ID to
+This function takes a numeric argument, which is the process ID to
 wait for. The return value is that of the
 @code{waitpid()} system call.
 
@@ -33845,8 +33882,8 @@ else
 @subsection Enabling In-Place File Editing
 
 @cindex @code{inplace} extension
-The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option
-which performs ``in place'' editing of each input file.
+The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option,
+which performs ``in-place'' editing of each input file.
 It uses the bundled @file{inplace.awk} include file to invoke the extension
 properly:
 
@@ -33942,14 +33979,14 @@ they are read, with each entry returned as a record.
 The record consists of three fields. The first two are the inode number and the
 @value{FN}, separated by a forward slash character.
 On systems where the directory entry contains the file type, the record
-has a third field (also separated by a slash) which is a single letter
+has a third field (also separated by a slash), which is a single letter
 indicating the type of the file. The letters and their corresponding file
 types are shown in @ref{table-readdir-file-types}.
 
 @float Table,table-readdir-file-types
 @caption{File types returned by the @code{readdir} extension}
 @multitable @columnfractions .1 .9
-@headitem Letter @tab File Type
+@headitem Letter @tab File type
 @item @code{b} @tab Block device
 @item @code{c} @tab Character device
 @item @code{d} @tab Directory
@@ -33977,7 +34014,7 @@ Here is an example:
 @@load "readdir"
 @dots{}
 BEGIN @{ FS = "/" @}
-@{ print "file name is", $2 @}
+@{ print "@value{FN} is", $2 @}
 @end example
 
 @node Extension Sample Revout
@@ -33998,8 +34035,7 @@ BEGIN @{
 @}
 @end example
 
-The output from this program is:
-@samp{cinap t'nod}.
+The output from this program is @samp{cinap t'nod}.
 
 @node Extension Sample Rev2way
 @subsection Two-Way I/O Example
@@ -34054,7 +34090,7 @@ success, or zero upon failure.
 @code{reada()} is the inverse of @code{writea()};
 it reads the file named as its first argument, filling in
 the array named as the second argument. It clears the array first.
-Here too, the return value is one on success and zero upon failure.
+Here too, the return value is one on success, or zero upon failure.
 @end table
 
 The array created by @code{reada()} is identical to that written by
@@ -34142,7 +34178,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}.
 Attempt to sleep for @var{seconds} seconds.  If @var{seconds} is negative,
 or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}.
 Otherwise, return zero after sleeping for the indicated amount of time.
-Note that @var{seconds} may be a floating-point (non-integral) value.
+Note that @var{seconds} may be a floating-point (nonintegral) value.
 Implementation details: depending on platform availability, this function
 tries to use @code{nanosleep()} or @code{select()} to implement the delay.
 @end table
@@ -34169,10 +34205,13 @@ project provides a number of @command{gawk} extensions, including one for
 processing XML files.  This is the evolution of the original @command{xgawk}
 (XML @command{gawk}) project.
 
-As of this writing, there are six extensions:
+As of this writing, there are seven extensions:
 
 @itemize @value{BULLET}
 @item
+@code{errno} extension
+
+@item
 GD graphics library extension
 
 @item
@@ -34183,7 +34222,7 @@ PostgreSQL extension
 
 @item
 MPFR library extension
-(this provides access to a number of MPFR functions which @command{gawk}'s
+(this provides access to a number of MPFR functions that @command{gawk}'s
 native MPFR support does not)
 
 @item
@@ -34237,7 +34276,7 @@ make install                          @ii{Install the extensions}
 
 If you have installed @command{gawk} in the standard way, then you
 will likely not need the @option{--with-gawk} option when configuring
-@code{gawkextlib}.  You may also need to use the @command{sudo} utility
+@code{gawkextlib}.  You may need to use the @command{sudo} utility
 to install both @command{gawk} and @code{gawkextlib}, depending upon
 how your system works.
 
@@ -34262,7 +34301,7 @@ named @code{plugin_is_GPL_compatible}.
 
 @item
 Communication between @command{gawk} and an extension is two-way.
-@command{gawk} passes a @code{struct} to the extension which contains
+@command{gawk} passes a @code{struct} to the extension that contains
 various data fields and function pointers.  The extension can then call
 into @command{gawk} via the supplied function pointers to accomplish
 certain tasks.
@@ -34275,7 +34314,7 @@ By convention, implementation functions are named @code{do_@var{XXXX}()}
 for some @command{awk}-level function @code{@var{XXXX}()}.
 
 @item
-The API is defined in a header file named @file{gawkpi.h}. You must include
+The API is defined in a header file named @file{gawkapi.h}. You must include
 a number of standard header files @emph{before} including it in your source file.
 
 @item
@@ -34320,7 +34359,7 @@ getting the count of elements in an array;
 creating a new array;
 clearing an array;
 and
-flattening an array for easy C style looping over all its indices and elements)
+flattening an array for easy C-style looping over all its indices and elements)
 @end itemize
 
 @item
@@ -34328,7 +34367,7 @@ The API defines a number of standard data types for representing
 @command{awk} values, array elements, and arrays.
 
 @item
-The API provide convenience functions for constructing values.
+The API provides convenience functions for constructing values.
 It also provides memory management functions to ensure compatibility
 between memory allocated by @command{gawk} and memory allocated by an
 extension.
@@ -34354,8 +34393,8 @@ file make this easier to do.
 
 @item
 The @command{gawk} distribution includes a number of small but useful
-sample extensions. The @code{gawkextlib} project includes several more,
-larger, extensions.  If you wish to write an extension and contribute it
+sample extensions. The @code{gawkextlib} project includes several more
+(larger) extensions.  If you wish to write an extension and contribute it
 to the community of @command{gawk} users, the @code{gawkextlib} project
 is the place to do so.