Doc on workaround for debugger -f limitation.

4 files changed, 233 insertions, 189 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index d51a9a17..2f802349 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,10 @@
+2019-04-21         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Limitations): Provide brief instructions
+	on how to use use a temporary file in a script with
+	the debugger.  Thanks to Holger Klene <h.klene@gmx.de>
+	for the discussion.
+
 2019-04-18         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in (Undocumented): Note an undocumented feature.
diff --git a/doc/gawk.info b/doc/gawk.info
index f7b93f6a..aacd68ed 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -22766,7 +22766,16 @@ some limitations.  A few that it's worth being aware of are:
      language that is used mainly for quickly executing, short programs.
 
    * The 'gawk' debugger only accepts source code supplied with the '-f'
-     option.
+     option.  If you have a shell script that provides an 'awk' program
+     as a command line parameter, and you need to use the debugger, you
+     can write the script to a temporary file, and use that as the
+     program, with the '-f' option.  This might look like this:
+
+          cat << \EOF > /tmp/script.$$
+          ...                                  Your program here
+          EOF
+          gawk -D -f /tmp/script.$$
+          rm /tmp/script.$$
 
 
 File: gawk.info,  Node: Debugging Summary,  Prev: Limitations,  Up: Debugger
@@ -37276,193 +37285,193 @@ Node: Debugger Info910229
 Node: Miscellaneous Debugger Commands914300
 Node: Readline Support919362
 Node: Limitations920258
