[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] gawk branch, gawk-5.1-stable, updated. gawk-4.1.0-4266-g727f3f7
|
From: |
Arnold Robbins |
|
Subject: |
[SCM] gawk branch, gawk-5.1-stable, updated. gawk-4.1.0-4266-g727f3f7 |
|
Date: |
Fri, 2 Jul 2021 04:45:25 -0400 (EDT) |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, gawk-5.1-stable has been updated
via 727f3f71878b35fb58fca41a6d5465e3b64b4dbc (commit)
from b3bfdb152de59cab66ee428a42bc2a7f6f97b636 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=727f3f71878b35fb58fca41a6d5465e3b64b4dbc
commit 727f3f71878b35fb58fca41a6d5465e3b64b4dbc
Author: Arnold D. Robbins <arnold@skeeve.com>
Date: Fri Jul 2 11:44:59 2021 +0300
Doc updates relating to bugs and bug reports.
diff --git a/NEWS b/NEWS
index d5a5278..7b9c4d2 100644
--- a/NEWS
+++ b/NEWS
@@ -50,7 +50,10 @@ Changes from 5.1.0 to 5.1.1
13. The "no effect" lint warnings have been fixed up and now behave
more sanely.
-14. There have been numerous minor code cleanups and bug fixes. See the
+14. The manual has been updated with much more information about what is
+ and is not a bug, and the changes in the gawk mailing lists.
+
+15. There have been numerous minor code cleanups and bug fixes. See the
ChangeLog for details.
Changes from 5.0.1 to 5.1.0
diff --git a/doc/ChangeLog b/doc/ChangeLog
index e4c30f9..488f01b 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2021-07-02 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in (Bugs): Added discussion of what is and is not
+ a bug, as well as of the new help-gawk@gnu.org list and how
+ things are now managed.
+
2021-06-30 Arnold D. Robbins <arnold@skeeve.com>
* texinfo.tex: Updated from GNULIB.
diff --git a/doc/gawk.info b/doc/gawk.info
index bf9cc78..95ddb3a 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -684,9 +684,11 @@ in (a) below. A copy of the license is included in the
section entitled
* VMS Old Gawk:: An old version comes with some VMS
systems.
* Bugs:: Reporting Problems and Bugs.
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a
performance issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
* Other Versions:: Other freely available 'awk'
implementations.
@@ -31410,41 +31412,129 @@ might well want to fix it.
* Menu:
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a performance
issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
-File: gawk.info, Node: Bug address, Next: Usenet, Up: Bugs
+File: gawk.info, Node: Bug definition, Next: Bug address, Up: Bugs
-B.4.1 Submitting Bug Reports
+B.4.1 Defining What Is and What Is Not A Bug
+--------------------------------------------
+
+Before talking about reporting bugs, let's define what is a bug, and
+what is not.
+
+ A bug is:
+
+ * When 'gawk' behaves differently from what's described in the POSIX
+ standard, and that difference is not mentioned in this Info file as
+ being done on purpose.
+
+ * When 'gawk' behaves differently from what's described in this Info
+ file.
+
+ * When 'gawk' behaves differently from other 'awk' implementations in
+ particular circumstances, and that behavior cannot be attributed to
+ an additional feature in 'gawk'.
+
+ * Something that is obviously wrong, such as a core dump.
+
+ * When this Info file is unclear or ambiguous about a particular
+ feature's behavior.
+
+ The following things are _not_ bugs, and should not be reported to
+the bug mailing list. You can ask about them on the "help" mailing list
+(*note Asking for help::), but don't be surprised if you get an answer
+of the form "that's how 'gawk' behaves and it isn't going to change."
+
+ * Missing features, for any definition of "feature". For example,
+ additional built-in arithmetic functions, or additional ways to
+ split fields or records, or anything else.
+
+ The number of features that 'gawk' does _not_ have is by definition
+ infinite. It cannot be all things to all people.
+
+ * Behaviors that are defined by the POSIX standard and/or for
+ historical compatibility with Unix 'awk'. Even if you happen to
+ dislike those behaviors, they're not going to change: changing them
+ would break millions of existing 'awk' programs.
+
+ * Behaviors that differ from how it's done in other languages. 'awk'
+ and 'gawk' stand on their own and do not have to follow the crowd.
+ This is particularly true when the requested behavior change would
+ break backwards compatibility.
+
+ * Documentation issues of the form "the manual doesn't tell me how to
+ do XYZ." The manual is not a cookbook to solve every little problem
+ you may have.
+
+ * General questions and discussion about 'awk' programming or why
+ 'gawk' behaves the way it does. For that use the "help" mailing
+ list: see *note Asking for help::.
+
+ For more information, see 'Fork My Code, Please!--An Open Letter To
+Those of You Who Are Unhappy' (http://www.skeeve.com/fork-my-code.html),
+by Arnold Robbins and Chet Ramey.
+
+
+File: gawk.info, Node: Bug address, Next: Usenet, Prev: Bug definition,
Up: Bugs
+
+B.4.2 Submitting Bug Reports
----------------------------
Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of 'gawk'. Many bugs
-(usually subtle ones) are fixed at each release, and if yours is out of
-date, the problem may already have been solved.
-
- Second, please see if setting the environment variable 'LC_ALL' to
-'LC_ALL=C' causes things to behave as you expect. If so, it's a locale
-issue, and may or may not really be a bug.
-
- Third, carefully reread the documentation and see if it says you can
-do what you're trying to do. If it's not clear whether you should be
-able to do something or not, report that too; it's a bug in the
-documentation!
-
- Finally, before reporting a bug or trying to fix it yourself, try to
-isolate it to the smallest possible 'awk' program and input data file
-that reproduce the problem. Then send us the program and data file,
-some idea of what kind of Unix system you're using, the compiler you
-used to compile 'gawk', and the exact results 'gawk' gave you. Also say
-what you expected to occur; this helps us decide whether the problem is
-really in the documentation.
-
- Make sure to include the version number of 'gawk' you are using. You
-can get this information with the command 'gawk --version'.
+
+ Here are the steps for submitting a bug report. Following them will
+make both your life and the lives of the maintainers much easier.
+
+ 1. Make sure that what you want to report is appropriate. *Note Bug
+ definition::. If it's not, you are wasting your time and ours.
+
+ 2. Verify that you have the latest version of 'gawk'. Many bugs
+ (usually subtle ones) are fixed at each release, and if yours is
+ out of date, the problem may already have been solved.
+
+ 3. Please see if setting the environment variable 'LC_ALL' to
+ 'LC_ALL=C' causes things to behave as you expect. If so, it's a
+ locale issue, and may or may not really be a bug.
+
+ 4. Carefully reread the documentation and see if it says you can do
+ what you're trying to do. If it's not clear whether you should be
+ able to do something or not, report that too; it's a bug in the
+ documentation!
+
+ 5. Before reporting a bug or trying to fix it yourself, try to isolate
+ it to the smallest possible 'awk' program and input data file that
+ reproduce the problem. Then send us:
+
+ * The program and data file.
+
+ * Some idea of what kind of Unix system you're using.
+
+ * The compiler you used to compile 'gawk'.
+
+ * The exact results 'gawk' gave you. Also say what you expected
+ to occur; this helps us decide whether the problem is really
+ in the documentation.
+
+ * The version number of 'gawk' you are using. You can get this
+ information with the command 'gawk --version'.
+
+ 6. Do _not_ send screenshots. Instead, use copy/paste to send text,
+ or send files.
+
+ 7. Do send files as attachments, instead of inline. This avoids
+ corruption by mailer programs out in the wilds of the Internet.
+
+ 8. Please be sure to send all mail in _plain text_, not (or not
+ exclusively) in HTML.
+
+ 9. _All email must be in English. This is the only language
+ understood in common by all the maintainers._
Once you have a precise problem description, send email to
<bug-gawk@gnu.org>.
@@ -31452,10 +31542,7 @@ can get this information with the command 'gawk
--version'.
The 'gawk' maintainers subscribe to this address, and thus they will
receive your bug report. Although you can send mail to the maintainers
directly, the bug reporting address is preferred because the email list
-is archived at the GNU Project. _All email must be in English. This is
-the only language understood in common by all the maintainers._ In
-addition, please be sure to send all mail in _plain text_, not (or not
-exclusively) in HTML.
+is archived at the GNU Project.
NOTE: Many distributions of GNU/Linux and the various BSD-based
operating systems have their own bug reporting systems. If you
@@ -31469,11 +31556,6 @@ exclusively) in HTML.
having everything at the GNU Project keeps things self-contained
and not dependent on other organizations.
- Non-bug suggestions are always welcome as well. If you have
-questions about things that are unclear in the documentation or are just
-obscure features, ask on the bug list; we will try to help you out if we
-can.
-
Please note: We ask that you follow the GNU Kind Communication
Guidelines (https://gnu.org/philosophy/kind-communication.html) in your
correspondence on the list (as well as off of it).
@@ -31481,7 +31563,7 @@ correspondence on the list (as well as off of it).
File: gawk.info, Node: Usenet, Next: Performance bugs, Prev: Bug address,
Up: Bugs
-B.4.2 Please Don't Post Bug Reports to USENET
+B.4.3 Please Don't Post Bug Reports to USENET
---------------------------------------------
I gave up on Usenet a couple of years ago and haven't really looked
@@ -31502,9 +31584,9 @@ web forums. The steps described here are the only
officially recognized
way for reporting bugs. Really.
-File: gawk.info, Node: Performance bugs, Next: Maintainers, Prev: Usenet,
Up: Bugs
+File: gawk.info, Node: Performance bugs, Next: Asking for help, Prev:
Usenet, Up: Bugs
-B.4.3 What To Do If You Think There Is A Performance Issue
+B.4.4 What To Do If You Think There Is A Performance Issue
----------------------------------------------------------
If you think that 'gawk' is too slow at doing a particular task, you
@@ -31526,10 +31608,10 @@ to follow:
Unpack the source code in a new directory, and configure it:
$ tar -xpzvf gawk-X.Y.Z.tar.gz
- -| ... Output ommited
+ -| ... Output omitted
$ cd gawk-X.Y.Z
$ ./configure
- -| ... Output ommited
+ -| ... Output omitted
3. Edit the files 'Makefile' and 'support/Makefile'. Change every
instance of '-O2' or '-O' to '-pg'. This causes 'gawk' to be
@@ -31538,7 +31620,7 @@ to follow:
4. Compile the program by running the 'make' command:
$ make
- -| ... Output ommited
+ -| ... Output omitted
5. Run the freshly compiled 'gawk' on a _real_ program, using _real_
data. Using an artificial program to try to time one particular
@@ -31551,6 +31633,8 @@ to follow:
to measure where 'gawk' spends its time. It should be at least 100
megabytes in size.
+ $ ./gawk -f realprogram.awk realdata > /dev/null
+
6. When done, you should have a file in the current directory named
'gmon.out'. Run the command 'gprof gawk gmon.out > gprof.out'.
@@ -31568,9 +31652,61 @@ to follow:
you will just have to live with 'gawk' as it is.
-File: gawk.info, Node: Maintainers, Prev: Performance bugs, Up: Bugs
+File: gawk.info, Node: Asking for help, Next: Maintainers, Prev:
Performance bugs, Up: Bugs
+
+B.4.5 Where To Send Non-bug Questions
+-------------------------------------
+
+If you have questions related to 'awk' programming, or why 'gawk'
+behaves a certain way, or any other 'awk'- or 'gawk'-related issue,
+please _do not_ send it to the bug reporting address.
+
+ As of July, 2021, there is a separate mailing list for this purpose:
+<help-gawk@gnu.org>. Anything that is not a bug report should be sent
+to that list.
+
+ NOTE: If you disregard these directions and send non-bug mails to
+ the bug list, you will be told to use the help list. After two
+ such requests you will be silently _blacklisted_ from the bug list.
+
+ Please note: As with the bug list, we ask that you follow the GNU
+Kind Communication Guidelines
+(https://gnu.org/philosophy/kind-communication.html) in your
+correspondence on the list (as well as off of it).
+
+ If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy of Bob
+Proulx:
+
+_Subscribe by email_
+
+ Send an email message to <help-gawk-request@gnu.org> with
+ "subscribe" in the body of the message. The subject does not
+ matter and is not used.
+
+_Subscribe by web form_
+
+ To use the web interface visit the list information page
+ (https://lists.gnu.org/mailman/listinfo/help-gawk). Use the
+ subscribe form to fill out your email address and submit using the
+ 'Subscribe' button.
+
+_Reply to the confirmation message_
+
+ In both cases then reply to the confirmation message that is sent
+ to your address in reply.
+
+ Bob mentions that you may also use email for subscribing and
+unsubscribing. For example:
+
+ $ echo help | mailx -s request help-gawk-request@gnu.org
+ $ echo subscribe | mailx -s request help-gawk-request@gnu.org
+ $ echo unsubscribe | mailx -s request help-gawk-request@gnu.org
+
+
+File: gawk.info, Node: Maintainers, Prev: Asking for help, Up: Bugs
-B.4.4 Reporting Problems with Non-Unix Ports
+B.4.6 Reporting Problems with Non-Unix Ports
--------------------------------------------
If you find bugs in one of the non-Unix ports of 'gawk', send an email
@@ -31666,8 +31802,8 @@ Unix 'awk'
provide the core 'awk' functionality. It also has a number of
extensions.
- The 'awk' translator is released under the GPL, and the library is
- under the LGPL.
+ Both the 'awk' translator and the library are released under the
+ GPL.
To get 'awka', go to <https://sourceforge.net/projects/awka>.
@@ -31808,6 +31944,10 @@ B.6 Summary
'gawk', how it was compiled, and a short program and data file that
demonstrate the problem.
+ * Non-bug emails should be sent to <help-gawk@gnu.org>. Repeatedly
+ sending non-bug emails to the bug list will get you blacklisted
+ from it.
+
* There are a number of other freely available 'awk' implementations.
Many are POSIX-compliant; others are less so.
@@ -35495,8 +35635,8 @@ Index
(line 51)
* buffers, flushing: I/O Functions. (line 32)
* buffers, flushing <1>: I/O Functions. (line 168)
-* bug reports, email address, bug-gawk@gnu.org: Bug address. (line 31)
-* bug-gawk@gnu.org bug reporting address: Bug address. (line 31)
+* bug reports, email address, bug-gawk@gnu.org: Bug address. (line 56)
+* bug-gawk@gnu.org bug reporting address: Bug address. (line 56)
* built-in functions: Functions. (line 6)
* built-in functions, evaluation order: Calling Built-in. (line 30)
* BusyBox Awk: Other Versions. (line 92)
@@ -36084,7 +36224,7 @@ Index
(line 48)
* elements in arrays, deleting: Delete. (line 6)
* email address for bug reports, bug-gawk@gnu.org: Bug address.
- (line 31)
+ (line 56)
* empty array elements: Reference to Elements.
(line 18)
* empty pattern: Empty. (line 6)
@@ -38234,606 +38374,608 @@ Index
Tag Table:
Node: Top1200
-Node: Foreword345061
-Node: Foreword449503
-Node: Preface51035
-Ref: Preface-Footnote-153894
-Ref: Preface-Footnote-254003
-Ref: Preface-Footnote-354237
-Node: History54379
-Node: Names56731
-Ref: Names-Footnote-157835
-Node: This Manual57982
-Ref: This Manual-Footnote-164621
-Node: Conventions64721
-Node: Manual History67090
-Ref: Manual History-Footnote-170087
-Ref: Manual History-Footnote-270128
-Node: How To Contribute70202
-Node: Acknowledgments71128
-Node: Getting Started76065
-Node: Running gawk78504
-Node: One-shot79694
-Node: Read Terminal80957
-Node: Long82950
-Node: Executable Scripts84463
-Ref: Executable Scripts-Footnote-187096
-Node: Comments87199
-Node: Quoting89683
-Node: DOS Quoting95209
-Node: Sample Data Files97265
-Node: Very Simple99860
-Node: Two Rules105962
-Node: More Complex107847
-Node: Statements/Lines110179
-Ref: Statements/Lines-Footnote-1114663
-Node: Other Features114928
-Node: When115864
-Ref: When-Footnote-1117618
-Node: Intro Summary117683
-Node: Invoking Gawk118567
-Node: Command Line120081
-Node: Options120879
-Ref: Options-Footnote-1138793
-Ref: Options-Footnote-2139024
-Node: Other Arguments139049
-Node: Naming Standard Input143060
-Node: Environment Variables144270
-Node: AWKPATH Variable144828
-Ref: AWKPATH Variable-Footnote-1148240
-Ref: AWKPATH Variable-Footnote-2148274
-Node: AWKLIBPATH Variable148645
-Ref: AWKLIBPATH Variable-Footnote-1150342
-Node: Other Environment Variables150717
-Node: Exit Status154538
-Node: Include Files155215
-Node: Loading Shared Libraries158905
-Node: Obsolete160333
-Node: Undocumented161025
-Node: Invoking Summary161322
-Node: Regexp164163
-Node: Regexp Usage165617
-Node: Escape Sequences167654
-Node: Regexp Operators173895
-Node: Regexp Operator Details174380
-Ref: Regexp Operator Details-Footnote-1181744
-Node: Interval Expressions181891
-Ref: Interval Expressions-Footnote-1183312
-Node: Bracket Expressions183410
-Ref: table-char-classes185886
-Node: Leftmost Longest189212
-Node: Computed Regexps190515
-Node: GNU Regexp Operators193942
-Node: Case-sensitivity197679
-Ref: Case-sensitivity-Footnote-1200545
-Ref: Case-sensitivity-Footnote-2200780
-Node: Regexp Summary200888
-Node: Reading Files202354
-Node: Records204623
-Node: awk split records205698
-Node: gawk split records210398
-Ref: gawk split records-Footnote-1215472
-Node: Fields215509
-Node: Nonconstant Fields218250
-Ref: Nonconstant Fields-Footnote-1220486
-Node: Changing Fields220690
-Node: Field Separators226721
-Node: Default Field Splitting229419
-Node: Regexp Field Splitting230537
-Node: Single Character Fields234214
-Node: Command Line Field Separator235274
-Node: Full Line Fields238492
-Ref: Full Line Fields-Footnote-1240014
-Ref: Full Line Fields-Footnote-2240060
-Node: Field Splitting Summary240161
-Node: Constant Size242235
-Node: Fixed width data242967
-Node: Skipping intervening246434
-Node: Allowing trailing data247232
-Node: Fields with fixed data248269
-Node: Splitting By Content249787
-Ref: Splitting By Content-Footnote-1253570
-Node: More CSV253733
-Node: Testing field creation255325
-Node: Multiple Line256950
-Node: Getline263227
-Node: Plain Getline265696
-Node: Getline/Variable268269
-Node: Getline/File269420
-Node: Getline/Variable/File270808
-Ref: Getline/Variable/File-Footnote-1272413
-Node: Getline/Pipe272501
-Node: Getline/Variable/Pipe275205
-Node: Getline/Coprocess276340
-Node: Getline/Variable/Coprocess277607
-Node: Getline Notes278349
-Node: Getline Summary281146
-Ref: table-getline-variants281570
-Node: Read Timeout282318
-Ref: Read Timeout-Footnote-1286224
-Node: Retrying Input286282
-Node: Command-line directories287481
-Node: Input Summary288387
-Node: Input Exercises291559
-Node: Printing291993
-Node: Print293827
-Node: Print Examples295284
-Node: Output Separators298064
-Node: OFMT300081
-Node: Printf301437
-Node: Basic Printf302222
-Node: Control Letters303796
-Node: Format Modifiers308960
-Node: Printf Examples314975
-Node: Redirection317461
-Node: Special FD324302
-Ref: Special FD-Footnote-1327470
-Node: Special Files327544
-Node: Other Inherited Files328161
-Node: Special Network329162
-Node: Special Caveats330022
-Node: Close Files And Pipes330971
-Ref: table-close-pipe-return-values337878
-Ref: Close Files And Pipes-Footnote-1338691
-Ref: Close Files And Pipes-Footnote-2338839
-Node: Nonfatal338991
-Node: Output Summary341329
-Node: Output Exercises342551
-Node: Expressions343230
-Node: Values344418
-Node: Constants345096
-Node: Scalar Constants345787
-Ref: Scalar Constants-Footnote-1348297
-Node: Nondecimal-numbers348547
-Node: Regexp Constants351548
-Node: Using Constant Regexps352074
-Node: Standard Regexp Constants352696
-Node: Strong Regexp Constants355884
-Node: Variables358896
-Node: Using Variables359553
-Node: Assignment Options361463
-Node: Conversion363934
-Node: Strings And Numbers364458
-Ref: Strings And Numbers-Footnote-1367521
-Node: Locale influences conversions367630
-Ref: table-locale-affects370388
-Node: All Operators371006
-Node: Arithmetic Ops371635
-Node: Concatenation374351
-Ref: Concatenation-Footnote-1377198
-Node: Assignment Ops377305
-Ref: table-assign-ops382296
-Node: Increment Ops383609
-Node: Truth Values and Conditions387069
-Node: Truth Values388143
-Node: Typing and Comparison389191
-Node: Variable Typing390011
-Ref: Variable Typing-Footnote-1396474
-Ref: Variable Typing-Footnote-2396546
-Node: Comparison Operators396623
-Ref: table-relational-ops397042
-Node: POSIX String Comparison400537
-Ref: POSIX String Comparison-Footnote-1402232
-Ref: POSIX String Comparison-Footnote-2402371
-Node: Boolean Ops402455
-Ref: Boolean Ops-Footnote-1406937
-Node: Conditional Exp407029
-Node: Function Calls408765
-Node: Precedence412642
-Node: Locales416301
-Node: Expressions Summary417933
-Node: Patterns and Actions420506
-Node: Pattern Overview421626
-Node: Regexp Patterns423303
-Node: Expression Patterns423845
-Node: Ranges427626
-Node: BEGIN/END430734
-Node: Using BEGIN/END431495
-Ref: Using BEGIN/END-Footnote-1434249
-Node: I/O And BEGIN/END434355
-Node: BEGINFILE/ENDFILE436668
-Node: Empty439899
-Node: Using Shell Variables440216
-Node: Action Overview442490
-Node: Statements444815
-Node: If Statement446663
-Node: While Statement448158
-Node: Do Statement450186
-Node: For Statement451334
-Node: Switch Statement454505
-Node: Break Statement456946
-Node: Continue Statement459038
-Node: Next Statement460865
-Node: Nextfile Statement463248
-Node: Exit Statement465937
-Node: Built-in Variables468340
-Node: User-modified469473
-Node: Auto-set477240
-Ref: Auto-set-Footnote-1494047
-Ref: Auto-set-Footnote-2494253
-Node: ARGC and ARGV494309
-Node: Pattern Action Summary498522
-Node: Arrays500952
-Node: Array Basics502281
-Node: Array Intro503125
-Ref: figure-array-elements505100
-Ref: Array Intro-Footnote-1507804
-Node: Reference to Elements507932
-Node: Assigning Elements510396
-Node: Array Example510887
-Node: Scanning an Array512646
-Node: Controlling Scanning515668
-Ref: Controlling Scanning-Footnote-1522124
-Node: Numeric Array Subscripts522440
-Node: Uninitialized Subscripts524624
-Node: Delete526243
-Ref: Delete-Footnote-1528995
-Node: Multidimensional529052
-Node: Multiscanning532147
-Node: Arrays of Arrays533738
-Node: Arrays Summary538506
-Node: Functions540599
-Node: Built-in541637
-Node: Calling Built-in542718
-Node: Numeric Functions544714
-Ref: Numeric Functions-Footnote-1548742
-Ref: Numeric Functions-Footnote-2549390
-Ref: Numeric Functions-Footnote-3549438
-Node: String Functions549710
-Ref: String Functions-Footnote-1573851
-Ref: String Functions-Footnote-2573979
-Ref: String Functions-Footnote-3574227
-Node: Gory Details574314
-Ref: table-sub-escapes576105
-Ref: table-sub-proposed577624
-Ref: table-posix-sub578987
-Ref: table-gensub-escapes580528
-Ref: Gory Details-Footnote-1581351
-Node: I/O Functions581505
-Ref: table-system-return-values587959
-Ref: I/O Functions-Footnote-1590039
-Ref: I/O Functions-Footnote-2590187
-Node: Time Functions590307
-Ref: Time Functions-Footnote-1600978
-Ref: Time Functions-Footnote-2601046
-Ref: Time Functions-Footnote-3601204
-Ref: Time Functions-Footnote-4601315
-Ref: Time Functions-Footnote-5601427
-Ref: Time Functions-Footnote-6601654
-Node: Bitwise Functions601920
-Ref: table-bitwise-ops602514
-Ref: Bitwise Functions-Footnote-1608577
-Ref: Bitwise Functions-Footnote-2608750
-Node: Type Functions608941
-Node: I18N Functions611804
-Node: User-defined613455
-Node: Definition Syntax614267
-Ref: Definition Syntax-Footnote-1619961
-Node: Function Example620032
-Ref: Function Example-Footnote-1622954
-Node: Function Calling622976
-Node: Calling A Function623564
-Node: Variable Scope624522
-Node: Pass By Value/Reference627516
-Node: Function Caveats630160
-Ref: Function Caveats-Footnote-1632207
-Node: Return Statement632327
-Node: Dynamic Typing635306
-Node: Indirect Calls636236
-Ref: Indirect Calls-Footnote-1646488
-Node: Functions Summary646616
-Node: Library Functions649321
-Ref: Library Functions-Footnote-1652928
-Ref: Library Functions-Footnote-2653071
-Node: Library Names653242
-Ref: Library Names-Footnote-1656909
-Ref: Library Names-Footnote-2657132
-Node: General Functions657218
-Node: Strtonum Function658400
-Node: Assert Function661422
-Node: Round Function664748
-Node: Cliff Random Function666288
-Node: Ordinal Functions667304
-Ref: Ordinal Functions-Footnote-1670367
-Ref: Ordinal Functions-Footnote-2670619
-Node: Join Function670829
-Ref: Join Function-Footnote-1672599
-Node: Getlocaltime Function672799
-Node: Readfile Function676541
-Node: Shell Quoting678518
-Node: Isnumeric Function679946
-Node: Data File Management681283
-Node: Filetrans Function681915
-Node: Rewind Function686011
-Node: File Checking687920
-Ref: File Checking-Footnote-1689254
-Node: Empty Files689455
-Node: Ignoring Assigns691434
-Node: Getopt Function692984
-Ref: Getopt Function-Footnote-1708207
-Node: Passwd Functions708407
-Ref: Passwd Functions-Footnote-1717246
-Node: Group Functions717334
-Ref: Group Functions-Footnote-1725232
-Node: Walking Arrays725439
-Node: Library Functions Summary728447
-Node: Library Exercises729853
-Node: Sample Programs730318
-Node: Running Examples731088
-Node: Clones731816
-Node: Cut Program733040
-Node: Egrep Program743180
-Node: Id Program752181
-Node: Split Program762128
-Ref: Split Program-Footnote-1772021
-Node: Tee Program772194
-Node: Uniq Program774984
-Node: Wc Program782572
-Node: Bytes vs. Characters782959
-Node: Using extensions784507
-Node: wc program785261
-Node: Miscellaneous Programs790126
-Node: Dupword Program791339
-Node: Alarm Program793369
-Node: Translate Program798224
-Ref: Translate Program-Footnote-1802789
-Node: Labels Program803059
-Ref: Labels Program-Footnote-1806410
-Node: Word Sorting806494
-Node: History Sorting810566
-Node: Extract Program812791
-Node: Simple Sed820845
-Node: Igawk Program823919
-Ref: Igawk Program-Footnote-1838250
-Ref: Igawk Program-Footnote-2838452
-Ref: Igawk Program-Footnote-3838574
-Node: Anagram Program838689
-Node: Signature Program841751
-Node: Programs Summary842998
-Node: Programs Exercises844212
-Ref: Programs Exercises-Footnote-1848342
-Node: Advanced Features848428
-Node: Nondecimal Data850495
-Node: Array Sorting852086
-Node: Controlling Array Traversal852786
-Ref: Controlling Array Traversal-Footnote-1861154
-Node: Array Sorting Functions861272
-Ref: Array Sorting Functions-Footnote-1866363
-Node: Two-way I/O866559
-Ref: Two-way I/O-Footnote-1874285
-Ref: Two-way I/O-Footnote-2874472
-Node: TCP/IP Networking874554
-Node: Profiling877672
-Node: Extension Philosophy886981
-Node: Advanced Features Summary888460
-Node: Internationalization890475
-Node: I18N and L10N892149
-Node: Explaining gettext892836
-Ref: Explaining gettext-Footnote-1898728
-Ref: Explaining gettext-Footnote-2898913
-Node: Programmer i18n899078
-Ref: Programmer i18n-Footnote-1904027
-Node: Translator i18n904076
-Node: String Extraction904870
-Ref: String Extraction-Footnote-1906002
-Node: Printf Ordering906088
-Ref: Printf Ordering-Footnote-1908874
-Node: I18N Portability908938
-Ref: I18N Portability-Footnote-1911394
-Node: I18N Example911457
-Ref: I18N Example-Footnote-1914732
-Ref: I18N Example-Footnote-2914805
-Node: Gawk I18N914914
-Node: I18N Summary915563
-Node: Debugger916904
-Node: Debugging917904
-Node: Debugging Concepts918345
-Node: Debugging Terms920154
-Node: Awk Debugging922729
-Ref: Awk Debugging-Footnote-1923674
-Node: Sample Debugging Session923806
-Node: Debugger Invocation924340
-Node: Finding The Bug925726
-Node: List of Debugger Commands932200
-Node: Breakpoint Control933533
-Node: Debugger Execution Control937227
-Node: Viewing And Changing Data940589
-Node: Execution Stack944130
-Node: Debugger Info945767
-Node: Miscellaneous Debugger Commands949838
-Node: Readline Support954900
-Node: Limitations955796
-Node: Debugging Summary958350
-Node: Namespaces959629
-Node: Global Namespace960740
-Node: Qualified Names962138
-Node: Default Namespace963137
-Node: Changing The Namespace963878
-Node: Naming Rules965492
-Node: Internal Name Management967340
-Node: Namespace Example968382
-Node: Namespace And Features970944
-Node: Namespace Summary972379
-Node: Arbitrary Precision Arithmetic973856
-Node: Computer Arithmetic975343
-Ref: table-numeric-ranges979109
-Ref: table-floating-point-ranges979602
-Ref: Computer Arithmetic-Footnote-1980260
-Node: Math Definitions980317
-Ref: table-ieee-formats983633
-Ref: Math Definitions-Footnote-1984236
-Node: MPFR features984341
-Node: FP Math Caution986059
-Ref: FP Math Caution-Footnote-1987131
-Node: Inexactness of computations987500
-Node: Inexact representation988460
-Node: Comparing FP Values989820
-Node: Errors accumulate991061
-Node: Getting Accuracy992494
-Node: Try To Round995204
-Node: Setting precision996103
-Ref: table-predefined-precision-strings996800
-Node: Setting the rounding mode998630
-Ref: table-gawk-rounding-modes999004
-Ref: Setting the rounding mode-Footnote-11002935
-Node: Arbitrary Precision Integers1003114
-Ref: Arbitrary Precision Integers-Footnote-11006289
-Node: Checking for MPFR1006438
-Node: POSIX Floating Point Problems1007912
-Ref: POSIX Floating Point Problems-Footnote-11012197
-Node: Floating point summary1012235
-Node: Dynamic Extensions1014425
-Node: Extension Intro1015978
-Node: Plugin License1017244
-Node: Extension Mechanism Outline1018041
-Ref: figure-load-extension1018480
-Ref: figure-register-new-function1020045
-Ref: figure-call-new-function1021137
-Node: Extension API Description1023199
-Node: Extension API Functions Introduction1024912
-Ref: table-api-std-headers1026748
-Node: General Data Types1030997
-Ref: General Data Types-Footnote-11039627
-Node: Memory Allocation Functions1039926
-Ref: Memory Allocation Functions-Footnote-11044427
-Node: Constructor Functions1044526
-Node: API Ownership of MPFR and GMP Values1047992
-Node: Registration Functions1049305
-Node: Extension Functions1050005
-Node: Exit Callback Functions1055327
-Node: Extension Version String1056577
-Node: Input Parsers1057240
-Node: Output Wrappers1069961
-Node: Two-way processors1074473
-Node: Printing Messages1076738
-Ref: Printing Messages-Footnote-11077909
-Node: Updating ERRNO1078062
-Node: Requesting Values1078801
-Ref: table-value-types-returned1079538
-Node: Accessing Parameters1080474
-Node: Symbol Table Access1081711
-Node: Symbol table by name1082223
-Ref: Symbol table by name-Footnote-11085247
-Node: Symbol table by cookie1085375
-Ref: Symbol table by cookie-Footnote-11089560
-Node: Cached values1089624
-Ref: Cached values-Footnote-11093160
-Node: Array Manipulation1093313
-Ref: Array Manipulation-Footnote-11094404
-Node: Array Data Types1094441
-Ref: Array Data Types-Footnote-11097099
-Node: Array Functions1097191
-Node: Flattening Arrays1101689
-Node: Creating Arrays1108665
-Node: Redirection API1113432
-Node: Extension API Variables1116265
-Node: Extension Versioning1116976
-Ref: gawk-api-version1117405
-Node: Extension GMP/MPFR Versioning1119136
-Node: Extension API Informational Variables1120764
-Node: Extension API Boilerplate1121837
-Node: Changes from API V11125811
-Node: Finding Extensions1127383
-Node: Extension Example1127942
-Node: Internal File Description1128740
-Node: Internal File Ops1132820
-Ref: Internal File Ops-Footnote-11144170
-Node: Using Internal File Ops1144310
-Ref: Using Internal File Ops-Footnote-11146693
-Node: Extension Samples1146967
-Node: Extension Sample File Functions1148496
-Node: Extension Sample Fnmatch1156145
-Node: Extension Sample Fork1157632
-Node: Extension Sample Inplace1158850
-Node: Extension Sample Ord1162476
-Node: Extension Sample Readdir1163312
-Ref: table-readdir-file-types1164201
-Node: Extension Sample Revout1165268
-Node: Extension Sample Rev2way1165857
-Node: Extension Sample Read write array1166597
-Node: Extension Sample Readfile1168539
-Node: Extension Sample Time1169634
-Node: Extension Sample API Tests1171386
-Node: gawkextlib1171878
-Node: Extension summary1174796
-Node: Extension Exercises1178498
-Node: Language History1179740
-Node: V7/SVR3.11181396
-Node: SVR41183548
-Node: POSIX1184982
-Node: BTL1186363
-Node: POSIX/GNU1187092
-Node: Feature History1192870
-Node: Common Extensions1210045
-Node: Ranges and Locales1211328
-Ref: Ranges and Locales-Footnote-11215944
-Ref: Ranges and Locales-Footnote-21215971
-Ref: Ranges and Locales-Footnote-31216206
-Node: Contributors1216429
-Node: History summary1222426
-Node: Installation1223806
-Node: Gawk Distribution1224750
-Node: Getting1225234
-Node: Extracting1226197
-Node: Distribution contents1227835
-Node: Unix Installation1234315
-Node: Quick Installation1234997
-Node: Compiling with MPFR1237478
-Node: Shell Startup Files1238170
-Node: Additional Configuration Options1239259
-Node: Configuration Philosophy1241574
-Node: Non-Unix Installation1243943
-Node: PC Installation1244403
-Node: PC Binary Installation1245241
-Node: PC Compiling1245676
-Node: PC Using1246793
-Node: Cygwin1250346
-Node: MSYS1251570
-Node: VMS Installation1252172
-Node: VMS Compilation1252963
-Ref: VMS Compilation-Footnote-11254192
-Node: VMS Dynamic Extensions1254250
-Node: VMS Installation Details1255935
-Node: VMS Running1258188
-Node: VMS GNV1262467
-Node: VMS Old Gawk1263202
-Node: Bugs1263673
-Node: Bug address1264422
-Node: Usenet1267404
-Node: Performance bugs1268413
-Node: Maintainers1271270
-Node: Other Versions1272465
-Node: Installation summary1280330
-Node: Notes1281539
-Node: Compatibility Mode1282333
-Node: Additions1283115
-Node: Accessing The Source1284040
-Node: Adding Code1285477
-Node: New Ports1291696
-Node: Derived Files1296071
-Ref: Derived Files-Footnote-11301731
-Ref: Derived Files-Footnote-21301766
-Ref: Derived Files-Footnote-31302364
-Node: Future Extensions1302478
-Node: Implementation Limitations1303136
-Node: Extension Design1304346
-Node: Old Extension Problems1305490
-Ref: Old Extension Problems-Footnote-11307008
-Node: Extension New Mechanism Goals1307065
-Ref: Extension New Mechanism Goals-Footnote-11310429
-Node: Extension Other Design Decisions1310618
-Node: Extension Future Growth1312731
-Node: Notes summary1313337
-Node: Basic Concepts1314495
-Node: Basic High Level1315176
-Ref: figure-general-flow1315458
-Ref: figure-process-flow1316143
-Ref: Basic High Level-Footnote-11319444
-Node: Basic Data Typing1319629
-Node: Glossary1322957
-Node: Copying1354842
-Node: GNU Free Documentation License1392385
-Node: Index1417505
+Node: Foreword345208
+Node: Foreword449650
+Node: Preface51182
+Ref: Preface-Footnote-154041
+Ref: Preface-Footnote-254150
+Ref: Preface-Footnote-354384
+Node: History54526
+Node: Names56878
+Ref: Names-Footnote-157982
+Node: This Manual58129
+Ref: This Manual-Footnote-164768
+Node: Conventions64868
+Node: Manual History67237
+Ref: Manual History-Footnote-170234
+Ref: Manual History-Footnote-270275
+Node: How To Contribute70349
+Node: Acknowledgments71275
+Node: Getting Started76212
+Node: Running gawk78651
+Node: One-shot79841
+Node: Read Terminal81104
+Node: Long83097
+Node: Executable Scripts84610
+Ref: Executable Scripts-Footnote-187243
+Node: Comments87346
+Node: Quoting89830
+Node: DOS Quoting95356
+Node: Sample Data Files97412
+Node: Very Simple100007
+Node: Two Rules106109
+Node: More Complex107994
+Node: Statements/Lines110326
+Ref: Statements/Lines-Footnote-1114810
+Node: Other Features115075
+Node: When116011
+Ref: When-Footnote-1117765
+Node: Intro Summary117830
+Node: Invoking Gawk118714
+Node: Command Line120228
+Node: Options121026
+Ref: Options-Footnote-1138940
+Ref: Options-Footnote-2139171
+Node: Other Arguments139196
+Node: Naming Standard Input143207
+Node: Environment Variables144417
+Node: AWKPATH Variable144975
+Ref: AWKPATH Variable-Footnote-1148387
+Ref: AWKPATH Variable-Footnote-2148421
+Node: AWKLIBPATH Variable148792
+Ref: AWKLIBPATH Variable-Footnote-1150489
+Node: Other Environment Variables150864
+Node: Exit Status154685
+Node: Include Files155362
+Node: Loading Shared Libraries159052
+Node: Obsolete160480
+Node: Undocumented161172
+Node: Invoking Summary161469
+Node: Regexp164310
+Node: Regexp Usage165764
+Node: Escape Sequences167801
+Node: Regexp Operators174042
+Node: Regexp Operator Details174527
+Ref: Regexp Operator Details-Footnote-1181891
+Node: Interval Expressions182038
+Ref: Interval Expressions-Footnote-1183459
+Node: Bracket Expressions183557
+Ref: table-char-classes186033
+Node: Leftmost Longest189359
+Node: Computed Regexps190662
+Node: GNU Regexp Operators194089
+Node: Case-sensitivity197826
+Ref: Case-sensitivity-Footnote-1200692
+Ref: Case-sensitivity-Footnote-2200927
+Node: Regexp Summary201035
+Node: Reading Files202501
+Node: Records204770
+Node: awk split records205845
+Node: gawk split records210545
+Ref: gawk split records-Footnote-1215619
+Node: Fields215656
+Node: Nonconstant Fields218397
+Ref: Nonconstant Fields-Footnote-1220633
+Node: Changing Fields220837
+Node: Field Separators226868
+Node: Default Field Splitting229566
+Node: Regexp Field Splitting230684
+Node: Single Character Fields234361
+Node: Command Line Field Separator235421
+Node: Full Line Fields238639
+Ref: Full Line Fields-Footnote-1240161
+Ref: Full Line Fields-Footnote-2240207
+Node: Field Splitting Summary240308
+Node: Constant Size242382
+Node: Fixed width data243114
+Node: Skipping intervening246581
+Node: Allowing trailing data247379
+Node: Fields with fixed data248416
+Node: Splitting By Content249934
+Ref: Splitting By Content-Footnote-1253717
+Node: More CSV253880
+Node: Testing field creation255472
+Node: Multiple Line257097
+Node: Getline263374
+Node: Plain Getline265843
+Node: Getline/Variable268416
+Node: Getline/File269567
+Node: Getline/Variable/File270955
+Ref: Getline/Variable/File-Footnote-1272560
+Node: Getline/Pipe272648
+Node: Getline/Variable/Pipe275352
+Node: Getline/Coprocess276487
+Node: Getline/Variable/Coprocess277754
+Node: Getline Notes278496
+Node: Getline Summary281293
+Ref: table-getline-variants281717
+Node: Read Timeout282465
+Ref: Read Timeout-Footnote-1286371
+Node: Retrying Input286429
+Node: Command-line directories287628
+Node: Input Summary288534
+Node: Input Exercises291706
+Node: Printing292140
+Node: Print293974
+Node: Print Examples295431
+Node: Output Separators298211
+Node: OFMT300228
+Node: Printf301584
+Node: Basic Printf302369
+Node: Control Letters303943
+Node: Format Modifiers309107
+Node: Printf Examples315122
+Node: Redirection317608
+Node: Special FD324449
+Ref: Special FD-Footnote-1327617
+Node: Special Files327691
+Node: Other Inherited Files328308
+Node: Special Network329309
+Node: Special Caveats330169
+Node: Close Files And Pipes331118
+Ref: table-close-pipe-return-values338025
+Ref: Close Files And Pipes-Footnote-1338838
+Ref: Close Files And Pipes-Footnote-2338986
+Node: Nonfatal339138
+Node: Output Summary341476
+Node: Output Exercises342698
+Node: Expressions343377
+Node: Values344565
+Node: Constants345243
+Node: Scalar Constants345934
+Ref: Scalar Constants-Footnote-1348444
+Node: Nondecimal-numbers348694
+Node: Regexp Constants351695
+Node: Using Constant Regexps352221
+Node: Standard Regexp Constants352843
+Node: Strong Regexp Constants356031
+Node: Variables359043
+Node: Using Variables359700
+Node: Assignment Options361610
+Node: Conversion364081
+Node: Strings And Numbers364605
+Ref: Strings And Numbers-Footnote-1367668
+Node: Locale influences conversions367777
+Ref: table-locale-affects370535
+Node: All Operators371153
+Node: Arithmetic Ops371782
+Node: Concatenation374498
+Ref: Concatenation-Footnote-1377345
+Node: Assignment Ops377452
+Ref: table-assign-ops382443
+Node: Increment Ops383756
+Node: Truth Values and Conditions387216
+Node: Truth Values388290
+Node: Typing and Comparison389338
+Node: Variable Typing390158
+Ref: Variable Typing-Footnote-1396621
+Ref: Variable Typing-Footnote-2396693
+Node: Comparison Operators396770
+Ref: table-relational-ops397189
+Node: POSIX String Comparison400684
+Ref: POSIX String Comparison-Footnote-1402379
+Ref: POSIX String Comparison-Footnote-2402518
+Node: Boolean Ops402602
+Ref: Boolean Ops-Footnote-1407084
+Node: Conditional Exp407176
+Node: Function Calls408912
+Node: Precedence412789
+Node: Locales416448
+Node: Expressions Summary418080
+Node: Patterns and Actions420653
+Node: Pattern Overview421773
+Node: Regexp Patterns423450
+Node: Expression Patterns423992
+Node: Ranges427773
+Node: BEGIN/END430881
+Node: Using BEGIN/END431642
+Ref: Using BEGIN/END-Footnote-1434396
+Node: I/O And BEGIN/END434502
+Node: BEGINFILE/ENDFILE436815
+Node: Empty440046
+Node: Using Shell Variables440363
+Node: Action Overview442637
+Node: Statements444962
+Node: If Statement446810
+Node: While Statement448305
+Node: Do Statement450333
+Node: For Statement451481
+Node: Switch Statement454652
+Node: Break Statement457093
+Node: Continue Statement459185
+Node: Next Statement461012
+Node: Nextfile Statement463395
+Node: Exit Statement466084
+Node: Built-in Variables468487
+Node: User-modified469620
+Node: Auto-set477387
+Ref: Auto-set-Footnote-1494194
+Ref: Auto-set-Footnote-2494400
+Node: ARGC and ARGV494456
+Node: Pattern Action Summary498669
+Node: Arrays501099
+Node: Array Basics502428
+Node: Array Intro503272
+Ref: figure-array-elements505247
+Ref: Array Intro-Footnote-1507951
+Node: Reference to Elements508079
+Node: Assigning Elements510543
+Node: Array Example511034
+Node: Scanning an Array512793
+Node: Controlling Scanning515815
+Ref: Controlling Scanning-Footnote-1522271
+Node: Numeric Array Subscripts522587
+Node: Uninitialized Subscripts524771
+Node: Delete526390
+Ref: Delete-Footnote-1529142
+Node: Multidimensional529199
+Node: Multiscanning532294
+Node: Arrays of Arrays533885
+Node: Arrays Summary538653
+Node: Functions540746
+Node: Built-in541784
+Node: Calling Built-in542865
+Node: Numeric Functions544861
+Ref: Numeric Functions-Footnote-1548889
+Ref: Numeric Functions-Footnote-2549537
+Ref: Numeric Functions-Footnote-3549585
+Node: String Functions549857
+Ref: String Functions-Footnote-1573998
+Ref: String Functions-Footnote-2574126
+Ref: String Functions-Footnote-3574374
+Node: Gory Details574461
+Ref: table-sub-escapes576252
+Ref: table-sub-proposed577771
+Ref: table-posix-sub579134
+Ref: table-gensub-escapes580675
+Ref: Gory Details-Footnote-1581498
+Node: I/O Functions581652
+Ref: table-system-return-values588106
+Ref: I/O Functions-Footnote-1590186
+Ref: I/O Functions-Footnote-2590334
+Node: Time Functions590454
+Ref: Time Functions-Footnote-1601125
+Ref: Time Functions-Footnote-2601193
+Ref: Time Functions-Footnote-3601351
+Ref: Time Functions-Footnote-4601462
+Ref: Time Functions-Footnote-5601574
+Ref: Time Functions-Footnote-6601801
+Node: Bitwise Functions602067
+Ref: table-bitwise-ops602661
+Ref: Bitwise Functions-Footnote-1608724
+Ref: Bitwise Functions-Footnote-2608897
+Node: Type Functions609088
+Node: I18N Functions611951
+Node: User-defined613602
+Node: Definition Syntax614414
+Ref: Definition Syntax-Footnote-1620108
+Node: Function Example620179
+Ref: Function Example-Footnote-1623101
+Node: Function Calling623123
+Node: Calling A Function623711
+Node: Variable Scope624669
+Node: Pass By Value/Reference627663
+Node: Function Caveats630307
+Ref: Function Caveats-Footnote-1632354
+Node: Return Statement632474
+Node: Dynamic Typing635453
+Node: Indirect Calls636383
+Ref: Indirect Calls-Footnote-1646635
+Node: Functions Summary646763
+Node: Library Functions649468
+Ref: Library Functions-Footnote-1653075
+Ref: Library Functions-Footnote-2653218
+Node: Library Names653389
+Ref: Library Names-Footnote-1657056
+Ref: Library Names-Footnote-2657279
+Node: General Functions657365
+Node: Strtonum Function658547
+Node: Assert Function661569
+Node: Round Function664895
+Node: Cliff Random Function666435
+Node: Ordinal Functions667451
+Ref: Ordinal Functions-Footnote-1670514
+Ref: Ordinal Functions-Footnote-2670766
+Node: Join Function670976
+Ref: Join Function-Footnote-1672746
+Node: Getlocaltime Function672946
+Node: Readfile Function676688
+Node: Shell Quoting678665
+Node: Isnumeric Function680093
+Node: Data File Management681430
+Node: Filetrans Function682062
+Node: Rewind Function686158
+Node: File Checking688067
+Ref: File Checking-Footnote-1689401
+Node: Empty Files689602
+Node: Ignoring Assigns691581
+Node: Getopt Function693131
+Ref: Getopt Function-Footnote-1708354
+Node: Passwd Functions708554
+Ref: Passwd Functions-Footnote-1717393
+Node: Group Functions717481
+Ref: Group Functions-Footnote-1725379
+Node: Walking Arrays725586
+Node: Library Functions Summary728594
+Node: Library Exercises730000
+Node: Sample Programs730465
+Node: Running Examples731235
+Node: Clones731963
+Node: Cut Program733187
+Node: Egrep Program743327
+Node: Id Program752328
+Node: Split Program762275
+Ref: Split Program-Footnote-1772168
+Node: Tee Program772341
+Node: Uniq Program775131
+Node: Wc Program782719
+Node: Bytes vs. Characters783106
+Node: Using extensions784654
+Node: wc program785408
+Node: Miscellaneous Programs790273
+Node: Dupword Program791486
+Node: Alarm Program793516
+Node: Translate Program798371
+Ref: Translate Program-Footnote-1802936
+Node: Labels Program803206
+Ref: Labels Program-Footnote-1806557
+Node: Word Sorting806641
+Node: History Sorting810713
+Node: Extract Program812938
+Node: Simple Sed820992
+Node: Igawk Program824066
+Ref: Igawk Program-Footnote-1838397
+Ref: Igawk Program-Footnote-2838599
+Ref: Igawk Program-Footnote-3838721
+Node: Anagram Program838836
+Node: Signature Program841898
+Node: Programs Summary843145
+Node: Programs Exercises844359
+Ref: Programs Exercises-Footnote-1848489
+Node: Advanced Features848575
+Node: Nondecimal Data850642
+Node: Array Sorting852233
+Node: Controlling Array Traversal852933
+Ref: Controlling Array Traversal-Footnote-1861301
+Node: Array Sorting Functions861419
+Ref: Array Sorting Functions-Footnote-1866510
+Node: Two-way I/O866706
+Ref: Two-way I/O-Footnote-1874432
+Ref: Two-way I/O-Footnote-2874619
+Node: TCP/IP Networking874701
+Node: Profiling877819
+Node: Extension Philosophy887128
+Node: Advanced Features Summary888607
+Node: Internationalization890622
+Node: I18N and L10N892296
+Node: Explaining gettext892983
+Ref: Explaining gettext-Footnote-1898875
+Ref: Explaining gettext-Footnote-2899060
+Node: Programmer i18n899225
+Ref: Programmer i18n-Footnote-1904174
+Node: Translator i18n904223
+Node: String Extraction905017
+Ref: String Extraction-Footnote-1906149
+Node: Printf Ordering906235
+Ref: Printf Ordering-Footnote-1909021
+Node: I18N Portability909085
+Ref: I18N Portability-Footnote-1911541
+Node: I18N Example911604
+Ref: I18N Example-Footnote-1914879
+Ref: I18N Example-Footnote-2914952
+Node: Gawk I18N915061
+Node: I18N Summary915710
+Node: Debugger917051
+Node: Debugging918051
+Node: Debugging Concepts918492
+Node: Debugging Terms920301
+Node: Awk Debugging922876
+Ref: Awk Debugging-Footnote-1923821
+Node: Sample Debugging Session923953
+Node: Debugger Invocation924487
+Node: Finding The Bug925873
+Node: List of Debugger Commands932347
+Node: Breakpoint Control933680
+Node: Debugger Execution Control937374
+Node: Viewing And Changing Data940736
+Node: Execution Stack944277
+Node: Debugger Info945914
+Node: Miscellaneous Debugger Commands949985
+Node: Readline Support955047
+Node: Limitations955943
+Node: Debugging Summary958497
+Node: Namespaces959776
+Node: Global Namespace960887
+Node: Qualified Names962285
+Node: Default Namespace963284
+Node: Changing The Namespace964025
+Node: Naming Rules965639
+Node: Internal Name Management967487
+Node: Namespace Example968529
+Node: Namespace And Features971091
+Node: Namespace Summary972526
+Node: Arbitrary Precision Arithmetic974003
+Node: Computer Arithmetic975490
+Ref: table-numeric-ranges979256
+Ref: table-floating-point-ranges979749
+Ref: Computer Arithmetic-Footnote-1980407
+Node: Math Definitions980464
+Ref: table-ieee-formats983780
+Ref: Math Definitions-Footnote-1984383
+Node: MPFR features984488
+Node: FP Math Caution986206
+Ref: FP Math Caution-Footnote-1987278
+Node: Inexactness of computations987647
+Node: Inexact representation988607
+Node: Comparing FP Values989967
+Node: Errors accumulate991208
+Node: Getting Accuracy992641
+Node: Try To Round995351
+Node: Setting precision996250
+Ref: table-predefined-precision-strings996947
+Node: Setting the rounding mode998777
+Ref: table-gawk-rounding-modes999151
+Ref: Setting the rounding mode-Footnote-11003082
+Node: Arbitrary Precision Integers1003261
+Ref: Arbitrary Precision Integers-Footnote-11006436
+Node: Checking for MPFR1006585
+Node: POSIX Floating Point Problems1008059
+Ref: POSIX Floating Point Problems-Footnote-11012344
+Node: Floating point summary1012382
+Node: Dynamic Extensions1014572
+Node: Extension Intro1016125
+Node: Plugin License1017391
+Node: Extension Mechanism Outline1018188
+Ref: figure-load-extension1018627
+Ref: figure-register-new-function1020192
+Ref: figure-call-new-function1021284
+Node: Extension API Description1023346
+Node: Extension API Functions Introduction1025059
+Ref: table-api-std-headers1026895
+Node: General Data Types1031144
+Ref: General Data Types-Footnote-11039774
+Node: Memory Allocation Functions1040073
+Ref: Memory Allocation Functions-Footnote-11044574
+Node: Constructor Functions1044673
+Node: API Ownership of MPFR and GMP Values1048139
+Node: Registration Functions1049452
+Node: Extension Functions1050152
+Node: Exit Callback Functions1055474
+Node: Extension Version String1056724
+Node: Input Parsers1057387
+Node: Output Wrappers1070108
+Node: Two-way processors1074620
+Node: Printing Messages1076885
+Ref: Printing Messages-Footnote-11078056
+Node: Updating ERRNO1078209
+Node: Requesting Values1078948
+Ref: table-value-types-returned1079685
+Node: Accessing Parameters1080621
+Node: Symbol Table Access1081858
+Node: Symbol table by name1082370
+Ref: Symbol table by name-Footnote-11085394
+Node: Symbol table by cookie1085522
+Ref: Symbol table by cookie-Footnote-11089707
+Node: Cached values1089771
+Ref: Cached values-Footnote-11093307
+Node: Array Manipulation1093460
+Ref: Array Manipulation-Footnote-11094551
+Node: Array Data Types1094588
+Ref: Array Data Types-Footnote-11097246
+Node: Array Functions1097338
+Node: Flattening Arrays1101836
+Node: Creating Arrays1108812
+Node: Redirection API1113579
+Node: Extension API Variables1116412
+Node: Extension Versioning1117123
+Ref: gawk-api-version1117552
+Node: Extension GMP/MPFR Versioning1119283
+Node: Extension API Informational Variables1120911
+Node: Extension API Boilerplate1121984
+Node: Changes from API V11125958
+Node: Finding Extensions1127530
+Node: Extension Example1128089
+Node: Internal File Description1128887
+Node: Internal File Ops1132967
+Ref: Internal File Ops-Footnote-11144317
+Node: Using Internal File Ops1144457
+Ref: Using Internal File Ops-Footnote-11146840
+Node: Extension Samples1147114
+Node: Extension Sample File Functions1148643
+Node: Extension Sample Fnmatch1156292
+Node: Extension Sample Fork1157779
+Node: Extension Sample Inplace1158997
+Node: Extension Sample Ord1162623
+Node: Extension Sample Readdir1163459
+Ref: table-readdir-file-types1164348
+Node: Extension Sample Revout1165415
+Node: Extension Sample Rev2way1166004
+Node: Extension Sample Read write array1166744
+Node: Extension Sample Readfile1168686
+Node: Extension Sample Time1169781
+Node: Extension Sample API Tests1171533
+Node: gawkextlib1172025
+Node: Extension summary1174943
+Node: Extension Exercises1178645
+Node: Language History1179887
+Node: V7/SVR3.11181543
+Node: SVR41183695
+Node: POSIX1185129
+Node: BTL1186510
+Node: POSIX/GNU1187239
+Node: Feature History1193017
+Node: Common Extensions1210192
+Node: Ranges and Locales1211475
+Ref: Ranges and Locales-Footnote-11216091
+Ref: Ranges and Locales-Footnote-21216118
+Ref: Ranges and Locales-Footnote-31216353
+Node: Contributors1216576
+Node: History summary1222573
+Node: Installation1223953
+Node: Gawk Distribution1224897
+Node: Getting1225381
+Node: Extracting1226344
+Node: Distribution contents1227982
+Node: Unix Installation1234462
+Node: Quick Installation1235144
+Node: Compiling with MPFR1237625
+Node: Shell Startup Files1238317
+Node: Additional Configuration Options1239406
+Node: Configuration Philosophy1241721
+Node: Non-Unix Installation1244090
+Node: PC Installation1244550
+Node: PC Binary Installation1245388
+Node: PC Compiling1245823
+Node: PC Using1246940
+Node: Cygwin1250493
+Node: MSYS1251717
+Node: VMS Installation1252319
+Node: VMS Compilation1253110
+Ref: VMS Compilation-Footnote-11254339
+Node: VMS Dynamic Extensions1254397
+Node: VMS Installation Details1256082
+Node: VMS Running1258335
+Node: VMS GNV1262614
+Node: VMS Old Gawk1263349
+Node: Bugs1263820
+Node: Bug definition1264700
+Node: Bug address1267204
+Node: Usenet1270592
+Node: Performance bugs1271601
+Node: Asking for help1274522
+Node: Maintainers1276484
+Node: Other Versions1277678
+Node: Installation summary1285530
+Node: Notes1286894
+Node: Compatibility Mode1287688
+Node: Additions1288470
+Node: Accessing The Source1289395
+Node: Adding Code1290832
+Node: New Ports1297051
+Node: Derived Files1301426
+Ref: Derived Files-Footnote-11307086
+Ref: Derived Files-Footnote-21307121
+Ref: Derived Files-Footnote-31307719
+Node: Future Extensions1307833
+Node: Implementation Limitations1308491
+Node: Extension Design1309701
+Node: Old Extension Problems1310845
+Ref: Old Extension Problems-Footnote-11312363
+Node: Extension New Mechanism Goals1312420
+Ref: Extension New Mechanism Goals-Footnote-11315784
+Node: Extension Other Design Decisions1315973
+Node: Extension Future Growth1318086
+Node: Notes summary1318692
+Node: Basic Concepts1319850
+Node: Basic High Level1320531
+Ref: figure-general-flow1320813
+Ref: figure-process-flow1321498
+Ref: Basic High Level-Footnote-11324799
+Node: Basic Data Typing1324984
+Node: Glossary1328312
+Node: Copying1360197
+Node: GNU Free Documentation License1397740
+Node: Index1422860
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index c628fb7..0f42423 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -1057,9 +1057,11 @@ particular records in a file and perform operations upon
them.
* VMS Old Gawk:: An old version comes with some VMS
systems.
* Bugs:: Reporting Problems and Bugs.
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a
performance issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
* Other Versions:: Other freely available @command{awk}
implementations.
@@ -42788,38 +42790,157 @@ report it to the developers; we cannot promise to do
anything,
but we might well want to fix it.
@menu
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a performance
issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
@end menu
+@node Bug definition
+@appendixsubsec Defining What Is and What Is Not A Bug
+
+Before talking about reporting bugs, let's define what is a bug,
+and what is not.
+
+A bug is:
+
+@itemize @bullet
+@item
+When @command{gawk} behaves differently from what's described
+in the POSIX standard, and that difference is not mentioned
+in this @value{DOCUMENT} as being done on purpose.
+
+@item
+When @command{gawk} behaves differently from what's described
+in this @value{DOCUMENT}.
+
+@item
+When @command{gawk} behaves differently from other @command{awk}
+implementations in particular circumstances, and that behavior cannot
+be attributed to an additional feature in @command{gawk}.
+
+@item
+Something that is obviously wrong, such as a core dump.
+
+@item
+When this @value{DOCUMENT} is unclear or ambiguous about a particular
+feature's behavior.
+@end itemize
+
+The following things are @emph{not} bugs, and should not be reported
+to the bug mailing list. You can ask about them on the ``help'' mailing
+list (@pxref{Asking for help}), but don't be surprised if you get an
+answer of the form ``that's how @command{gawk} behaves and it isn't
+going to change.''
+
+@itemize @bullet
+@item
+Missing features, for any definition of @dfn{feature}. For example,
+additional built-in arithmetic functions, or additional ways to split
+fields or records, or anything else.
+
+The number of features that @command{gawk} does @emph{not} have is
+by definition infinite. It cannot be all things to all people.
+
+@item
+Behaviors that are defined by the POSIX standard and/or for historical
+compatibility with Unix @command{awk}. Even if you happen to dislike
+those behaviors, they're not going to change: changing them would
+break millions of existing @command{awk} programs.
+
+@item
+Behaviors that differ from how it's done in other languages. @command{awk}
+and @command{gawk} stand on their own and do not have to follow the crowd.
+This is particularly true when the requested behavior change would break
+backwards compatibility.
+
+@item
+Documentation issues of the form ``the manual doesn't tell me how to
+do XYZ.'' The manual is not a cookbook to solve every little problem
+you may have.
+
+@item
+General questions and discussion about @command{awk} programming or
+why @command{gawk} behaves the way it does. For that use the ``help''
+mailing list: see @ref{Asking for help}.
+@end itemize
+
+For more information, see @uref{http://www.skeeve.com/fork-my-code.html,
+@cite{Fork My Code, Please!---An Open Letter To Those of You Who Are Unhappy}},
+by Arnold Robbins and Chet Ramey.
+
@node Bug address
@appendixsubsec Submitting Bug Reports
Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of @command{gawk}.
+
+Here are the steps for submitting a bug report. Following them will
+make both your life and the lives of the maintainers much easier.
+
+@enumerate 1
+@item
+Make sure that what you want to report is appropriate.
+@xref{Bug definition}. If it's not, you are wasting your
+time and ours.
+
+@item
+Verify that you have the latest version of @command{gawk}.
Many bugs (usually subtle ones) are fixed at each release, and if yours
is out of date, the problem may already have been solved.
-Second, please see if setting the environment variable @env{LC_ALL}
+@item
+Please see if setting the environment variable @env{LC_ALL}
to @code{LC_ALL=C} causes things to behave as you expect. If so, it's
a locale issue, and may or may not really be a bug.
-Third, carefully reread the documentation and see if it says you can do
+@item
+Carefully reread the documentation and see if it says you can do
what you're trying to do. If it's not clear whether you should be able
to do something or not, report that too; it's a bug in the documentation!
-Finally, before reporting a bug or trying to fix it yourself, try to isolate it
+@item
+Before reporting a bug or trying to fix it yourself, try to isolate it
to the smallest possible @command{awk} program and input @value{DF} that
-reproduce the problem. Then send us the program and @value{DF},
-some idea of what kind of Unix system you're using,
-the compiler you used to compile @command{gawk}, and the exact results
+reproduce the problem. Then send us:
+
+@itemize @bullet
+@item
+The program and @value{DF}.
+
+@item
+Some idea of what kind of Unix system you're using.
+
+@item
+The compiler you used to compile @command{gawk}.
+
+@item
+The exact results
@command{gawk} gave you. Also say what you expected to occur; this helps
us decide whether the problem is really in the documentation.
-Make sure to include the version number of @command{gawk} you are using.
+@item
+The version number of @command{gawk} you are using.
You can get this information with the command @samp{gawk --version}.
+@end itemize
+
+@item
+Do @emph{not} send screenshots. Instead, use copy/paste to send text, or
+send files.
+
+@item
+Do send files as attachments, instead of inline. This avoids corruption
+by mailer programs out in the wilds of the Internet.
+
+@item
+Please be sure to send all mail in @emph{plain text},
+not (or not exclusively) in HTML.
+
+@item
+@emph{All email must be in English. This is the only language
+understood in common by all the maintainers.}
+@end enumerate
@cindex @code{bug-gawk@@gnu.org} bug reporting address
@cindex email address for bug reports, @code{bug-gawk@@gnu.org}
@@ -42832,10 +42953,6 @@ thus they will receive your bug report.
Although you can send mail to the maintainers directly,
the bug reporting address is preferred because the
email list is archived at the GNU Project.
-@emph{All email must be in English. This is the only language
-understood in common by all the maintainers.}
-In addition, please be sure to send all mail in @emph{plain text},
-not (or not exclusively) in HTML.
@quotation NOTE
Many distributions of GNU/Linux and the various BSD-based operating systems
@@ -42850,10 +42967,6 @@ mail to the GNU list is archived, and having
everything at the GNU Project
keeps things self-contained and not dependent on other organizations.
@end quotation
-Non-bug suggestions are always welcome as well. If you have questions
-about things that are unclear in the documentation or are just obscure
-features, ask on the bug list; we will try to help you out if we can.
-
Please note: We ask that you follow the
@uref{https://gnu.org/philosophy/kind-communication.html,
GNU Kind Communication Guidelines} in your correspondence on the
@@ -42931,10 +43044,10 @@ it:
@example
$ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
$ @kbd{cd gawk-X.Y.Z}
$ @kbd{./configure}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
@end example
@item
@@ -42948,7 +43061,7 @@ Compile the program by running the @command{make}
command:
@example
@group
$ @kbd{make}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
@end group
@end example
@@ -42962,6 +43075,10 @@ that something is slow, it @emph{must} be done using a
real program and real dat
Use a data file that is large enough for the statistical profiling to measure
where @command{gawk} spends its time. It should be at least 100 megabytes in
size.
+@example
+$ @kbd{./gawk -f realprogram.awk realdata > /dev/null}
+@end example
+
@item
When done, you should have a file in the current directory named
@file{gmon.out}.
Run the command @samp{gprof gawk gmon.out > gprof.out}.
@@ -42982,6 +43099,65 @@ rerun the profiling in order to see if the patches
were effective.
If you are incapable or unwilling to do the steps listed above, then you will
just have to live with @command{gawk} as it is.
+@node Asking for help
+@appendixsubsec Where To Send Non-bug Questions
+
+If you have questions related to @command{awk} programming, or why
@command{gawk}
+behaves a certain way, or any other @command{awk}- or @command{gawk}-related
issue,
+please @emph{do not} send it to the bug reporting address.
+
+As of July, 2021, there is a separate mailing list for this purpose:
+@EMAIL{help-gawk@@gnu.org, help-gawk at gnu.org}.
+Anything that is not a bug report should be sent to that list.
+
+@quotation NOTE
+If you disregard these directions and send non-bug mails to the bug list,
+you will be told to use the help list.
+After two such requests you will be silently @emph{blacklisted} from the bug
list.
+@end quotation
+
+Please note: As with the bug list, we ask that you follow the
+@uref{https://gnu.org/philosophy/kind-communication.html,
+GNU Kind Communication Guidelines} in your correspondence on the
+list (as well as off of it).
+
+If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy
+of Bob Proulx:
+
+
+@table @emph
+@item Subscribe by email
+
+Send an email message to
+@EMAIL{help-gawk-request@@gnu.org, help-gawk-request AT gnu.org}
+with ``subscribe'' in
+the body of the message. The subject does not matter and is not used.
+
+@item Subscribe by web form
+
+To use the web interface visit
+@uref{https://lists.gnu.org/mailman/listinfo/help-gawk,
+the list information page}.
+Use the
+subscribe form to fill out your email address and submit using the
+@code{Subscribe} button.
+
+@item Reply to the confirmation message
+
+In both cases then reply to the confirmation message that is sent to
+your address in reply.
+@end table
+
+Bob mentions that you may also use email for subscribing and
+unsubscribing. For example:
+
+@example
+$ @kbd{echo help | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo subscribe | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo unsubscribe | mailx -s request help-gawk-request@@gnu.org}
+@end example
+
@node Maintainers
@appendixsubsec Reporting Problems with Non-Unix Ports
@@ -43132,8 +43308,7 @@ and links them with a library of functions that provide
the core
@command{awk} functionality.
It also has a number of extensions.
-The @command{awk} translator is released under the GPL, and the library
-is under the LGPL.
+Both the @command{awk} translator and the library are released under the GPL.
To get @command{awka}, go to @url{https://sourceforge.net/projects/awka}.
@c You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
@@ -43310,12 +43485,16 @@ and both Vax/VMS and OpenVMS.
Instructions for each system are included in this @value{APPENDIX}.
@item
-Bug reports should be sent via email to @email{bug-gawk@@gnu.org}.
+Bug reports should be sent via email to @EMAIL{bug-gawk@@gnu.org, bug-gawk AT
gnu.org}.
Bug reports should be in English and should include the version of
@command{gawk},
how it was compiled, and a short program and @value{DF} that demonstrate
the problem.
@item
+Non-bug emails should be sent to @EMAIL{help-gawk@@gnu.org, help-gawk AT
gnu.org}.
+Repeatedly sending non-bug emails to the bug list will get you blacklisted
from it.
+
+@item
There are a number of other freely available @command{awk}
implementations. Many are POSIX-compliant; others are less so.
@@ -43628,7 +43807,7 @@ your code in the public domain and submit a signed
statement to that
effect, or assign the copyright in your code to the FSF.
Both of these actions are easy to do and @emph{many} people have done so
already. If you have questions, please contact me, or
-@email{gnu@@gnu.org}.
+@EMAIL{gnu@@gnu.org, gnu AT gnu.org}.
@item
When doing a port, bear in mind that your code must coexist peacefully
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index b9a45f3..897098c 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -1052,9 +1052,11 @@ particular records in a file and perform operations upon
them.
* VMS Old Gawk:: An old version comes with some VMS
systems.
* Bugs:: Reporting Problems and Bugs.
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a
performance issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
* Other Versions:: Other freely available @command{awk}
implementations.
@@ -41631,38 +41633,157 @@ report it to the developers; we cannot promise to do
anything,
but we might well want to fix it.
@menu
+* Bug definition:: Defining what is and is not a bug.
* Bug address:: Where to send reports to.
* Usenet:: Where not to send reports to.
* Performance bugs:: What to do if you think there is a performance
issue.
+* Asking for help:: Dealing with non-bug questions.
* Maintainers:: Maintainers of non-*nix ports.
@end menu
+@node Bug definition
+@appendixsubsec Defining What Is and What Is Not A Bug
+
+Before talking about reporting bugs, let's define what is a bug,
+and what is not.
+
+A bug is:
+
+@itemize @bullet
+@item
+When @command{gawk} behaves differently from what's described
+in the POSIX standard, and that difference is not mentioned
+in this @value{DOCUMENT} as being done on purpose.
+
+@item
+When @command{gawk} behaves differently from what's described
+in this @value{DOCUMENT}.
+
+@item
+When @command{gawk} behaves differently from other @command{awk}
+implementations in particular circumstances, and that behavior cannot
+be attributed to an additional feature in @command{gawk}.
+
+@item
+Something that is obviously wrong, such as a core dump.
+
+@item
+When this @value{DOCUMENT} is unclear or ambiguous about a particular
+feature's behavior.
+@end itemize
+
+The following things are @emph{not} bugs, and should not be reported
+to the bug mailing list. You can ask about them on the ``help'' mailing
+list (@pxref{Asking for help}), but don't be surprised if you get an
+answer of the form ``that's how @command{gawk} behaves and it isn't
+going to change.''
+
+@itemize @bullet
+@item
+Missing features, for any definition of @dfn{feature}. For example,
+additional built-in arithmetic functions, or additional ways to split
+fields or records, or anything else.
+
+The number of features that @command{gawk} does @emph{not} have is
+by definition infinite. It cannot be all things to all people.
+
+@item
+Behaviors that are defined by the POSIX standard and/or for historical
+compatibility with Unix @command{awk}. Even if you happen to dislike
+those behaviors, they're not going to change: changing them would
+break millions of existing @command{awk} programs.
+
+@item
+Behaviors that differ from how it's done in other languages. @command{awk}
+and @command{gawk} stand on their own and do not have to follow the crowd.
+This is particularly true when the requested behavior change would break
+backwards compatibility.
+
+@item
+Documentation issues of the form ``the manual doesn't tell me how to
+do XYZ.'' The manual is not a cookbook to solve every little problem
+you may have.
+
+@item
+General questions and discussion about @command{awk} programming or
+why @command{gawk} behaves the way it does. For that use the ``help''
+mailing list: see @ref{Asking for help}.
+@end itemize
+
+For more information, see @uref{http://www.skeeve.com/fork-my-code.html,
+@cite{Fork My Code, Please!---An Open Letter To Those of You Who Are Unhappy}},
+by Arnold Robbins and Chet Ramey.
+
@node Bug address
@appendixsubsec Submitting Bug Reports
Before reporting a bug, make sure you have really found a genuine bug.
-First, verify that you have the latest version of @command{gawk}.
+
+Here are the steps for submitting a bug report. Following them will
+make both your life and the lives of the maintainers much easier.
+
+@enumerate 1
+@item
+Make sure that what you want to report is appropriate.
+@xref{Bug definition}. If it's not, you are wasting your
+time and ours.
+
+@item
+Verify that you have the latest version of @command{gawk}.
Many bugs (usually subtle ones) are fixed at each release, and if yours
is out of date, the problem may already have been solved.
-Second, please see if setting the environment variable @env{LC_ALL}
+@item
+Please see if setting the environment variable @env{LC_ALL}
to @code{LC_ALL=C} causes things to behave as you expect. If so, it's
a locale issue, and may or may not really be a bug.
-Third, carefully reread the documentation and see if it says you can do
+@item
+Carefully reread the documentation and see if it says you can do
what you're trying to do. If it's not clear whether you should be able
to do something or not, report that too; it's a bug in the documentation!
-Finally, before reporting a bug or trying to fix it yourself, try to isolate it
+@item
+Before reporting a bug or trying to fix it yourself, try to isolate it
to the smallest possible @command{awk} program and input @value{DF} that
-reproduce the problem. Then send us the program and @value{DF},
-some idea of what kind of Unix system you're using,
-the compiler you used to compile @command{gawk}, and the exact results
+reproduce the problem. Then send us:
+
+@itemize @bullet
+@item
+The program and @value{DF}.
+
+@item
+Some idea of what kind of Unix system you're using.
+
+@item
+The compiler you used to compile @command{gawk}.
+
+@item
+The exact results
@command{gawk} gave you. Also say what you expected to occur; this helps
us decide whether the problem is really in the documentation.
-Make sure to include the version number of @command{gawk} you are using.
+@item
+The version number of @command{gawk} you are using.
You can get this information with the command @samp{gawk --version}.
+@end itemize
+
+@item
+Do @emph{not} send screenshots. Instead, use copy/paste to send text, or
+send files.
+
+@item
+Do send files as attachments, instead of inline. This avoids corruption
+by mailer programs out in the wilds of the Internet.
+
+@item
+Please be sure to send all mail in @emph{plain text},
+not (or not exclusively) in HTML.
+
+@item
+@emph{All email must be in English. This is the only language
+understood in common by all the maintainers.}
+@end enumerate
@cindex @code{bug-gawk@@gnu.org} bug reporting address
@cindex email address for bug reports, @code{bug-gawk@@gnu.org}
@@ -41675,10 +41796,6 @@ thus they will receive your bug report.
Although you can send mail to the maintainers directly,
the bug reporting address is preferred because the
email list is archived at the GNU Project.
-@emph{All email must be in English. This is the only language
-understood in common by all the maintainers.}
-In addition, please be sure to send all mail in @emph{plain text},
-not (or not exclusively) in HTML.
@quotation NOTE
Many distributions of GNU/Linux and the various BSD-based operating systems
@@ -41693,10 +41810,6 @@ mail to the GNU list is archived, and having
everything at the GNU Project
keeps things self-contained and not dependent on other organizations.
@end quotation
-Non-bug suggestions are always welcome as well. If you have questions
-about things that are unclear in the documentation or are just obscure
-features, ask on the bug list; we will try to help you out if we can.
-
Please note: We ask that you follow the
@uref{https://gnu.org/philosophy/kind-communication.html,
GNU Kind Communication Guidelines} in your correspondence on the
@@ -41774,10 +41887,10 @@ it:
@example
$ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
$ @kbd{cd gawk-X.Y.Z}
$ @kbd{./configure}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
@end example
@item
@@ -41791,7 +41904,7 @@ Compile the program by running the @command{make}
command:
@example
@group
$ @kbd{make}
-@print{} @dots{} @ii{Output ommited}
+@print{} @dots{} @ii{Output omitted}
@end group
@end example
@@ -41805,6 +41918,10 @@ that something is slow, it @emph{must} be done using a
real program and real dat
Use a data file that is large enough for the statistical profiling to measure
where @command{gawk} spends its time. It should be at least 100 megabytes in
size.
+@example
+$ @kbd{./gawk -f realprogram.awk realdata > /dev/null}
+@end example
+
@item
When done, you should have a file in the current directory named
@file{gmon.out}.
Run the command @samp{gprof gawk gmon.out > gprof.out}.
@@ -41825,6 +41942,65 @@ rerun the profiling in order to see if the patches
were effective.
If you are incapable or unwilling to do the steps listed above, then you will
just have to live with @command{gawk} as it is.
+@node Asking for help
+@appendixsubsec Where To Send Non-bug Questions
+
+If you have questions related to @command{awk} programming, or why
@command{gawk}
+behaves a certain way, or any other @command{awk}- or @command{gawk}-related
issue,
+please @emph{do not} send it to the bug reporting address.
+
+As of July, 2021, there is a separate mailing list for this purpose:
+@EMAIL{help-gawk@@gnu.org, help-gawk at gnu.org}.
+Anything that is not a bug report should be sent to that list.
+
+@quotation NOTE
+If you disregard these directions and send non-bug mails to the bug list,
+you will be told to use the help list.
+After two such requests you will be silently @emph{blacklisted} from the bug
list.
+@end quotation
+
+Please note: As with the bug list, we ask that you follow the
+@uref{https://gnu.org/philosophy/kind-communication.html,
+GNU Kind Communication Guidelines} in your correspondence on the
+list (as well as off of it).
+
+If you wish to the subscribe to the list, in order to help out
+others, or to learn from others, here are instructions, courtesy
+of Bob Proulx:
+
+
+@table @emph
+@item Subscribe by email
+
+Send an email message to
+@EMAIL{help-gawk-request@@gnu.org, help-gawk-request AT gnu.org}
+with ``subscribe'' in
+the body of the message. The subject does not matter and is not used.
+
+@item Subscribe by web form
+
+To use the web interface visit
+@uref{https://lists.gnu.org/mailman/listinfo/help-gawk,
+the list information page}.
+Use the
+subscribe form to fill out your email address and submit using the
+@code{Subscribe} button.
+
+@item Reply to the confirmation message
+
+In both cases then reply to the confirmation message that is sent to
+your address in reply.
+@end table
+
+Bob mentions that you may also use email for subscribing and
+unsubscribing. For example:
+
+@example
+$ @kbd{echo help | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo subscribe | mailx -s request help-gawk-request@@gnu.org}
+$ @kbd{echo unsubscribe | mailx -s request help-gawk-request@@gnu.org}
+@end example
+
@node Maintainers
@appendixsubsec Reporting Problems with Non-Unix Ports
@@ -41975,8 +42151,7 @@ and links them with a library of functions that provide
the core
@command{awk} functionality.
It also has a number of extensions.
-The @command{awk} translator is released under the GPL, and the library
-is under the LGPL.
+Both the @command{awk} translator and the library are released under the GPL.
To get @command{awka}, go to @url{https://sourceforge.net/projects/awka}.
@c You can reach Andrew Sumner at @email{andrew@@zbcom.net}.
@@ -42153,12 +42328,16 @@ and both Vax/VMS and OpenVMS.
Instructions for each system are included in this @value{APPENDIX}.
@item
-Bug reports should be sent via email to @email{bug-gawk@@gnu.org}.
+Bug reports should be sent via email to @EMAIL{bug-gawk@@gnu.org, bug-gawk AT
gnu.org}.
Bug reports should be in English and should include the version of
@command{gawk},
how it was compiled, and a short program and @value{DF} that demonstrate
the problem.
@item
+Non-bug emails should be sent to @EMAIL{help-gawk@@gnu.org, help-gawk AT
gnu.org}.
+Repeatedly sending non-bug emails to the bug list will get you blacklisted
from it.
+
+@item
There are a number of other freely available @command{awk}
implementations. Many are POSIX-compliant; others are less so.
@@ -42471,7 +42650,7 @@ your code in the public domain and submit a signed
statement to that
effect, or assign the copyright in your code to the FSF.
Both of these actions are easy to do and @emph{many} people have done so
already. If you have questions, please contact me, or
-@email{gnu@@gnu.org}.
+@EMAIL{gnu@@gnu.org, gnu AT gnu.org}.
@item
When doing a port, bear in mind that your code must coexist peacefully
-----------------------------------------------------------------------
Summary of changes:
NEWS | 5 +-
doc/ChangeLog | 6 +
doc/gawk.info | 1436 ++++++++++++++++++++++++++++++-------------------------
doc/gawk.texi | 225 ++++++++-
doc/gawktexi.in | 225 ++++++++-
5 files changed, 1203 insertions(+), 694 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] gawk branch, gawk-5.1-stable, updated. gawk-4.1.0-4266-g727f3f7,
Arnold Robbins <=