Improve documentation of API strnum feature.

4 files changed, 166 insertions, 137 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 879be20a..7bebbd1e 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2016-12-05         Andrew J. Schorr     <aschorr@telemetry-investments.com>
+
+	* gawktexi.in: Explain why an API extension function might want
+	to use the AWK_STRNUM type to return data.
+
 2016-12-23         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Update API table of type requested / type returned.
diff --git a/doc/gawk.info b/doc/gawk.info
index dd920c6d..ee2b5f13 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -23684,6 +23684,14 @@ extension creates a strnum value, the result is a string flagged as user
 input.  Subsequent parsing by 'gawk' then determines whether it looks
 like a number and should be treated as a strnum, or as a regular string.
 
+   This is useful in cases where an extension function would like to do
+something comparable to the 'split()' function which sets the user input
+attribute on the array elements it creates.  For example, an extension
+that implements CSV splitting would want to use this feature.  This is
+also useful for a function that retrieves a data item from a database.
+The PostgreSQL 'PQgetvalue()' function, for example, returns a string
+that may be numeric or textual depending on the contents.
+
    Typed regexp values (*note Strong Regexp Constants::) are not of much
 use to extension functions.  Extension functions can tell that they've
 received them, and create them for scalar values.  Otherwise, they can
@@ -35862,142 +35870,142 @@ Ref: figure-call-new-function948497
 Node: Extension API Description950559
 Node: Extension API Functions Introduction952201
 Node: General Data Types957512