-Node: Debugging Summary922367
-Node: Namespaces923646
-Node: Global Namespace924725
-Node: Qualified Names926123
-Node: Default Namespace927122
-Node: Changing The Namespace927863
-Node: Naming Rules929477
-Node: Internal Name Management931325
-Node: Namespace Example932367
-Node: Namespace And Features934929
-Node: Namespace Summary936364
-Node: Arbitrary Precision Arithmetic937841
-Node: Computer Arithmetic939328
-Ref: table-numeric-ranges943094
-Ref: table-floating-point-ranges943587
-Ref: Computer Arithmetic-Footnote-1944245
-Node: Math Definitions944302
-Ref: table-ieee-formats947618
-Ref: Math Definitions-Footnote-1948221
-Node: MPFR features948326
-Node: FP Math Caution950044
-Ref: FP Math Caution-Footnote-1951116
-Node: Inexactness of computations951485
-Node: Inexact representation952445
-Node: Comparing FP Values953805
-Node: Errors accumulate955046
-Node: Getting Accuracy956479
-Node: Try To Round959189
-Node: Setting precision960088
-Ref: table-predefined-precision-strings960785
-Node: Setting the rounding mode962615
-Ref: table-gawk-rounding-modes962989
-Ref: Setting the rounding mode-Footnote-1966920
-Node: Arbitrary Precision Integers967099
-Ref: Arbitrary Precision Integers-Footnote-1970274
-Node: Checking for MPFR970423
-Node: POSIX Floating Point Problems971897
-Ref: POSIX Floating Point Problems-Footnote-1976182
-Node: Floating point summary976220
-Node: Dynamic Extensions978410
-Node: Extension Intro979963
-Node: Plugin License981229
-Node: Extension Mechanism Outline982026
-Ref: figure-load-extension982465
-Ref: figure-register-new-function984030
-Ref: figure-call-new-function985122
-Node: Extension API Description987184
-Node: Extension API Functions Introduction988826
-Ref: table-api-std-headers990662
-Node: General Data Types994527
-Ref: General Data Types-Footnote-11002888
-Node: Memory Allocation Functions1003187
-Ref: Memory Allocation Functions-Footnote-11007397
-Node: Constructor Functions1007496
-Node: Registration Functions1011082
-Node: Extension Functions1011767
-Node: Exit Callback Functions1017089
-Node: Extension Version String1018339
-Node: Input Parsers1019002
-Node: Output Wrappers1031723
-Node: Two-way processors1036235
-Node: Printing Messages1038500
-Ref: Printing Messages-Footnote-11039671
-Node: Updating ERRNO1039824
-Node: Requesting Values1040563
-Ref: table-value-types-returned1041300
-Node: Accessing Parameters1042236
-Node: Symbol Table Access1043471
-Node: Symbol table by name1043983
-Ref: Symbol table by name-Footnote-11047007
-Node: Symbol table by cookie1047135
-Ref: Symbol table by cookie-Footnote-11051320
-Node: Cached values1051384
-Ref: Cached values-Footnote-11054920
-Node: Array Manipulation1055073
-Ref: Array Manipulation-Footnote-11056164
-Node: Array Data Types1056201
-Ref: Array Data Types-Footnote-11058859
-Node: Array Functions1058951
-Node: Flattening Arrays1063449
-Node: Creating Arrays1070425
-Node: Redirection API1075192
-Node: Extension API Variables1078025
-Node: Extension Versioning1078736
-Ref: gawk-api-version1079165
-Node: Extension GMP/MPFR Versioning1080896
-Node: Extension API Informational Variables1082524
-Node: Extension API Boilerplate1083597
-Node: Changes from API V11087571
-Node: Finding Extensions1089143
-Node: Extension Example1089702
-Node: Internal File Description1090500
-Node: Internal File Ops1094580
-Ref: Internal File Ops-Footnote-11105930
-Node: Using Internal File Ops1106070
-Ref: Using Internal File Ops-Footnote-11108453
-Node: Extension Samples1108727
-Node: Extension Sample File Functions1110256
-Node: Extension Sample Fnmatch1117905
-Node: Extension Sample Fork1119392
-Node: Extension Sample Inplace1120610
-Node: Extension Sample Ord1123914
-Node: Extension Sample Readdir1124750
-Ref: table-readdir-file-types1125639
-Node: Extension Sample Revout1126444
-Node: Extension Sample Rev2way1127033
-Node: Extension Sample Read write array1127773
-Node: Extension Sample Readfile1129715
-Node: Extension Sample Time1130810
-Node: Extension Sample API Tests1132158
-Node: gawkextlib1132650
-Node: Extension summary1135568
-Node: Extension Exercises1139270
-Node: Language History1140512
-Node: V7/SVR3.11142168
-Node: SVR41144320
-Node: POSIX1145754
-Node: BTL1147134
-Node: POSIX/GNU1147863
-Node: Feature History1153641
-Node: Common Extensions1169687
-Node: Ranges and Locales1170970
-Ref: Ranges and Locales-Footnote-11175586
-Ref: Ranges and Locales-Footnote-21175613
-Ref: Ranges and Locales-Footnote-31175848
-Node: Contributors1176069
-Node: History summary1182014
-Node: Installation1183394
-Node: Gawk Distribution1184338
-Node: Getting1184822
-Node: Extracting1185785
-Node: Distribution contents1187423
-Node: Unix Installation1193903
-Node: Quick Installation1194585
-Node: Shell Startup Files1196999
-Node: Additional Configuration Options1198088
-Node: Configuration Philosophy1200253
-Node: Non-Unix Installation1202622
-Node: PC Installation1203082
-Node: PC Binary Installation1203920
-Node: PC Compiling1204355
-Node: PC Using1205472
-Node: Cygwin1209025
-Node: MSYS1210124
-Node: VMS Installation1210625
-Node: VMS Compilation1211416
-Ref: VMS Compilation-Footnote-11212645
-Node: VMS Dynamic Extensions1212703
-Node: VMS Installation Details1214388
-Node: VMS Running1216641
-Node: VMS GNV1220920
-Node: VMS Old Gawk1221655
-Node: Bugs1222126
-Node: Bug address1222789
-Node: Usenet1225771
-Node: Maintainers1226775
-Node: Other Versions1228036
-Node: Installation summary1234950
-Node: Notes1236152
-Node: Compatibility Mode1236946
-Node: Additions1237728
-Node: Accessing The Source1238653
-Node: Adding Code1240090
-Node: New Ports1246309
-Node: Derived Files1250684
-Ref: Derived Files-Footnote-11256344
-Ref: Derived Files-Footnote-21256379
-Ref: Derived Files-Footnote-31256977
-Node: Future Extensions1257091
-Node: Implementation Limitations1257749
-Node: Extension Design1258932
-Node: Old Extension Problems1260076
-Ref: Old Extension Problems-Footnote-11261594
-Node: Extension New Mechanism Goals1261651
-Ref: Extension New Mechanism Goals-Footnote-11265015
-Node: Extension Other Design Decisions1265204
-Node: Extension Future Growth1267317
-Node: Notes summary1268153
-Node: Basic Concepts1269311
-Node: Basic High Level1269992
-Ref: figure-general-flow1270274
-Ref: figure-process-flow1270959
-Ref: Basic High Level-Footnote-11274260
-Node: Basic Data Typing1274445
-Node: Glossary1277773
-Node: Copying1309611
-Node: GNU Free Documentation License1347154
-Node: Index1372274
+Node: Debugging Summary922812
+Node: Namespaces924091
+Node: Global Namespace925170
+Node: Qualified Names926568
+Node: Default Namespace927567
+Node: Changing The Namespace928308
+Node: Naming Rules929922
+Node: Internal Name Management931770
+Node: Namespace Example932812
+Node: Namespace And Features935374
+Node: Namespace Summary936809
+Node: Arbitrary Precision Arithmetic938286
+Node: Computer Arithmetic939773
+Ref: table-numeric-ranges943539
+Ref: table-floating-point-ranges944032
+Ref: Computer Arithmetic-Footnote-1944690
+Node: Math Definitions944747
+Ref: table-ieee-formats948063
+Ref: Math Definitions-Footnote-1948666
+Node: MPFR features948771
+Node: FP Math Caution950489
+Ref: FP Math Caution-Footnote-1951561
+Node: Inexactness of computations951930
+Node: Inexact representation952890
+Node: Comparing FP Values954250
+Node: Errors accumulate955491
+Node: Getting Accuracy956924
+Node: Try To Round959634
+Node: Setting precision960533
+Ref: table-predefined-precision-strings961230
+Node: Setting the rounding mode963060
+Ref: table-gawk-rounding-modes963434
+Ref: Setting the rounding mode-Footnote-1967365
+Node: Arbitrary Precision Integers967544
+Ref: Arbitrary Precision Integers-Footnote-1970719
+Node: Checking for MPFR970868
+Node: POSIX Floating Point Problems972342
+Ref: POSIX Floating Point Problems-Footnote-1976627
+Node: Floating point summary976665
+Node: Dynamic Extensions978855
+Node: Extension Intro980408
+Node: Plugin License981674
+Node: Extension Mechanism Outline982471
+Ref: figure-load-extension982910
+Ref: figure-register-new-function984475
+Ref: figure-call-new-function985567
+Node: Extension API Description987629
+Node: Extension API Functions Introduction989271
+Ref: table-api-std-headers991107
+Node: General Data Types994972
+Ref: General Data Types-Footnote-11003333
+Node: Memory Allocation Functions1003632
+Ref: Memory Allocation Functions-Footnote-11007842
+Node: Constructor Functions1007941
+Node: Registration Functions1011527
+Node: Extension Functions1012212
+Node: Exit Callback Functions1017534
+Node: Extension Version String1018784
+Node: Input Parsers1019447
+Node: Output Wrappers1032168
+Node: Two-way processors1036680
+Node: Printing Messages1038945
+Ref: Printing Messages-Footnote-11040116
+Node: Updating ERRNO1040269
+Node: Requesting Values1041008
+Ref: table-value-types-returned1041745
+Node: Accessing Parameters1042681
+Node: Symbol Table Access1043916
+Node: Symbol table by name1044428
+Ref: Symbol table by name-Footnote-11047452
+Node: Symbol table by cookie1047580
+Ref: Symbol table by cookie-Footnote-11051765
+Node: Cached values1051829
+Ref: Cached values-Footnote-11055365
+Node: Array Manipulation1055518
+Ref: Array Manipulation-Footnote-11056609
+Node: Array Data Types1056646
+Ref: Array Data Types-Footnote-11059304
+Node: Array Functions1059396
+Node: Flattening Arrays1063894
+Node: Creating Arrays1070870
+Node: Redirection API1075637
+Node: Extension API Variables1078470
+Node: Extension Versioning1079181
+Ref: gawk-api-version1079610
+Node: Extension GMP/MPFR Versioning1081341
+Node: Extension API Informational Variables1082969
+Node: Extension API Boilerplate1084042
+Node: Changes from API V11088016
+Node: Finding Extensions1089588
+Node: Extension Example1090147
+Node: Internal File Description1090945
+Node: Internal File Ops1095025
+Ref: Internal File Ops-Footnote-11106375
+Node: Using Internal File Ops1106515
+Ref: Using Internal File Ops-Footnote-11108898
+Node: Extension Samples1109172
+Node: Extension Sample File Functions1110701
+Node: Extension Sample Fnmatch1118350
+Node: Extension Sample Fork1119837
+Node: Extension Sample Inplace1121055
+Node: Extension Sample Ord1124359
+Node: Extension Sample Readdir1125195
+Ref: table-readdir-file-types1126084
+Node: Extension Sample Revout1126889
+Node: Extension Sample Rev2way1127478
+Node: Extension Sample Read write array1128218
+Node: Extension Sample Readfile1130160
+Node: Extension Sample Time1131255
+Node: Extension Sample API Tests1132603
+Node: gawkextlib1133095
+Node: Extension summary1136013
+Node: Extension Exercises1139715
+Node: Language History1140957
+Node: V7/SVR3.11142613
+Node: SVR41144765
+Node: POSIX1146199
+Node: BTL1147579
+Node: POSIX/GNU1148308
+Node: Feature History1154086
+Node: Common Extensions1170132
+Node: Ranges and Locales1171415
+Ref: Ranges and Locales-Footnote-11176031
+Ref: Ranges and Locales-Footnote-21176058
+Ref: Ranges and Locales-Footnote-31176293
+Node: Contributors1176514
+Node: History summary1182459
+Node: Installation1183839
+Node: Gawk Distribution1184783
+Node: Getting1185267
+Node: Extracting1186230
+Node: Distribution contents1187868
+Node: Unix Installation1194348
+Node: Quick Installation1195030
+Node: Shell Startup Files1197444
+Node: Additional Configuration Options1198533
+Node: Configuration Philosophy1200698
+Node: Non-Unix Installation1203067
+Node: PC Installation1203527
+Node: PC Binary Installation1204365
+Node: PC Compiling1204800
+Node: PC Using1205917
+Node: Cygwin1209470
+Node: MSYS1210569
+Node: VMS Installation1211070
+Node: VMS Compilation1211861
+Ref: VMS Compilation-Footnote-11213090
+Node: VMS Dynamic Extensions1213148
+Node: VMS Installation Details1214833
+Node: VMS Running1217086
+Node: VMS GNV1221365
+Node: VMS Old Gawk1222100
+Node: Bugs1222571
+Node: Bug address1223234
+Node: Usenet1226216
+Node: Maintainers1227220
+Node: Other Versions1228481
+Node: Installation summary1235395
+Node: Notes1236597
+Node: Compatibility Mode1237391
+Node: Additions1238173
+Node: Accessing The Source1239098
+Node: Adding Code1240535
+Node: New Ports1246754
+Node: Derived Files1251129
+Ref: Derived Files-Footnote-11256789
+Ref: Derived Files-Footnote-21256824
+Ref: Derived Files-Footnote-31257422
+Node: Future Extensions1257536
+Node: Implementation Limitations1258194
+Node: Extension Design1259377
+Node: Old Extension Problems1260521
+Ref: Old Extension Problems-Footnote-11262039
+Node: Extension New Mechanism Goals1262096
+Ref: Extension New Mechanism Goals-Footnote-11265460
+Node: Extension Other Design Decisions1265649
+Node: Extension Future Growth1267762
+Node: Notes summary1268598
+Node: Basic Concepts1269756
+Node: Basic High Level1270437
+Ref: figure-general-flow1270719
+Ref: figure-process-flow1271404
+Ref: Basic High Level-Footnote-11274705
+Node: Basic Data Typing1274890
+Node: Glossary1278218
+Node: Copying1310056
+Node: GNU Free Documentation License1347599
+Node: Index1372719
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 02481a7c..dd7389b8 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -31721,6 +31721,18 @@ executing, short programs.
 
 @item
 The @command{gawk} debugger only accepts source code supplied with the @option{-f} option.
