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

4 files changed, 167 insertions, 150 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 48727973..dec843a2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2022-02-25         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (API Ownership of MPFR and GMP Values): Rework for
+	changes to code.
+
 2022-02-23         Andrew J. Schorr      <aschorr@telemetry-investments.com>
 
 	* gawktexi.in (Extension Sample Read write array): Fix description of
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
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index b43dde16..d9b7fbc3 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -36243,8 +36243,13 @@ p = NULL;                       @ii{now} q @ii{``owns'' it}
 MPFR and GMP objects are indeed allocated on the stack or dynamically,
 but the MPFR and GMP libraries treat these objects as values, the same way that
 you would pass an @code{int} or a @code{double} by value.  There is no
-way to ``transfer ownership'' of MPFR and GMP objects.  Thus, code in
-an extension should look like this:
+way to ``transfer ownership'' of MPFR and GMP objects.
+
+The final results of an MPFR or GMP calculation should be passed back
+to @command{gawk}, by value, as you would a string or a @code{double}.
+@command{gawk} will take care of freeing the storage.
+
+Thus, code in an extension should look like this:
 
 @example
 mpz_t part1, part2, answer;             @ii{declare local values}
@@ -36258,9 +36263,8 @@ make_number_mpz(answer, & result);      @ii{set it with final GMP value}
 
 mpz_clear(part1);                       @ii{release intermediate values}
 mpz_clear(part2);
-mpz_clear(answer);
 
-return result;
+return result;                          @ii{value in @code{answer} managed by @code{gawk}}
 @end example
 
 @node Registration Functions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 2eb81be6..991136c3 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -35086,8 +35086,13 @@ p = NULL;                       @ii{now} q @ii{``owns'' it}
 MPFR and GMP objects are indeed allocated on the stack or dynamically,
 but the MPFR and GMP libraries treat these objects as values, the same way that
 you would pass an @code{int} or a @code{double} by value.  There is no
-way to ``transfer ownership'' of MPFR and GMP objects.  Thus, code in
-an extension should look like this:
+way to ``transfer ownership'' of MPFR and GMP objects.
+
+The final results of an MPFR or GMP calculation should be passed back
+to @command{gawk}, by value, as you would a string or a @code{double}.
+@command{gawk} will take care of freeing the storage.
+
+Thus, code in an extension should look like this:
 
 @example
 mpz_t part1, part2, answer;             @ii{declare local values}
@@ -35101,9 +35106,8 @@ make_number_mpz(answer, & result);      @ii{set it with final GMP value}
 
 mpz_clear(part1);                       @ii{release intermediate values}
 mpz_clear(part2);
-mpz_clear(answer);
 
-return result;
+return result;                          @ii{value in @code{answer} managed by @code{gawk}}
 @end example
 
 @node Registration Functions