-Ref: General Data Types-Footnote-1964234
-Node: Memory Allocation Functions964533
-Ref: Memory Allocation Functions-Footnote-1967378
-Node: Constructor Functions967477
-Node: Registration Functions970476
-Node: Extension Functions971161
-Node: Exit Callback Functions976359
-Node: Extension Version String977609
-Node: Input Parsers978272
-Node: Output Wrappers988154
-Node: Two-way processors992666
-Node: Printing Messages994931
-Ref: Printing Messages-Footnote-1996102
-Node: Updating ERRNO996255
-Node: Requesting Values996994
-Ref: table-value-types-returned997731
-Node: Accessing Parameters998667
-Node: Symbol Table Access999902
-Node: Symbol table by name1000414
-Node: Symbol table by cookie1002203
-Ref: Symbol table by cookie-Footnote-11006388
-Node: Cached values1006452
-Ref: Cached values-Footnote-11009988
-Node: Array Manipulation1010079
-Ref: Array Manipulation-Footnote-11011170
-Node: Array Data Types1011207
-Ref: Array Data Types-Footnote-11013865
-Node: Array Functions1013957
-Node: Flattening Arrays1018352
-Node: Creating Arrays1025293
-Node: Redirection API1030062
-Node: Extension API Variables1032893
-Node: Extension Versioning1033526
-Ref: gawk-api-version1033963
-Node: Extension API Informational Variables1035691
-Node: Extension API Boilerplate1036755
-Node: Changes from API V11040617
-Node: Finding Extensions1041277
-Node: Extension Example1041836
-Node: Internal File Description1042634
-Node: Internal File Ops1046714
-Ref: Internal File Ops-Footnote-11058114
-Node: Using Internal File Ops1058254
-Ref: Using Internal File Ops-Footnote-11060637
-Node: Extension Samples1060911
-Node: Extension Sample File Functions1062440
-Node: Extension Sample Fnmatch1070089
-Node: Extension Sample Fork1071576
-Node: Extension Sample Inplace1072794
-Node: Extension Sample Ord1076004
-Node: Extension Sample Readdir1076840
-Ref: table-readdir-file-types1077729
-Node: Extension Sample Revout1078534
-Node: Extension Sample Rev2way1079123
-Node: Extension Sample Read write array1079863
-Node: Extension Sample Readfile1081805
-Node: Extension Sample Time1082900
-Node: Extension Sample API Tests1084248
-Node: gawkextlib1084740
-Node: Extension summary1087187
-Node: Extension Exercises1090889
-Node: Language History1092387
-Node: V7/SVR3.11094043
-Node: SVR41096195
-Node: POSIX1097629
-Node: BTL1099008
-Node: POSIX/GNU1099737
-Node: Feature History1105599
-Node: Common Extensions1119969
-Node: Ranges and Locales1121252
-Ref: Ranges and Locales-Footnote-11125868
-Ref: Ranges and Locales-Footnote-21125895
-Ref: Ranges and Locales-Footnote-31126130
-Node: Contributors1126351
-Node: History summary1131911
-Node: Installation1133291
-Node: Gawk Distribution1134235
-Node: Getting1134719
-Node: Extracting1135680
-Node: Distribution contents1137318
-Node: Unix Installation1143660
-Node: Quick Installation1144342
-Node: Shell Startup Files1146756
-Node: Additional Configuration Options1147834
-Node: Configuration Philosophy1149639
-Node: Non-Unix Installation1152008
-Node: PC Installation1152468
-Node: PC Binary Installation1153306
-Node: PC Compiling1153741
-Node: PC Using1154858
-Node: Cygwin1157903
-Node: MSYS1158673
-Node: VMS Installation1159174
-Node: VMS Compilation1159965
-Ref: VMS Compilation-Footnote-11161194
-Node: VMS Dynamic Extensions1161252
-Node: VMS Installation Details1162937
-Node: VMS Running1165190
-Node: VMS GNV1169469
-Node: VMS Old Gawk1170204
-Node: Bugs1170675
-Node: Bug address1171338
-Node: Usenet1173735
-Node: Maintainers1174510
-Node: Other Versions1175886
-Node: Installation summary1182470
-Node: Notes1183505
-Node: Compatibility Mode1184370
-Node: Additions1185152
-Node: Accessing The Source1186077
-Node: Adding Code1187512
-Node: New Ports1193731
-Node: Derived Files1198219
-Ref: Derived Files-Footnote-11203704
-Ref: Derived Files-Footnote-21203739
-Ref: Derived Files-Footnote-31204337
-Node: Future Extensions1204451
-Node: Implementation Limitations1205109
-Node: Extension Design1206292
-Node: Old Extension Problems1207446
-Ref: Old Extension Problems-Footnote-11208964
-Node: Extension New Mechanism Goals1209021
-Ref: Extension New Mechanism Goals-Footnote-11212385
-Node: Extension Other Design Decisions1212574
-Node: Extension Future Growth1214687
-Node: Old Extension Mechanism1215523
-Node: Notes summary1217286
-Node: Basic Concepts1218468
-Node: Basic High Level1219149
-Ref: figure-general-flow1219431
-Ref: figure-process-flow1220116
-Ref: Basic High Level-Footnote-11223417
-Node: Basic Data Typing1223602
-Node: Glossary1226930
-Node: Copying1258877
-Node: GNU Free Documentation License1296416
-Node: Index1321534
+Ref: General Data Types-Footnote-1964721
+Node: Memory Allocation Functions965020
+Ref: Memory Allocation Functions-Footnote-1967865
+Node: Constructor Functions967964
+Node: Registration Functions970963
+Node: Extension Functions971648
+Node: Exit Callback Functions976846
+Node: Extension Version String978096
+Node: Input Parsers978759
+Node: Output Wrappers988641
+Node: Two-way processors993153
+Node: Printing Messages995418
+Ref: Printing Messages-Footnote-1996589
+Node: Updating ERRNO996742
+Node: Requesting Values997481
+Ref: table-value-types-returned998218
+Node: Accessing Parameters999154
+Node: Symbol Table Access1000389
+Node: Symbol table by name1000901
+Node: Symbol table by cookie1002690
+Ref: Symbol table by cookie-Footnote-11006875
+Node: Cached values1006939
+Ref: Cached values-Footnote-11010475
+Node: Array Manipulation1010566
+Ref: Array Manipulation-Footnote-11011657
+Node: Array Data Types1011694
+Ref: Array Data Types-Footnote-11014352
+Node: Array Functions1014444
+Node: Flattening Arrays1018839
+Node: Creating Arrays1025780
+Node: Redirection API1030549
+Node: Extension API Variables1033380
+Node: Extension Versioning1034013
+Ref: gawk-api-version1034450
+Node: Extension API Informational Variables1036178
+Node: Extension API Boilerplate1037242
+Node: Changes from API V11041104
+Node: Finding Extensions1041764
+Node: Extension Example1042323
+Node: Internal File Description1043121
+Node: Internal File Ops1047201
+Ref: Internal File Ops-Footnote-11058601
+Node: Using Internal File Ops1058741
+Ref: Using Internal File Ops-Footnote-11061124
+Node: Extension Samples1061398
+Node: Extension Sample File Functions1062927
+Node: Extension Sample Fnmatch1070576
+Node: Extension Sample Fork1072063
+Node: Extension Sample Inplace1073281
+Node: Extension Sample Ord1076491
+Node: Extension Sample Readdir1077327
+Ref: table-readdir-file-types1078216
+Node: Extension Sample Revout1079021
+Node: Extension Sample Rev2way1079610
+Node: Extension Sample Read write array1080350
+Node: Extension Sample Readfile1082292
+Node: Extension Sample Time1083387
+Node: Extension Sample API Tests1084735
+Node: gawkextlib1085227
+Node: Extension summary1087674
+Node: Extension Exercises1091376
+Node: Language History1092874
+Node: V7/SVR3.11094530
+Node: SVR41096682
+Node: POSIX1098116
+Node: BTL1099495
+Node: POSIX/GNU1100224
+Node: Feature History1106086
+Node: Common Extensions1120456
+Node: Ranges and Locales1121739
+Ref: Ranges and Locales-Footnote-11126355
+Ref: Ranges and Locales-Footnote-21126382
+Ref: Ranges and Locales-Footnote-31126617
+Node: Contributors1126838
+Node: History summary1132398
+Node: Installation1133778
+Node: Gawk Distribution1134722
+Node: Getting1135206
+Node: Extracting1136167
+Node: Distribution contents1137805
+Node: Unix Installation1144147
+Node: Quick Installation1144829
+Node: Shell Startup Files1147243
+Node: Additional Configuration Options1148321
+Node: Configuration Philosophy1150126
+Node: Non-Unix Installation1152495
+Node: PC Installation1152955
+Node: PC Binary Installation1153793
+Node: PC Compiling1154228
+Node: PC Using1155345
+Node: Cygwin1158390
+Node: MSYS1159160
+Node: VMS Installation1159661
+Node: VMS Compilation1160452
+Ref: VMS Compilation-Footnote-11161681
+Node: VMS Dynamic Extensions1161739
+Node: VMS Installation Details1163424
+Node: VMS Running1165677
+Node: VMS GNV1169956
+Node: VMS Old Gawk1170691
+Node: Bugs1171162
+Node: Bug address1171825
+Node: Usenet1174222
+Node: Maintainers1174997
+Node: Other Versions1176373
+Node: Installation summary1182957
+Node: Notes1183992
+Node: Compatibility Mode1184857
+Node: Additions1185639
+Node: Accessing The Source1186564
+Node: Adding Code1187999
+Node: New Ports1194218
+Node: Derived Files1198706
+Ref: Derived Files-Footnote-11204191
+Ref: Derived Files-Footnote-21204226
+Ref: Derived Files-Footnote-31204824
+Node: Future Extensions1204938
+Node: Implementation Limitations1205596
+Node: Extension Design1206779
+Node: Old Extension Problems1207933
+Ref: Old Extension Problems-Footnote-11209451
+Node: Extension New Mechanism Goals1209508
+Ref: Extension New Mechanism Goals-Footnote-11212872
+Node: Extension Other Design Decisions1213061
+Node: Extension Future Growth1215174
+Node: Old Extension Mechanism1216010
+Node: Notes summary1217773
+Node: Basic Concepts1218955
+Node: Basic High Level1219636
+Ref: figure-general-flow1219918
+Ref: figure-process-flow1220603
+Ref: Basic High Level-Footnote-11223904
+Node: Basic Data Typing1224089
+Node: Glossary1227417
+Node: Copying1259364
+Node: GNU Free Documentation License1296903
+Node: Index1322021
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 25468301..e78134cb 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -32618,6 +32618,14 @@ When an extension creates a strnum value, the result is a string flagged
 as user input. Subsequent parsing by @command{gawk} then determines whether it
 looks like a number and should be treated as a strnum, or as a regular string.
 