+If you have a shell script that provides an @command{awk} program as a command
+line parameter, and you need to use the debugger, you can write the script
+to a temporary file, and use that as the program, with the @option{-f} option. This
+might look like this:
+
+@example
+cat << \EOF > /tmp/script.$$
+@dots{}                                  @ii{Your program here}
+EOF
+gawk -D -f /tmp/script.$$
+rm /tmp/script.$$
+@end example
 @end itemize
 
 @ignore
@@ -45178,3 +45190,5 @@ Add a section explaining recursion from ground zero. Probably
 easiest to do it with factorial as the example. Explain that
 recursion needs a stopping condition. Thanks to
 Bill Duncan <bduncan@beachnet.org> for the suggestion.
+
+4/2109: Go through and check @print{} vs. @error{} in examples
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 0408d61c..6b17f5ea 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -30733,6 +30733,18 @@ executing, short programs.
 
 @item
 The @command{gawk} debugger only accepts source code supplied with the @option{-f} option.
+If you have a shell script that provides an @command{awk} program as a command
+line parameter, and you need to use the debugger, you can write the script
+to a temporary file, and use that as the program, with the @option{-f} option. This
+might look like this:
+
+@example
+cat << \EOF > /tmp/script.$$
+@dots{}                                  @ii{Your program here}
+EOF
+gawk -D -f /tmp/script.$$
+rm /tmp/script.$$
+@end example
 @end itemize
 
 @ignore
@@ -44151,3 +44163,5 @@ Add a section explaining recursion from ground zero. Probably
 easiest to do it with factorial as the example. Explain that
 recursion needs a stopping condition. Thanks to
 Bill Duncan <bduncan@beachnet.org> for the suggestion.
+
+4/2109: Go through and check @print{} vs. @error{} in examples