New doc section on extension philosophy.

4 files changed, 745 insertions, 599 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 4d392a01..3e58a174 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -2,6 +2,7 @@
 
 	* gawkinet.texi: Lots of cleanup edits. Bump the minor part
 	of the edition.
+	* gawktexi.in: New section on extension philosphy.
 
 2020-11-28         Arnold D. Robbins     <arnold@skeeve.com>
 
diff --git a/doc/gawk.info b/doc/gawk.info
index b1ba8672..985e4c6a 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -495,6 +495,7 @@ in (a) below.  A copy of the license is included in the section entitled
 * TCP/IP Networking::                   Using 'gawk' for network
                                         programming.
 * Profiling::                           Profiling your 'awk' programs.
+* Extension Philosophy::                What should be built-in and what should not.
 * Advanced Features Summary::           Summary of advanced features.
 * I18N and L10N::                       Internationalization and Localization.
 * Explaining gettext::                  How GNU 'gettext' works.
@@ -20831,6 +20832,7 @@ their own:
 * Two-way I/O::                 Two-way communications with another process.
 * TCP/IP Networking::           Using 'gawk' for network programming.
 * Profiling::                   Profiling your 'awk' programs.
+* Extension Philosophy::        What should be built-in and what should not.
 * Advanced Features Summary::   Summary of advanced features.
 
 
@@ -21550,7 +21552,7 @@ complete introduction and discussion, as well as extensive examples.
      this includes any web service whose URL starts with 'https://'.
 
 
-File: gawk.info,  Node: Profiling,  Next: Advanced Features Summary,  Prev: TCP/IP Networking,  Up: Advanced Features
+File: gawk.info,  Node: Profiling,  Next: Extension Philosophy,  Prev: TCP/IP Networking,  Up: Advanced Features
 
 12.5 Profiling Your 'awk' Programs
 ==================================
@@ -21812,9 +21814,46 @@ numeric constants; if you used an octal or hexadecimal value in your
 source code, it will appear that way in the output.
 
 
-File: gawk.info,  Node: Advanced Features Summary,  Prev: Profiling,  Up: Advanced Features
+File: gawk.info,  Node: Extension Philosophy,  Next: Advanced Features Summary,  Prev: Profiling,  Up: Advanced Features
 
-12.6 Summary
+12.6 Builtin Features vs. Extensions
+====================================
+
+As this and subsequent major nodes show, 'gawk' has a large number of
+extensions over standard 'awk' built-in to the program.  These have
+developed over time.  More recently, the focus has moved to using the
+extension mechanism (*note Dynamic Extensions::) for adding features.
+This minor node discusses the "guiding philosophy" behind what should be
+added to the interpreter as a built-in feature vs. what should be done
+in extensions.
+
+   There are several goals:
+
+  1. Keep the language 'awk'; it should not become unrecognizable, even
+     if programs in it will only run on 'gawk'.
+
+  2. Keep the core from getting any larger unless absolutely necessary.
+
+  3. Add new functionality either in 'awk' scripts ('-f', '@include') or
+     in loadable extensions written in C or C++ ('-l', '@load').
+
+  4. Extend the core interpreter only if some feature is:
+
+       A. Truly desirable.
+       B. Cannot be done via (2) or (3) above.
+       C. Can be implemented without too much pain in the core.
+
+   Combining modules with 'awk' files is a powerful technique.  Some of
+the sample extensions demonstrate this.
+
+   Loading extensions and library files should not be done
+automatically, because then there's overhead that most users don't want
+or need.
+
+
+File: gawk.info,  Node: Advanced Features Summary,  Prev: Extension Philosophy,  Up: Advanced Features
+
+12.7 Summary
 ============
 
    * The '--non-decimal-data' option causes 'gawk' to treat octal- and
@@ -21852,6 +21891,9 @@ File: gawk.info,  Node: Advanced Features Summary,  Prev: Profiling,  Up: Advanc
 
    * You can also just "pretty-print" the program.
 
+   * New features should be developed using the extension mechansim if
+     possible, and added to the core interpreter only as a last resort.
+
 
 File: gawk.info,  Node: Internationalization,  Next: Debugger,  Prev: Advanced Features,  Up: Top
 
@@ -37942,602 +37984,603 @@ Index
 
 Tag Table:
 Node: Top1200
