Update doc for change to extension management of GMP/MPFR values.

1 files changed, 146 insertions, 142 deletions

diff --git a/doc/gawk.info b/doc/gawk.info
index e17e97e7..f0450b45 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -26141,7 +26141,12 @@ example:
 dynamically, but the MPFR and GMP libraries treat these objects as
 values, the same way that you would pass an 'int' or a 'double' by
 value.  There is no way to "transfer ownership" of MPFR and GMP objects.
-Thus, code in an extension should look like this:
+
+   The final results of an MPFR or GMP calculation should be passed back
+to 'gawk', by value, as you would a string or a 'double'.  'gawk' will
+take care of freeing the storage.
+
+   Thus, code in an extension should look like this:
 
      mpz_t part1, part2, answer;             declare local values
 
@@ -26154,9 +26159,8 @@ Thus, code in an extension should look like this:
 
      mpz_clear(part1);                       release intermediate values
      mpz_clear(part2);
-     mpz_clear(answer);
 
-     return result;
+     return result;                          value in 'answer' managed by 'gawk'
 
 
 File: gawk.info,  Node: Registration Functions,  Next: Printing Messages,  Prev: API Ownership of MPFR and GMP Values,  Up: Extension API Description
@@ -39235,145 +39239,145 @@ Node: Memory Allocation Functions1050681
 Ref: Memory Allocation Functions-Footnote-11055182
 Node: Constructor Functions1055281
 Node: API Ownership of MPFR and GMP Values1058934
