Documentation fixes and improvements.

5 files changed, 735 insertions, 589 deletions

diff --git a/awklib/eg/prog/uniq.awk b/awklib/eg/prog/uniq.awk
index effc8f6c..2a2cf63e 100644
--- a/awklib/eg/prog/uniq.awk
+++ b/awklib/eg/prog/uniq.awk
@@ -30,7 +30,7 @@ BEGIN {
         else if (c == "c")
             do_count++
         else if (index("0123456789", c) != 0) {
-            # getopt requires args to options
+            # getopt() requires args to options
             # this messes us up for things like -5
             if (Optarg ~ /^[[:digit:]]+$/)
                 fcount = (c Optarg) + 0
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 620ad769..2ea9bbc7 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2014-09-03         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Further fixes from reviews and bug reports.
+
 2014-09-02         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Corrections to walkthrough in debugger chapter.
diff --git a/doc/gawk.info b/doc/gawk.info
index c8212732..1e6e93f5 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -2222,7 +2222,7 @@ determining the type of a variable, and array sorting.
 
    As we develop our presentation of the `awk' language, we introduce
 most of the variables and many of the functions. They are described
-systematically in *note Built-in Variables::, and *note Built-in::.
+systematically in *note Built-in Variables::, and in *note Built-in::.
 
 
 File: gawk.info,  Node: When,  Next: Intro Summary,  Prev: Other Features,  Up: Getting Started
@@ -14880,7 +14880,7 @@ that might be as follows:
 
    This function reads from `file' one record at a time, building up
 the full contents of the file in the local variable `contents'.  It
-works, but is not necessarily efficient.(1)
+works, but is not necessarily efficient.
 
    The following function, based on a suggestion by Denis Shirokov,
 reads the entire contents of the named file in one shot:
@@ -14915,13 +14915,6 @@ string.  Thus calling code may use something like:
    This tests the result to see if it is empty or not. An equivalent
 test would be `contents == ""'.
 
-   ---------- Footnotes ----------
-
-   (1) Execution time grows quadratically in the size of the input; for
-each record, `awk' has to allocate a bigger internal buffer for
-`contents', copy the old contents into it, and then append the contents
-of the new record.
-
 
 File: gawk.info,  Node: Data File Management,  Next: Getopt Function,  Prev: General Functions,  Up: Library Functions
 
@@ -17054,7 +17047,7 @@ standard output, `/dev/stdout':
              else if (c == "c")
                  do_count++
              else if (index("0123456789", c) != 0) {
-                 # getopt requires args to options
+                 # getopt() requires args to options
                  # this messes us up for things like -5
                  if (Optarg ~ /^[[:digit:]]+$/)
                      fcount = (c Optarg) + 0
@@ -17651,8 +17644,8 @@ program.
 enclosed in square brackets (`[a-z]') and quoted, to prevent the shell
 from attempting a file name expansion.  This is not a feature.
 
-   (2) This program was written before `gawk' acquired the ability to
-split each character in a string into separate array elements.
+   (2) This program was also written before `gawk' acquired the ability
+to split each character in a string into separate array elements.
 
 
 File: gawk.info,  Node: Labels Program,  Next: Word Sorting,  Prev: Translate Program,  Up: Miscellaneous Programs
@@ -18745,23 +18738,35 @@ File: gawk.info,  Node: Programs Exercises,  Prev: Programs Summary,  Up: Sample
 
   5. The `split.awk' program (*note Split Program::) assumes that
      letters are contiguous in the character set, which isn't true for
-     EBCDIC systems.  Fix this problem.
-
-  6. Why can't the `wc.awk' program (*note Wc Program::) just use the
+     EBCDIC systems.  Fix this problem.  (Hint: Consider a different
+     way to work through the alphabet, without relying on `ord()' and
+     `chr()'.)
+
+  6. In `uniq.awk' (*note Uniq Program::, the logic for choosing which
+     lines to print represents a "state machine", which is "a device
+     that can be in one of a set number of stable conditions depending
+     on its previous condition and on the present values of its
+     inputs."(1) Brian Kernighan suggests that "an alternative approach
+     to state mechines is to just read the input into an array, then
+     use indexing.  It's almost always easier code, and for most inputs
+     where you would use this, just as fast."  Rewrite the logic to
+     follow this suggestion.
+
+  7. Why can't the `wc.awk' program (*note Wc Program::) just use the
      value of `FNR' in `endfile()'?  Hint: Examine the code in *note
      Filetrans Function::.
 
-  7. Manipulation of individual characters in the `translate' program
+  8. Manipulation of individual characters in the `translate' program
      (*note Translate Program::) is painful using standard `awk'
      functions.  Given that `gawk' can split strings into individual
      characters using `""' as the separator, how might you use this
      feature to simplify the program?
 
-  8. The `extract.awk' program (*note Extract Program::) was written
+  9. The `extract.awk' program (*note Extract Program::) was written
      before `gawk' had the `gensub()' function.  Use it to simplify the
      code.
 
-  9. Compare the performance of the `awksed.awk' program (*note Simple
+ 10. Compare the performance of the `awksed.awk' program (*note Simple
      Sed::) with the more straightforward:
 
           BEGIN {
@@ -18772,16 +18777,16 @@ File: gawk.info,  Node: Programs Exercises,  Prev: Programs Summary,  Up: Sample
 
           { gsub(pat, repl); print }
 
- 10. What are the advantages and disadvantages of `awksed.awk' versus
+ 11. What are the advantages and disadvantages of `awksed.awk' versus
      the real `sed' utility?
 
- 11. In *note Igawk Program::, we mentioned that not trying to save the
+ 12. In *note Igawk Program::, we mentioned that not trying to save the
      line read with `getline' in the `pathto()' function when testing
      for the file's accessibility for use with the main program
      simplifies things considerably.  What problem does this engender
      though?
 
- 12. As an additional example of the idea that it is not always
+ 13. As an additional example of the idea that it is not always
      necessary to add new features to a program, consider the idea of
      having two files in a directory in the search path:
 
@@ -18804,10 +18809,15 @@ File: gawk.info,  Node: Programs Exercises,  Prev: Programs Summary,  Up: Sample
      `@include' statements for the desired library functions.  Make
      this change.
 
- 13. Modify `anagram.awk' (*note Anagram Program::), to avoid the use
+ 14. Modify `anagram.awk' (*note Anagram Program::), to avoid the use
      of the external `sort' utility.
 
 
+   ---------- Footnotes ----------
+
+   (1) This is the definition returned from entering `define: state
+machine' into Google.
+
 
 File: gawk.info,  Node: Advanced Features,  Next: Internationalization,  Prev: Sample Programs,  Up: Top
 
@@ -21358,7 +21368,7 @@ some limitations.  A few which are worth being aware of are:
      what your mistake was, though, you'll feel like a real guru.
 
    * If you perused the dump of opcodes in *note Miscellaneous Debugger
-     Commands::, (or if you are already familiar with `gawk' internals),
+     Commands:: (or if you are already familiar with `gawk' internals),
      you will realize that much of the internal manipulation of data in
      `gawk', as in many interpreters, is done on a stack.  `Op_push',
      `Op_pop', etc., are the "bread and butter" of most `gawk' code.
@@ -32060,7 +32070,7 @@ Index
                                                               (line  66)
 * directories, command-line:             Command-line directories.
                                                               (line   6)
-* directories, searching:                Programs Exercises.  (line  63)
+* directories, searching:                Programs Exercises.  (line  75)
 * directories, searching for loadable extensions: AWKLIBPATH Variable.
                                                               (line   6)
 * directories, searching for source files: AWKPATH Variable.  (line   6)
@@ -32341,7 +32351,7 @@ Index
 * files, reading, multiline records:     Multiple Line.       (line   6)
 * files, searching for regular expressions: Egrep Program.    (line   6)
 * files, skipping:                       File Checking.       (line   6)
-* files, source, search path for:        Programs Exercises.  (line  63)
+* files, source, search path for:        Programs Exercises.  (line  75)
 * files, splitting:                      Split Program.       (line   6)
 * files, Texinfo, extracting programs from: Extract Program.  (line   6)
 * find substring in string:              String Functions.    (line 155)
@@ -33509,11 +33519,11 @@ Index
 * search in string:                      String Functions.    (line 155)
 * search paths <1>:                      VMS Running.         (line  58)
 * search paths <2>:                      PC Using.            (line  10)
-* search paths:                          Programs Exercises.  (line  63)
+* search paths:                          Programs Exercises.  (line  75)
 * search paths, for loadable extensions: AWKLIBPATH Variable. (line   6)
 * search paths, for source files <1>:    VMS Running.         (line  58)
 * search paths, for source files <2>:    PC Using.            (line  10)
-* search paths, for source files <3>:    Programs Exercises.  (line  63)
+* search paths, for source files <3>:    Programs Exercises.  (line  75)
 * search paths, for source files:        AWKPATH Variable.    (line   6)
 * searching, files for regular expressions: Egrep Program.    (line   6)
 * searching, for words:                  Dupword Program.     (line   6)
@@ -33660,7 +33670,7 @@ Index
 * source code, QSE Awk:                  Other Versions.      (line 131)
 * source code, QuikTrim Awk:             Other Versions.      (line 135)
 * source code, Solaris awk:              Other Versions.      (line  96)
-* source files, search path for:         Programs Exercises.  (line  63)
+* source files, search path for:         Programs Exercises.  (line  75)
 * sparse arrays:                         Array Intro.         (line  72)
 * Spencer, Henry:                        Glossary.            (line  11)
 * split:                                 String Functions.    (line 313)
@@ -34051,519 +34061,519 @@ Ref: More Complex-Footnote-1102513
 Node: Statements/Lines102598
 Ref: Statements/Lines-Footnote-1107054
 Node: Other Features107319
-Node: When108247
-Ref: When-Footnote-1110003
-Node: Intro Summary110068
-Node: Invoking Gawk110951
-Node: Command Line112466
-Node: Options113257
-Ref: Options-Footnote-1129033
-Node: Other Arguments129058
-Node: Naming Standard Input131886
-Node: Environment Variables132979
-Node: AWKPATH Variable133537
-Ref: AWKPATH Variable-Footnote-1136403
-Ref: AWKPATH Variable-Footnote-2136448
-Node: AWKLIBPATH Variable136708
-Node: Other Environment Variables137467
-Node: Exit Status141124
-Node: Include Files141799
-Node: Loading Shared Libraries145377
-Node: Obsolete146761
-Node: Undocumented147458
-Node: Invoking Summary147725
-Node: Regexp149325
-Node: Regexp Usage150784
-Node: Escape Sequences152817
-Node: Regexp Operators158805
-Ref: Regexp Operators-Footnote-1166236
-Ref: Regexp Operators-Footnote-2166383
-Node: Bracket Expressions166481
-Ref: table-char-classes168499
-Node: Leftmost Longest171439
-Node: Computed Regexps172643
-Node: GNU Regexp Operators176021
-Node: Case-sensitivity179727
-Ref: Case-sensitivity-Footnote-1182617
-Ref: Case-sensitivity-Footnote-2182852
-Node: Regexp Summary182960
-Node: Reading Files184429
-Node: Records186521
-Node: awk split records187243
-Node: gawk split records192101
-Ref: gawk split records-Footnote-1196622
-Node: Fields196659
-Ref: Fields-Footnote-1199623
-Node: Nonconstant Fields199709
-Ref: Nonconstant Fields-Footnote-1201939
-Node: Changing Fields202141
-Node: Field Separators208095
-Node: Default Field Splitting210797
-Node: Regexp Field Splitting211914
-Node: Single Character Fields215241
-Node: Command Line Field Separator216300
-Node: Full Line Fields219726
-Ref: Full Line Fields-Footnote-1220234
-Node: Field Splitting Summary220280
-Ref: Field Splitting Summary-Footnote-1223412
-Node: Constant Size223513
-Node: Splitting By Content228119
-Ref: Splitting By Content-Footnote-1232192
-Node: Multiple Line232232
-Ref: Multiple Line-Footnote-1238088
-Node: Getline238267
-Node: Plain Getline240478
-Node: Getline/Variable243184
-Node: Getline/File244331
-Node: Getline/Variable/File245715
-Ref: Getline/Variable/File-Footnote-1247314
-Node: Getline/Pipe247401
-Node: Getline/Variable/Pipe250087
-Node: Getline/Coprocess251194
-Node: Getline/Variable/Coprocess252446
-Node: Getline Notes253183
-Node: Getline Summary255987
-Ref: table-getline-variants256395
-Node: Read Timeout257307
-Ref: Read Timeout-Footnote-1261134
-Node: Command-line directories261192
-Node: Input Summary262096
-Node: Input Exercises265233
-Node: Printing265961
-Node: Print267683
-Node: Print Examples269176
-Node: Output Separators271955
-Node: OFMT273971
-Node: Printf275329
-Node: Basic Printf276235
-Node: Control Letters277774
-Node: Format Modifiers281765
-Node: Printf Examples287792
-Node: Redirection290256
-Node: Special Files297228
-Node: Special FD297761
-Ref: Special FD-Footnote-1301358
-Node: Special Network301432
-Node: Special Caveats302282
-Node: Close Files And Pipes303078
-Ref: Close Files And Pipes-Footnote-1310239
-Ref: Close Files And Pipes-Footnote-2310387
-Node: Output Summary310537
-Node: Output Exercises311534
-Node: Expressions312214
-Node: Values313399
-Node: Constants314075
-Node: Scalar Constants314755
-Ref: Scalar Constants-Footnote-1315614
-Node: Nondecimal-numbers315864
-Node: Regexp Constants318864
-Node: Using Constant Regexps319389
-Node: Variables322461
-Node: Using Variables323116
-Node: Assignment Options324840
-Node: Conversion326715
-Node: Strings And Numbers327239
-Ref: Strings And Numbers-Footnote-1330301
-Node: Locale influences conversions330410
-Ref: table-locale-affects333127
-Node: All Operators333715
-Node: Arithmetic Ops334345
-Node: Concatenation336850
-Ref: Concatenation-Footnote-1339669
-Node: Assignment Ops339775
-Ref: table-assign-ops344758
-Node: Increment Ops346061
-Node: Truth Values and Conditions349499
-Node: Truth Values350582
-Node: Typing and Comparison351631
-Node: Variable Typing352424
-Node: Comparison Operators356076
-Ref: table-relational-ops356486
-Node: POSIX String Comparison360036
-Ref: POSIX String Comparison-Footnote-1361120
-Node: Boolean Ops361258
-Ref: Boolean Ops-Footnote-1365597
-Node: Conditional Exp365688
-Node: Function Calls367415
-Node: Precedence371295
-Node: Locales374964
-Node: Expressions Summary376595
-Node: Patterns and Actions379136
-Node: Pattern Overview380252
-Node: Regexp Patterns381929
-Node: Expression Patterns382472
-Node: Ranges386252
-Node: BEGIN/END389358
-Node: Using BEGIN/END390120
-Ref: Using BEGIN/END-Footnote-1392856
-Node: I/O And BEGIN/END392962
-Node: BEGINFILE/ENDFILE395233
-Node: Empty398164
-Node: Using Shell Variables398481
-Node: Action Overview400764
-Node: Statements403091
-Node: If Statement404939
-Node: While Statement406437
-Node: Do Statement408481
-Node: For Statement409637
-Node: Switch Statement412789
-Node: Break Statement415177
-Node: Continue Statement417218
-Node: Next Statement419043
-Node: Nextfile Statement421433
-Node: Exit Statement424090
-Node: Built-in Variables426494
-Node: User-modified427621
-Ref: User-modified-Footnote-1435310
-Node: Auto-set435372
-Ref: Auto-set-Footnote-1447954
-Ref: Auto-set-Footnote-2448159
-Node: ARGC and ARGV448215
-Node: Pattern Action Summary452119
-Node: Arrays454342
-Node: Array Basics455891
-Node: Array Intro456717
-Ref: figure-array-elements458690
-Ref: Array Intro-Footnote-1461214
-Node: Reference to Elements461342
-Node: Assigning Elements463792
-Node: Array Example464283
-Node: Scanning an Array466015
-Node: Controlling Scanning469016
-Ref: Controlling Scanning-Footnote-1474189
-Node: Delete474505
-Ref: Delete-Footnote-1477256
-Node: Numeric Array Subscripts477313
-Node: Uninitialized Subscripts479496
-Node: Multidimensional481123
-Node: Multiscanning484236
-Node: Arrays of Arrays485825
-Node: Arrays Summary490488
-Node: Functions492593
-Node: Built-in493466
-Node: Calling Built-in494544
-Node: Numeric Functions496532
-Ref: Numeric Functions-Footnote-1500566
-Ref: Numeric Functions-Footnote-2500923
-Ref: Numeric Functions-Footnote-3500971
-Node: String Functions501240
-Ref: String Functions-Footnote-1524237
-Ref: String Functions-Footnote-2524366
-Ref: String Functions-Footnote-3524614
-Node: Gory Details524701
-Ref: table-sub-escapes526474
-Ref: table-sub-proposed527994
-Ref: table-posix-sub529358
-Ref: table-gensub-escapes530898
-Ref: Gory Details-Footnote-1532074
-Node: I/O Functions532225
-Ref: I/O Functions-Footnote-1539335
-Node: Time Functions539482
-Ref: Time Functions-Footnote-1549946
-Ref: Time Functions-Footnote-2550014
-Ref: Time Functions-Footnote-3550172
-Ref: Time Functions-Footnote-4550283
-Ref: Time Functions-Footnote-5550395
-Ref: Time Functions-Footnote-6550622
-Node: Bitwise Functions550888
-Ref: table-bitwise-ops551450
-Ref: Bitwise Functions-Footnote-1555695
-Node: Type Functions555879
-Node: I18N Functions557021
-Node: User-defined558666
-Node: Definition Syntax559470
-Ref: Definition Syntax-Footnote-1564783
-Node: Function Example564852
-Ref: Function Example-Footnote-1567492
-Node: Function Caveats567514
-Node: Calling A Function568032
-Node: Variable Scope568987
-Node: Pass By Value/Reference571975
-Node: Return Statement575485
-Node: Dynamic Typing578469
-Node: Indirect Calls579398
-Node: Functions Summary589111
-Node: Library Functions591650
-Ref: Library Functions-Footnote-1595268
-Ref: Library Functions-Footnote-2595411
-Node: Library Names595582
-Ref: Library Names-Footnote-1599055
-Ref: Library Names-Footnote-2599275
-Node: General Functions599361
-Node: Strtonum Function600389
-Node: Assert Function603263
-Node: Round Function606589
-Node: Cliff Random Function608130
-Node: Ordinal Functions609146
-Ref: Ordinal Functions-Footnote-1612211
-Ref: Ordinal Functions-Footnote-2612463
-Node: Join Function612674
-Ref: Join Function-Footnote-1614445
-Node: Getlocaltime Function614645
-Node: Readfile Function618381
-Ref: Readfile Function-Footnote-1620259
-Node: Data File Management620487
-Node: Filetrans Function621119
-Node: Rewind Function625188
-Node: File Checking626746
-Ref: File Checking-Footnote-1627878
-Node: Empty Files628079
-Node: Ignoring Assigns630058
-Node: Getopt Function631612
-Ref: Getopt Function-Footnote-1642876
-Node: Passwd Functions643079
-Ref: Passwd Functions-Footnote-1652058
-Node: Group Functions652146
-Ref: Group Functions-Footnote-1660077
-Node: Walking Arrays660290
-Node: Library Functions Summary661893
-Node: Library Exercises663281
-Node: Sample Programs664561
-Node: Running Examples665331
-Node: Clones666059
-Node: Cut Program667283
-Node: Egrep Program677141
-Ref: Egrep Program-Footnote-1684728
-Node: Id Program684838
-Node: Split Program688492
-Ref: Split Program-Footnote-1692030
-Node: Tee Program692158
-Node: Uniq Program694945
-Node: Wc Program702366
-Ref: Wc Program-Footnote-1706631
-Node: Miscellaneous Programs706723
-Node: Dupword Program707936
-Node: Alarm Program709967
-Node: Translate Program714771
-Ref: Translate Program-Footnote-1719162
-Ref: Translate Program-Footnote-2719432
-Node: Labels Program719566
-Ref: Labels Program-Footnote-1722927
-Node: Word Sorting723011
-Node: History Sorting727054
-Node: Extract Program728890
-Node: Simple Sed736426
-Node: Igawk Program739488
-Ref: Igawk Program-Footnote-1753792
-Ref: Igawk Program-Footnote-2753993
-Node: Anagram Program754131
-Node: Signature Program757199
-Node: Programs Summary758446
-Node: Programs Exercises759661
-Node: Advanced Features763312
-Node: Nondecimal Data765260
-Node: Array Sorting766837
-Node: Controlling Array Traversal767534
-Node: Array Sorting Functions775814
-Ref: Array Sorting Functions-Footnote-1779721
-Node: Two-way I/O779915
-Ref: Two-way I/O-Footnote-1784859
-Ref: Two-way I/O-Footnote-2785038
-Node: TCP/IP Networking785120
-Node: Profiling787965
-Node: Advanced Features Summary795507
-Node: Internationalization797371
-Node: I18N and L10N798851
-Node: Explaining gettext799537
-Ref: Explaining gettext-Footnote-1804563
-Ref: Explaining gettext-Footnote-2804747
-Node: Programmer i18n804912
-Ref: Programmer i18n-Footnote-1809706
-Node: Translator i18n809755
-Node: String Extraction810549
-Ref: String Extraction-Footnote-1811682
-Node: Printf Ordering811768
-Ref: Printf Ordering-Footnote-1814550
-Node: I18N Portability814614
-Ref: I18N Portability-Footnote-1817063
-Node: I18N Example817126
-Ref: I18N Example-Footnote-1819832
-Node: Gawk I18N819904
-Node: I18N Summary820542
-Node: Debugger821881
-Node: Debugging822903
-Node: Debugging Concepts823344
-Node: Debugging Terms825200
-Node: Awk Debugging827797
-Node: Sample Debugging Session828689
-Node: Debugger Invocation829209
-Node: Finding The Bug830545
-Node: List of Debugger Commands837024
-Node: Breakpoint Control838356
-Node: Debugger Execution Control842020
-Node: Viewing And Changing Data845380
-Node: Execution Stack848738
-Node: Debugger Info850251
-Node: Miscellaneous Debugger Commands854245
-Node: Readline Support859429
-Node: Limitations860321
-Node: Debugging Summary862595
-Node: Arbitrary Precision Arithmetic863763
-Node: Computer Arithmetic865250
-Ref: Computer Arithmetic-Footnote-1869637
-Node: Math Definitions869694
-Ref: table-ieee-formats872983
-Ref: Math Definitions-Footnote-1873523
-Node: MPFR features873626
-Node: FP Math Caution875243
-Ref: FP Math Caution-Footnote-1876293
-Node: Inexactness of computations876662
-Node: Inexact representation877610
-Node: Comparing FP Values878965
-Node: Errors accumulate879929
-Node: Getting Accuracy881362
-Node: Try To Round884021
-Node: Setting precision884920
-Ref: table-predefined-precision-strings885602
-Node: Setting the rounding mode887395
-Ref: table-gawk-rounding-modes887759
-Ref: Setting the rounding mode-Footnote-1891213
-Node: Arbitrary Precision Integers891392
-Ref: Arbitrary Precision Integers-Footnote-1894373
-Node: POSIX Floating Point Problems894522
-Ref: POSIX Floating Point Problems-Footnote-1898398
-Node: Floating point summary898436
-Node: Dynamic Extensions900640
-Node: Extension Intro902192
-Node: Plugin License903457
-Node: Extension Mechanism Outline904142
-Ref: figure-load-extension904566
-Ref: figure-load-new-function906051
-Ref: figure-call-new-function907053
-Node: Extension API Description909037
-Node: Extension API Functions Introduction910487
-Node: General Data Types915354
-Ref: General Data Types-Footnote-1921047
-Node: Requesting Values921346
-Ref: table-value-types-returned922083
-Node: Memory Allocation Functions923041
-Ref: Memory Allocation Functions-Footnote-1925788
-Node: Constructor Functions925884
-Node: Registration Functions927642
-Node: Extension Functions928327
-Node: Exit Callback Functions930629
-Node: Extension Version String931877
-Node: Input Parsers932527
-Node: Output Wrappers942341
-Node: Two-way processors946857
-Node: Printing Messages949061
-Ref: Printing Messages-Footnote-1950138
-Node: Updating `ERRNO'950290
-Node: Accessing Parameters951029
-Node: Symbol Table Access952259
-Node: Symbol table by name952773
-Node: Symbol table by cookie954749
-Ref: Symbol table by cookie-Footnote-1958882
-Node: Cached values958945
-Ref: Cached values-Footnote-1962449
-Node: Array Manipulation962540
-Ref: Array Manipulation-Footnote-1963638
-Node: Array Data Types963677
-Ref: Array Data Types-Footnote-1966380
-Node: Array Functions966472
-Node: Flattening Arrays970346
-Node: Creating Arrays977198
-Node: Extension API Variables981929
-Node: Extension Versioning982565
-Node: Extension API Informational Variables984466
-Node: Extension API Boilerplate985552
-Node: Finding Extensions989356
-Node: Extension Example989916
-Node: Internal File Description990646
-Node: Internal File Ops994737
-Ref: Internal File Ops-Footnote-11006169
-Node: Using Internal File Ops1006309
-Ref: Using Internal File Ops-Footnote-11008656
-Node: Extension Samples1008924
-Node: Extension Sample File Functions1010448
-Node: Extension Sample Fnmatch1018016
-Node: Extension Sample Fork1019498
-Node: Extension Sample Inplace1020711
-Node: Extension Sample Ord1022386
-Node: Extension Sample Readdir1023222
-Ref: table-readdir-file-types1024078
-Node: Extension Sample Revout1024877
-Node: Extension Sample Rev2way1025468
-Node: Extension Sample Read write array1026209
-Node: Extension Sample Readfile1028088
-Node: Extension Sample API Tests1029188
-Node: Extension Sample Time1029713
-Node: gawkextlib1031028
-Node: Extension summary1033841
-Node: Extension Exercises1037534
-Node: Language History1038256
-Node: V7/SVR3.11039899
-Node: SVR41042219
-Node: POSIX1043661
-Node: BTL1045047
-Node: POSIX/GNU1045781
-Node: Feature History1051497
-Node: Common Extensions1064588
-Node: Ranges and Locales1065900
-Ref: Ranges and Locales-Footnote-11070517
-Ref: Ranges and Locales-Footnote-21070544
-Ref: Ranges and Locales-Footnote-31070778
-Node: Contributors1070999
-Node: History summary1076424
-Node: Installation1077793
-Node: Gawk Distribution1078744
-Node: Getting1079228
-Node: Extracting1080052
-Node: Distribution contents1081694
-Node: Unix Installation1087411
-Node: Quick Installation1088028
-Node: Additional Configuration Options1090470
-Node: Configuration Philosophy1092208
-Node: Non-Unix Installation1094559
-Node: PC Installation1095017
-Node: PC Binary Installation1096328
-Node: PC Compiling1098176
-Ref: PC Compiling-Footnote-11101175
-Node: PC Testing1101280
-Node: PC Using1102456
-Node: Cygwin1106608
-Node: MSYS1107417
-Node: VMS Installation1107931
-Node: VMS Compilation1108727
-Ref: VMS Compilation-Footnote-11109949
-Node: VMS Dynamic Extensions1110007
-Node: VMS Installation Details1111380
-Node: VMS Running1113632
-Node: VMS GNV1116466
-Node: VMS Old Gawk1117189
-Node: Bugs1117659
-Node: Other Versions1121663
-Node: Installation summary1127890
-Node: Notes1128946
-Node: Compatibility Mode1129811
-Node: Additions1130593
-Node: Accessing The Source1131518
-Node: Adding Code1132954
-Node: New Ports1139132
-Node: Derived Files1143613
-Ref: Derived Files-Footnote-11148694
-Ref: Derived Files-Footnote-21148728
-Ref: Derived Files-Footnote-31149324
-Node: Future Extensions1149438
-Node: Implementation Limitations1150044
-Node: Extension Design1151292
-Node: Old Extension Problems1152446
-Ref: Old Extension Problems-Footnote-11153963
-Node: Extension New Mechanism Goals1154020
-Ref: Extension New Mechanism Goals-Footnote-11157380
-Node: Extension Other Design Decisions1157569
-Node: Extension Future Growth1159675
-Node: Old Extension Mechanism1160511
-Node: Notes summary1162273
-Node: Basic Concepts1163459
-Node: Basic High Level1164140
-Ref: figure-general-flow1164412
-Ref: figure-process-flow1165011
-Ref: Basic High Level-Footnote-11168240
-Node: Basic Data Typing1168425
-Node: Glossary1171753
-Node: Copying1196905
-Node: GNU Free Documentation License1234461
-Node: Index1259597
+Node: When108250
+Ref: When-Footnote-1110006
+Node: Intro Summary110071
+Node: Invoking Gawk110954
+Node: Command Line112469
+Node: Options113260
+Ref: Options-Footnote-1129036
+Node: Other Arguments129061
+Node: Naming Standard Input131889
+Node: Environment Variables132982
+Node: AWKPATH Variable133540
+Ref: AWKPATH Variable-Footnote-1136406
+Ref: AWKPATH Variable-Footnote-2136451
+Node: AWKLIBPATH Variable136711
+Node: Other Environment Variables137470
+Node: Exit Status141127
+Node: Include Files141802
+Node: Loading Shared Libraries145380
+Node: Obsolete146764
+Node: Undocumented147461
+Node: Invoking Summary147728
+Node: Regexp149328
+Node: Regexp Usage150787
+Node: Escape Sequences152820
+Node: Regexp Operators158808
+Ref: Regexp Operators-Footnote-1166239
+Ref: Regexp Operators-Footnote-2166386
+Node: Bracket Expressions166484
+Ref: table-char-classes168502
+Node: Leftmost Longest171442
+Node: Computed Regexps172646
+Node: GNU Regexp Operators176024
+Node: Case-sensitivity179730
+Ref: Case-sensitivity-Footnote-1182620
+Ref: Case-sensitivity-Footnote-2182855
+Node: Regexp Summary182963
+Node: Reading Files184432
+Node: Records186524
+Node: awk split records187246
+Node: gawk split records192104
+Ref: gawk split records-Footnote-1196625
+Node: Fields196662
+Ref: Fields-Footnote-1199626
+Node: Nonconstant Fields199712
+Ref: Nonconstant Fields-Footnote-1201942
+Node: Changing Fields202144
+Node: Field Separators208098
+Node: Default Field Splitting210800
+Node: Regexp Field Splitting211917
+Node: Single Character Fields215244
+Node: Command Line Field Separator216303
+Node: Full Line Fields219729
+Ref: Full Line Fields-Footnote-1220237
+Node: Field Splitting Summary220283
+Ref: Field Splitting Summary-Footnote-1223415
+Node: Constant Size223516
+Node: Splitting By Content228122
+Ref: Splitting By Content-Footnote-1232195
+Node: Multiple Line232235
+Ref: Multiple Line-Footnote-1238091
+Node: Getline238270
+Node: Plain Getline240481
+Node: Getline/Variable243187
+Node: Getline/File244334
+Node: Getline/Variable/File245718
+Ref: Getline/Variable/File-Footnote-1247317
+Node: Getline/Pipe247404
+Node: Getline/Variable/Pipe250090
+Node: Getline/Coprocess251197
+Node: Getline/Variable/Coprocess252449
+Node: Getline Notes253186
+Node: Getline Summary255990
+Ref: table-getline-variants256398
+Node: Read Timeout257310
+Ref: Read Timeout-Footnote-1261137
+Node: Command-line directories261195
+Node: Input Summary262099
+Node: Input Exercises265236
+Node: Printing265964
+Node: Print267686
+Node: Print Examples269179
+Node: Output Separators271958
+Node: OFMT273974
+Node: Printf275332
+Node: Basic Printf276238
+Node: Control Letters277777
+Node: Format Modifiers281768
+Node: Printf Examples287795
+Node: Redirection290259
+Node: Special Files297231
+Node: Special FD297764
+Ref: Special FD-Footnote-1301361
+Node: Special Network301435
+Node: Special Caveats302285
+Node: Close Files And Pipes303081
+Ref: Close Files And Pipes-Footnote-1310242
+Ref: Close Files And Pipes-Footnote-2310390
+Node: Output Summary310540
+Node: Output Exercises311537
+Node: Expressions312217
+Node: Values313402
+Node: Constants314078
+Node: Scalar Constants314758
+Ref: Scalar Constants-Footnote-1315617
+Node: Nondecimal-numbers315867
+Node: Regexp Constants318867
+Node: Using Constant Regexps319392
+Node: Variables322464
+Node: Using Variables323119
+Node: Assignment Options324843
+Node: Conversion326718
+Node: Strings And Numbers327242
+Ref: Strings And Numbers-Footnote-1330304
+Node: Locale influences conversions330413
+Ref: table-locale-affects333130
+Node: All Operators333718
+Node: Arithmetic Ops334348
+Node: Concatenation336853
+Ref: Concatenation-Footnote-1339672
+Node: Assignment Ops339778
+Ref: table-assign-ops344761
+Node: Increment Ops346064
+Node: Truth Values and Conditions349502
+Node: Truth Values350585
+Node: Typing and Comparison351634
+Node: Variable Typing352427
+Node: Comparison Operators356079
+Ref: table-relational-ops356489
+Node: POSIX String Comparison360039
+Ref: POSIX String Comparison-Footnote-1361123
+Node: Boolean Ops361261
+Ref: Boolean Ops-Footnote-1365600
+Node: Conditional Exp365691
+Node: Function Calls367418
+Node: Precedence371298
+Node: Locales374967
+Node: Expressions Summary376598
+Node: Patterns and Actions379139
+Node: Pattern Overview380255
+Node: Regexp Patterns381932
+Node: Expression Patterns382475
+Node: Ranges386255
+Node: BEGIN/END389361
+Node: Using BEGIN/END390123
+Ref: Using BEGIN/END-Footnote-1392859
+Node: I/O And BEGIN/END392965
+Node: BEGINFILE/ENDFILE395236
+Node: Empty398167
+Node: Using Shell Variables398484
+Node: Action Overview400767
+Node: Statements403094
+Node: If Statement404942
+Node: While Statement406440
+Node: Do Statement408484
+Node: For Statement409640
+Node: Switch Statement412792
+Node: Break Statement415180
+Node: Continue Statement417221
+Node: Next Statement419046
+Node: Nextfile Statement421436
+Node: Exit Statement424093
+Node: Built-in Variables426497
+Node: User-modified427624
+Ref: User-modified-Footnote-1435313
+Node: Auto-set435375
+Ref: Auto-set-Footnote-1447957
+Ref: Auto-set-Footnote-2448162
+Node: ARGC and ARGV448218
+Node: Pattern Action Summary452122
+Node: Arrays454345
+Node: Array Basics455894
+Node: Array Intro456720
+Ref: figure-array-elements458693
+Ref: Array Intro-Footnote-1461217
+Node: Reference to Elements461345
+Node: Assigning Elements463795
+Node: Array Example464286
+Node: Scanning an Array466018
+Node: Controlling Scanning469019
+Ref: Controlling Scanning-Footnote-1474192
+Node: Delete474508
+Ref: Delete-Footnote-1477259
+Node: Numeric Array Subscripts477316
+Node: Uninitialized Subscripts479499
+Node: Multidimensional481126
+Node: Multiscanning484239
+Node: Arrays of Arrays485828
+Node: Arrays Summary490491
+Node: Functions492596
+Node: Built-in493469
+Node: Calling Built-in494547
+Node: Numeric Functions496535
+Ref: Numeric Functions-Footnote-1500569
+Ref: Numeric Functions-Footnote-2500926
+Ref: Numeric Functions-Footnote-3500974
+Node: String Functions501243
+Ref: String Functions-Footnote-1524240
+Ref: String Functions-Footnote-2524369
+Ref: String Functions-Footnote-3524617
+Node: Gory Details524704
+Ref: table-sub-escapes526477
+Ref: table-sub-proposed527997
+Ref: table-posix-sub529361
+Ref: table-gensub-escapes530901
+Ref: Gory Details-Footnote-1532077
+Node: I/O Functions532228
+Ref: I/O Functions-Footnote-1539338
+Node: Time Functions539485
+Ref: Time Functions-Footnote-1549949
+Ref: Time Functions-Footnote-2550017
+Ref: Time Functions-Footnote-3550175
+Ref: Time Functions-Footnote-4550286
+Ref: Time Functions-Footnote-5550398
+Ref: Time Functions-Footnote-6550625
+Node: Bitwise Functions550891
+Ref: table-bitwise-ops551453
+Ref: Bitwise Functions-Footnote-1555698
+Node: Type Functions555882
+Node: I18N Functions557024
+Node: User-defined558669
+Node: Definition Syntax559473
+Ref: Definition Syntax-Footnote-1564786
+Node: Function Example564855
+Ref: Function Example-Footnote-1567495
+Node: Function Caveats567517
+Node: Calling A Function568035
+Node: Variable Scope568990
+Node: Pass By Value/Reference571978
+Node: Return Statement575488
+Node: Dynamic Typing578472
+Node: Indirect Calls579401
+Node: Functions Summary589114
+Node: Library Functions591653
+Ref: Library Functions-Footnote-1595271
+Ref: Library Functions-Footnote-2595414
+Node: Library Names595585
+Ref: Library Names-Footnote-1599058
+Ref: Library Names-Footnote-2599278
+Node: General Functions599364
+Node: Strtonum Function600392
+Node: Assert Function603266
+Node: Round Function606592
+Node: Cliff Random Function608133
+Node: Ordinal Functions609149
+Ref: Ordinal Functions-Footnote-1612214
+Ref: Ordinal Functions-Footnote-2612466
+Node: Join Function612677
+Ref: Join Function-Footnote-1614448
+Node: Getlocaltime Function614648
+Node: Readfile Function618384
+Node: Data File Management620223
+Node: Filetrans Function620855
+Node: Rewind Function624924
+Node: File Checking626482
+Ref: File Checking-Footnote-1627614
+Node: Empty Files627815
+Node: Ignoring Assigns629794
+Node: Getopt Function631348
+Ref: Getopt Function-Footnote-1642612
+Node: Passwd Functions642815
+Ref: Passwd Functions-Footnote-1651794
+Node: Group Functions651882
+Ref: Group Functions-Footnote-1659813
+Node: Walking Arrays660026
+Node: Library Functions Summary661629
+Node: Library Exercises663017
+Node: Sample Programs664297
+Node: Running Examples665067
+Node: Clones665795
+Node: Cut Program667019
+Node: Egrep Program676877
+Ref: Egrep Program-Footnote-1684464
+Node: Id Program684574
+Node: Split Program688228
+Ref: Split Program-Footnote-1691766
+Node: Tee Program691894
+Node: Uniq Program694681
+Node: Wc Program702104
+Ref: Wc Program-Footnote-1706369
+Node: Miscellaneous Programs706461
+Node: Dupword Program707674
+Node: Alarm Program709705
+Node: Translate Program714509
+Ref: Translate Program-Footnote-1718900
+Ref: Translate Program-Footnote-2719170
+Node: Labels Program719309
+Ref: Labels Program-Footnote-1722670
+Node: Word Sorting722754
+Node: History Sorting726797
+Node: Extract Program728633
+Node: Simple Sed736169
+Node: Igawk Program739231
+Ref: Igawk Program-Footnote-1753535
+Ref: Igawk Program-Footnote-2753736
+Node: Anagram Program753874
+Node: Signature Program756942
+Node: Programs Summary758189
+Node: Programs Exercises759404
+Ref: Programs Exercises-Footnote-1763791
+Node: Advanced Features763882
+Node: Nondecimal Data765830
+Node: Array Sorting767407
+Node: Controlling Array Traversal768104
+Node: Array Sorting Functions776384
+Ref: Array Sorting Functions-Footnote-1780291
+Node: Two-way I/O780485
+Ref: Two-way I/O-Footnote-1785429
+Ref: Two-way I/O-Footnote-2785608
+Node: TCP/IP Networking785690
+Node: Profiling788535
+Node: Advanced Features Summary796077
+Node: Internationalization797941
+Node: I18N and L10N799421
+Node: Explaining gettext800107
+Ref: Explaining gettext-Footnote-1805133
+Ref: Explaining gettext-Footnote-2805317
+Node: Programmer i18n805482
+Ref: Programmer i18n-Footnote-1810276
+Node: Translator i18n810325
+Node: String Extraction811119
+Ref: String Extraction-Footnote-1812252
+Node: Printf Ordering812338
+Ref: Printf Ordering-Footnote-1815120
+Node: I18N Portability815184
+Ref: I18N Portability-Footnote-1817633
+Node: I18N Example817696
+Ref: I18N Example-Footnote-1820402
+Node: Gawk I18N820474
+Node: I18N Summary821112
+Node: Debugger822451
+Node: Debugging823473
+Node: Debugging Concepts823914
+Node: Debugging Terms825770
+Node: Awk Debugging828367
+Node: Sample Debugging Session829259
+Node: Debugger Invocation829779
+Node: Finding The Bug831115
+Node: List of Debugger Commands837594
+Node: Breakpoint Control838926
+Node: Debugger Execution Control842590
+Node: Viewing And Changing Data845950
+Node: Execution Stack849308
+Node: Debugger Info850821
+Node: Miscellaneous Debugger Commands854815
+Node: Readline Support859999
+Node: Limitations860891
+Node: Debugging Summary863164
+Node: Arbitrary Precision Arithmetic864332
+Node: Computer Arithmetic865819
+Ref: Computer Arithmetic-Footnote-1870206
+Node: Math Definitions870263
+Ref: table-ieee-formats873552
+Ref: Math Definitions-Footnote-1874092
+Node: MPFR features874195
+Node: FP Math Caution875812
+Ref: FP Math Caution-Footnote-1876862
+Node: Inexactness of computations877231
+Node: Inexact representation878179
+Node: Comparing FP Values879534
+Node: Errors accumulate880498
+Node: Getting Accuracy881931
+Node: Try To Round884590
+Node: Setting precision885489
+Ref: table-predefined-precision-strings886171
+Node: Setting the rounding mode887964
+Ref: table-gawk-rounding-modes888328
+Ref: Setting the rounding mode-Footnote-1891782
+Node: Arbitrary Precision Integers891961
+Ref: Arbitrary Precision Integers-Footnote-1894942
+Node: POSIX Floating Point Problems895091
+Ref: POSIX Floating Point Problems-Footnote-1898967
+Node: Floating point summary899005
+Node: Dynamic Extensions901209
+Node: Extension Intro902761
+Node: Plugin License904026
+Node: Extension Mechanism Outline904711
+Ref: figure-load-extension905135
+Ref: figure-load-new-function906620
+Ref: figure-call-new-function907622
+Node: Extension API Description909606
+Node: Extension API Functions Introduction911056
+Node: General Data Types915923
+Ref: General Data Types-Footnote-1921616
+Node: Requesting Values921915
+Ref: table-value-types-returned922652
+Node: Memory Allocation Functions923610
+Ref: Memory Allocation Functions-Footnote-1926357
+Node: Constructor Functions926453
+Node: Registration Functions928211
+Node: Extension Functions928896
+Node: Exit Callback Functions931198
+Node: Extension Version String932446
+Node: Input Parsers933096
+Node: Output Wrappers942910
+Node: Two-way processors947426
+Node: Printing Messages949630
+Ref: Printing Messages-Footnote-1950707
+Node: Updating `ERRNO'950859
+Node: Accessing Parameters951598
+Node: Symbol Table Access952828
+Node: Symbol table by name953342
+Node: Symbol table by cookie955318
+Ref: Symbol table by cookie-Footnote-1959451
+Node: Cached values959514
+Ref: Cached values-Footnote-1963018
+Node: Array Manipulation963109
+Ref: Array Manipulation-Footnote-1964207
+Node: Array Data Types964246
+Ref: Array Data Types-Footnote-1966949
+Node: Array Functions967041
+Node: Flattening Arrays970915
+Node: Creating Arrays977767
+Node: Extension API Variables982498
+Node: Extension Versioning983134
+Node: Extension API Informational Variables985035
+Node: Extension API Boilerplate986121
+Node: Finding Extensions989925
+Node: Extension Example990485
+Node: Internal File Description991215
+Node: Internal File Ops995306
+Ref: Internal File Ops-Footnote-11006738
+Node: Using Internal File Ops1006878
+Ref: Using Internal File Ops-Footnote-11009225
+Node: Extension Samples1009493
+Node: Extension Sample File Functions1011017
+Node: Extension Sample Fnmatch1018585
+Node: Extension Sample Fork1020067
+Node: Extension Sample Inplace1021280
+Node: Extension Sample Ord1022955
+Node: Extension Sample Readdir1023791
+Ref: table-readdir-file-types1024647
+Node: Extension Sample Revout1025446
+Node: Extension Sample Rev2way1026037
+Node: Extension Sample Read write array1026778
+Node: Extension Sample Readfile1028657
+Node: Extension Sample API Tests1029757
+Node: Extension Sample Time1030282
+Node: gawkextlib1031597
+Node: Extension summary1034410
+Node: Extension Exercises1038103
+Node: Language History1038825
+Node: V7/SVR3.11040468
+Node: SVR41042788
+Node: POSIX1044230
+Node: BTL1045616
+Node: POSIX/GNU1046350
+Node: Feature History1052066
+Node: Common Extensions1065157
+Node: Ranges and Locales1066469
+Ref: Ranges and Locales-Footnote-11071086
+Ref: Ranges and Locales-Footnote-21071113
+Ref: Ranges and Locales-Footnote-31071347
+Node: Contributors1071568
+Node: History summary1076993
+Node: Installation1078362
+Node: Gawk Distribution1079313
+Node: Getting1079797
+Node: Extracting1080621
+Node: Distribution contents1082263
+Node: Unix Installation1087980
+Node: Quick Installation1088597
+Node: Additional Configuration Options1091039
+Node: Configuration Philosophy1092777
+Node: Non-Unix Installation1095128
+Node: PC Installation1095586
+Node: PC Binary Installation1096897
+Node: PC Compiling1098745
+Ref: PC Compiling-Footnote-11101744
+Node: PC Testing1101849
+Node: PC Using1103025
+Node: Cygwin1107177
+Node: MSYS1107986
+Node: VMS Installation1108500
+Node: VMS Compilation1109296
+Ref: VMS Compilation-Footnote-11110518
+Node: VMS Dynamic Extensions1110576
+Node: VMS Installation Details1111949
+Node: VMS Running1114201
+Node: VMS GNV1117035
+Node: VMS Old Gawk1117758
+Node: Bugs1118228
+Node: Other Versions1122232
+Node: Installation summary1128459
+Node: Notes1129515
+Node: Compatibility Mode1130380
+Node: Additions1131162
+Node: Accessing The Source1132087
+Node: Adding Code1133523
+Node: New Ports1139701
+Node: Derived Files1144182
+Ref: Derived Files-Footnote-11149263
+Ref: Derived Files-Footnote-21149297
+Ref: Derived Files-Footnote-31149893
+Node: Future Extensions1150007
+Node: Implementation Limitations1150613
+Node: Extension Design1151861
+Node: Old Extension Problems1153015
+Ref: Old Extension Problems-Footnote-11154532
+Node: Extension New Mechanism Goals1154589
+Ref: Extension New Mechanism Goals-Footnote-11157949
+Node: Extension Other Design Decisions1158138
+Node: Extension Future Growth1160244
+Node: Old Extension Mechanism1161080
+Node: Notes summary1162842
+Node: Basic Concepts1164028
+Node: Basic High Level1164709
+Ref: figure-general-flow1164981
+Ref: figure-process-flow1165580
+Ref: Basic High Level-Footnote-11168809
+Node: Basic Data Typing1168994
+Node: Glossary1172322
+Node: Copying1197474
+Node: GNU Free Documentation License1235030
+Node: Index1260166
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 7078a70e..0257a828 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -165,6 +165,19 @@
 @end macro
 @end ifdocbook
 
+@c hack for docbook, where comma shouldn't always follow an @ref{}
+@ifdocbook
+@macro DBREF{text}
+@ref{\text\}
+@end macro
+@end ifdocbook
+
+@ifnotdocbook
+@macro DBREF{text}
+@ref{\text\},
+@end macro
+@end ifnotdocbook
+
 @ifclear FOR_PRINT
 @set FN file name
 @set FFN File Name
@@ -1622,7 +1635,7 @@ available @command{awk} implementations.
 
 @ifset FOR_PRINT
 
-@ref{Copying},
+@DBREF{Copying}
 presents the license that covers the @command{gawk} source code.
 
 The version of this @value{DOCUMENT} distributed with @command{gawk}
@@ -3403,7 +3416,7 @@ and array sorting.
 
 As we develop our presentation of the @command{awk} language, we introduce
 most of the variables and many of the functions. They are described
-systematically in @ref{Built-in Variables}, and
+systematically in @ref{Built-in Variables}, and in
 @ref{Built-in}.
 
 @node When
@@ -5202,7 +5215,7 @@ The escape sequences described
 @ifnotinfo
 earlier
 @end ifnotinfo
-in @ref{Escape Sequences},
+in @DBREF{Escape Sequences}
 are valid inside a regexp.  They are introduced by a @samp{\} and
 are recognized and converted into corresponding real characters as
 the very first step in processing regexps.
@@ -5438,7 +5451,7 @@ Within a bracket expression, a @dfn{range expression} consists of two
 characters separated by a hyphen.  It matches any single character that
 sorts between the two characters, based upon the system's native character
 set.  For example, @samp{[0-9]} is equivalent to @samp{[0123456789]}.
-(See @ref{Ranges and Locales}, for an explanation of how the POSIX
+(See @DBREF{Ranges and Locales} for an explanation of how the POSIX
 standard and @command{gawk} have changed over time.  This is mainly
 of historical interest.)
 
@@ -8019,6 +8032,16 @@ processing on the next record @emph{right now}.  For example:
 @}
 @end example
 
+@c 8/2014: Here is some sample input:
+@ignore
+mon/*comment*/key
+rab/*commen
+t*/bit
+horse /*comment*/more text
+part 1 /*comment*/part 2 /*comment*/part 3
+no comment
+@end ignore
+
 This @command{awk} program deletes C-style comments (@samp{/* @dots{}
 */}) from the input.
 It uses a number of features we haven't covered yet, including
@@ -8434,7 +8457,7 @@ probably by accident, and you should reconsider what it is you're
 trying to accomplish.
 
 @item
-@ref{Getline Summary}, presents a table summarizing the
+@DBREF{Getline Summary} presents a table summarizing the
 @code{getline} variants and which variables they can affect.
 It is worth noting that those variants which do not use redirection
 can cause @code{FILENAME} to be updated if they cause
@@ -15031,7 +15054,7 @@ changed.
 @cindex arguments, command-line
 @cindex command line, arguments
 
-@ref{Auto-set},
+@DBREF{Auto-set}
 presented the following program describing the information contained in @code{ARGC}
 and @code{ARGV}:
 
@@ -20234,7 +20257,7 @@ It contains the following chapters:
 @c STARTOFRANGE fudlib
 @cindex functions, user-defined, library of
 
-@ref{User-defined}, describes how to write
+@DBREF{User-defined} describes how to write
 your own @command{awk} functions.  Writing functions is important, because
 it allows you to encapsulate algorithms and program tasks in a single
 place.  It simplifies programming, making program development more
@@ -20267,7 +20290,7 @@ use these functions.
 The functions are presented here in a progression from simple to complex.
 
 @cindex Texinfo
-@ref{Extract Program},
+@DBREF{Extract Program}
 presents a program that you can use to extract the source code for
 these example library functions and programs from the Texinfo source
 for this @value{DOCUMENT}.
@@ -20418,7 +20441,7 @@ A different convention, common in the Tcl community, is to use a single
 associative array to hold the values needed by the library function(s), or
 ``package.''  This significantly decreases the number of actual global names
 in use.  For example, the functions described in
-@ref{Passwd Functions},
+@DBREF{Passwd Functions}
 might have used array elements @code{@w{PW_data["inited"]}}, @code{@w{PW_data["total"]}},
 @code{@w{PW_data["count"]}}, and @code{@w{PW_data["awklib"]}}, instead of
 @code{@w{_pw_inited}}, @code{@w{_pw_awklib}}, @code{@w{_pw_total}},
@@ -20981,7 +21004,7 @@ more difficult than they really need to be.}
 @cindex timestamps, formatted
 @cindex time, managing
 The @code{systime()} and @code{strftime()} functions described in
-@ref{Time Functions},
+@DBREF{Time Functions}
 provide the minimum functionality necessary for dealing with the time of day
 in human readable form.  While @code{strftime()} is extensive, the control
 formats are not necessarily easy to remember or intuitively obvious when
@@ -21067,7 +21090,7 @@ function getlocaltime(time,    ret, now, i)
 
 The string indices are easier to use and read than the various formats
 required by @code{strftime()}.  The @code{alarm} program presented in
-@ref{Alarm Program},
+@DBREF{Alarm Program}
 uses this function.
 A more general design for the @code{getlocaltime()} function would have
 allowed the user to supply an optional timestamp value to use instead
@@ -21099,10 +21122,13 @@ This function reads from @code{file} one record at a time, building
 up the full contents of the file in the local variable @code{contents}.
 It works, but is not necessarily
 @c 8/2014. Thanks to BWK for pointing this out:
-efficient.@footnote{Execution time grows quadratically in the size of
+efficient.
+@ignore
+@footnote{Execution time grows quadratically in the size of
 the input; for each record, @command{awk} has to allocate a bigger
 internal buffer for @code{contents}, copy the old contents into it,
 and then append the contents of the new record.}
+@end ignore
 
 The following function, based on a suggestion by Denis Shirokov,
 reads the entire contents of the named file in one shot:
@@ -21275,7 +21301,7 @@ END  @{ endfile(_filename_) @}
 @c endfile
 @end example
 
-@ref{Wc Program},
+@DBREF{Wc Program}
 shows how this library function can be used and
 how it simplifies writing the main program.
 
@@ -22278,7 +22304,7 @@ once.  If you are worried about squeezing every last cycle out of your
 this is not necessary, since most @command{awk} programs are I/O-bound,
 and such a change would clutter up the code.
 
-The @command{id} program in @ref{Id Program},
+The @command{id} program in @DBREF{Id Program}
 uses these functions.
 @c ENDOFRANGE libfudata
 @c ENDOFRANGE flibudata
@@ -22304,7 +22330,7 @@ uses these functions.
 @cindex group file
 @cindex files, group
 Much of the discussion presented in
-@ref{Passwd Functions},
+@DBREF{Passwd Functions}
 applies to the group database as well.  Although there has traditionally
 been a well-known file (@file{/etc/group}) in a well-known format, the POSIX
 standard only provides a set of C library routines
@@ -22643,13 +22669,13 @@ Most of the work is in scanning the database and building the various
 associative arrays.  The functions that the user calls are themselves very
 simple, relying on @command{awk}'s associative arrays to do work.
 
-The @command{id} program in @ref{Id Program},
+The @command{id} program in @DBREF{Id Program}
 uses these functions.
 
 @node Walking Arrays
 @section Traversing Arrays of Arrays
 
-@ref{Arrays of Arrays}, described how @command{gawk}
+@DBREF{Arrays of Arrays} described how @command{gawk}
 provides arrays of arrays.  In particular, any element of
 an array may be either a scalar, or another array. The
 @code{isarray()} function (@pxref{Type Functions})
@@ -22804,7 +22830,7 @@ As a related challenge, revise that code to handle the case where
 an intervening value in @code{ARGV} is a variable assignment.
 
 @item
-@ref{Walking Arrays}, presented a function that walked a multidimensional
+@DBREF{Walking Arrays} presented a function that walked a multidimensional
 array to print it out.  However, walking an array and processing
 each element is a general-purpose operation.  Generalize the
 @code{walk_array()} function by adding an additional parameter named
@@ -23817,6 +23843,11 @@ This program is a bit sloppy; it relies on @command{awk} to automatically close
 instead of doing it in an @code{END} rule.
 It also assumes that letters are contiguous in the character set,
 which isn't true for EBCDIC systems.
+@ifset FOR_PRINT
+You might want to consider how to eliminate the use of
+@code{ord()} and @code{chr()}; this can be done in such a
+way as to solve the EBCDIC issue as well.
+@end ifset
 
 @c ENDOFRANGE filspl
 @c ENDOFRANGE split
@@ -24062,7 +24093,7 @@ BEGIN @{
         else if (c == "c")
             do_count++
         else if (index("0123456789", c) != 0) @{
-            # getopt requires args to options
+            # getopt() requires args to options
             # this messes us up for things like -5
             if (Optarg ~ /^[[:digit:]]+$/)
                 fcount = (c Optarg) + 0
@@ -24199,6 +24230,22 @@ END @{
 @}
 @c endfile
 @end example
+
+@ifset FOR_PRINT
+The logic for choosing which lines to print represents a @dfn{state
+machine}, which is ``a device that can be in one of a set number of stable
+conditions depending on its previous condition and on the present values
+of its inputs.''@footnote{This is the definition returned from entering
+@code{define: state machine} into Google.}
+Brian Kernighan suggests that
+``an alternative approach to state mechines is to just read
+the input into an array, then use indexing.  It's almost always
+easier code, and for most inputs where you would use this, just
+as fast.''  Consider how to rewrite the logic to follow this 
+suggestion.
+@end ifset
+
+
 @c ENDOFRANGE prunt
 @c ENDOFRANGE tpul
 @c ENDOFRANGE uniq
@@ -24724,7 +24771,7 @@ of standard @command{awk}: dealing with individual characters is very
 painful, requiring repeated use of the @code{substr()}, @code{index()},
 and @code{gsub()} built-in functions
 (@pxref{String Functions}).@footnote{This
-program was written before @command{gawk} acquired the ability to
+program was also written before @command{gawk} acquired the ability to
 split each character in a string into separate array elements.}
 There are two functions.  The first, @code{stranslate()}, takes three
 arguments:
@@ -26338,6 +26385,23 @@ The @code{split.awk} program (@pxref{Split Program}) assumes
 that letters are contiguous in the character set,
 which isn't true for EBCDIC systems.
 Fix this problem.
+(Hint: Consider a different way to work through the alphabet,
+without relying on @code{ord()} and @code{chr()}.)
+
+@item
+In @file{uniq.awk} (@pxref{Uniq Program}, the
+logic for choosing which lines to print represents a @dfn{state
+machine}, which is ``a device that can be in one of a set number of stable
+conditions depending on its previous condition and on the present values
+of its inputs.''@footnote{This is the definition returned from entering
+@code{define: state machine} into Google.}
+Brian Kernighan suggests that
+``an alternative approach to state mechines is to just read
+the input into an array, then use indexing.  It's almost always
+easier code, and for most inputs where you would use this, just
+as fast.''  Rewrite the logic to follow this 
+suggestion.
+
 
 @item
 Why can't the @file{wc.awk} program (@pxref{Wc Program}) just
@@ -26615,7 +26679,7 @@ Often, though, it is desirable to be able to loop over the elements
 in a particular order that you, the programmer, choose.  @command{gawk}
 lets you do this.
 
-@ref{Controlling Scanning}, describes how you can assign special,
+@DBREF{Controlling Scanning} describes how you can assign special,
 pre-defined values to @code{PROCINFO["sorted_in"]} in order to
 control the order in which @command{gawk} traverses an array
 during a @code{for} loop.
@@ -29771,7 +29835,9 @@ responds @samp{syntax error}.  When you do figure out what your mistake was,
 though, you'll feel like a real guru.
 
 @item
-If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands},
+@c NOTE: no comma after the ref{} on purpose, due to following
+@c parenthetical remark.
+If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}
 (or if you are already familiar with @command{gawk} internals),
 you will realize that much of the internal manipulation of data
 in @command{gawk}, as in many interpreters, is done on a stack.
@@ -38187,7 +38253,7 @@ as well as any considerations you should bear in mind.
 @appendixsubsec Accessing The @command{gawk} Git Repository
 
 As @command{gawk} is Free Software, the source code is always available.
-@ref{Gawk Distribution}, describes how to get and build the formal,
+@DBREF{Gawk Distribution} describes how to get and build the formal,
 released versions of @command{gawk}.
 
 @cindex @command{git} utility
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index ebd1ce17..002f5ec5 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -160,6 +160,19 @@
 @end macro
 @end ifdocbook
 
+@c hack for docbook, where comma shouldn't always follow an @ref{}
+@ifdocbook
+@macro DBREF{text}
+@ref{\text\}
+@end macro
+@end ifdocbook
+
+@ifnotdocbook
+@macro DBREF{text}
+@ref{\text\},
+@end macro
+@end ifnotdocbook
+
 @ifclear FOR_PRINT
 @set FN file name
 @set FFN File Name
@@ -1589,7 +1602,7 @@ available @command{awk} implementations.
 
 @ifset FOR_PRINT
 
-@ref{Copying},
+@DBREF{Copying}
 presents the license that covers the @command{gawk} source code.
 
 The version of this @value{DOCUMENT} distributed with @command{gawk}
@@ -3314,7 +3327,7 @@ and array sorting.
 
 As we develop our presentation of the @command{awk} language, we introduce
 most of the variables and many of the functions. They are described
-systematically in @ref{Built-in Variables}, and
+systematically in @ref{Built-in Variables}, and in
 @ref{Built-in}.
 
 @node When
@@ -5030,7 +5043,7 @@ The escape sequences described
 @ifnotinfo
 earlier
 @end ifnotinfo
-in @ref{Escape Sequences},
+in @DBREF{Escape Sequences}
 are valid inside a regexp.  They are introduced by a @samp{\} and
 are recognized and converted into corresponding real characters as
 the very first step in processing regexps.
@@ -5266,7 +5279,7 @@ Within a bracket expression, a @dfn{range expression} consists of two
 characters separated by a hyphen.  It matches any single character that
 sorts between the two characters, based upon the system's native character
 set.  For example, @samp{[0-9]} is equivalent to @samp{[0123456789]}.
-(See @ref{Ranges and Locales}, for an explanation of how the POSIX
+(See @DBREF{Ranges and Locales} for an explanation of how the POSIX
 standard and @command{gawk} have changed over time.  This is mainly
 of historical interest.)
 
@@ -7621,6 +7634,16 @@ processing on the next record @emph{right now}.  For example:
 @}
 @end example
 
+@c 8/2014: Here is some sample input:
+@ignore
+mon/*comment*/key
+rab/*commen
+t*/bit
+horse /*comment*/more text
+part 1 /*comment*/part 2 /*comment*/part 3
+no comment
+@end ignore
+
 This @command{awk} program deletes C-style comments (@samp{/* @dots{}
 */}) from the input.
 It uses a number of features we haven't covered yet, including
@@ -8036,7 +8059,7 @@ probably by accident, and you should reconsider what it is you're
 trying to accomplish.
 
 @item
-@ref{Getline Summary}, presents a table summarizing the
+@DBREF{Getline Summary} presents a table summarizing the
 @code{getline} variants and which variables they can affect.
 It is worth noting that those variants which do not use redirection
 can cause @code{FILENAME} to be updated if they cause
@@ -14319,7 +14342,7 @@ changed.
 @cindex arguments, command-line
 @cindex command line, arguments
 
-@ref{Auto-set},
+@DBREF{Auto-set}
 presented the following program describing the information contained in @code{ARGC}
 and @code{ARGV}:
 
@@ -19361,7 +19384,7 @@ It contains the following chapters:
 @c STARTOFRANGE fudlib
 @cindex functions, user-defined, library of
 
-@ref{User-defined}, describes how to write
+@DBREF{User-defined} describes how to write
 your own @command{awk} functions.  Writing functions is important, because
 it allows you to encapsulate algorithms and program tasks in a single
 place.  It simplifies programming, making program development more
@@ -19394,7 +19417,7 @@ use these functions.
 The functions are presented here in a progression from simple to complex.
 
 @cindex Texinfo
-@ref{Extract Program},
+@DBREF{Extract Program}
 presents a program that you can use to extract the source code for
 these example library functions and programs from the Texinfo source
 for this @value{DOCUMENT}.
@@ -19545,7 +19568,7 @@ A different convention, common in the Tcl community, is to use a single
 associative array to hold the values needed by the library function(s), or
 ``package.''  This significantly decreases the number of actual global names
 in use.  For example, the functions described in
-@ref{Passwd Functions},
+@DBREF{Passwd Functions}
 might have used array elements @code{@w{PW_data["inited"]}}, @code{@w{PW_data["total"]}},
 @code{@w{PW_data["count"]}}, and @code{@w{PW_data["awklib"]}}, instead of
 @code{@w{_pw_inited}}, @code{@w{_pw_awklib}}, @code{@w{_pw_total}},
@@ -20108,7 +20131,7 @@ more difficult than they really need to be.}
 @cindex timestamps, formatted
 @cindex time, managing
 The @code{systime()} and @code{strftime()} functions described in
-@ref{Time Functions},
+@DBREF{Time Functions}
 provide the minimum functionality necessary for dealing with the time of day
 in human readable form.  While @code{strftime()} is extensive, the control
 formats are not necessarily easy to remember or intuitively obvious when
@@ -20194,7 +20217,7 @@ function getlocaltime(time,    ret, now, i)
 
 The string indices are easier to use and read than the various formats
 required by @code{strftime()}.  The @code{alarm} program presented in
-@ref{Alarm Program},
+@DBREF{Alarm Program}
 uses this function.
 A more general design for the @code{getlocaltime()} function would have
 allowed the user to supply an optional timestamp value to use instead
@@ -20226,10 +20249,13 @@ This function reads from @code{file} one record at a time, building
 up the full contents of the file in the local variable @code{contents}.
 It works, but is not necessarily
 @c 8/2014. Thanks to BWK for pointing this out:
-efficient.@footnote{Execution time grows quadratically in the size of
+efficient.
+@ignore
+@footnote{Execution time grows quadratically in the size of
 the input; for each record, @command{awk} has to allocate a bigger
 internal buffer for @code{contents}, copy the old contents into it,
 and then append the contents of the new record.}
+@end ignore
 
 The following function, based on a suggestion by Denis Shirokov,
 reads the entire contents of the named file in one shot:
@@ -20402,7 +20428,7 @@ END  @{ endfile(_filename_) @}
 @c endfile
 @end example
 
-@ref{Wc Program},
+@DBREF{Wc Program}
 shows how this library function can be used and
 how it simplifies writing the main program.
 
@@ -21376,7 +21402,7 @@ once.  If you are worried about squeezing every last cycle out of your
 this is not necessary, since most @command{awk} programs are I/O-bound,
 and such a change would clutter up the code.
 
-The @command{id} program in @ref{Id Program},
+The @command{id} program in @DBREF{Id Program}
 uses these functions.
 @c ENDOFRANGE libfudata
 @c ENDOFRANGE flibudata
@@ -21402,7 +21428,7 @@ uses these functions.
 @cindex group file
 @cindex files, group
 Much of the discussion presented in
-@ref{Passwd Functions},
+@DBREF{Passwd Functions}
 applies to the group database as well.  Although there has traditionally
 been a well-known file (@file{/etc/group}) in a well-known format, the POSIX
 standard only provides a set of C library routines
@@ -21741,13 +21767,13 @@ Most of the work is in scanning the database and building the various
 associative arrays.  The functions that the user calls are themselves very
 simple, relying on @command{awk}'s associative arrays to do work.
 
-The @command{id} program in @ref{Id Program},
+The @command{id} program in @DBREF{Id Program}
 uses these functions.
 
 @node Walking Arrays
 @section Traversing Arrays of Arrays
 
-@ref{Arrays of Arrays}, described how @command{gawk}
+@DBREF{Arrays of Arrays} described how @command{gawk}
 provides arrays of arrays.  In particular, any element of
 an array may be either a scalar, or another array. The
 @code{isarray()} function (@pxref{Type Functions})
@@ -21902,7 +21928,7 @@ As a related challenge, revise that code to handle the case where
 an intervening value in @code{ARGV} is a variable assignment.
 
 @item
-@ref{Walking Arrays}, presented a function that walked a multidimensional
+@DBREF{Walking Arrays} presented a function that walked a multidimensional
 array to print it out.  However, walking an array and processing
 each element is a general-purpose operation.  Generalize the
 @code{walk_array()} function by adding an additional parameter named
@@ -22915,6 +22941,11 @@ This program is a bit sloppy; it relies on @command{awk} to automatically close
 instead of doing it in an @code{END} rule.
 It also assumes that letters are contiguous in the character set,
 which isn't true for EBCDIC systems.
+@ifset FOR_PRINT
+You might want to consider how to eliminate the use of
+@code{ord()} and @code{chr()}; this can be done in such a
+way as to solve the EBCDIC issue as well.
+@end ifset
 
 @c ENDOFRANGE filspl
 @c ENDOFRANGE split
@@ -23160,7 +23191,7 @@ BEGIN @{
         else if (c == "c")
             do_count++
         else if (index("0123456789", c) != 0) @{
-            # getopt requires args to options
+            # getopt() requires args to options
             # this messes us up for things like -5
             if (Optarg ~ /^[[:digit:]]+$/)
                 fcount = (c Optarg) + 0
@@ -23297,6 +23328,22 @@ END @{
 @}
 @c endfile
 @end example
+
+@ifset FOR_PRINT
+The logic for choosing which lines to print represents a @dfn{state
+machine}, which is ``a device that can be in one of a set number of stable
+conditions depending on its previous condition and on the present values
+of its inputs.''@footnote{This is the definition returned from entering
+@code{define: state machine} into Google.}
+Brian Kernighan suggests that
+``an alternative approach to state mechines is to just read
+the input into an array, then use indexing.  It's almost always
+easier code, and for most inputs where you would use this, just
+as fast.''  Consider how to rewrite the logic to follow this 
+suggestion.
+@end ifset
+
+
 @c ENDOFRANGE prunt
 @c ENDOFRANGE tpul
 @c ENDOFRANGE uniq
@@ -23822,7 +23869,7 @@ of standard @command{awk}: dealing with individual characters is very
 painful, requiring repeated use of the @code{substr()}, @code{index()},
 and @code{gsub()} built-in functions
 (@pxref{String Functions}).@footnote{This
-program was written before @command{gawk} acquired the ability to
+program was also written before @command{gawk} acquired the ability to
 split each character in a string into separate array elements.}
 There are two functions.  The first, @code{stranslate()}, takes three
 arguments:
@@ -25436,6 +25483,23 @@ The @code{split.awk} program (@pxref{Split Program}) assumes
 that letters are contiguous in the character set,
 which isn't true for EBCDIC systems.
 Fix this problem.
+(Hint: Consider a different way to work through the alphabet,
+without relying on @code{ord()} and @code{chr()}.)
+
+@item
+In @file{uniq.awk} (@pxref{Uniq Program}, the
+logic for choosing which lines to print represents a @dfn{state
+machine}, which is ``a device that can be in one of a set number of stable
+conditions depending on its previous condition and on the present values
+of its inputs.''@footnote{This is the definition returned from entering
+@code{define: state machine} into Google.}
+Brian Kernighan suggests that
+``an alternative approach to state mechines is to just read
+the input into an array, then use indexing.  It's almost always
+easier code, and for most inputs where you would use this, just
+as fast.''  Rewrite the logic to follow this 
+suggestion.
+
 
 @item
 Why can't the @file{wc.awk} program (@pxref{Wc Program}) just
@@ -25713,7 +25777,7 @@ Often, though, it is desirable to be able to loop over the elements
 in a particular order that you, the programmer, choose.  @command{gawk}
 lets you do this.
 
-@ref{Controlling Scanning}, describes how you can assign special,
+@DBREF{Controlling Scanning} describes how you can assign special,
 pre-defined values to @code{PROCINFO["sorted_in"]} in order to
 control the order in which @command{gawk} traverses an array
 during a @code{for} loop.
@@ -28869,7 +28933,9 @@ responds @samp{syntax error}.  When you do figure out what your mistake was,
 though, you'll feel like a real guru.
 
 @item
-If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands},
+@c NOTE: no comma after the ref{} on purpose, due to following
+@c parenthetical remark.
+If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}
 (or if you are already familiar with @command{gawk} internals),
 you will realize that much of the internal manipulation of data
 in @command{gawk}, as in many interpreters, is done on a stack.
@@ -37285,7 +37351,7 @@ as well as any considerations you should bear in mind.
 @appendixsubsec Accessing The @command{gawk} Git Repository
 
 As @command{gawk} is Free Software, the source code is always available.
-@ref{Gawk Distribution}, describes how to get and build the formal,
+@DBREF{Gawk Distribution} describes how to get and build the formal,
 released versions of @command{gawk}.
 
 @cindex @command{git} utility