-Node: Foreword344474
-Node: Foreword448916
-Node: Preface50448
-Ref: Preface-Footnote-153307
-Ref: Preface-Footnote-253416
-Ref: Preface-Footnote-353650
-Node: History53792
-Node: Names56144
-Ref: Names-Footnote-157248
-Node: This Manual57395
-Ref: This Manual-Footnote-164034
-Node: Conventions64134
-Node: Manual History66503
-Ref: Manual History-Footnote-169500
-Ref: Manual History-Footnote-269541
-Node: How To Contribute69615
-Node: Acknowledgments70541
-Node: Getting Started75478
-Node: Running gawk77917
-Node: One-shot79107
-Node: Read Terminal80370
-Node: Long82363
-Node: Executable Scripts83876
-Ref: Executable Scripts-Footnote-186509
-Node: Comments86612
-Node: Quoting89096
-Node: DOS Quoting94622
-Node: Sample Data Files96678
-Node: Very Simple99273
-Node: Two Rules105375
-Node: More Complex107260
-Node: Statements/Lines109592
-Ref: Statements/Lines-Footnote-1114076
-Node: Other Features114341
-Node: When115277
-Ref: When-Footnote-1117031
-Node: Intro Summary117096
-Node: Invoking Gawk117980
-Node: Command Line119494
-Node: Options120292
-Ref: Options-Footnote-1138206
-Ref: Options-Footnote-2138437
-Node: Other Arguments138462
-Node: Naming Standard Input142473
-Node: Environment Variables143683
-Node: AWKPATH Variable144241
-Ref: AWKPATH Variable-Footnote-1147653
-Ref: AWKPATH Variable-Footnote-2147687
-Node: AWKLIBPATH Variable148058
-Ref: AWKLIBPATH Variable-Footnote-1149755
-Node: Other Environment Variables150130
-Node: Exit Status153951
-Node: Include Files154628
-Node: Loading Shared Libraries158318
-Node: Obsolete159746
-Node: Undocumented160438
-Node: Invoking Summary160735
-Node: Regexp163576
-Node: Regexp Usage165030
-Node: Escape Sequences167067
-Node: Regexp Operators173308
-Node: Regexp Operator Details173793
-Ref: Regexp Operator Details-Footnote-1180225
-Node: Interval Expressions180372
-Ref: Interval Expressions-Footnote-1181793
-Node: Bracket Expressions181891
-Ref: table-char-classes184367
-Node: Leftmost Longest187693
-Node: Computed Regexps188996
-Node: GNU Regexp Operators192423
-Node: Case-sensitivity196160
-Ref: Case-sensitivity-Footnote-1199026
-Ref: Case-sensitivity-Footnote-2199261
-Node: Regexp Summary199369
-Node: Reading Files200835
-Node: Records203104
-Node: awk split records204179
-Node: gawk split records209454
-Ref: gawk split records-Footnote-1214187
-Node: Fields214224
-Node: Nonconstant Fields216965
-Ref: Nonconstant Fields-Footnote-1219201
-Node: Changing Fields219405
-Node: Field Separators225436
-Node: Default Field Splitting228134
-Node: Regexp Field Splitting229252
-Node: Single Character Fields232605
-Node: Command Line Field Separator233665
-Node: Full Line Fields236883
-Ref: Full Line Fields-Footnote-1238405
-Ref: Full Line Fields-Footnote-2238451
-Node: Field Splitting Summary238552
-Node: Constant Size240626
-Node: Fixed width data241358
-Node: Skipping intervening244825
-Node: Allowing trailing data245623
-Node: Fields with fixed data246660
-Node: Splitting By Content248178
-Ref: Splitting By Content-Footnote-1251961
-Node: More CSV252124
-Node: Testing field creation253434
-Node: Multiple Line255059
-Node: Getline261336
-Node: Plain Getline263805
-Node: Getline/Variable266378
-Node: Getline/File267529
-Node: Getline/Variable/File268917
-Ref: Getline/Variable/File-Footnote-1270522
-Node: Getline/Pipe270610
-Node: Getline/Variable/Pipe273314
-Node: Getline/Coprocess274449
-Node: Getline/Variable/Coprocess275716
-Node: Getline Notes276458
-Node: Getline Summary279255
-Ref: table-getline-variants279679
-Node: Read Timeout280427
-Ref: Read Timeout-Footnote-1284333
-Node: Retrying Input284391
-Node: Command-line directories285590
-Node: Input Summary286496
-Node: Input Exercises289668
-Node: Printing290102
-Node: Print291936
-Node: Print Examples293393
-Node: Output Separators296173
-Node: OFMT298190
-Node: Printf299546
-Node: Basic Printf300331
-Node: Control Letters301905
-Node: Format Modifiers307069
-Node: Printf Examples313084
-Node: Redirection315570
-Node: Special FD322411
-Ref: Special FD-Footnote-1325579
-Node: Special Files325653
-Node: Other Inherited Files326270
-Node: Special Network327271
-Node: Special Caveats328131
-Node: Close Files And Pipes329080
-Ref: table-close-pipe-return-values335987
-Ref: Close Files And Pipes-Footnote-1336800
-Ref: Close Files And Pipes-Footnote-2336948
-Node: Nonfatal337100
-Node: Output Summary339438
-Node: Output Exercises340660
-Node: Expressions341339
-Node: Values342527
-Node: Constants343205
-Node: Scalar Constants343896
-Ref: Scalar Constants-Footnote-1346406
-Node: Nondecimal-numbers346656
-Node: Regexp Constants349657
-Node: Using Constant Regexps350183
-Node: Standard Regexp Constants350805
-Node: Strong Regexp Constants353993
-Node: Variables357005
-Node: Using Variables357662
-Node: Assignment Options359572
-Node: Conversion362043
-Node: Strings And Numbers362567
-Ref: Strings And Numbers-Footnote-1365630
-Node: Locale influences conversions365739
-Ref: table-locale-affects368497
-Node: All Operators369115
-Node: Arithmetic Ops369744
-Node: Concatenation372460
-Ref: Concatenation-Footnote-1375307
-Node: Assignment Ops375414
-Ref: table-assign-ops380405
-Node: Increment Ops381718
-Node: Truth Values and Conditions385178
-Node: Truth Values386252
-Node: Typing and Comparison387300
-Node: Variable Typing388120
-Ref: Variable Typing-Footnote-1394583
-Ref: Variable Typing-Footnote-2394655
-Node: Comparison Operators394732
-Ref: table-relational-ops395151
-Node: POSIX String Comparison398646
-Ref: POSIX String Comparison-Footnote-1400341
-Ref: POSIX String Comparison-Footnote-2400480
-Node: Boolean Ops400564
-Ref: Boolean Ops-Footnote-1405046
-Node: Conditional Exp405138
-Node: Function Calls406874
-Node: Precedence410751
-Node: Locales414410
-Node: Expressions Summary416042
-Node: Patterns and Actions418615
-Node: Pattern Overview419735
-Node: Regexp Patterns421412
-Node: Expression Patterns421954
-Node: Ranges425735
-Node: BEGIN/END428843
-Node: Using BEGIN/END429604
-Ref: Using BEGIN/END-Footnote-1432358
-Node: I/O And BEGIN/END432464
-Node: BEGINFILE/ENDFILE434777
-Node: Empty438008
-Node: Using Shell Variables438325
-Node: Action Overview440599
-Node: Statements442924
-Node: If Statement444772
-Node: While Statement446267
-Node: Do Statement448295
-Node: For Statement449443
-Node: Switch Statement452614
-Node: Break Statement455055
-Node: Continue Statement457147
-Node: Next Statement458974
-Node: Nextfile Statement461357
-Node: Exit Statement464046
-Node: Built-in Variables466449
-Node: User-modified467582
-Node: Auto-set475349
-Ref: Auto-set-Footnote-1492156
-Ref: Auto-set-Footnote-2492362
-Node: ARGC and ARGV492418
-Node: Pattern Action Summary496631
-Node: Arrays499061
-Node: Array Basics500390
-Node: Array Intro501234
-Ref: figure-array-elements503209
-Ref: Array Intro-Footnote-1505913
-Node: Reference to Elements506041
-Node: Assigning Elements508505
-Node: Array Example508996
-Node: Scanning an Array510755
-Node: Controlling Scanning513777
-Ref: Controlling Scanning-Footnote-1520233
-Node: Numeric Array Subscripts520549
-Node: Uninitialized Subscripts522733
-Node: Delete524352
-Ref: Delete-Footnote-1527104
-Node: Multidimensional527161
-Node: Multiscanning530256
-Node: Arrays of Arrays531847
-Node: Arrays Summary536615
-Node: Functions538708
-Node: Built-in539746
-Node: Calling Built-in540827
-Node: Numeric Functions542823
-Ref: Numeric Functions-Footnote-1546851
-Ref: Numeric Functions-Footnote-2547499
-Ref: Numeric Functions-Footnote-3547547
-Node: String Functions547819
-Ref: String Functions-Footnote-1571960
-Ref: String Functions-Footnote-2572088
-Ref: String Functions-Footnote-3572336
-Node: Gory Details572423
-Ref: table-sub-escapes574214
-Ref: table-sub-proposed575733
-Ref: table-posix-sub577096
-Ref: table-gensub-escapes578637
-Ref: Gory Details-Footnote-1579460
-Node: I/O Functions579614
-Ref: table-system-return-values586068
-Ref: I/O Functions-Footnote-1588148
-Ref: I/O Functions-Footnote-2588296
-Node: Time Functions588416
-Ref: Time Functions-Footnote-1599087
-Ref: Time Functions-Footnote-2599155
-Ref: Time Functions-Footnote-3599313
-Ref: Time Functions-Footnote-4599424
-Ref: Time Functions-Footnote-5599536
-Ref: Time Functions-Footnote-6599763
-Node: Bitwise Functions600029
-Ref: table-bitwise-ops600623
-Ref: Bitwise Functions-Footnote-1606686
-Ref: Bitwise Functions-Footnote-2606859
-Node: Type Functions607050
-Node: I18N Functions609913
-Node: User-defined611564
-Node: Definition Syntax612376
-Ref: Definition Syntax-Footnote-1618070
-Node: Function Example618141
-Ref: Function Example-Footnote-1621063
-Node: Function Calling621085
-Node: Calling A Function621673
-Node: Variable Scope622631
-Node: Pass By Value/Reference625625
-Node: Function Caveats628269
-Ref: Function Caveats-Footnote-1630316
-Node: Return Statement630436
-Node: Dynamic Typing633415
-Node: Indirect Calls634345
-Ref: Indirect Calls-Footnote-1644597
-Node: Functions Summary644725
-Node: Library Functions647430
-Ref: Library Functions-Footnote-1651037
-Ref: Library Functions-Footnote-2651180
-Node: Library Names651351
-Ref: Library Names-Footnote-1655018
-Ref: Library Names-Footnote-2655241
-Node: General Functions655327
-Node: Strtonum Function656430
-Node: Assert Function659452
-Node: Round Function662778
-Node: Cliff Random Function664318
-Node: Ordinal Functions665334
-Ref: Ordinal Functions-Footnote-1668397
-Ref: Ordinal Functions-Footnote-2668649
-Node: Join Function668859
-Ref: Join Function-Footnote-1670629
-Node: Getlocaltime Function670829
-Node: Readfile Function674571
-Node: Shell Quoting676548
-Node: Data File Management677949
-Node: Filetrans Function678581
-Node: Rewind Function682677
-Node: File Checking684586
-Ref: File Checking-Footnote-1685920
-Node: Empty Files686121
-Node: Ignoring Assigns688100
-Node: Getopt Function689650
-Ref: Getopt Function-Footnote-1704861
-Node: Passwd Functions705061
-Ref: Passwd Functions-Footnote-1713900
-Node: Group Functions713988
-Ref: Group Functions-Footnote-1721886
-Node: Walking Arrays722093
-Node: Library Functions Summary725101
-Node: Library Exercises726507
-Node: Sample Programs726972
-Node: Running Examples727742
-Node: Clones728470
-Node: Cut Program729694
-Node: Egrep Program739834
-Node: Id Program748845
-Node: Split Program758792
-Ref: Split Program-Footnote-1768682
-Node: Tee Program768855
-Node: Uniq Program771645
-Node: Wc Program779233
-Node: Bytes vs. Characters779630
-Node: Using extensions781178
-Node: wc program781932
-Node: Miscellaneous Programs786797
-Node: Dupword Program788010
-Node: Alarm Program790040
-Node: Translate Program794895
-Ref: Translate Program-Footnote-1799460
-Node: Labels Program799730
-Ref: Labels Program-Footnote-1803081
-Node: Word Sorting803165
-Node: History Sorting807237
-Node: Extract Program809462
-Node: Simple Sed817516
-Node: Igawk Program820590
-Ref: Igawk Program-Footnote-1834921
-Ref: Igawk Program-Footnote-2835123
-Ref: Igawk Program-Footnote-3835245
-Node: Anagram Program835360
-Node: Signature Program838422
-Node: Programs Summary839669
-Node: Programs Exercises840883
-Ref: Programs Exercises-Footnote-1845013
-Node: Advanced Features845099
-Node: Nondecimal Data847089
-Node: Array Sorting848680
-Node: Controlling Array Traversal849380
-Ref: Controlling Array Traversal-Footnote-1857748
-Node: Array Sorting Functions857866
-Ref: Array Sorting Functions-Footnote-1862957
-Node: Two-way I/O863153
-Ref: Two-way I/O-Footnote-1870874
-Ref: Two-way I/O-Footnote-2871061
-Node: TCP/IP Networking871143
-Node: Profiling874261
-Node: Advanced Features Summary883575
-Node: Internationalization885419
-Node: I18N and L10N886899
-Node: Explaining gettext887586
-Ref: Explaining gettext-Footnote-1893478
-Ref: Explaining gettext-Footnote-2893663
-Node: Programmer i18n893828
-Ref: Programmer i18n-Footnote-1898777
-Node: Translator i18n898826
-Node: String Extraction899620
-Ref: String Extraction-Footnote-1900752
-Node: Printf Ordering900838
-Ref: Printf Ordering-Footnote-1903624
-Node: I18N Portability903688
-Ref: I18N Portability-Footnote-1906144
-Node: I18N Example906207
-Ref: I18N Example-Footnote-1909482
-Ref: I18N Example-Footnote-2909555
-Node: Gawk I18N909664
-Node: I18N Summary910313
-Node: Debugger911654
-Node: Debugging912654
-Node: Debugging Concepts913095
-Node: Debugging Terms914904
-Node: Awk Debugging917479
-Ref: Awk Debugging-Footnote-1918424
-Node: Sample Debugging Session918556
-Node: Debugger Invocation919090
-Node: Finding The Bug920476
-Node: List of Debugger Commands926950
-Node: Breakpoint Control928283
-Node: Debugger Execution Control931977
-Node: Viewing And Changing Data935339
-Node: Execution Stack938880
-Node: Debugger Info940517
-Node: Miscellaneous Debugger Commands944588
-Node: Readline Support949650
-Node: Limitations950546
-Node: Debugging Summary953100
-Node: Namespaces954379
-Node: Global Namespace955490
-Node: Qualified Names956888
-Node: Default Namespace957887
-Node: Changing The Namespace958628
-Node: Naming Rules960242
-Node: Internal Name Management962090
-Node: Namespace Example963132
-Node: Namespace And Features965694
-Node: Namespace Summary967129
-Node: Arbitrary Precision Arithmetic968606
-Node: Computer Arithmetic970093
-Ref: table-numeric-ranges973859
-Ref: table-floating-point-ranges974352
-Ref: Computer Arithmetic-Footnote-1975010
-Node: Math Definitions975067
-Ref: table-ieee-formats978383
-Ref: Math Definitions-Footnote-1978986
-Node: MPFR features979091
-Node: FP Math Caution980809
-Ref: FP Math Caution-Footnote-1981881
-Node: Inexactness of computations982250
-Node: Inexact representation983210
-Node: Comparing FP Values984570
-Node: Errors accumulate985811
-Node: Getting Accuracy987244
-Node: Try To Round989954
-Node: Setting precision990853
-Ref: table-predefined-precision-strings991550
-Node: Setting the rounding mode993380
-Ref: table-gawk-rounding-modes993754
-Ref: Setting the rounding mode-Footnote-1997685
-Node: Arbitrary Precision Integers997864
-Ref: Arbitrary Precision Integers-Footnote-11001039
-Node: Checking for MPFR1001188
-Node: POSIX Floating Point Problems1002662
-Ref: POSIX Floating Point Problems-Footnote-11006947
-Node: Floating point summary1006985
-Node: Dynamic Extensions1009175
-Node: Extension Intro1010728
-Node: Plugin License1011994
-Node: Extension Mechanism Outline1012791
-Ref: figure-load-extension1013230
-Ref: figure-register-new-function1014795
-Ref: figure-call-new-function1015887
-Node: Extension API Description1017949
-Node: Extension API Functions Introduction1019662
-Ref: table-api-std-headers1021498
-Node: General Data Types1025747
-Ref: General Data Types-Footnote-11034377
-Node: Memory Allocation Functions1034676
-Ref: Memory Allocation Functions-Footnote-11039177
-Node: Constructor Functions1039276
-Node: API Ownership of MPFR and GMP Values1042742
-Node: Registration Functions1044055
-Node: Extension Functions1044755
-Node: Exit Callback Functions1050077
-Node: Extension Version String1051327
-Node: Input Parsers1051990
-Node: Output Wrappers1064711
-Node: Two-way processors1069223
-Node: Printing Messages1071488
-Ref: Printing Messages-Footnote-11072659
-Node: Updating ERRNO1072812
-Node: Requesting Values1073551
-Ref: table-value-types-returned1074288
-Node: Accessing Parameters1075224
-Node: Symbol Table Access1076461
-Node: Symbol table by name1076973
-Ref: Symbol table by name-Footnote-11079997
-Node: Symbol table by cookie1080125
-Ref: Symbol table by cookie-Footnote-11084310
-Node: Cached values1084374
-Ref: Cached values-Footnote-11087910
-Node: Array Manipulation1088063
-Ref: Array Manipulation-Footnote-11089154
-Node: Array Data Types1089191
-Ref: Array Data Types-Footnote-11091849
-Node: Array Functions1091941
-Node: Flattening Arrays1096439
-Node: Creating Arrays1103415
-Node: Redirection API1108182
-Node: Extension API Variables1111015
-Node: Extension Versioning1111726
-Ref: gawk-api-version1112155
-Node: Extension GMP/MPFR Versioning1113886
-Node: Extension API Informational Variables1115514
-Node: Extension API Boilerplate1116587
-Node: Changes from API V11120561
-Node: Finding Extensions1122133
-Node: Extension Example1122692
-Node: Internal File Description1123490
-Node: Internal File Ops1127570
-Ref: Internal File Ops-Footnote-11138920
-Node: Using Internal File Ops1139060
-Ref: Using Internal File Ops-Footnote-11141443
-Node: Extension Samples1141717
-Node: Extension Sample File Functions1143246
-Node: Extension Sample Fnmatch1150895
-Node: Extension Sample Fork1152382
-Node: Extension Sample Inplace1153600
-Node: Extension Sample Ord1157226
-Node: Extension Sample Readdir1158062
-Ref: table-readdir-file-types1158951
-Node: Extension Sample Revout1160018
-Node: Extension Sample Rev2way1160607
-Node: Extension Sample Read write array1161347
-Node: Extension Sample Readfile1163289
-Node: Extension Sample Time1164384
-Node: Extension Sample API Tests1166136
-Node: gawkextlib1166628
-Node: Extension summary1169546
-Node: Extension Exercises1173248
-Node: Language History1174490
-Node: V7/SVR3.11176146
-Node: SVR41178298
-Node: POSIX1179732
-Node: BTL1181113
-Node: POSIX/GNU1181842
-Node: Feature History1187620
-Node: Common Extensions1203939
-Node: Ranges and Locales1205222
-Ref: Ranges and Locales-Footnote-11209838
-Ref: Ranges and Locales-Footnote-21209865
-Ref: Ranges and Locales-Footnote-31210100
-Node: Contributors1210323
-Node: History summary1216320
-Node: Installation1217700
-Node: Gawk Distribution1218644
-Node: Getting1219128
-Node: Extracting1220091
-Node: Distribution contents1221729
-Node: Unix Installation1228209
-Node: Quick Installation1228891
-Node: Shell Startup Files1231305
-Node: Additional Configuration Options1232394
-Node: Configuration Philosophy1234709
-Node: Non-Unix Installation1237078
-Node: PC Installation1237538
-Node: PC Binary Installation1238376
-Node: PC Compiling1238811
-Node: PC Using1239928
-Node: Cygwin1243481
-Node: MSYS1244705
-Node: VMS Installation1245307
-Node: VMS Compilation1246098
-Ref: VMS Compilation-Footnote-11247327
-Node: VMS Dynamic Extensions1247385
-Node: VMS Installation Details1249070
-Node: VMS Running1251323
-Node: VMS GNV1255602
-Node: VMS Old Gawk1256337
-Node: Bugs1256808
-Node: Bug address1257471
-Node: Usenet1260453
-Node: Maintainers1261457
-Node: Other Versions1262642
-Node: Installation summary1269730
-Node: Notes1270939
-Node: Compatibility Mode1271733
-Node: Additions1272515
-Node: Accessing The Source1273440
-Node: Adding Code1274877
-Node: New Ports1281096
-Node: Derived Files1285471
-Ref: Derived Files-Footnote-11291131
-Ref: Derived Files-Footnote-21291166
-Ref: Derived Files-Footnote-31291764
-Node: Future Extensions1291878
-Node: Implementation Limitations1292536
-Node: Extension Design1293746
-Node: Old Extension Problems1294890
-Ref: Old Extension Problems-Footnote-11296408
-Node: Extension New Mechanism Goals1296465
-Ref: Extension New Mechanism Goals-Footnote-11299829
-Node: Extension Other Design Decisions1300018
-Node: Extension Future Growth1302131
-Node: Notes summary1302737
-Node: Basic Concepts1303895
-Node: Basic High Level1304576
-Ref: figure-general-flow1304858
-Ref: figure-process-flow1305543
-Ref: Basic High Level-Footnote-11308844
-Node: Basic Data Typing1309029
-Node: Glossary1312357
-Node: Copying1344242
-Node: GNU Free Documentation License1381785
-Node: Index1406905
+Node: Foreword344559
+Node: Foreword449001
+Node: Preface50533
+Ref: Preface-Footnote-153392
+Ref: Preface-Footnote-253501
+Ref: Preface-Footnote-353735
+Node: History53877
+Node: Names56229
+Ref: Names-Footnote-157333
+Node: This Manual57480
+Ref: This Manual-Footnote-164119
+Node: Conventions64219
+Node: Manual History66588
+Ref: Manual History-Footnote-169585
+Ref: Manual History-Footnote-269626
+Node: How To Contribute69700
+Node: Acknowledgments70626
+Node: Getting Started75563
+Node: Running gawk78002
+Node: One-shot79192
+Node: Read Terminal80455
+Node: Long82448
+Node: Executable Scripts83961
+Ref: Executable Scripts-Footnote-186594
+Node: Comments86697
+Node: Quoting89181
+Node: DOS Quoting94707
+Node: Sample Data Files96763
+Node: Very Simple99358
+Node: Two Rules105460
+Node: More Complex107345
+Node: Statements/Lines109677
+Ref: Statements/Lines-Footnote-1114161
+Node: Other Features114426
+Node: When115362
+Ref: When-Footnote-1117116
+Node: Intro Summary117181
+Node: Invoking Gawk118065
+Node: Command Line119579
+Node: Options120377
+Ref: Options-Footnote-1138291
+Ref: Options-Footnote-2138522
+Node: Other Arguments138547
+Node: Naming Standard Input142558
+Node: Environment Variables143768
+Node: AWKPATH Variable144326
+Ref: AWKPATH Variable-Footnote-1147738
+Ref: AWKPATH Variable-Footnote-2147772
+Node: AWKLIBPATH Variable148143
+Ref: AWKLIBPATH Variable-Footnote-1149840
+Node: Other Environment Variables150215
+Node: Exit Status154036
+Node: Include Files154713
+Node: Loading Shared Libraries158403
+Node: Obsolete159831
+Node: Undocumented160523
+Node: Invoking Summary160820
+Node: Regexp163661
+Node: Regexp Usage165115
+Node: Escape Sequences167152
+Node: Regexp Operators173393
+Node: Regexp Operator Details173878
+Ref: Regexp Operator Details-Footnote-1180310
+Node: Interval Expressions180457
+Ref: Interval Expressions-Footnote-1181878
+Node: Bracket Expressions181976
+Ref: table-char-classes184452
+Node: Leftmost Longest187778
+Node: Computed Regexps189081
+Node: GNU Regexp Operators192508
+Node: Case-sensitivity196245
+Ref: Case-sensitivity-Footnote-1199111
+Ref: Case-sensitivity-Footnote-2199346
+Node: Regexp Summary199454
+Node: Reading Files200920
+Node: Records203189
+Node: awk split records204264
+Node: gawk split records209539
+Ref: gawk split records-Footnote-1214272
+Node: Fields214309
+Node: Nonconstant Fields217050
+Ref: Nonconstant Fields-Footnote-1219286
+Node: Changing Fields219490
+Node: Field Separators225521
+Node: Default Field Splitting228219
+Node: Regexp Field Splitting229337
+Node: Single Character Fields232690
+Node: Command Line Field Separator233750
+Node: Full Line Fields236968
+Ref: Full Line Fields-Footnote-1238490
+Ref: Full Line Fields-Footnote-2238536
+Node: Field Splitting Summary238637
+Node: Constant Size240711
+Node: Fixed width data241443
+Node: Skipping intervening244910
+Node: Allowing trailing data245708
+Node: Fields with fixed data246745
+Node: Splitting By Content248263
+Ref: Splitting By Content-Footnote-1252046
+Node: More CSV252209
+Node: Testing field creation253519
+Node: Multiple Line255144
+Node: Getline261421
+Node: Plain Getline263890
+Node: Getline/Variable266463
+Node: Getline/File267614
+Node: Getline/Variable/File269002
+Ref: Getline/Variable/File-Footnote-1270607
+Node: Getline/Pipe270695
+Node: Getline/Variable/Pipe273399
+Node: Getline/Coprocess274534
+Node: Getline/Variable/Coprocess275801
+Node: Getline Notes276543
+Node: Getline Summary279340
+Ref: table-getline-variants279764
+Node: Read Timeout280512
+Ref: Read Timeout-Footnote-1284418
+Node: Retrying Input284476
+Node: Command-line directories285675
+Node: Input Summary286581
+Node: Input Exercises289753
+Node: Printing290187
+Node: Print292021
+Node: Print Examples293478
+Node: Output Separators296258
+Node: OFMT298275
+Node: Printf299631
+Node: Basic Printf300416
+Node: Control Letters301990
+Node: Format Modifiers307154
+Node: Printf Examples313169
+Node: Redirection315655
+Node: Special FD322496
+Ref: Special FD-Footnote-1325664
+Node: Special Files325738
+Node: Other Inherited Files326355
+Node: Special Network327356
+Node: Special Caveats328216
+Node: Close Files And Pipes329165
+Ref: table-close-pipe-return-values336072
+Ref: Close Files And Pipes-Footnote-1336885
+Ref: Close Files And Pipes-Footnote-2337033
+Node: Nonfatal337185
+Node: Output Summary339523
+Node: Output Exercises340745
+Node: Expressions341424
+Node: Values342612
+Node: Constants343290
+Node: Scalar Constants343981
+Ref: Scalar Constants-Footnote-1346491
+Node: Nondecimal-numbers346741
+Node: Regexp Constants349742
+Node: Using Constant Regexps350268
+Node: Standard Regexp Constants350890
+Node: Strong Regexp Constants354078
+Node: Variables357090
+Node: Using Variables357747
+Node: Assignment Options359657
+Node: Conversion362128
+Node: Strings And Numbers362652
+Ref: Strings And Numbers-Footnote-1365715
+Node: Locale influences conversions365824
+Ref: table-locale-affects368582
+Node: All Operators369200
+Node: Arithmetic Ops369829
+Node: Concatenation372545
+Ref: Concatenation-Footnote-1375392
+Node: Assignment Ops375499
+Ref: table-assign-ops380490
+Node: Increment Ops381803
+Node: Truth Values and Conditions385263
+Node: Truth Values386337
+Node: Typing and Comparison387385
+Node: Variable Typing388205
+Ref: Variable Typing-Footnote-1394668
+Ref: Variable Typing-Footnote-2394740
+Node: Comparison Operators394817
+Ref: table-relational-ops395236
+Node: POSIX String Comparison398731
+Ref: POSIX String Comparison-Footnote-1400426
+Ref: POSIX String Comparison-Footnote-2400565
+Node: Boolean Ops400649
+Ref: Boolean Ops-Footnote-1405131
+Node: Conditional Exp405223
+Node: Function Calls406959
+Node: Precedence410836
+Node: Locales414495
+Node: Expressions Summary416127
+Node: Patterns and Actions418700
+Node: Pattern Overview419820
+Node: Regexp Patterns421497
+Node: Expression Patterns422039
+Node: Ranges425820
+Node: BEGIN/END428928
+Node: Using BEGIN/END429689
+Ref: Using BEGIN/END-Footnote-1432443
+Node: I/O And BEGIN/END432549
+Node: BEGINFILE/ENDFILE434862
+Node: Empty438093
+Node: Using Shell Variables438410
+Node: Action Overview440684
+Node: Statements443009
+Node: If Statement444857
+Node: While Statement446352
+Node: Do Statement448380
+Node: For Statement449528
+Node: Switch Statement452699
+Node: Break Statement455140
+Node: Continue Statement457232
+Node: Next Statement459059
+Node: Nextfile Statement461442
+Node: Exit Statement464131
+Node: Built-in Variables466534
+Node: User-modified467667
+Node: Auto-set475434
+Ref: Auto-set-Footnote-1492241
+Ref: Auto-set-Footnote-2492447
+Node: ARGC and ARGV492503
+Node: Pattern Action Summary496716
+Node: Arrays499146
+Node: Array Basics500475
+Node: Array Intro501319
+Ref: figure-array-elements503294
+Ref: Array Intro-Footnote-1505998
+Node: Reference to Elements506126
+Node: Assigning Elements508590
+Node: Array Example509081
+Node: Scanning an Array510840
+Node: Controlling Scanning513862
+Ref: Controlling Scanning-Footnote-1520318
+Node: Numeric Array Subscripts520634
+Node: Uninitialized Subscripts522818
+Node: Delete524437
+Ref: Delete-Footnote-1527189
+Node: Multidimensional527246
+Node: Multiscanning530341
+Node: Arrays of Arrays531932
+Node: Arrays Summary536700
+Node: Functions538793
+Node: Built-in539831
+Node: Calling Built-in540912
+Node: Numeric Functions542908
+Ref: Numeric Functions-Footnote-1546936
+Ref: Numeric Functions-Footnote-2547584
+Ref: Numeric Functions-Footnote-3547632
+Node: String Functions547904
+Ref: String Functions-Footnote-1572045
+Ref: String Functions-Footnote-2572173
+Ref: String Functions-Footnote-3572421
+Node: Gory Details572508
+Ref: table-sub-escapes574299
+Ref: table-sub-proposed575818
+Ref: table-posix-sub577181
+Ref: table-gensub-escapes578722
+Ref: Gory Details-Footnote-1579545
+Node: I/O Functions579699
+Ref: table-system-return-values586153
+Ref: I/O Functions-Footnote-1588233
+Ref: I/O Functions-Footnote-2588381
+Node: Time Functions588501
+Ref: Time Functions-Footnote-1599172
+Ref: Time Functions-Footnote-2599240
+Ref: Time Functions-Footnote-3599398
+Ref: Time Functions-Footnote-4599509
+Ref: Time Functions-Footnote-5599621
+Ref: Time Functions-Footnote-6599848
+Node: Bitwise Functions600114
+Ref: table-bitwise-ops600708
+Ref: Bitwise Functions-Footnote-1606771
+Ref: Bitwise Functions-Footnote-2606944
+Node: Type Functions607135
+Node: I18N Functions609998
+Node: User-defined611649
+Node: Definition Syntax612461
+Ref: Definition Syntax-Footnote-1618155
+Node: Function Example618226
+Ref: Function Example-Footnote-1621148
+Node: Function Calling621170
+Node: Calling A Function621758
+Node: Variable Scope622716
+Node: Pass By Value/Reference625710
+Node: Function Caveats628354
+Ref: Function Caveats-Footnote-1630401
+Node: Return Statement630521
+Node: Dynamic Typing633500
+Node: Indirect Calls634430
+Ref: Indirect Calls-Footnote-1644682
+Node: Functions Summary644810
+Node: Library Functions647515
+Ref: Library Functions-Footnote-1651122
+Ref: Library Functions-Footnote-2651265
+Node: Library Names651436
+Ref: Library Names-Footnote-1655103
+Ref: Library Names-Footnote-2655326
+Node: General Functions655412
+Node: Strtonum Function656515
+Node: Assert Function659537
+Node: Round Function662863
+Node: Cliff Random Function664403
+Node: Ordinal Functions665419
+Ref: Ordinal Functions-Footnote-1668482
+Ref: Ordinal Functions-Footnote-2668734
+Node: Join Function668944
+Ref: Join Function-Footnote-1670714
+Node: Getlocaltime Function670914
+Node: Readfile Function674656
+Node: Shell Quoting676633
+Node: Data File Management678034
+Node: Filetrans Function678666
+Node: Rewind Function682762
+Node: File Checking684671
+Ref: File Checking-Footnote-1686005
+Node: Empty Files686206
+Node: Ignoring Assigns688185
+Node: Getopt Function689735
+Ref: Getopt Function-Footnote-1704946
+Node: Passwd Functions705146
+Ref: Passwd Functions-Footnote-1713985
+Node: Group Functions714073
+Ref: Group Functions-Footnote-1721971
+Node: Walking Arrays722178
+Node: Library Functions Summary725186
+Node: Library Exercises726592
+Node: Sample Programs727057
+Node: Running Examples727827
+Node: Clones728555
+Node: Cut Program729779
+Node: Egrep Program739919
+Node: Id Program748930
+Node: Split Program758877
+Ref: Split Program-Footnote-1768767
+Node: Tee Program768940
+Node: Uniq Program771730
+Node: Wc Program779318
+Node: Bytes vs. Characters779715
+Node: Using extensions781263
+Node: wc program782017
+Node: Miscellaneous Programs786882
+Node: Dupword Program788095
+Node: Alarm Program790125
+Node: Translate Program794980
+Ref: Translate Program-Footnote-1799545
+Node: Labels Program799815
+Ref: Labels Program-Footnote-1803166
+Node: Word Sorting803250
+Node: History Sorting807322
+Node: Extract Program809547
+Node: Simple Sed817601
+Node: Igawk Program820675
+Ref: Igawk Program-Footnote-1835006
+Ref: Igawk Program-Footnote-2835208
+Ref: Igawk Program-Footnote-3835330
+Node: Anagram Program835445
+Node: Signature Program838507
+Node: Programs Summary839754
+Node: Programs Exercises840968
+Ref: Programs Exercises-Footnote-1845098
+Node: Advanced Features845184
+Node: Nondecimal Data847251
+Node: Array Sorting848842
+Node: Controlling Array Traversal849542
+Ref: Controlling Array Traversal-Footnote-1857910
+Node: Array Sorting Functions858028
+Ref: Array Sorting Functions-Footnote-1863119
+Node: Two-way I/O863315
+Ref: Two-way I/O-Footnote-1871036
+Ref: Two-way I/O-Footnote-2871223
+Node: TCP/IP Networking871305
+Node: Profiling874423
+Node: Extension Philosophy883732
+Node: Advanced Features Summary885183
+Node: Internationalization887182
+Node: I18N and L10N888662
+Node: Explaining gettext889349
+Ref: Explaining gettext-Footnote-1895241
+Ref: Explaining gettext-Footnote-2895426
+Node: Programmer i18n895591
+Ref: Programmer i18n-Footnote-1900540
+Node: Translator i18n900589
+Node: String Extraction901383
+Ref: String Extraction-Footnote-1902515
+Node: Printf Ordering902601
+Ref: Printf Ordering-Footnote-1905387
+Node: I18N Portability905451
+Ref: I18N Portability-Footnote-1907907
+Node: I18N Example907970
+Ref: I18N Example-Footnote-1911245
+Ref: I18N Example-Footnote-2911318
+Node: Gawk I18N911427
+Node: I18N Summary912076
+Node: Debugger913417
+Node: Debugging914417
+Node: Debugging Concepts914858
+Node: Debugging Terms916667
+Node: Awk Debugging919242
+Ref: Awk Debugging-Footnote-1920187
+Node: Sample Debugging Session920319
+Node: Debugger Invocation920853
+Node: Finding The Bug922239
+Node: List of Debugger Commands928713
+Node: Breakpoint Control930046
+Node: Debugger Execution Control933740
+Node: Viewing And Changing Data937102
+Node: Execution Stack940643
+Node: Debugger Info942280
+Node: Miscellaneous Debugger Commands946351
+Node: Readline Support951413
+Node: Limitations952309
+Node: Debugging Summary954863
+Node: Namespaces956142
+Node: Global Namespace957253
+Node: Qualified Names958651
+Node: Default Namespace959650
+Node: Changing The Namespace960391
+Node: Naming Rules962005
+Node: Internal Name Management963853
+Node: Namespace Example964895
+Node: Namespace And Features967457
+Node: Namespace Summary968892
+Node: Arbitrary Precision Arithmetic970369
+Node: Computer Arithmetic971856
+Ref: table-numeric-ranges975622
+Ref: table-floating-point-ranges976115
+Ref: Computer Arithmetic-Footnote-1976773
+Node: Math Definitions976830
+Ref: table-ieee-formats980146
+Ref: Math Definitions-Footnote-1980749
+Node: MPFR features980854
+Node: FP Math Caution982572
+Ref: FP Math Caution-Footnote-1983644
+Node: Inexactness of computations984013
+Node: Inexact representation984973
+Node: Comparing FP Values986333
+Node: Errors accumulate987574
+Node: Getting Accuracy989007
+Node: Try To Round991717
+Node: Setting precision992616
+Ref: table-predefined-precision-strings993313
+Node: Setting the rounding mode995143
+Ref: table-gawk-rounding-modes995517
+Ref: Setting the rounding mode-Footnote-1999448
+Node: Arbitrary Precision Integers999627
+Ref: Arbitrary Precision Integers-Footnote-11002802
+Node: Checking for MPFR1002951
+Node: POSIX Floating Point Problems1004425
+Ref: POSIX Floating Point Problems-Footnote-11008710
+Node: Floating point summary1008748
+Node: Dynamic Extensions1010938
+Node: Extension Intro1012491
+Node: Plugin License1013757
+Node: Extension Mechanism Outline1014554
+Ref: figure-load-extension1014993
+Ref: figure-register-new-function1016558
+Ref: figure-call-new-function1017650
+Node: Extension API Description1019712
+Node: Extension API Functions Introduction1021425
+Ref: table-api-std-headers1023261
+Node: General Data Types1027510
+Ref: General Data Types-Footnote-11036140
+Node: Memory Allocation Functions1036439
+Ref: Memory Allocation Functions-Footnote-11040940
+Node: Constructor Functions1041039
+Node: API Ownership of MPFR and GMP Values1044505
+Node: Registration Functions1045818
+Node: Extension Functions1046518
+Node: Exit Callback Functions1051840
+Node: Extension Version String1053090
+Node: Input Parsers1053753
+Node: Output Wrappers1066474
+Node: Two-way processors1070986
+Node: Printing Messages1073251
+Ref: Printing Messages-Footnote-11074422
+Node: Updating ERRNO1074575
+Node: Requesting Values1075314
+Ref: table-value-types-returned1076051
+Node: Accessing Parameters1076987
+Node: Symbol Table Access1078224
+Node: Symbol table by name1078736
+Ref: Symbol table by name-Footnote-11081760
+Node: Symbol table by cookie1081888
+Ref: Symbol table by cookie-Footnote-11086073
+Node: Cached values1086137
+Ref: Cached values-Footnote-11089673
+Node: Array Manipulation1089826
+Ref: Array Manipulation-Footnote-11090917
+Node: Array Data Types1090954
+Ref: Array Data Types-Footnote-11093612
+Node: Array Functions1093704
+Node: Flattening Arrays1098202
+Node: Creating Arrays1105178
+Node: Redirection API1109945
+Node: Extension API Variables1112778
+Node: Extension Versioning1113489
+Ref: gawk-api-version1113918
+Node: Extension GMP/MPFR Versioning1115649
+Node: Extension API Informational Variables1117277
+Node: Extension API Boilerplate1118350
+Node: Changes from API V11122324
+Node: Finding Extensions1123896
+Node: Extension Example1124455
+Node: Internal File Description1125253
+Node: Internal File Ops1129333
+Ref: Internal File Ops-Footnote-11140683
+Node: Using Internal File Ops1140823
+Ref: Using Internal File Ops-Footnote-11143206
+Node: Extension Samples1143480
+Node: Extension Sample File Functions1145009
+Node: Extension Sample Fnmatch1152658
+Node: Extension Sample Fork1154145
+Node: Extension Sample Inplace1155363
+Node: Extension Sample Ord1158989
+Node: Extension Sample Readdir1159825
+Ref: table-readdir-file-types1160714
+Node: Extension Sample Revout1161781
+Node: Extension Sample Rev2way1162370
+Node: Extension Sample Read write array1163110
+Node: Extension Sample Readfile1165052
+Node: Extension Sample Time1166147
+Node: Extension Sample API Tests1167899
+Node: gawkextlib1168391
+Node: Extension summary1171309
+Node: Extension Exercises1175011
+Node: Language History1176253
+Node: V7/SVR3.11177909
+Node: SVR41180061
+Node: POSIX1181495
+Node: BTL1182876
+Node: POSIX/GNU1183605
+Node: Feature History1189383
+Node: Common Extensions1205702
+Node: Ranges and Locales1206985
+Ref: Ranges and Locales-Footnote-11211601
+Ref: Ranges and Locales-Footnote-21211628
+Ref: Ranges and Locales-Footnote-31211863
+Node: Contributors1212086
+Node: History summary1218083
+Node: Installation1219463
+Node: Gawk Distribution1220407
+Node: Getting1220891
+Node: Extracting1221854
+Node: Distribution contents1223492
+Node: Unix Installation1229972
+Node: Quick Installation1230654
+Node: Shell Startup Files1233068
+Node: Additional Configuration Options1234157
+Node: Configuration Philosophy1236472
+Node: Non-Unix Installation1238841
+Node: PC Installation1239301
+Node: PC Binary Installation1240139
+Node: PC Compiling1240574
+Node: PC Using1241691
+Node: Cygwin1245244
+Node: MSYS1246468
+Node: VMS Installation1247070
+Node: VMS Compilation1247861
+Ref: VMS Compilation-Footnote-11249090
+Node: VMS Dynamic Extensions1249148
+Node: VMS Installation Details1250833
+Node: VMS Running1253086
+Node: VMS GNV1257365
+Node: VMS Old Gawk1258100
+Node: Bugs1258571
+Node: Bug address1259234
+Node: Usenet1262216
+Node: Maintainers1263220
+Node: Other Versions1264405
+Node: Installation summary1271493
+Node: Notes1272702
+Node: Compatibility Mode1273496
+Node: Additions1274278
+Node: Accessing The Source1275203
+Node: Adding Code1276640
+Node: New Ports1282859
+Node: Derived Files1287234
+Ref: Derived Files-Footnote-11292894
+Ref: Derived Files-Footnote-21292929
+Ref: Derived Files-Footnote-31293527
+Node: Future Extensions1293641
+Node: Implementation Limitations1294299
+Node: Extension Design1295509
+Node: Old Extension Problems1296653
+Ref: Old Extension Problems-Footnote-11298171
+Node: Extension New Mechanism Goals1298228
+Ref: Extension New Mechanism Goals-Footnote-11301592
+Node: Extension Other Design Decisions1301781
+Node: Extension Future Growth1303894
+Node: Notes summary1304500
+Node: Basic Concepts1305658
+Node: Basic High Level1306339
+Ref: figure-general-flow1306621
+Ref: figure-process-flow1307306
+Ref: Basic High Level-Footnote-11310607
+Node: Basic Data Typing1310792
+Node: Glossary1314120
+Node: Copying1346005
+Node: GNU Free Documentation License1383548
+Node: Index1408668
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index d211e482..7f9816aa 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -868,6 +868,7 @@ particular records in a file and perform operations upon them.
 * TCP/IP Networking::                   Using @command{gawk} for network
                                         programming.
 * Profiling::                           Profiling your @command{awk} programs.
