Doc updates.

5 files changed, 182 insertions, 148 deletions

diff --git a/README.git b/README.git
index 7dbc24c8..7d0d260c 100644
--- a/README.git
+++ b/README.git
@@ -1,4 +1,4 @@
-Sun Aug  5 16:25:58 IDT 2012
+Sat Dec  1 21:53:02 IST 2012
 ============================
 
 If you are reading this, you have retrieved the gawk code base via
@@ -327,3 +327,26 @@ turn, followed by "bzr pull" to sync the branch.
 
 It depends upon if you have pushed the commit or not. Lots of good
 info is at http://stackoverflow.com/questions/927358/git-undo-last-commit .
+
+- What is the difference between using `git rebase' and `git merge' ?
+
+Both of these can be used to bring one branch up to date with respect
+to another.  For example, if you are working on a feature branch based
+off master, and master has since progressed, you can use
+
+	git checkout feature
+	git merge master
+
+or
+
+	git checkout feature
+	git rebase master
+
+In the end, you will have your changes on top of the current version of
+master in the feature branch.
+
+So which to use?  The answer depends on whether your feature branch
+has been pushed up to the Savannah repo or not.
+
+If your branch is completely local to your machine, use `git rebase'.
+Otherwise, use `git merge'.
diff --git a/TODO b/TODO
index 676e56a0..b14a002f 100644
--- a/TODO
+++ b/TODO
@@ -19,12 +19,12 @@ Minor Cleanups and Code Improvements
 	Make GAWKDEBUG pass the test suite.
 
 	API:
-		awk_true and awk_false ???
+		DONE: awk_true and awk_false
 		DONE: Update doc to use gcc -o filefuncs.so -shared filefuncs.o
 			instead of ld ...
 		??? #if !defined(GAWK) && !defined(GAWK_OMIT_CONVENIENCE_MACROS)
 
-	Make fflush() and fflush("") both flush all files, as in BWK awk.
+	DONE: Make fflush() and fflush("") both flush all files, as in BWK awk.
 
 	?? Add debugger commands to reference card
 
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 21a1c976..1d4a9e32 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2012-12-01         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawk.texi: API chapter. Sync with gawkapi.h
+
 2012-11-27         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawk.texi: API chapter. Change command for making shared libs