-Node: Registration Functions1060247
-Node: Extension Functions1060947
-Node: Exit Callback Functions1066269
-Node: Extension Version String1067519
-Node: Input Parsers1068182
-Node: Output Wrappers1080903
-Node: Two-way processors1085415
-Node: Printing Messages1087680
-Ref: Printing Messages-Footnote-11088851
-Node: Updating ERRNO1089004
-Node: Requesting Values1089743
-Ref: table-value-types-returned1090480
-Node: Accessing Parameters1091589
-Node: Symbol Table Access1092826
-Node: Symbol table by name1093338
-Ref: Symbol table by name-Footnote-11096363
-Node: Symbol table by cookie1096491
-Ref: Symbol table by cookie-Footnote-11100676
-Node: Cached values1100740
-Ref: Cached values-Footnote-11104276
-Node: Array Manipulation1104429
-Ref: Array Manipulation-Footnote-11105520
-Node: Array Data Types1105557
-Ref: Array Data Types-Footnote-11108215
-Node: Array Functions1108307
-Node: Flattening Arrays1112805
-Node: Creating Arrays1119781
-Node: Redirection API1124548
-Node: Extension API Variables1127381
-Node: Extension Versioning1128092
-Ref: gawk-api-version1128521
-Node: Extension GMP/MPFR Versioning1130253
-Node: Extension API Informational Variables1131881
-Node: Extension API Boilerplate1132954
-Node: Changes from API V11136928
-Node: Finding Extensions1138500
-Node: Extension Example1139059
-Node: Internal File Description1139857
-Node: Internal File Ops1143937
-Ref: Internal File Ops-Footnote-11155287
-Node: Using Internal File Ops1155427
-Ref: Using Internal File Ops-Footnote-11157810
-Node: Extension Samples1158084
-Node: Extension Sample File Functions1159613
-Node: Extension Sample Fnmatch1167262
-Node: Extension Sample Fork1168749
-Node: Extension Sample Inplace1169967
-Node: Extension Sample Ord1173593
-Node: Extension Sample Readdir1174429
-Ref: table-readdir-file-types1175318
-Node: Extension Sample Revout1176386
-Node: Extension Sample Rev2way1176975
-Node: Extension Sample Read write array1177715
-Node: Extension Sample Readfile1180880
-Node: Extension Sample Time1181975
-Node: Extension Sample API Tests1183727
-Node: gawkextlib1184219
-Node: Extension summary1187137
-Node: Extension Exercises1190839
-Node: Language History1192081
-Node: V7/SVR3.11193737
-Node: SVR41195889
-Node: POSIX1197323
-Node: BTL1198704
-Node: POSIX/GNU1199433
-Node: Feature History1205211
-Node: Common Extensions1222386
-Node: Ranges and Locales1223669
-Ref: Ranges and Locales-Footnote-11228285
-Ref: Ranges and Locales-Footnote-21228312
-Ref: Ranges and Locales-Footnote-31228547
-Node: Contributors1228770
-Node: History summary1234767
-Node: Installation1236147
-Node: Gawk Distribution1237091
-Node: Getting1237575
-Node: Extracting1238538
-Node: Distribution contents1240176
-Node: Unix Installation1247237
-Node: Quick Installation1248041
-Node: Compiling with MPFR1250461
-Node: Shell Startup Files1251151
-Node: Additional Configuration Options1252240
-Node: Configuration Philosophy1254555
-Node: Compiling from Git1256951
-Node: Building the Documentation1257506
-Node: Non-Unix Installation1258890
-Node: PC Installation1259350
-Node: PC Binary Installation1260188
-Node: PC Compiling1261061
-Node: PC Using1262178
-Node: Cygwin1265731
-Node: MSYS1266955
-Node: VMS Installation1267557
-Node: VMS Compilation1268276
-Ref: VMS Compilation-Footnote-11269505
-Node: VMS Dynamic Extensions1269563
-Node: VMS Installation Details1271248
-Node: VMS Running1273510
-Node: VMS GNV1277789
-Node: Bugs1278503
-Node: Bug definition1279415
-Node: Bug address1282351
-Node: Usenet1285739
-Node: Performance bugs1286928
-Node: Asking for help1289849
-Node: Maintainers1291816
-Node: Other Versions1293010
-Node: Installation summary1301174
-Node: Notes1302538
-Node: Compatibility Mode1303332
-Node: Additions1304114
-Node: Accessing The Source1305039
-Node: Adding Code1306476
-Node: New Ports1312668
-Node: Derived Files1317043
-Ref: Derived Files-Footnote-11322703
-Ref: Derived Files-Footnote-21322738
-Ref: Derived Files-Footnote-31323336
-Node: Future Extensions1323450
-Node: Implementation Limitations1324108
-Node: Extension Design1325318
-Node: Old Extension Problems1326462
-Ref: Old Extension Problems-Footnote-11327980
-Node: Extension New Mechanism Goals1328037
-Ref: Extension New Mechanism Goals-Footnote-11331401
-Node: Extension Other Design Decisions1331590
-Node: Extension Future Growth1333703
-Node: Notes summary1334309
-Node: Basic Concepts1335467
-Node: Basic High Level1336148
-Ref: figure-general-flow1336430
-Ref: figure-process-flow1337116
-Ref: Basic High Level-Footnote-11340418
-Node: Basic Data Typing1340603
-Node: Glossary1343931
-Node: Copying1375818
-Node: GNU Free Documentation License1413361
-Node: Index1438481
+Node: Registration Functions1060467
+Node: Extension Functions1061167
+Node: Exit Callback Functions1066489
+Node: Extension Version String1067739
+Node: Input Parsers1068402
+Node: Output Wrappers1081123
+Node: Two-way processors1085635
+Node: Printing Messages1087900
+Ref: Printing Messages-Footnote-11089071
+Node: Updating ERRNO1089224
+Node: Requesting Values1089963
+Ref: table-value-types-returned1090700
+Node: Accessing Parameters1091809
+Node: Symbol Table Access1093046
+Node: Symbol table by name1093558
+Ref: Symbol table by name-Footnote-11096583
+Node: Symbol table by cookie1096711
+Ref: Symbol table by cookie-Footnote-11100896
+Node: Cached values1100960
+Ref: Cached values-Footnote-11104496
+Node: Array Manipulation1104649
+Ref: Array Manipulation-Footnote-11105740
+Node: Array Data Types1105777
+Ref: Array Data Types-Footnote-11108435
+Node: Array Functions1108527
+Node: Flattening Arrays1113025
+Node: Creating Arrays1120001
+Node: Redirection API1124768
+Node: Extension API Variables1127601
+Node: Extension Versioning1128312
+Ref: gawk-api-version1128741
+Node: Extension GMP/MPFR Versioning1130473
+Node: Extension API Informational Variables1132101
+Node: Extension API Boilerplate1133174
+Node: Changes from API V11137148
+Node: Finding Extensions1138720
+Node: Extension Example1139279
+Node: Internal File Description1140077
+Node: Internal File Ops1144157
+Ref: Internal File Ops-Footnote-11155507
+Node: Using Internal File Ops1155647
+Ref: Using Internal File Ops-Footnote-11158030
+Node: Extension Samples1158304
+Node: Extension Sample File Functions1159833
+Node: Extension Sample Fnmatch1167482
+Node: Extension Sample Fork1168969
+Node: Extension Sample Inplace1170187
+Node: Extension Sample Ord1173813
+Node: Extension Sample Readdir1174649
+Ref: table-readdir-file-types1175538
+Node: Extension Sample Revout1176606
+Node: Extension Sample Rev2way1177195
+Node: Extension Sample Read write array1177935
+Node: Extension Sample Readfile1181100
+Node: Extension Sample Time1182195
+Node: Extension Sample API Tests1183947
+Node: gawkextlib1184439
+Node: Extension summary1187357
+Node: Extension Exercises1191059
+Node: Language History1192301
+Node: V7/SVR3.11193957
+Node: SVR41196109
+Node: POSIX1197543
+Node: BTL1198924
+Node: POSIX/GNU1199653
+Node: Feature History1205431
+Node: Common Extensions1222606
+Node: Ranges and Locales1223889
+Ref: Ranges and Locales-Footnote-11228505
+Ref: Ranges and Locales-Footnote-21228532
+Ref: Ranges and Locales-Footnote-31228767
+Node: Contributors1228990
+Node: History summary1234987
+Node: Installation1236367
+Node: Gawk Distribution1237311
+Node: Getting1237795
+Node: Extracting1238758
+Node: Distribution contents1240396
+Node: Unix Installation1247457
+Node: Quick Installation1248261
+Node: Compiling with MPFR1250681
+Node: Shell Startup Files1251371
+Node: Additional Configuration Options1252460
+Node: Configuration Philosophy1254775
+Node: Compiling from Git1257171
+Node: Building the Documentation1257726
+Node: Non-Unix Installation1259110
+Node: PC Installation1259570
+Node: PC Binary Installation1260408
+Node: PC Compiling1261281
+Node: PC Using1262398
+Node: Cygwin1265951
+Node: MSYS1267175
+Node: VMS Installation1267777
+Node: VMS Compilation1268496
+Ref: VMS Compilation-Footnote-11269725
+Node: VMS Dynamic Extensions1269783
+Node: VMS Installation Details1271468
+Node: VMS Running1273730
+Node: VMS GNV1278009
+Node: Bugs1278723
+Node: Bug definition1279635
+Node: Bug address1282571
+Node: Usenet1285959
+Node: Performance bugs1287148
+Node: Asking for help1290069
+Node: Maintainers1292036
+Node: Other Versions1293230
+Node: Installation summary1301394
+Node: Notes1302758
+Node: Compatibility Mode1303552
+Node: Additions1304334
+Node: Accessing The Source1305259
+Node: Adding Code1306696
+Node: New Ports1312888
+Node: Derived Files1317263
+Ref: Derived Files-Footnote-11322923
+Ref: Derived Files-Footnote-21322958
+Ref: Derived Files-Footnote-31323556
+Node: Future Extensions1323670
+Node: Implementation Limitations1324328
+Node: Extension Design1325538
+Node: Old Extension Problems1326682
+Ref: Old Extension Problems-Footnote-11328200
+Node: Extension New Mechanism Goals1328257
+Ref: Extension New Mechanism Goals-Footnote-11331621
+Node: Extension Other Design Decisions1331810
+Node: Extension Future Growth1333923
+Node: Notes summary1334529
+Node: Basic Concepts1335687
+Node: Basic High Level1336368
+Ref: figure-general-flow1336650
+Ref: figure-process-flow1337336
+Ref: Basic High Level-Footnote-11340638
+Node: Basic Data Typing1340823
+Node: Glossary1344151
+Node: Copying1376038
+Node: GNU Free Documentation License1413581
+Node: Index1438701
 
 End Tag Table