+* Extension Philosophy::                What should be built-in and what should not.
 * Advanced Features Summary::           Summary of advanced features.
 * I18N and L10N::                       Internationalization and Localization.
 * Explaining gettext::                  How GNU @command{gettext} works.
@@ -29249,6 +29250,7 @@ discusses the ability to dynamically add new built-in functions to
 * Two-way I/O::                 Two-way communications with another process.
 * TCP/IP Networking::           Using @command{gawk} for network programming.
 * Profiling::                   Profiling your @command{awk} programs.
+* Extension Philosophy::        What should be built-in and what should not.
 * Advanced Features Summary::   Summary of advanced features.
 @end menu
 
@@ -30523,6 +30525,52 @@ Profiling and pretty-printing also preserve the original format of numeric
 constants; if you used an octal or hexadecimal value in your source
 code, it will appear that way in the output.
 
+@node Extension Philosophy
+@section Builtin Features vs.@: Extensions
+
+As this and subsequent @value{CHAPTER}s show, @command{gawk} has a
+large number of extensions over standard @command{awk} built-in to
+the program.  These have developed over time.  More recently, the
+focus has moved to using the extension mechanism (@pxref{Dynamic Extensions})
+for adding features.  This @value{SECTION} discusses the ``guiding philosophy''
+behind what should be added to the interpreter as a built-in
+feature vs.@: what should be done in extensions.
+
+There are several goals:
+
+@enumerate 1
+@item
+Keep the language @command{awk}; it should not become unrecognizable, even
+if programs in it will only run on @command{gawk}.
+
+@item
+Keep the core from getting any larger unless absolutely necessary.
+
+@item
+Add new functionality either in @command{awk} scripts (@option{-f},
+@code{@@include}) or in loadable extensions written in C or C++
+(@option{-l}, @code{@@load}).
+
+@item
+Extend the core interpreter only if some feature is:
+
+@c sublist
+@enumerate A
+@item
+Truly desirable.
+@item
+Cannot be done via (2) or (3) above.
+@item
+Can be implemented without too much pain in the core.
+@end enumerate
+@end enumerate
+
+Combining modules with @command{awk} files is a powerful technique.
+Some of the sample extensions demonstrate this.
+
+Loading extensions and library files should not be done automatically,
+because then there's overhead that most users don't want or need.
+
 @node Advanced Features Summary
 @section Summary
 