diff --git a/doc/gawk.info b/doc/gawk.info
index ca986467..724ae201 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -21920,11 +21920,16 @@ that use them.
      in the API data structures unwritable from extension code, while
      allowing `gawk' to use them as it needs to.
 
-`typedef int awk_bool_t;'
-     A simple boolean type. At the moment, the API does not define
-     special "true" and "false" values, although perhaps it should.
+`typedef enum awk_bool {'
 
-`typedef struct {'
+`    awk_false = 0,'
+
+`    awk_true'
+
+`} awk_bool_t;'
+     A simple boolean type.
+
+`typedef struct awk_string {'
 `    char *str;      /* data */'
 `    size_t len;     /* length thereof, in chars */'
 `} awk_string_t;'
@@ -21946,7 +21951,7 @@ that use them.
      This `enum' indicates the type of a value.  It is used in the
      following `struct'.
 
-`typedef struct {'
+`typedef struct awk_value {'
 `    awk_valtype_t   val_type;'
 `    union {'
 `        awk_string_t       s;'
@@ -22166,7 +22171,7 @@ File: gawk.info,  Node: Extension Functions,  Next: Exit Callback Functions,  Up
 
 Extension functions are described by the following record:
 
-     typedef struct {
+     typedef struct awk_ext_func {
          const char *name;
          awk_value_t *(*function)(int num_actual_args, awk_value_t *result);
          size_t num_expected_args;
@@ -22285,11 +22290,11 @@ used for `RT', if any.
    Your extension should package these functions inside an
 `awk_input_parser_t', which looks like this:
 
-     typedef struct input_parser {
+     typedef struct awk_input_parser {
          const char *name;   /* name of parser */
          awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf);
          awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf);
-         awk_const struct input_parser *awk_const next;    /* for use by gawk */
+         awk_const struct awk_input_parser *awk_const next;    /* for use by gawk */
      } awk_input_parser_t;
 
    The fields are:
@@ -22456,11 +22461,11 @@ an extension to take over the output to a file opened with the `>' or
 
    The output wrapper is very similar to the input parser structure:
 
-     typedef struct output_wrapper {
+     typedef struct awk_output_wrapper {
          const char *name;   /* name of the wrapper */
          awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf);
          awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf);
-         awk_const struct output_wrapper *awk_const next;  /* for use by gawk */
+         awk_const struct awk_output_wrapper *awk_const next;  /* for use by gawk */
      } awk_output_wrapper_t;
 
    The members are as follows:
@@ -22487,7 +22492,7 @@ an extension to take over the output to a file opened with the `>' or
 
    The `awk_output_buf_t' structure looks like this:
 
-     typedef struct {
+     typedef struct awk_output_buf {
          const char *name;   /* name of output file */
          const char *mode;   /* mode argument to fopen */
          FILE *fp;           /* stdio file pointer */
@@ -22563,13 +22568,13 @@ structures as described earlier.
 
    A two-way processor is represented by the following structure:
 
-     typedef struct two_way_processor {
+     typedef struct awk_two_way_processor {
          const char *name;   /* name of the two-way processor */
          awk_bool_t (*can_take_two_way)(const char *name);
          awk_bool_t (*take_control_of)(const char *name,
                                        awk_input_buf_t *inbuf,
                                        awk_output_buf_t *outbuf);
-         awk_const struct two_way_processor *awk_const next;  /* for use by gawk */
+         awk_const struct awk_two_way_processor *awk_const next;  /* for use by gawk */
      } awk_two_way_processor_t;
 
    The fields are as follows:
@@ -23612,8 +23617,8 @@ in the `gawkapi.h' header file:
      If you need to do some initialization work, you should define a
      function that does it (creates variables, opens files, etc.)  and
      then define the `init_func' pointer to point to your function.
-     The function should return zero (false) upon failure, non-zero
-     (success) if everything goes well.
+     The function should return `awk_false' upon failure, or `awk_true'
+     if everything goes well.
 
      If you don't need to do any initialization, define the pointer and
      initialize it to `NULL'.
@@ -23634,7 +23639,7 @@ standard work. It does the following:
      to load, it prints a warning message but continues on.
 
   3. If the `init_func' pointer is not `NULL', call the function it
-     points to. If it returns non-zero, print a warning message.
+     points to. If it returns `awk_false', print a warning message.
 
   4. If `ext_version' is not `NULL', register the version string with
      `gawk'.
@@ -32167,117 +32172,117 @@ Node: Extension Future Growth878591
 Node: Extension API Description879409
 Node: Extension API Functions Introduction880737
 Node: General Data Types885437
-Ref: General Data Types-Footnote-1891070
-Node: Requesting Values891369
-Ref: table-value-types-returned892100
-Node: Constructor Functions893054
-Node: Registration Functions896050
-Node: Extension Functions896735
-Node: Exit Callback Functions898554
-Node: Extension Version String899797
-Node: Input Parsers900447
-Node: Output Wrappers909026
-Node: Two-way processors913419
-Node: Printing Messages915541
-Ref: Printing Messages-Footnote-1916618
-Node: Updating `ERRNO'916770
-Node: Accessing Parameters917509
-Node: Symbol Table Access918739
-Node: Symbol table by name919251
-Ref: Symbol table by name-Footnote-1921421
-Node: Symbol table by cookie921501
-Ref: Symbol table by cookie-Footnote-1925630
-Node: Cached values925693
-Ref: Cached values-Footnote-1929136
-Node: Array Manipulation929227
-Ref: Array Manipulation-Footnote-1930325
-Node: Array Data Types930364
-Ref: Array Data Types-Footnote-1933067
-Node: Array Functions933159
-Node: Flattening Arrays936925
-Node: Creating Arrays943758
-Node: Extension API Variables948553
-Node: Extension Versioning949189
-Node: Extension API Informational Variables951090
-Node: Extension API Boilerplate952176
-Node: Finding Extensions956010
-Node: Extension Example956557
-Node: Internal File Description957295
-Node: Internal File Ops960983
-Ref: Internal File Ops-Footnote-1972430
-Node: Using Internal File Ops972570
-Ref: Using Internal File Ops-Footnote-1974923
-Node: Extension Samples975189
-Node: Extension Sample File Functions976632
-Node: Extension Sample Fnmatch985105
-Node: Extension Sample Fork986831
-Node: Extension Sample Ord988045
-Node: Extension Sample Readdir988821
-Node: Extension Sample Revout990325
-Node: Extension Sample Rev2way990918
-Node: Extension Sample Read write array991608
-Node: Extension Sample Readfile993491
-Node: Extension Sample API Tests994246
-Node: Extension Sample Time994771
-Node: gawkextlib996078
-Node: Language History998459
-Node: V7/SVR3.1999981
-Node: SVR41002302
-Node: POSIX1003744
-Node: BTL1004752
-Node: POSIX/GNU1005486
-Node: Common Extensions1011021
-Node: Ranges and Locales1012128
-Ref: Ranges and Locales-Footnote-11016746
-Ref: Ranges and Locales-Footnote-21016773
-Ref: Ranges and Locales-Footnote-31017033
-Node: Contributors1017254
-Node: Installation1021550
-Node: Gawk Distribution1022444
-Node: Getting1022928
-Node: Extracting1023754
-Node: Distribution contents1025446
-Node: Unix Installation1030668
-Node: Quick Installation1031285
-Node: Additional Configuration Options1033247
-Node: Configuration Philosophy1034724
-Node: Non-Unix Installation1037066
-Node: PC Installation1037524
-Node: PC Binary Installation1038823
-Node: PC Compiling1040671
-Node: PC Testing1043615
-Node: PC Using1044791
-Node: Cygwin1048976
-Node: MSYS1049976
-Node: VMS Installation1050490
-Node: VMS Compilation1051093
-Ref: VMS Compilation-Footnote-11052100
-Node: VMS Installation Details1052158
-Node: VMS Running1053793
-Node: VMS Old Gawk1055400
-Node: Bugs1055874
-Node: Other Versions1059726
-Node: Notes1065041
-Node: Compatibility Mode1065700
-Node: Additions1066483
-Node: Accessing The Source1067410
-Node: Adding Code1069013
-Node: New Ports1075055
-Node: Derived Files1079190
-Ref: Derived Files-Footnote-11084498
-Ref: Derived Files-Footnote-21084532
-Ref: Derived Files-Footnote-31085132
-Node: Future Extensions1085230
-Node: Implementation Limitations1085811
-Node: Basic Concepts1087038
-Node: Basic High Level1087719
-Ref: figure-general-flow1087990
-Ref: figure-process-flow1088589
-Ref: Basic High Level-Footnote-11091818
-Node: Basic Data Typing1092003
-Node: Glossary1095358
-Node: Copying1120669
-Node: GNU Free Documentation License1158226
-Node: Index1183363
+Ref: General Data Types-Footnote-1891039
+Node: Requesting Values891338
+Ref: table-value-types-returned892069
+Node: Constructor Functions893023
+Node: Registration Functions896019
+Node: Extension Functions896704
+Node: Exit Callback Functions898536
+Node: Extension Version String899779
+Node: Input Parsers900429
+Node: Output Wrappers909016
+Node: Two-way processors913432
+Node: Printing Messages915562
+Ref: Printing Messages-Footnote-1916639
+Node: Updating `ERRNO'916791
+Node: Accessing Parameters917530
+Node: Symbol Table Access918760
+Node: Symbol table by name919272
+Ref: Symbol table by name-Footnote-1921442
+Node: Symbol table by cookie921522
+Ref: Symbol table by cookie-Footnote-1925651
+Node: Cached values925714
+Ref: Cached values-Footnote-1929157
+Node: Array Manipulation929248
+Ref: Array Manipulation-Footnote-1930346
+Node: Array Data Types930385
+Ref: Array Data Types-Footnote-1933088
+Node: Array Functions933180
+Node: Flattening Arrays936946
+Node: Creating Arrays943779
+Node: Extension API Variables948574
+Node: Extension Versioning949210
+Node: Extension API Informational Variables951111
+Node: Extension API Boilerplate952197
+Node: Finding Extensions956028
+Node: Extension Example956575
+Node: Internal File Description957313
+Node: Internal File Ops961001
+Ref: Internal File Ops-Footnote-1972448
+Node: Using Internal File Ops972588
+Ref: Using Internal File Ops-Footnote-1974941
+Node: Extension Samples975207
+Node: Extension Sample File Functions976650
+Node: Extension Sample Fnmatch985123
+Node: Extension Sample Fork986849
+Node: Extension Sample Ord988063
+Node: Extension Sample Readdir988839
+Node: Extension Sample Revout990343
+Node: Extension Sample Rev2way990936
+Node: Extension Sample Read write array991626
+Node: Extension Sample Readfile993509
+Node: Extension Sample API Tests994264
+Node: Extension Sample Time994789
+Node: gawkextlib996096
+Node: Language History998477
+Node: V7/SVR3.1999999
+Node: SVR41002320
+Node: POSIX1003762
+Node: BTL1004770
+Node: POSIX/GNU1005504
+Node: Common Extensions1011039
+Node: Ranges and Locales1012146
+Ref: Ranges and Locales-Footnote-11016764
+Ref: Ranges and Locales-Footnote-21016791
+Ref: Ranges and Locales-Footnote-31017051
+Node: Contributors1017272
+Node: Installation1021568
+Node: Gawk Distribution1022462
+Node: Getting1022946
+Node: Extracting1023772
+Node: Distribution contents1025464
+Node: Unix Installation1030686
+Node: Quick Installation1031303
+Node: Additional Configuration Options1033265
+Node: Configuration Philosophy1034742
+Node: Non-Unix Installation1037084
+Node: PC Installation1037542
+Node: PC Binary Installation1038841
+Node: PC Compiling1040689
+Node: PC Testing1043633
+Node: PC Using1044809
+Node: Cygwin1048994
+Node: MSYS1049994
+Node: VMS Installation1050508
+Node: VMS Compilation1051111
+Ref: VMS Compilation-Footnote-11052118
+Node: VMS Installation Details1052176
+Node: VMS Running1053811
+Node: VMS Old Gawk1055418
+Node: Bugs1055892
+Node: Other Versions1059744
+Node: Notes1065059
+Node: Compatibility Mode1065718
+Node: Additions1066501
+Node: Accessing The Source1067428
+Node: Adding Code1069031
+Node: New Ports1075073
+Node: Derived Files1079208
+Ref: Derived Files-Footnote-11084516
+Ref: Derived Files-Footnote-21084550
+Ref: Derived Files-Footnote-31085150
+Node: Future Extensions1085248
+Node: Implementation Limitations1085829
+Node: Basic Concepts1087056
+Node: Basic High Level1087737
+Ref: figure-general-flow1088008
+Ref: figure-process-flow1088607
+Ref: Basic High Level-Footnote-11091836
+Node: Basic Data Typing1092021
+Node: Glossary1095376
+Node: Copying1120687
+Node: GNU Free Documentation License1158244
+Node: Index1183381
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 6abc337f..02b7623b 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -28818,11 +28818,13 @@ and to nothing when compiling @command{gawk} itself.  This makes
 certain fields in the API data structures unwritable from extension code,
 while allowing @command{gawk} to use them as it needs to.
 
-@item typedef int awk_bool_t;
-A simple boolean type. At the moment, the API does not define special
-``true'' and ``false'' values, although perhaps it should.
+@item typedef enum awk_bool @{
+@item @ @ @ @ awk_false = 0,
+@item @ @ @ @ awk_true
+@item @} awk_bool_t;
+A simple boolean type.
 
-@item typedef struct @{
+@item typedef struct awk_string @{
 @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */
 @itemx @ @ @ @ size_t len;@ @ @ @ @ /* length thereof, in chars */
 @itemx @} awk_string_t;
@@ -28845,7 +28847,7 @@ multibyte encoding.
 This @code{enum} indicates the type of a value.
 It is used in the following @code{struct}.
 
-@item typedef struct @{
+@item typedef struct awk_value @{
 @itemx @ @ @ @ awk_valtype_t   val_type;
 @itemx @ @ @ @ union @{
 @itemx @ @ @ @ @ @ @ @ awk_string_t@ @ @ @ @ @ @ s;
@@ -29091,7 +29093,7 @@ registering parts of your extension with @command{gawk}.
 Extension functions are described by the following record:
 
 @example
-typedef struct @{
+typedef struct awk_ext_func @{
 @ @ @ @ const char *name;
 @ @ @ @ awk_value_t *(*function)(int num_actual_args, awk_value_t *result);
 @ @ @ @ size_t num_expected_args;
@@ -29220,11 +29222,11 @@ Your extension should package these functions inside an
 @code{awk_input_parser_t}, which looks like this:
 
 @example
-typedef struct input_parser @{
+typedef struct awk_input_parser @{
     const char *name;   /* name of parser */
     awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf);
     awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf);
-    awk_const struct input_parser *awk_const next;    /* for use by gawk */
+    awk_const struct awk_input_parser *awk_const next;    /* for use by gawk */
 @} awk_input_parser_t;
 @end example
 
@@ -29413,11 +29415,11 @@ with the @samp{>} or @samp{>>} operators (@pxref{Redirection}).
 The output wrapper is very similar to the input parser structure:
 
 @example
-typedef struct output_wrapper @{
+typedef struct awk_output_wrapper @{
     const char *name;   /* name of the wrapper */
     awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf);
     awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf);
-    awk_const struct output_wrapper *awk_const next;  /* for use by gawk */
+    awk_const struct awk_output_wrapper *awk_const next;  /* for use by gawk */
 @} awk_output_wrapper_t;
 @end example
 
@@ -29447,7 +29449,7 @@ This is for use by @command{gawk}.
 The @code{awk_output_buf_t} structure looks like this:
 
 @example
-typedef struct @{
+typedef struct awk_output_buf @{
     const char *name;   /* name of output file */
     const char *mode;   /* mode argument to fopen */
     FILE *fp;           /* stdio file pointer */
@@ -29526,13 +29528,13 @@ as described earlier.
 A two-way processor is represented by the following structure:
 
 @example
-typedef struct two_way_processor @{
+typedef struct awk_two_way_processor @{
     const char *name;   /* name of the two-way processor */
     awk_bool_t (*can_take_two_way)(const char *name);
     awk_bool_t (*take_control_of)(const char *name,
                                   awk_input_buf_t *inbuf,
                                   awk_output_buf_t *outbuf);
-    awk_const struct two_way_processor *awk_const next;  /* for use by gawk */
+    awk_const struct awk_two_way_processor *awk_const next;  /* for use by gawk */
 @} awk_two_way_processor_t;
 @end example
 
@@ -30432,7 +30434,7 @@ static awk_bool_t init_testarray(void)
 @{
     create_new_array();
 
-    return 1;
+    return awk_true;
 @}
 
 static awk_bool_t (*init_func)(void) = init_testarray;
@@ -30650,8 +30652,8 @@ If you need to do some initialization work, you should define a
 function that does it (creates variables, opens files, etc.)
 and then define the @code{init_func} pointer to point to your
 function.
-The function should return zero (false) upon failure, non-zero
-(success) if everything goes well.
+The function should return @code{awk_false} upon failure, or @code{awk_true}
+if everything goes well.
 
 If you don't need to do any initialization, define the pointer and
 initialize it to @code{NULL}.
@@ -30678,7 +30680,7 @@ continues on.
 
 @item
 If the @code{init_func} pointer is not @code{NULL}, call the
-function it points to. If it returns non-zero, print a
+function it points to. If it returns @code{awk_false}, print a
 warning message.
 
 @item