O'Reilly edits, through Chapter 16.

1 files changed, 139 insertions, 133 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index e7d979d9..76d0c546 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -31636,7 +31636,7 @@ 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 both storage space within the running @command{gawk}
+variable.  This saves storage space within the running @command{gawk}
 process and reduces the time needed to create the value.
 
 @node Memory Allocation Functions
@@ -31665,13 +31665,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
@@ -31681,7 +31681,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{}
@@ -31718,7 +31718,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
@@ -31743,7 +31743,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}.
 
@@ -31794,7 +31794,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}
@@ -31808,7 +31808,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
@@ -31860,20 +31860,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);
@@ -31895,7 +31895,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.
 
@@ -31913,9 +31913,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
@@ -32008,7 +32008,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
@@ -32030,21 +32030,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.
@@ -32055,7 +32055,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.
 
@@ -32108,17 +32108,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}).
@@ -32228,7 +32228,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.
@@ -32239,7 +32239,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:
@@ -32279,14 +32279,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.
 
@@ -32315,7 +32315,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.}
@@ -32368,7 +32368,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}.
 
@@ -32401,32 +32401,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>
@@ -32438,11 +32438,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>
@@ -32460,12 +32460,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
@@ -32476,21 +32476,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
@@ -32507,16 +32507,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
@@ -32540,8 +32540,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,
@@ -32550,14 +32551,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.
@@ -32582,7 +32583,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:
 
@@ -32698,7 +32699,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()}
@@ -32776,7 +32777,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.
@@ -32880,7 +32881,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);
@@ -32899,13 +32900,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,
@@ -32961,7 +32962,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
@@ -32971,7 +32972,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.
 
@@ -33028,9 +33029,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 */
@@ -33066,7 +33067,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
@@ -33087,7 +33088,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)) @{
@@ -33102,7 +33103,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
@@ -33390,10 +33391,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
@@ -33411,14 +33412,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
@@ -33432,7 +33433,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
@@ -33479,7 +33480,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;
@@ -33538,7 +33539,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()}.
@@ -33669,7 +33670,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"
@@ -33725,7 +33726,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.
@@ -33748,7 +33749,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}):
@@ -33778,7 +33779,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}):
@@ -33819,9 +33820,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
@@ -33867,7 +33868,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 */
@@ -33923,9 +33924,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}).
 
@@ -34046,8 +34047,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:
@@ -34103,7 +34104,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);
@@ -34125,7 +34126,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
@@ -34250,9 +34253,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.
 
@@ -34288,14 +34291,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
@@ -34322,10 +34325,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"},
@@ -34335,15 +34338,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
@@ -34399,7 +34402,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:
@@ -34441,7 +34445,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
@@ -34483,14 +34487,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:
@@ -34527,14 +34531,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.
 
@@ -34562,8 +34566,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:
 
@@ -34659,14 +34663,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
@@ -34694,7 +34698,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
@@ -34715,8 +34719,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
@@ -34771,7 +34774,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
@@ -34859,7 +34862,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
@@ -34886,10 +34889,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
@@ -34900,7 +34906,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
@@ -34954,7 +34960,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.
 
@@ -34979,7 +34985,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.
@@ -34992,7 +34998,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
@@ -35037,7 +35043,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
@@ -35045,7 +35051,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.
@@ -35071,8 +35077,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.