@@ -30565,6 +30613,9 @@ you tune them more easily.  Sending the @code{USR1} signal while profiling cause
 @item
 You can also just ``pretty-print'' the program.
 
+@item
+New features should be developed using the extension mechansim if possible, and added
+to the core interpreter only as a last resort.
 @end itemize
 
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index a5c65a3e..ceacad6b 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -863,6 +863,7 @@ particular records in a file and perform operations upon them.
 * TCP/IP Networking::                   Using @command{gawk} for network
                                         programming.
 * Profiling::                           Profiling your @command{awk} programs.
+* Extension Philosophy::                What should be built-in and what should not.
 * Advanced Features Summary::           Summary of advanced features.
 * I18N and L10N::                       Internationalization and Localization.
 * Explaining gettext::                  How GNU @command{gettext} works.
@@ -28215,6 +28216,7 @@ discusses the ability to dynamically add new built-in functions to
 * Two-way I/O::                 Two-way communications with another process.
 * TCP/IP Networking::           Using @command{gawk} for network programming.
 * Profiling::                   Profiling your @command{awk} programs.
+* Extension Philosophy::        What should be built-in and what should not.
 * Advanced Features Summary::   Summary of advanced features.
 @end menu
 
@@ -29489,6 +29491,52 @@ Profiling and pretty-printing also preserve the original format of numeric
 constants; if you used an octal or hexadecimal value in your source
 code, it will appear that way in the output.
 