+This is useful in cases where an extension function would like to do something
+comparable to the @code{split()} function which sets the user input attribute
+on the array elements it creates.  For example, an extension that implements
+CSV splitting would want to use this feature. This is also useful for a
+function that retrieves a data item from a database. The PostgreSQL
+@code{PQgetvalue()} function, for example, returns a string that may be numeric
+or textual depending on the contents.
+
 Typed regexp values (@pxref{Strong Regexp Constants}) are not of
 much use to extension functions.  Extension functions can tell that
 they've received them, and create them for scalar values. Otherwise,
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index d8f10f76..9967c5a2 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -31632,6 +31632,14 @@ When an extension creates a strnum value, the result is a string flagged
 as user input. Subsequent parsing by @command{gawk} then determines whether it
 looks like a number and should be treated as a strnum, or as a regular string.
 
+This is useful in cases where an extension function would like to do something
+comparable to the @code{split()} function which sets the user input attribute
+on the array elements it creates.  For example, an extension that implements
+CSV splitting would want to use this feature. This is also useful for a
+function that retrieves a data item from a database. The PostgreSQL
+@code{PQgetvalue()} function, for example, returns a string that may be numeric
+or textual depending on the contents.
+
 Typed regexp values (@pxref{Strong Regexp Constants}) are not of
 much use to extension functions.  Extension functions can tell that
 they've received them, and create them for scalar values. Otherwise,