More doc fixes.

2 files changed, 227 insertions, 214 deletions

diff --git a/doc/gawk.info b/doc/gawk.info
index 8d95f43b..3f7609d3 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -9917,6 +9917,11 @@ since the `PROCINFO' array is not special in that case. For example:
      -| 3 3
      -| 4 4
 
+   As a side note, sorting the array indices before traversing the
+array has been reported to add 15% to 20% overhead to the execution
+time of `awk' programs. For this reason, sorted array traversal is not
+the default.
+
 
 File: gawk.info,  Node: Delete,  Next: Numeric Array Subscripts,  Prev: Array Basics,  Up: Arrays
 
@@ -27273,219 +27278,219 @@ Node: Reference to Elements411101
 Node: Assigning Elements413371
 Node: Array Example413862
 Node: Scanning an Array415594
-Node: Delete418822
-Ref: Delete-Footnote-1421253
-Node: Numeric Array Subscripts421310
-Node: Uninitialized Subscripts423493
-Node: Multi-dimensional425121
-Node: Multi-scanning428212
-Node: Array Sorting429796
-Ref: Array Sorting-Footnote-1432994
-Node: Arrays of Arrays433188
-Node: Functions437726
-Node: Built-in438548
-Node: Calling Built-in439626
-Node: Numeric Functions441602
-Ref: Numeric Functions-Footnote-1445359
-Ref: Numeric Functions-Footnote-2445695
-Ref: Numeric Functions-Footnote-3445743
-Node: String Functions446012
-Ref: String Functions-Footnote-1467818
-Ref: String Functions-Footnote-2467947
-Ref: String Functions-Footnote-3468195
-Node: Gory Details468282
-Ref: table-sub-escapes469939
-Ref: table-posix-sub471253
-Ref: table-gensub-escapes472153
-Node: I/O Functions473324
-Ref: I/O Functions-Footnote-1480019
-Node: Time Functions480166
-Ref: Time Functions-Footnote-1491033
-Ref: Time Functions-Footnote-2491101
-Ref: Time Functions-Footnote-3491259
-Ref: Time Functions-Footnote-4491370
-Ref: Time Functions-Footnote-5491482
-Ref: Time Functions-Footnote-6491709
-Node: Bitwise Functions491975
-Ref: table-bitwise-ops492533
-Ref: Bitwise Functions-Footnote-1496693
-Node: Type Functions496877
-Node: I18N Functions497315
-Node: User-defined498942
-Node: Definition Syntax499746
-Ref: Definition Syntax-Footnote-1504383
-Node: Function Example504452
-Node: Function Caveats507046
-Node: Calling A Function507467
-Node: Variable Scope508582
-Node: Pass By Value/Reference510510
-Node: Return Statement513950
-Node: Dynamic Typing516892
-Node: Indirect Calls517629
-Node: Internationalization527314
-Node: I18N and L10N528742
-Node: Explaining gettext529428
-Ref: Explaining gettext-Footnote-1534490
-Ref: Explaining gettext-Footnote-2534673
-Node: Programmer i18n534838
-Node: Translator i18n539129
-Node: String Extraction539922
-Ref: String Extraction-Footnote-1540883
-Node: Printf Ordering540969
-Ref: Printf Ordering-Footnote-1543753
-Node: I18N Portability543817
-Ref: I18N Portability-Footnote-1546266
-Node: I18N Example546329
-Ref: I18N Example-Footnote-1548964
-Node: Gawk I18N549036
-Node: Advanced Features549653
-Node: Nondecimal Data550972
-Node: Two-way I/O552553
-Ref: Two-way I/O-Footnote-1557967
-Node: TCP/IP Networking558044
-Node: Profiling560887
-Node: Library Functions568287
-Ref: Library Functions-Footnote-1571326
-Node: Library Names571497
-Ref: Library Names-Footnote-1574968
-Ref: Library Names-Footnote-2575188
-Node: General Functions575274
-Node: Nextfile Function576337
-Node: Strtonum Function580718
-Node: Assert Function583669
-Node: Round Function586995
-Node: Cliff Random Function588536
-Node: Ordinal Functions589552
-Ref: Ordinal Functions-Footnote-1592622
-Ref: Ordinal Functions-Footnote-2592874
-Node: Join Function593090
-Ref: Join Function-Footnote-1594861
-Node: Gettimeofday Function595061
-Node: Data File Management598776
-Node: Filetrans Function599408
-Node: Rewind Function603645
-Node: File Checking605098
-Node: Empty Files606192
-Node: Ignoring Assigns608422
-Node: Getopt Function609975
-Ref: Getopt Function-Footnote-1621300
-Node: Passwd Functions621503
-Ref: Passwd Functions-Footnote-1630491
-Node: Group Functions630579
-Node: Walking Arrays638682
-Node: Sample Programs640248
-Node: Running Examples640913
-Node: Clones641641
-Node: Cut Program642764
-Node: Egrep Program652605
-Ref: Egrep Program-Footnote-1660376
-Node: Id Program660486
-Node: Split Program664102
-Ref: Split Program-Footnote-1667621
-Node: Tee Program667749
-Node: Uniq Program670552
-Node: Wc Program677975
-Ref: Wc Program-Footnote-1682239
-Node: Miscellaneous Programs682439
-Node: Dupword Program683627
-Node: Alarm Program685658
-Node: Translate Program690380
-Ref: Translate Program-Footnote-1694759
-Ref: Translate Program-Footnote-2694987
-Node: Labels Program695121
-Ref: Labels Program-Footnote-1698492
-Node: Word Sorting698576
-Node: History Sorting702921
-Node: Extract Program704759
-Ref: Extract Program-Footnote-1712240
-Node: Simple Sed712368
-Node: Igawk Program715430
-Ref: Igawk Program-Footnote-1730462
-Ref: Igawk Program-Footnote-2730663
-Node: Anagram Program730801
-Node: Signature Program733899
-Node: Debugger734981
-Node: Debugging735892
-Node: Debugging Concepts736206
-Node: Debugging Terms738062
-Node: Awk Debugging740607
-Node: Sample dgawk session741499
-Node: dgawk invocation741991
-Node: Finding The Bug743173
-Node: List of Debugger Commands749657
-Node: Breakpoint Control750968
-Node: Dgawk Execution Control754444
-Node: Viewing And Changing Data757795
-Node: Dgawk Stack761104
-Node: Dgawk Info762564
-Node: Miscellaneous Dgawk Commands766512
-Node: Readline Support771940
-Node: Dgawk Limitations772767
-Node: Language History774906
-Node: V7/SVR3.1776338
-Node: SVR4778633
-Node: POSIX780075
-Node: BTL781073
-Node: POSIX/GNU781807
-Node: Common Extensions786993
-Node: Contributors788126
-Node: Installation792161
-Node: Gawk Distribution793055
-Node: Getting793539
-Node: Extracting794365
-Node: Distribution contents796043
-Node: Unix Installation801061
-Node: Quick Installation801678
-Node: Additional Configuration Options803640
-Node: Configuration Philosophy805117
-Node: Non-Unix Installation807459
-Node: PC Installation807917
-Node: PC Binary Installation809216
-Node: PC Compiling811064
-Node: PC Testing814210
-Node: PC Using815386
-Node: Cygwin819571
-Node: MSYS820568
-Node: VMS Installation821082
-Node: VMS Compilation821686
-Node: VMS Installation Details823263
-Node: VMS Running824893
-Node: VMS POSIX826490
-Node: VMS Old Gawk827788
-Node: Bugs828260
-Node: Other Versions832125
-Node: Notes837404
-Node: Compatibility Mode838096
-Node: Additions838879
-Node: Accessing The Source839691
-Node: Adding Code841114
-Node: New Ports846662
-Node: Dynamic Extensions850775
-Node: Internals852151
-Node: Plugin License861267
-Node: Sample Library861901
-Node: Internal File Description862587
-Node: Internal File Ops866294
-Ref: Internal File Ops-Footnote-1871062
-Node: Using Internal File Ops871210
-Node: Future Extensions873587
-Node: Basic Concepts876091
-Node: Basic High Level876848
-Ref: Basic High Level-Footnote-1880883
-Node: Basic Data Typing881068
-Node: Floating Point Issues885593
-Node: String Conversion Precision886676
-Ref: String Conversion Precision-Footnote-1888370
-Node: Unexpected Results888479
-Node: POSIX Floating Point Problems890305
-Ref: POSIX Floating Point Problems-Footnote-1894001
-Node: Glossary894039
-Node: Copying918138
-Node: GNU Free Documentation License955695
-Node: next-edition980839
-Node: unresolved981191
-Node: revision981691
-Node: consistency982114
-Node: Index985613
+Node: Delete419042
+Ref: Delete-Footnote-1421473
+Node: Numeric Array Subscripts421530
+Node: Uninitialized Subscripts423713
+Node: Multi-dimensional425341
+Node: Multi-scanning428432
+Node: Array Sorting430016
+Ref: Array Sorting-Footnote-1433214
+Node: Arrays of Arrays433408
+Node: Functions437946
+Node: Built-in438768
+Node: Calling Built-in439846
+Node: Numeric Functions441822
+Ref: Numeric Functions-Footnote-1445579
+Ref: Numeric Functions-Footnote-2445915
+Ref: Numeric Functions-Footnote-3445963
+Node: String Functions446232
+Ref: String Functions-Footnote-1468038
+Ref: String Functions-Footnote-2468167
+Ref: String Functions-Footnote-3468415
+Node: Gory Details468502
+Ref: table-sub-escapes470159
+Ref: table-posix-sub471473
+Ref: table-gensub-escapes472373
+Node: I/O Functions473544
+Ref: I/O Functions-Footnote-1480239
+Node: Time Functions480386
+Ref: Time Functions-Footnote-1491253
+Ref: Time Functions-Footnote-2491321
+Ref: Time Functions-Footnote-3491479
+Ref: Time Functions-Footnote-4491590
+Ref: Time Functions-Footnote-5491702
+Ref: Time Functions-Footnote-6491929
+Node: Bitwise Functions492195
+Ref: table-bitwise-ops492753
+Ref: Bitwise Functions-Footnote-1496913
+Node: Type Functions497097
+Node: I18N Functions497535
+Node: User-defined499162
+Node: Definition Syntax499966
+Ref: Definition Syntax-Footnote-1504603
+Node: Function Example504672
+Node: Function Caveats507266
+Node: Calling A Function507687
+Node: Variable Scope508802
+Node: Pass By Value/Reference510730
+Node: Return Statement514170
+Node: Dynamic Typing517112
+Node: Indirect Calls517849
+Node: Internationalization527534
+Node: I18N and L10N528962
+Node: Explaining gettext529648
+Ref: Explaining gettext-Footnote-1534710
+Ref: Explaining gettext-Footnote-2534893
+Node: Programmer i18n535058
+Node: Translator i18n539349
+Node: String Extraction540142
+Ref: String Extraction-Footnote-1541103
+Node: Printf Ordering541189
+Ref: Printf Ordering-Footnote-1543973
+Node: I18N Portability544037
+Ref: I18N Portability-Footnote-1546486
+Node: I18N Example546549
+Ref: I18N Example-Footnote-1549184
+Node: Gawk I18N549256
+Node: Advanced Features549873
+Node: Nondecimal Data551192
+Node: Two-way I/O552773
+Ref: Two-way I/O-Footnote-1558187
+Node: TCP/IP Networking558264
+Node: Profiling561107
+Node: Library Functions568507
+Ref: Library Functions-Footnote-1571546
+Node: Library Names571717
+Ref: Library Names-Footnote-1575188
+Ref: Library Names-Footnote-2575408
+Node: General Functions575494
+Node: Nextfile Function576557
+Node: Strtonum Function580938
+Node: Assert Function583889
+Node: Round Function587215
+Node: Cliff Random Function588756
+Node: Ordinal Functions589772
+Ref: Ordinal Functions-Footnote-1592842
+Ref: Ordinal Functions-Footnote-2593094
+Node: Join Function593310
+Ref: Join Function-Footnote-1595081
+Node: Gettimeofday Function595281
+Node: Data File Management598996
+Node: Filetrans Function599628
+Node: Rewind Function603865
+Node: File Checking605318
+Node: Empty Files606412
+Node: Ignoring Assigns608642
+Node: Getopt Function610195
+Ref: Getopt Function-Footnote-1621520
+Node: Passwd Functions621723
+Ref: Passwd Functions-Footnote-1630711
+Node: Group Functions630799
+Node: Walking Arrays638902
+Node: Sample Programs640468
+Node: Running Examples641133
+Node: Clones641861
+Node: Cut Program642984
+Node: Egrep Program652825
+Ref: Egrep Program-Footnote-1660596
+Node: Id Program660706
+Node: Split Program664322
+Ref: Split Program-Footnote-1667841
+Node: Tee Program667969
+Node: Uniq Program670772
+Node: Wc Program678195
+Ref: Wc Program-Footnote-1682459
+Node: Miscellaneous Programs682659
+Node: Dupword Program683847
+Node: Alarm Program685878
+Node: Translate Program690600
+Ref: Translate Program-Footnote-1694979
+Ref: Translate Program-Footnote-2695207
+Node: Labels Program695341
+Ref: Labels Program-Footnote-1698712
+Node: Word Sorting698796
+Node: History Sorting703141
+Node: Extract Program704979
+Ref: Extract Program-Footnote-1712460
+Node: Simple Sed712588
+Node: Igawk Program715650
+Ref: Igawk Program-Footnote-1730682
+Ref: Igawk Program-Footnote-2730883
+Node: Anagram Program731021
+Node: Signature Program734119
+Node: Debugger735201
+Node: Debugging736112
+Node: Debugging Concepts736426
+Node: Debugging Terms738282
+Node: Awk Debugging740827
+Node: Sample dgawk session741719
+Node: dgawk invocation742211
+Node: Finding The Bug743393
+Node: List of Debugger Commands749877
+Node: Breakpoint Control751188
+Node: Dgawk Execution Control754664
+Node: Viewing And Changing Data758015
+Node: Dgawk Stack761324
+Node: Dgawk Info762784
+Node: Miscellaneous Dgawk Commands766732
+Node: Readline Support772160
+Node: Dgawk Limitations772987
+Node: Language History775126
+Node: V7/SVR3.1776558
+Node: SVR4778853
+Node: POSIX780295
+Node: BTL781293
+Node: POSIX/GNU782027
+Node: Common Extensions787213
+Node: Contributors788346
+Node: Installation792381
+Node: Gawk Distribution793275
+Node: Getting793759
+Node: Extracting794585
+Node: Distribution contents796263
+Node: Unix Installation801281
+Node: Quick Installation801898
+Node: Additional Configuration Options803860
+Node: Configuration Philosophy805337
+Node: Non-Unix Installation807679
+Node: PC Installation808137
+Node: PC Binary Installation809436
+Node: PC Compiling811284
+Node: PC Testing814430
+Node: PC Using815606
+Node: Cygwin819791
+Node: MSYS820788
+Node: VMS Installation821302
+Node: VMS Compilation821906
+Node: VMS Installation Details823483
+Node: VMS Running825113
+Node: VMS POSIX826710
+Node: VMS Old Gawk828008
+Node: Bugs828480
+Node: Other Versions832345
+Node: Notes837624
+Node: Compatibility Mode838316
+Node: Additions839099
+Node: Accessing The Source839911
+Node: Adding Code841334
+Node: New Ports846882
+Node: Dynamic Extensions850995
+Node: Internals852371
+Node: Plugin License861487
+Node: Sample Library862121
+Node: Internal File Description862807
+Node: Internal File Ops866514
+Ref: Internal File Ops-Footnote-1871282
+Node: Using Internal File Ops871430
+Node: Future Extensions873807
+Node: Basic Concepts876311
+Node: Basic High Level877068
+Ref: Basic High Level-Footnote-1881103
+Node: Basic Data Typing881288
+Node: Floating Point Issues885813
+Node: String Conversion Precision886896
+Ref: String Conversion Precision-Footnote-1888590
+Node: Unexpected Results888699
+Node: POSIX Floating Point Problems890525
+Ref: POSIX Floating Point Problems-Footnote-1894221
+Node: Glossary894259
+Node: Copying918358
+Node: GNU Free Documentation License955915
+Node: next-edition981059
+Node: unresolved981411
+Node: revision981911
+Node: consistency982334
+Node: Index985833
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 78c4f198..d0654969 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -13414,6 +13414,14 @@ $ @kbd{gawk 'BEGIN @{}
 @print{} 4 4
 @end example
 
+As a side note, sorting the array indices before traversing
+the array has been reported to add 15% to 20% overhead to the
+execution time of @command{awk} programs. For this reason,
+sorted array traversal is not the default.
+@c The @command{gawk}
+@c maintainers believe that only the people who wish to use a
+@c feature should have to pay for it.
+
 @node Delete
 @section The @code{delete} Statement
 @cindex @code{delete} statement