+@node Extension Philosophy
+@section Builtin Features vs.@: Extensions
+
+As this and subsequent @value{CHAPTER}s show, @command{gawk} has a
+large number of extensions over standard @command{awk} built-in to
+the program.  These have developed over time.  More recently, the
+focus has moved to using the extension mechanism (@pxref{Dynamic Extensions})
+for adding features.  This @value{SECTION} discusses the ``guiding philosophy''
+behind what should be added to the interpreter as a built-in
+feature vs.@: what should be done in extensions.
+
+There are several goals:
+
+@enumerate 1
+@item
+Keep the language @command{awk}; it should not become unrecognizable, even
+if programs in it will only run on @command{gawk}.
+
+@item
+Keep the core from getting any larger unless absolutely necessary.
+
+@item
+Add new functionality either in @command{awk} scripts (@option{-f},
+@code{@@include}) or in loadable extensions written in C or C++
+(@option{-l}, @code{@@load}).
+
+@item
+Extend the core interpreter only if some feature is:
+
+@c sublist
+@enumerate A
+@item
+Truly desirable.
+@item
+Cannot be done via (2) or (3) above.
+@item
+Can be implemented without too much pain in the core.
+@end enumerate
+@end enumerate
+
+Combining modules with @command{awk} files is a powerful technique.
+Some of the sample extensions demonstrate this.
+
+Loading extensions and library files should not be done automatically,
+because then there's overhead that most users don't want or need.
+
 @node Advanced Features Summary
 @section Summary
 
@@ -29531,6 +29579,9 @@ you tune them more easily.  Sending the @code{USR1} signal while profiling cause
 @item
 You can also just ``pretty-print'' the program.
 
+@item
+New features should be developed using the extension mechansim if possible, and added
+to the core interpreter only as a last resort.
 @end itemize