diff options
| author | Arnold D. Robbins <arnold@skeeve.com> | 2014-03-28 15:01:23 +0300 |
|---|---|---|
| committer | Arnold D. Robbins <arnold@skeeve.com> | 2014-03-28 15:01:23 +0300 |
| commit | 55e88440b48a274e14b395a20181d71f160a4b5a (patch) | |
| tree | d33b41f341783f5839338ec07612518d3278666b | |
| parent | 573c640c1e99757f36d0f1e7099624d6170cb8b8 (diff) | |
| parent | 97ffd21c9b52c3405d27fb9f8d69480a9e681c4e (diff) | |
| download | egawk-55e88440b48a274e14b395a20181d71f160a4b5a.tar.gz egawk-55e88440b48a274e14b395a20181d71f160a4b5a.tar.bz2 egawk-55e88440b48a274e14b395a20181d71f160a4b5a.zip | |
Merge branch 'gawk-4.1-stable'
| -rw-r--r-- | doc/ChangeLog | 9 | ||||
| -rw-r--r-- | doc/gawk.info | 1095 | ||||
| -rw-r--r-- | doc/gawk.texi | 363 | ||||
| -rw-r--r-- | doc/gawktexi.in | 363 |
4 files changed, 1211 insertions, 619 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 8d6166a8..4ef12ca6 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,12 @@ +2014-03-28 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor cleanups to the indexing. + + Unrelated: + + * gawktexi.in: Merge in changes needed for creating valid + DocBook XML. Works with post-5.2 Texinfo and dblatex! + 2014-03-27 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Finish the massive indexing improvements such that diff --git a/doc/gawk.info b/doc/gawk.info index 4c1d5972..d11fdac9 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9,8 +9,7 @@ START-INFO-DIR-ENTRY * awk: (gawk)Invoking gawk. Text scanning and processing. END-INFO-DIR-ENTRY - Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, -2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, 2014 + Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2014 Free Software Foundation, Inc. @@ -41,8 +40,7 @@ General Introduction This file documents `awk', a program that you can use to select particular records in a file and perform operations upon them. - Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, -2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, 2014 + Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2014 Free Software Foundation, Inc. @@ -23158,7 +23156,7 @@ The following functions relate to individual array elements. strings (*note Conversion::); thus using integral values is safest. As with _all_ strings passed into `gawk' from an extension, the - string value of `index' must come from the api-provided functions + string value of `index' must come from the API-provided functions `api_malloc()', `api_calloc()' or `api_realloc()' and `gawk' releases the storage. @@ -28023,7 +28021,7 @@ D.1 What a Program Does ======================= At the most basic level, the job of a program is to process some input -data and produce results. See *note figure-general-flow::. +data and produce results. See *note figure-general-flow::. _______ +------+ / \ +---------+ @@ -28407,8 +28405,8 @@ Dynamic Regular Expression (*Note Computed Regexps::.) Environment - A collection of strings, of the form NAME`='VAL, that each program - has available to it. Users generally place values into the + A collection of strings, of the form NAME`='`val', that each + program has available to it. Users generally place values into the environment in order to provide information to various programs. Typical examples are the environment variables `HOME' and `PATH'. @@ -28823,7 +28821,6 @@ GNU General Public License ************************** Version 3, 29 June 2007 - Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/' Everyone is permitted to copy and distribute verbatim copies of this @@ -29546,7 +29543,6 @@ GNU Free Documentation License ****************************** Version 1.3, 3 November 2008 - Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. `http://fsf.org/' @@ -30447,7 +30443,7 @@ Index * asterisk (*), **= operator: Assignment Ops. (line 129) * asterisk (*), *= operator <1>: Precedence. (line 95) * asterisk (*), *= operator: Assignment Ops. (line 129) -* atan2() function: Numeric Functions. (line 11) +* atan2: Numeric Functions. (line 11) * automatic displays, in debugger: Debugger Info. (line 24) * awf (amazingly workable formatter) program: Glossary. (line 25) * awk debugging, enabling: Options. (line 108) @@ -30671,7 +30667,7 @@ Index * Brown, Martin: Contributors. (line 82) * BSD-based operating systems: Glossary. (line 616) * bt debugger command (alias for backtrace): Execution Stack. (line 13) -* Buening, Andreas <1>: Bugs. (line 71) +* Buening, Andreas <1>: Bugs. (line 70) * Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) * buffering, input/output <1>: Two-way I/O. (line 70) @@ -31036,6 +31032,7 @@ Index (line 67) * debugger commands, watch: Viewing And Changing Data. (line 67) +* debugger default list amount: Debugger Info. (line 69) * debugger history file: Debugger Info. (line 80) * debugger history size: Debugger Info. (line 65) * debugger options: Debugger Info. (line 57) @@ -31166,8 +31163,8 @@ Index * dynamically loaded extensions: Dynamic Extensions. (line 6) * e debugger command (alias for enable): Breakpoint Control. (line 73) * EBCDIC: Ordinal Functions. (line 45) -* effective group id of gawk user: Auto-set. (line 147) -* effective user id of gawk user: Auto-set. (line 151) +* effective group ID of gawk user: Auto-set. (line 147) +* effective user ID of gawk user: Auto-set. (line 151) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Bracket Expressions. (line 24) * egrep.awk program: Egrep Program. (line 54) @@ -31316,7 +31313,7 @@ Index * f debugger command (alias for frame): Execution Stack. (line 25) * false, logical: Truth Values. (line 6) * FDL (Free Documentation License): GNU Free Documentation License. - (line 6) + (line 7) * features, adding to gawk: Adding Code. (line 6) * features, advanced, See advanced features: Obsolete. (line 6) * features, deprecated: Obsolete. (line 6) @@ -31461,7 +31458,7 @@ Index (line 27) * frame debugger command: Execution Stack. (line 25) * Free Documentation License (FDL): GNU Free Documentation License. - (line 6) + (line 7) * Free Software Foundation (FSF) <1>: Glossary. (line 297) * Free Software Foundation (FSF) <2>: Getting. (line 10) * Free Software Foundation (FSF): Manual History. (line 6) @@ -31686,7 +31683,7 @@ Index * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 49) * GNU Free Documentation License: GNU Free Documentation License. - (line 6) + (line 7) * GNU General Public License: Glossary. (line 306) * GNU Lesser General Public License: Glossary. (line 397) * GNU long options <1>: Options. (line 6) @@ -31705,7 +31702,7 @@ Index * Grigera, Juan: Contributors. (line 57) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) -* group id of gawk user: Auto-set. (line 186) +* group ID of gawk user: Auto-set. (line 186) * groups, information about: Group Functions. (line 6) * gsub <1>: String Functions. (line 135) * gsub: Using Constant Regexps. @@ -31980,7 +31977,7 @@ Index * mail-list file: Sample Data Files. (line 6) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) -* Malmberg, John <1>: Bugs. (line 72) +* Malmberg, John <1>: Bugs. (line 70) * Malmberg, John: Acknowledgments. (line 60) * mark parity: Ordinal Functions. (line 45) * marked string extraction (internationalization): String Extraction. @@ -32191,7 +32188,7 @@ Index * p debugger command (alias for print): Viewing And Changing Data. (line 36) * P1003.1 POSIX standard: Glossary. (line 454) -* parent process id of gawk process: Auto-set. (line 195) +* parent process ID of gawk process: Auto-set. (line 195) * parentheses (), in a profile: Profiling. (line 146) * parentheses (), regexp operator: Regexp Operators. (line 79) * password file: Passwd Functions. (line 16) @@ -32222,7 +32219,7 @@ Index (line 6) * pipe, input: Getline/Pipe. (line 9) * pipe, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 73) +* Pitts, Dave <1>: Bugs. (line 70) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) * plug-in: Extension Intro. (line 6) @@ -32355,8 +32352,8 @@ Index * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) -* process group id of gawk process: Auto-set. (line 189) -* process id of gawk process: Auto-set. (line 192) +* process group idIDof gawk process: Auto-set. (line 189) +* process ID of gawk process: Auto-set. (line 192) * processes, two-way communications with: Two-way I/O. (line 23) * processing data: Basic High Level. (line 6) * PROCINFO array <1>: Passwd Functions. (line 6) @@ -32426,7 +32423,7 @@ Index * range expressions (regexps): Bracket Expressions. (line 6) * range patterns: Ranges. (line 6) * range patterns, line continuation and: Ranges. (line 65) -* Rankin, Pat <1>: Bugs. (line 72) +* Rankin, Pat <1>: Bugs. (line 70) * Rankin, Pat <2>: Contributors. (line 37) * Rankin, Pat <3>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 60) @@ -33100,530 +33097,530 @@ Index Tag Table: -Node: Top1366 -Node: Foreword40929 -Node: Preface45274 -Ref: Preface-Footnote-148327 -Ref: Preface-Footnote-248423 -Node: History48655 -Node: Names51029 -Ref: Names-Footnote-152506 -Node: This Manual52578 -Ref: This Manual-Footnote-158352 -Node: Conventions58452 -Node: Manual History60608 -Ref: Manual History-Footnote-164056 -Ref: Manual History-Footnote-264097 -Node: How To Contribute64171 -Node: Acknowledgments65315 -Node: Getting Started69509 -Node: Running gawk71888 -Node: One-shot73074 -Node: Read Terminal74299 -Ref: Read Terminal-Footnote-175949 -Ref: Read Terminal-Footnote-276225 -Node: Long76396 -Node: Executable Scripts77772 -Ref: Executable Scripts-Footnote-179605 -Ref: Executable Scripts-Footnote-279707 -Node: Comments80254 -Node: Quoting82721 -Node: DOS Quoting87344 -Node: Sample Data Files88019 -Node: Very Simple90534 -Node: Two Rules95185 -Node: More Complex97083 -Ref: More Complex-Footnote-1100013 -Node: Statements/Lines100098 -Ref: Statements/Lines-Footnote-1104561 -Node: Other Features104826 -Node: When105754 -Node: Invoking Gawk107901 -Node: Command Line109364 -Node: Options110147 -Ref: Options-Footnote-1125525 -Node: Other Arguments125550 -Node: Naming Standard Input128208 -Node: Environment Variables129302 -Node: AWKPATH Variable129860 -Ref: AWKPATH Variable-Footnote-1132641 -Ref: AWKPATH Variable-Footnote-2132686 -Node: AWKLIBPATH Variable132946 -Node: Other Environment Variables133664 -Node: Exit Status136627 -Node: Include Files137302 -Node: Loading Shared Libraries140871 -Node: Obsolete142235 -Node: Undocumented142932 -Node: Regexp143174 -Node: Regexp Usage144563 -Node: Escape Sequences146588 -Node: Regexp Operators152257 -Ref: Regexp Operators-Footnote-1159637 -Ref: Regexp Operators-Footnote-2159784 -Node: Bracket Expressions159882 -Ref: table-char-classes161772 -Node: GNU Regexp Operators164295 -Node: Case-sensitivity168018 -Ref: Case-sensitivity-Footnote-1170986 -Ref: Case-sensitivity-Footnote-2171221 -Node: Leftmost Longest171329 -Node: Computed Regexps172530 -Node: Reading Files175867 -Node: Records177869 -Ref: Records-Footnote-1187392 -Node: Fields187429 -Ref: Fields-Footnote-1190385 -Node: Nonconstant Fields190471 -Node: Changing Fields192677 -Node: Field Separators198636 -Node: Default Field Splitting201338 -Node: Regexp Field Splitting202455 -Node: Single Character Fields205797 -Node: Command Line Field Separator206856 -Node: Full Line Fields210198 -Ref: Full Line Fields-Footnote-1210706 -Node: Field Splitting Summary210752 -Ref: Field Splitting Summary-Footnote-1213851 -Node: Constant Size213952 -Node: Splitting By Content218559 -Ref: Splitting By Content-Footnote-1222308 -Node: Multiple Line222348 -Ref: Multiple Line-Footnote-1228195 -Node: Getline228374 -Node: Plain Getline230590 -Node: Getline/Variable232685 -Node: Getline/File233832 -Node: Getline/Variable/File235173 -Ref: Getline/Variable/File-Footnote-1236772 -Node: Getline/Pipe236859 -Node: Getline/Variable/Pipe239558 -Node: Getline/Coprocess240665 -Node: Getline/Variable/Coprocess241917 -Node: Getline Notes242654 -Node: Getline Summary245441 -Ref: table-getline-variants245849 -Node: Read Timeout246761 -Ref: Read Timeout-Footnote-1250502 -Node: Command line directories250559 -Node: Printing251189 -Node: Print252820 -Node: Print Examples254157 -Node: Output Separators256941 -Node: OFMT258957 -Node: Printf260315 -Node: Basic Printf261221 -Node: Control Letters262760 -Node: Format Modifiers266572 -Node: Printf Examples272581 -Node: Redirection275293 -Node: Special Files282267 -Node: Special FD282800 -Ref: Special FD-Footnote-1286425 -Node: Special Network286499 -Node: Special Caveats287349 -Node: Close Files And Pipes288145 -Ref: Close Files And Pipes-Footnote-1295128 -Ref: Close Files And Pipes-Footnote-2295276 -Node: Expressions295426 -Node: Values296558 -Node: Constants297234 -Node: Scalar Constants297914 -Ref: Scalar Constants-Footnote-1298773 -Node: Nondecimal-numbers298955 -Node: Regexp Constants301955 -Node: Using Constant Regexps302430 -Node: Variables305485 -Node: Using Variables306140 -Node: Assignment Options307864 -Node: Conversion309739 -Ref: table-locale-affects315239 -Ref: Conversion-Footnote-1315863 -Node: All Operators315972 -Node: Arithmetic Ops316602 -Node: Concatenation319107 -Ref: Concatenation-Footnote-1321895 -Node: Assignment Ops322015 -Ref: table-assign-ops327003 -Node: Increment Ops328334 -Node: Truth Values and Conditions331768 -Node: Truth Values332851 -Node: Typing and Comparison333900 -Node: Variable Typing334693 -Ref: Variable Typing-Footnote-1338590 -Node: Comparison Operators338712 -Ref: table-relational-ops339122 -Node: POSIX String Comparison342670 -Ref: POSIX String Comparison-Footnote-1343626 -Node: Boolean Ops343764 -Ref: Boolean Ops-Footnote-1347834 -Node: Conditional Exp347925 -Node: Function Calls349657 -Node: Precedence353251 -Node: Locales356920 -Node: Patterns and Actions358009 -Node: Pattern Overview359063 -Node: Regexp Patterns360732 -Node: Expression Patterns361275 -Node: Ranges365056 -Node: BEGIN/END368160 -Node: Using BEGIN/END368922 -Ref: Using BEGIN/END-Footnote-1371658 -Node: I/O And BEGIN/END371764 -Node: BEGINFILE/ENDFILE374046 -Node: Empty376960 -Node: Using Shell Variables377277 -Node: Action Overview379562 -Node: Statements381919 -Node: If Statement383773 -Node: While Statement385272 -Node: Do Statement387316 -Node: For Statement388472 -Node: Switch Statement391624 -Node: Break Statement393778 -Node: Continue Statement395768 -Node: Next Statement397561 -Node: Nextfile Statement399951 -Node: Exit Statement402606 -Node: Built-in Variables405022 -Node: User-modified406117 -Ref: User-modified-Footnote-1414475 -Node: Auto-set414537 -Ref: Auto-set-Footnote-1427993 -Ref: Auto-set-Footnote-2428198 -Node: ARGC and ARGV428254 -Node: Arrays432108 -Node: Array Basics433613 -Node: Array Intro434439 -Node: Reference to Elements438756 -Node: Assigning Elements441026 -Node: Array Example441517 -Node: Scanning an Array443249 -Node: Controlling Scanning445563 -Ref: Controlling Scanning-Footnote-1450650 -Node: Delete450966 -Ref: Delete-Footnote-1453731 -Node: Numeric Array Subscripts453788 -Node: Uninitialized Subscripts455971 -Node: Multidimensional457598 -Node: Multiscanning460691 -Node: Arrays of Arrays462280 -Node: Functions466920 -Node: Built-in467739 -Node: Calling Built-in468817 -Node: Numeric Functions470805 -Ref: Numeric Functions-Footnote-1474637 -Ref: Numeric Functions-Footnote-2474994 -Ref: Numeric Functions-Footnote-3475042 -Node: String Functions475311 -Ref: String Functions-Footnote-1498269 -Ref: String Functions-Footnote-2498398 -Ref: String Functions-Footnote-3498646 -Node: Gory Details498733 -Ref: table-sub-escapes500412 -Ref: table-sub-posix-92501766 -Ref: table-sub-proposed503117 -Ref: table-posix-sub504471 -Ref: table-gensub-escapes506016 -Ref: Gory Details-Footnote-1507192 -Ref: Gory Details-Footnote-2507243 -Node: I/O Functions507394 -Ref: I/O Functions-Footnote-1514384 -Node: Time Functions514531 -Ref: Time Functions-Footnote-1525514 -Ref: Time Functions-Footnote-2525582 -Ref: Time Functions-Footnote-3525740 -Ref: Time Functions-Footnote-4525851 -Ref: Time Functions-Footnote-5525963 -Ref: Time Functions-Footnote-6526190 -Node: Bitwise Functions526456 -Ref: table-bitwise-ops527018 -Ref: Bitwise Functions-Footnote-1531239 -Node: Type Functions531423 -Node: I18N Functions532574 -Node: User-defined534201 -Node: Definition Syntax535005 -Ref: Definition Syntax-Footnote-1539919 -Node: Function Example539988 -Ref: Function Example-Footnote-1542637 -Node: Function Caveats542659 -Node: Calling A Function543177 -Node: Variable Scope544132 -Node: Pass By Value/Reference547095 -Node: Return Statement550603 -Node: Dynamic Typing553584 -Node: Indirect Calls554515 -Node: Library Functions564202 -Ref: Library Functions-Footnote-1567715 -Ref: Library Functions-Footnote-2567858 -Node: Library Names568029 -Ref: Library Names-Footnote-1571502 -Ref: Library Names-Footnote-2571722 -Node: General Functions571808 -Node: Strtonum Function572836 -Node: Assert Function575766 -Node: Round Function579092 -Node: Cliff Random Function580633 -Node: Ordinal Functions581649 -Ref: Ordinal Functions-Footnote-1584726 -Ref: Ordinal Functions-Footnote-2584978 -Node: Join Function585189 -Ref: Join Function-Footnote-1586960 -Node: Getlocaltime Function587160 -Node: Readfile Function590901 -Node: Data File Management592740 -Node: Filetrans Function593372 -Node: Rewind Function597441 -Node: File Checking598828 -Node: Empty Files599922 -Node: Ignoring Assigns602152 -Node: Getopt Function603706 -Ref: Getopt Function-Footnote-1615009 -Node: Passwd Functions615212 -Ref: Passwd Functions-Footnote-1624190 -Node: Group Functions624278 -Node: Walking Arrays632362 -Node: Sample Programs634498 -Node: Running Examples635172 -Node: Clones635900 -Node: Cut Program637124 -Node: Egrep Program646975 -Ref: Egrep Program-Footnote-1654748 -Node: Id Program654858 -Node: Split Program658507 -Ref: Split Program-Footnote-1662026 -Node: Tee Program662154 -Node: Uniq Program664957 -Node: Wc Program672386 -Ref: Wc Program-Footnote-1676652 -Ref: Wc Program-Footnote-2676852 -Node: Miscellaneous Programs676944 -Node: Dupword Program678132 -Node: Alarm Program680163 -Node: Translate Program684970 -Ref: Translate Program-Footnote-1689357 -Ref: Translate Program-Footnote-2689605 -Node: Labels Program689739 -Ref: Labels Program-Footnote-1693110 -Node: Word Sorting693194 -Node: History Sorting697078 -Node: Extract Program698917 -Ref: Extract Program-Footnote-1706420 -Node: Simple Sed706548 -Node: Igawk Program709610 -Ref: Igawk Program-Footnote-1724767 -Ref: Igawk Program-Footnote-2724968 -Node: Anagram Program725106 -Node: Signature Program728174 -Node: Advanced Features729274 -Node: Nondecimal Data731160 -Node: Array Sorting732743 -Node: Controlling Array Traversal733440 -Node: Array Sorting Functions741724 -Ref: Array Sorting Functions-Footnote-1745593 -Node: Two-way I/O745787 -Ref: Two-way I/O-Footnote-1751219 -Node: TCP/IP Networking751301 -Node: Profiling754145 -Node: Internationalization761648 -Node: I18N and L10N763073 -Node: Explaining gettext763759 -Ref: Explaining gettext-Footnote-1768827 -Ref: Explaining gettext-Footnote-2769011 -Node: Programmer i18n769176 -Node: Translator i18n773378 -Node: String Extraction774172 -Ref: String Extraction-Footnote-1775133 -Node: Printf Ordering775219 -Ref: Printf Ordering-Footnote-1778001 -Node: I18N Portability778065 -Ref: I18N Portability-Footnote-1780514 -Node: I18N Example780577 -Ref: I18N Example-Footnote-1783215 -Node: Gawk I18N783287 -Node: Debugger783908 -Node: Debugging784879 -Node: Debugging Concepts785312 -Node: Debugging Terms787168 -Node: Awk Debugging789765 -Node: Sample Debugging Session790657 -Node: Debugger Invocation791177 -Node: Finding The Bug792510 -Node: List of Debugger Commands798997 -Node: Breakpoint Control800331 -Node: Debugger Execution Control803995 -Node: Viewing And Changing Data807355 -Node: Execution Stack810711 -Node: Debugger Info812178 -Node: Miscellaneous Debugger Commands816160 -Node: Readline Support821336 -Node: Limitations822167 -Node: Arbitrary Precision Arithmetic824419 -Ref: Arbitrary Precision Arithmetic-Footnote-1826068 -Node: General Arithmetic826216 -Node: Floating Point Issues827936 -Node: String Conversion Precision828817 -Ref: String Conversion Precision-Footnote-1830522 -Node: Unexpected Results830631 -Node: POSIX Floating Point Problems832784 -Ref: POSIX Floating Point Problems-Footnote-1836609 -Node: Integer Programming836647 -Node: Floating-point Programming838386 -Ref: Floating-point Programming-Footnote-1844717 -Ref: Floating-point Programming-Footnote-2844987 -Node: Floating-point Representation845251 -Node: Floating-point Context846416 -Ref: table-ieee-formats847255 -Node: Rounding Mode848639 -Ref: table-rounding-modes849118 -Ref: Rounding Mode-Footnote-1852133 -Node: Gawk and MPFR852312 -Node: Arbitrary Precision Floats853567 -Ref: Arbitrary Precision Floats-Footnote-1856010 -Node: Setting Precision856326 -Ref: table-predefined-precision-strings857012 -Node: Setting Rounding Mode859157 -Ref: table-gawk-rounding-modes859561 -Node: Floating-point Constants860748 -Node: Changing Precision862177 -Ref: Changing Precision-Footnote-1863574 -Node: Exact Arithmetic863748 -Node: Arbitrary Precision Integers866886 -Ref: Arbitrary Precision Integers-Footnote-1869901 -Node: Dynamic Extensions870048 -Node: Extension Intro871506 -Node: Plugin License872771 -Node: Extension Mechanism Outline873456 -Ref: load-extension873873 -Ref: load-new-function875351 -Ref: call-new-function876346 -Node: Extension API Description878361 -Node: Extension API Functions Introduction879648 -Node: General Data Types884575 -Ref: General Data Types-Footnote-1890270 -Node: Requesting Values890569 -Ref: table-value-types-returned891306 -Node: Memory Allocation Functions892260 -Ref: Memory Allocation Functions-Footnote-1895006 -Node: Constructor Functions895102 -Node: Registration Functions896860 -Node: Extension Functions897545 -Node: Exit Callback Functions899847 -Node: Extension Version String901096 -Node: Input Parsers901746 -Node: Output Wrappers911503 -Node: Two-way processors916013 -Node: Printing Messages918221 -Ref: Printing Messages-Footnote-1919298 -Node: Updating `ERRNO'919450 -Node: Accessing Parameters920189 -Node: Symbol Table Access921419 -Node: Symbol table by name921933 -Node: Symbol table by cookie923909 -Ref: Symbol table by cookie-Footnote-1928041 -Node: Cached values928104 -Ref: Cached values-Footnote-1931594 -Node: Array Manipulation931685 -Ref: Array Manipulation-Footnote-1932783 -Node: Array Data Types932822 -Ref: Array Data Types-Footnote-1935525 -Node: Array Functions935617 -Node: Flattening Arrays939453 -Node: Creating Arrays946305 -Node: Extension API Variables951030 -Node: Extension Versioning951666 -Node: Extension API Informational Variables953567 -Node: Extension API Boilerplate954653 -Node: Finding Extensions958457 -Node: Extension Example959017 -Node: Internal File Description959747 -Node: Internal File Ops963838 -Ref: Internal File Ops-Footnote-1975347 -Node: Using Internal File Ops975487 -Ref: Using Internal File Ops-Footnote-1977840 -Node: Extension Samples978106 -Node: Extension Sample File Functions979630 -Node: Extension Sample Fnmatch988115 -Node: Extension Sample Fork989884 -Node: Extension Sample Inplace991097 -Node: Extension Sample Ord992875 -Node: Extension Sample Readdir993711 -Node: Extension Sample Revout995243 -Node: Extension Sample Rev2way995836 -Node: Extension Sample Read write array996526 -Node: Extension Sample Readfile998409 -Node: Extension Sample API Tests999509 -Node: Extension Sample Time1000034 -Node: gawkextlib1001398 -Node: Language History1004179 -Node: V7/SVR3.11005772 -Node: SVR41008092 -Node: POSIX1009534 -Node: BTL1010920 -Node: POSIX/GNU1011654 -Node: Feature History1017253 -Node: Common Extensions1030229 -Node: Ranges and Locales1031541 -Ref: Ranges and Locales-Footnote-11036158 -Ref: Ranges and Locales-Footnote-21036185 -Ref: Ranges and Locales-Footnote-31036419 -Node: Contributors1036640 -Node: Installation1042021 -Node: Gawk Distribution1042915 -Node: Getting1043399 -Node: Extracting1044225 -Node: Distribution contents1045917 -Node: Unix Installation1051622 -Node: Quick Installation1052239 -Node: Additional Configuration Options1054685 -Node: Configuration Philosophy1056421 -Node: Non-Unix Installation1058775 -Node: PC Installation1059233 -Node: PC Binary Installation1060532 -Node: PC Compiling1062380 -Node: PC Testing1065324 -Node: PC Using1066500 -Node: Cygwin1070668 -Node: MSYS1071477 -Node: VMS Installation1071991 -Node: VMS Compilation1072755 -Ref: VMS Compilation-Footnote-11074007 -Node: VMS Dynamic Extensions1074065 -Node: VMS Installation Details1075438 -Node: VMS Running1077689 -Node: VMS GNV1080523 -Node: VMS Old Gawk1081246 -Node: Bugs1081716 -Node: Other Versions1085634 -Node: Notes1091718 -Node: Compatibility Mode1092518 -Node: Additions1093301 -Node: Accessing The Source1094228 -Node: Adding Code1095668 -Node: New Ports1101713 -Node: Derived Files1105848 -Ref: Derived Files-Footnote-11111169 -Ref: Derived Files-Footnote-21111203 -Ref: Derived Files-Footnote-31111803 -Node: Future Extensions1111901 -Node: Implementation Limitations1112484 -Node: Extension Design1113736 -Node: Old Extension Problems1114890 -Ref: Old Extension Problems-Footnote-11116398 -Node: Extension New Mechanism Goals1116455 -Ref: Extension New Mechanism Goals-Footnote-11119820 -Node: Extension Other Design Decisions1120006 -Node: Extension Future Growth1122112 -Node: Old Extension Mechanism1122948 -Node: Basic Concepts1124688 -Node: Basic High Level1125369 -Ref: figure-general-flow1125640 -Ref: figure-process-flow1126239 -Ref: Basic High Level-Footnote-11129468 -Node: Basic Data Typing1129653 -Node: Glossary1133008 -Node: Copying1158237 -Node: GNU Free Documentation License1195794 -Node: Index1220931 +Node: Top1292 +Node: Foreword40781 +Node: Preface45126 +Ref: Preface-Footnote-148179 +Ref: Preface-Footnote-248275 +Node: History48507 +Node: Names50881 +Ref: Names-Footnote-152358 +Node: This Manual52430 +Ref: This Manual-Footnote-158204 +Node: Conventions58304 +Node: Manual History60460 +Ref: Manual History-Footnote-163908 +Ref: Manual History-Footnote-263949 +Node: How To Contribute64023 +Node: Acknowledgments65167 +Node: Getting Started69361 +Node: Running gawk71740 +Node: One-shot72926 +Node: Read Terminal74151 +Ref: Read Terminal-Footnote-175801 +Ref: Read Terminal-Footnote-276077 +Node: Long76248 +Node: Executable Scripts77624 +Ref: Executable Scripts-Footnote-179457 +Ref: Executable Scripts-Footnote-279559 +Node: Comments80106 +Node: Quoting82573 +Node: DOS Quoting87196 +Node: Sample Data Files87871 +Node: Very Simple90386 +Node: Two Rules95037 +Node: More Complex96935 +Ref: More Complex-Footnote-199865 +Node: Statements/Lines99950 +Ref: Statements/Lines-Footnote-1104413 +Node: Other Features104678 +Node: When105606 +Node: Invoking Gawk107753 +Node: Command Line109216 +Node: Options109999 +Ref: Options-Footnote-1125377 +Node: Other Arguments125402 +Node: Naming Standard Input128060 +Node: Environment Variables129154 +Node: AWKPATH Variable129712 +Ref: AWKPATH Variable-Footnote-1132493 +Ref: AWKPATH Variable-Footnote-2132538 +Node: AWKLIBPATH Variable132798 +Node: Other Environment Variables133516 +Node: Exit Status136479 +Node: Include Files137154 +Node: Loading Shared Libraries140723 +Node: Obsolete142087 +Node: Undocumented142784 +Node: Regexp143026 +Node: Regexp Usage144415 +Node: Escape Sequences146440 +Node: Regexp Operators152109 +Ref: Regexp Operators-Footnote-1159489 +Ref: Regexp Operators-Footnote-2159636 +Node: Bracket Expressions159734 +Ref: table-char-classes161624 +Node: GNU Regexp Operators164147 +Node: Case-sensitivity167870 +Ref: Case-sensitivity-Footnote-1170838 +Ref: Case-sensitivity-Footnote-2171073 +Node: Leftmost Longest171181 +Node: Computed Regexps172382 +Node: Reading Files175719 +Node: Records177721 +Ref: Records-Footnote-1187244 +Node: Fields187281 +Ref: Fields-Footnote-1190237 +Node: Nonconstant Fields190323 +Node: Changing Fields192529 +Node: Field Separators198488 +Node: Default Field Splitting201190 +Node: Regexp Field Splitting202307 +Node: Single Character Fields205649 +Node: Command Line Field Separator206708 +Node: Full Line Fields210050 +Ref: Full Line Fields-Footnote-1210558 +Node: Field Splitting Summary210604 +Ref: Field Splitting Summary-Footnote-1213703 +Node: Constant Size213804 +Node: Splitting By Content218411 +Ref: Splitting By Content-Footnote-1222160 +Node: Multiple Line222200 +Ref: Multiple Line-Footnote-1228047 +Node: Getline228226 +Node: Plain Getline230442 +Node: Getline/Variable232537 +Node: Getline/File233684 +Node: Getline/Variable/File235025 +Ref: Getline/Variable/File-Footnote-1236624 +Node: Getline/Pipe236711 +Node: Getline/Variable/Pipe239410 +Node: Getline/Coprocess240517 +Node: Getline/Variable/Coprocess241769 +Node: Getline Notes242506 +Node: Getline Summary245293 +Ref: table-getline-variants245701 +Node: Read Timeout246613 +Ref: Read Timeout-Footnote-1250354 +Node: Command line directories250411 +Node: Printing251041 +Node: Print252672 +Node: Print Examples254009 +Node: Output Separators256793 +Node: OFMT258809 +Node: Printf260167 +Node: Basic Printf261073 +Node: Control Letters262612 +Node: Format Modifiers266424 +Node: Printf Examples272433 +Node: Redirection275145 +Node: Special Files282119 +Node: Special FD282652 +Ref: Special FD-Footnote-1286277 +Node: Special Network286351 +Node: Special Caveats287201 +Node: Close Files And Pipes287997 +Ref: Close Files And Pipes-Footnote-1294980 +Ref: Close Files And Pipes-Footnote-2295128 +Node: Expressions295278 +Node: Values296410 +Node: Constants297086 +Node: Scalar Constants297766 +Ref: Scalar Constants-Footnote-1298625 +Node: Nondecimal-numbers298807 +Node: Regexp Constants301807 +Node: Using Constant Regexps302282 +Node: Variables305337 +Node: Using Variables305992 +Node: Assignment Options307716 +Node: Conversion309591 +Ref: table-locale-affects315091 +Ref: Conversion-Footnote-1315715 +Node: All Operators315824 +Node: Arithmetic Ops316454 +Node: Concatenation318959 +Ref: Concatenation-Footnote-1321747 +Node: Assignment Ops321867 +Ref: table-assign-ops326855 +Node: Increment Ops328186 +Node: Truth Values and Conditions331620 +Node: Truth Values332703 +Node: Typing and Comparison333752 +Node: Variable Typing334545 +Ref: Variable Typing-Footnote-1338442 +Node: Comparison Operators338564 +Ref: table-relational-ops338974 +Node: POSIX String Comparison342522 +Ref: POSIX String Comparison-Footnote-1343478 +Node: Boolean Ops343616 +Ref: Boolean Ops-Footnote-1347686 +Node: Conditional Exp347777 +Node: Function Calls349509 +Node: Precedence353103 +Node: Locales356772 +Node: Patterns and Actions357861 +Node: Pattern Overview358915 +Node: Regexp Patterns360584 +Node: Expression Patterns361127 +Node: Ranges364908 +Node: BEGIN/END368012 +Node: Using BEGIN/END368774 +Ref: Using BEGIN/END-Footnote-1371510 +Node: I/O And BEGIN/END371616 +Node: BEGINFILE/ENDFILE373898 +Node: Empty376812 +Node: Using Shell Variables377129 +Node: Action Overview379414 +Node: Statements381771 +Node: If Statement383625 +Node: While Statement385124 +Node: Do Statement387168 +Node: For Statement388324 +Node: Switch Statement391476 +Node: Break Statement393630 +Node: Continue Statement395620 +Node: Next Statement397413 +Node: Nextfile Statement399803 +Node: Exit Statement402458 +Node: Built-in Variables404874 +Node: User-modified405969 +Ref: User-modified-Footnote-1414327 +Node: Auto-set414389 +Ref: Auto-set-Footnote-1427845 +Ref: Auto-set-Footnote-2428050 +Node: ARGC and ARGV428106 +Node: Arrays431960 +Node: Array Basics433465 +Node: Array Intro434291 +Node: Reference to Elements438608 +Node: Assigning Elements440878 +Node: Array Example441369 +Node: Scanning an Array443101 +Node: Controlling Scanning445415 +Ref: Controlling Scanning-Footnote-1450502 +Node: Delete450818 +Ref: Delete-Footnote-1453583 +Node: Numeric Array Subscripts453640 +Node: Uninitialized Subscripts455823 +Node: Multidimensional457450 +Node: Multiscanning460543 +Node: Arrays of Arrays462132 +Node: Functions466772 +Node: Built-in467591 +Node: Calling Built-in468669 +Node: Numeric Functions470657 +Ref: Numeric Functions-Footnote-1474489 +Ref: Numeric Functions-Footnote-2474846 +Ref: Numeric Functions-Footnote-3474894 +Node: String Functions475163 +Ref: String Functions-Footnote-1498121 +Ref: String Functions-Footnote-2498250 +Ref: String Functions-Footnote-3498498 +Node: Gory Details498585 +Ref: table-sub-escapes500264 +Ref: table-sub-posix-92501618 +Ref: table-sub-proposed502969 +Ref: table-posix-sub504323 +Ref: table-gensub-escapes505868 +Ref: Gory Details-Footnote-1507044 +Ref: Gory Details-Footnote-2507095 +Node: I/O Functions507246 +Ref: I/O Functions-Footnote-1514236 +Node: Time Functions514383 +Ref: Time Functions-Footnote-1525366 +Ref: Time Functions-Footnote-2525434 +Ref: Time Functions-Footnote-3525592 +Ref: Time Functions-Footnote-4525703 +Ref: Time Functions-Footnote-5525815 +Ref: Time Functions-Footnote-6526042 +Node: Bitwise Functions526308 +Ref: table-bitwise-ops526870 +Ref: Bitwise Functions-Footnote-1531091 +Node: Type Functions531275 +Node: I18N Functions532426 +Node: User-defined534053 +Node: Definition Syntax534857 +Ref: Definition Syntax-Footnote-1539771 +Node: Function Example539840 +Ref: Function Example-Footnote-1542489 +Node: Function Caveats542511 +Node: Calling A Function543029 +Node: Variable Scope543984 +Node: Pass By Value/Reference546947 +Node: Return Statement550455 +Node: Dynamic Typing553436 +Node: Indirect Calls554367 +Node: Library Functions564054 +Ref: Library Functions-Footnote-1567567 +Ref: Library Functions-Footnote-2567710 +Node: Library Names567881 +Ref: Library Names-Footnote-1571354 +Ref: Library Names-Footnote-2571574 +Node: General Functions571660 +Node: Strtonum Function572688 +Node: Assert Function575618 +Node: Round Function578944 +Node: Cliff Random Function580485 +Node: Ordinal Functions581501 +Ref: Ordinal Functions-Footnote-1584578 +Ref: Ordinal Functions-Footnote-2584830 +Node: Join Function585041 +Ref: Join Function-Footnote-1586812 +Node: Getlocaltime Function587012 +Node: Readfile Function590753 +Node: Data File Management592592 +Node: Filetrans Function593224 +Node: Rewind Function597293 +Node: File Checking598680 +Node: Empty Files599774 +Node: Ignoring Assigns602004 +Node: Getopt Function603558 +Ref: Getopt Function-Footnote-1614861 +Node: Passwd Functions615064 +Ref: Passwd Functions-Footnote-1624042 +Node: Group Functions624130 +Node: Walking Arrays632214 +Node: Sample Programs634350 +Node: Running Examples635024 +Node: Clones635752 +Node: Cut Program636976 +Node: Egrep Program646827 +Ref: Egrep Program-Footnote-1654600 +Node: Id Program654710 +Node: Split Program658359 +Ref: Split Program-Footnote-1661878 +Node: Tee Program662006 +Node: Uniq Program664809 +Node: Wc Program672238 +Ref: Wc Program-Footnote-1676504 +Ref: Wc Program-Footnote-2676704 +Node: Miscellaneous Programs676796 +Node: Dupword Program677984 +Node: Alarm Program680015 +Node: Translate Program684822 +Ref: Translate Program-Footnote-1689209 +Ref: Translate Program-Footnote-2689457 +Node: Labels Program689591 +Ref: Labels Program-Footnote-1692962 +Node: Word Sorting693046 +Node: History Sorting696930 +Node: Extract Program698769 +Ref: Extract Program-Footnote-1706272 +Node: Simple Sed706400 +Node: Igawk Program709462 +Ref: Igawk Program-Footnote-1724619 +Ref: Igawk Program-Footnote-2724820 +Node: Anagram Program724958 +Node: Signature Program728026 +Node: Advanced Features729126 +Node: Nondecimal Data731012 +Node: Array Sorting732595 +Node: Controlling Array Traversal733292 +Node: Array Sorting Functions741576 +Ref: Array Sorting Functions-Footnote-1745445 +Node: Two-way I/O745639 +Ref: Two-way I/O-Footnote-1751071 +Node: TCP/IP Networking751153 +Node: Profiling753997 +Node: Internationalization761500 +Node: I18N and L10N762925 +Node: Explaining gettext763611 +Ref: Explaining gettext-Footnote-1768679 +Ref: Explaining gettext-Footnote-2768863 +Node: Programmer i18n769028 +Node: Translator i18n773230 +Node: String Extraction774024 +Ref: String Extraction-Footnote-1774985 +Node: Printf Ordering775071 +Ref: Printf Ordering-Footnote-1777853 +Node: I18N Portability777917 +Ref: I18N Portability-Footnote-1780366 +Node: I18N Example780429 +Ref: I18N Example-Footnote-1783067 +Node: Gawk I18N783139 +Node: Debugger783760 +Node: Debugging784731 +Node: Debugging Concepts785164 +Node: Debugging Terms787020 +Node: Awk Debugging789617 +Node: Sample Debugging Session790509 +Node: Debugger Invocation791029 +Node: Finding The Bug792362 +Node: List of Debugger Commands798849 +Node: Breakpoint Control800183 +Node: Debugger Execution Control803847 +Node: Viewing And Changing Data807207 +Node: Execution Stack810563 +Node: Debugger Info812030 +Node: Miscellaneous Debugger Commands816012 +Node: Readline Support821188 +Node: Limitations822019 +Node: Arbitrary Precision Arithmetic824271 +Ref: Arbitrary Precision Arithmetic-Footnote-1825920 +Node: General Arithmetic826068 +Node: Floating Point Issues827788 +Node: String Conversion Precision828669 +Ref: String Conversion Precision-Footnote-1830374 +Node: Unexpected Results830483 +Node: POSIX Floating Point Problems832636 +Ref: POSIX Floating Point Problems-Footnote-1836461 +Node: Integer Programming836499 +Node: Floating-point Programming838238 +Ref: Floating-point Programming-Footnote-1844569 +Ref: Floating-point Programming-Footnote-2844839 +Node: Floating-point Representation845103 +Node: Floating-point Context846268 +Ref: table-ieee-formats847107 +Node: Rounding Mode848491 +Ref: table-rounding-modes848970 +Ref: Rounding Mode-Footnote-1851985 +Node: Gawk and MPFR852164 +Node: Arbitrary Precision Floats853419 +Ref: Arbitrary Precision Floats-Footnote-1855862 +Node: Setting Precision856178 +Ref: table-predefined-precision-strings856864 +Node: Setting Rounding Mode859009 +Ref: table-gawk-rounding-modes859413 +Node: Floating-point Constants860600 +Node: Changing Precision862029 +Ref: Changing Precision-Footnote-1863426 +Node: Exact Arithmetic863600 +Node: Arbitrary Precision Integers866738 +Ref: Arbitrary Precision Integers-Footnote-1869753 +Node: Dynamic Extensions869900 +Node: Extension Intro871358 +Node: Plugin License872623 +Node: Extension Mechanism Outline873308 +Ref: load-extension873725 +Ref: load-new-function875203 +Ref: call-new-function876198 +Node: Extension API Description878213 +Node: Extension API Functions Introduction879500 +Node: General Data Types884427 +Ref: General Data Types-Footnote-1890122 +Node: Requesting Values890421 +Ref: table-value-types-returned891158 +Node: Memory Allocation Functions892112 +Ref: Memory Allocation Functions-Footnote-1894858 +Node: Constructor Functions894954 +Node: Registration Functions896712 +Node: Extension Functions897397 +Node: Exit Callback Functions899699 +Node: Extension Version String900948 +Node: Input Parsers901598 +Node: Output Wrappers911355 +Node: Two-way processors915865 +Node: Printing Messages918073 +Ref: Printing Messages-Footnote-1919150 +Node: Updating `ERRNO'919302 +Node: Accessing Parameters920041 +Node: Symbol Table Access921271 +Node: Symbol table by name921785 +Node: Symbol table by cookie923761 +Ref: Symbol table by cookie-Footnote-1927893 +Node: Cached values927956 +Ref: Cached values-Footnote-1931446 +Node: Array Manipulation931537 +Ref: Array Manipulation-Footnote-1932635 +Node: Array Data Types932674 +Ref: Array Data Types-Footnote-1935377 +Node: Array Functions935469 +Node: Flattening Arrays939305 +Node: Creating Arrays946157 +Node: Extension API Variables950882 +Node: Extension Versioning951518 +Node: Extension API Informational Variables953419 +Node: Extension API Boilerplate954505 +Node: Finding Extensions958309 +Node: Extension Example958869 +Node: Internal File Description959599 +Node: Internal File Ops963690 +Ref: Internal File Ops-Footnote-1975199 +Node: Using Internal File Ops975339 +Ref: Using Internal File Ops-Footnote-1977692 +Node: Extension Samples977958 +Node: Extension Sample File Functions979482 +Node: Extension Sample Fnmatch987967 +Node: Extension Sample Fork989736 +Node: Extension Sample Inplace990949 +Node: Extension Sample Ord992727 +Node: Extension Sample Readdir993563 +Node: Extension Sample Revout995095 +Node: Extension Sample Rev2way995688 +Node: Extension Sample Read write array996378 +Node: Extension Sample Readfile998261 +Node: Extension Sample API Tests999361 +Node: Extension Sample Time999886 +Node: gawkextlib1001250 +Node: Language History1004031 +Node: V7/SVR3.11005624 +Node: SVR41007944 +Node: POSIX1009386 +Node: BTL1010772 +Node: POSIX/GNU1011506 +Node: Feature History1017105 +Node: Common Extensions1030081 +Node: Ranges and Locales1031393 +Ref: Ranges and Locales-Footnote-11036010 +Ref: Ranges and Locales-Footnote-21036037 +Ref: Ranges and Locales-Footnote-31036271 +Node: Contributors1036492 +Node: Installation1041873 +Node: Gawk Distribution1042767 +Node: Getting1043251 +Node: Extracting1044077 +Node: Distribution contents1045769 +Node: Unix Installation1051474 +Node: Quick Installation1052091 +Node: Additional Configuration Options1054537 +Node: Configuration Philosophy1056273 +Node: Non-Unix Installation1058627 +Node: PC Installation1059085 +Node: PC Binary Installation1060384 +Node: PC Compiling1062232 +Node: PC Testing1065176 +Node: PC Using1066352 +Node: Cygwin1070520 +Node: MSYS1071329 +Node: VMS Installation1071843 +Node: VMS Compilation1072607 +Ref: VMS Compilation-Footnote-11073859 +Node: VMS Dynamic Extensions1073917 +Node: VMS Installation Details1075290 +Node: VMS Running1077541 +Node: VMS GNV1080375 +Node: VMS Old Gawk1081098 +Node: Bugs1081568 +Node: Other Versions1085486 +Node: Notes1091570 +Node: Compatibility Mode1092370 +Node: Additions1093153 +Node: Accessing The Source1094080 +Node: Adding Code1095520 +Node: New Ports1101565 +Node: Derived Files1105700 +Ref: Derived Files-Footnote-11111021 +Ref: Derived Files-Footnote-21111055 +Ref: Derived Files-Footnote-31111655 +Node: Future Extensions1111753 +Node: Implementation Limitations1112336 +Node: Extension Design1113588 +Node: Old Extension Problems1114742 +Ref: Old Extension Problems-Footnote-11116250 +Node: Extension New Mechanism Goals1116307 +Ref: Extension New Mechanism Goals-Footnote-11119672 +Node: Extension Other Design Decisions1119858 +Node: Extension Future Growth1121964 +Node: Old Extension Mechanism1122800 +Node: Basic Concepts1124540 +Node: Basic High Level1125221 +Ref: figure-general-flow1125493 +Ref: figure-process-flow1126092 +Ref: Basic High Level-Footnote-11129321 +Node: Basic Data Typing1129506 +Node: Glossary1132861 +Node: Copying1158092 +Node: GNU Free Documentation License1195648 +Node: Index1220784 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index b9d65bd0..2b666d35 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -116,11 +116,19 @@ @end ifnottex @ifnottex +@ifnotdocbook @macro ii{text} @i{\text\} @end macro +@end ifnotdocbook @end ifnottex +@ifdocbook +@macro ii{text} +@inlineraw{docbook,<lineannotation>\text\</lineannotation>} +@end macro +@end ifdocbook + @c For HTML, spell out email addresses, to avoid problems with @c address harvesters for spammers. @ifhtml @@ -176,6 +184,10 @@ Some comments on the layout for TeX. @syncodeindex fn cp @syncodeindex vr cp @end ifxml +@ifdocbook +@synindex fn cp +@synindex vr cp +@end ifdocbook @c If "finalout" is commented out, the printed output will show @c black boxes that mark lines that are too long. Thus, it is @@ -187,10 +199,26 @@ Some comments on the layout for TeX. @end iftex @copying -Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, -2014 +@docbook +<para>Published by:</para> + +<literallayout class="normal">Free Software Foundation +51 Franklin Street, Fifth Floor +Boston, MA 02110-1301 USA +Phone: +1-617-542-5942 +Fax: +1-617-542-2652 +Email: <email>gnu@@gnu.org</email> +URL: <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></literallayout> + +<literallayout class="normal">Copyright © 1989, 1991, 1992, 1993, 1996–2005, 2007, 2009–2014 +Free Software Foundation, Inc. +All Rights Reserved.</literallayout> +@end docbook + +@ifnotdocbook +Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2014 @* Free Software Foundation, Inc. +@end ifnotdocbook @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}}, @@ -238,6 +266,7 @@ supports it in developing GNU and promoting software freedom.'' @subtitle @value{UPDATE-MONTH} @author Arnold D. Robbins +@ifnotdocbook @c Include the Distribution inside the titlepage environment so @c that headings are turned off. Headings on and off do not work. @@ -262,6 +291,7 @@ URL: @uref{http://www.gnu.org/} @* ISBN 1-882114-28-0 @* @sp 2 @insertcopying +@end ifnotdocbook @end titlepage @c Thanks to Bob Chassell for directions on doing dedications. @@ -286,6 +316,18 @@ ISBN 1-882114-28-0 @* @headings on @end iftex +@docbook +<dedication> +<simplelist> +<member>To Miriam, for making me complete.</member> +<member>To Chana, for the joy you bring us.</member> +<member>To Rivka, for the exponential increase.</member> +<member>To Nachum, for the added dimension.</member> +<member>To Malka, for the new beginning.</member> +</simplelist> +</dedication> +@end docbook + @iftex @headings off @evenheading @thispage@ @ @ @strong{@value{TITLE}} @| @| @@ -294,6 +336,7 @@ ISBN 1-882114-28-0 @* @ifnottex @ifnotxml +@ifnotdocbook @node Top @top General Introduction @c Preface node should come right after the Top @@ -305,6 +348,7 @@ particular records in a file and perform operations upon them. @insertcopying +@end ifnotdocbook @end ifnotxml @end ifnottex @@ -1001,21 +1045,37 @@ and the AWK prototype becomes the product. The new @command{pgawk} (profiling @command{gawk}), produces program execution counts. I recently experimented with an algorithm that for -@math{n} lines of input, exhibited +@ifnotdocbook +@math{n} +@end ifnotdocbook +@ifdocbook +@i{n} +@end ifdocbook +lines of input, exhibited @tex $\sim\! Cn^2$ @end tex @ifnottex +@ifnotdocbook ~ C n^2 +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn<superscript>2</superscript></emphasis>  +@end docbook performance, while theory predicted @tex $\sim\! Cn\log n$ @end tex @ifnottex +@ifnotdocbook ~ C n log n +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn log n</emphasis>  +@end docbook behavior. A few minutes poring over the @file{awkprof.out} profile pinpointed the problem to a single line of code. @command{pgawk} is a welcome addition to @@ -3176,10 +3236,19 @@ There are two ways to run @command{awk}---with an explicit program or with one or more program files. Here are templates for both of them; items enclosed in [@dots{}] in these templates are optional: +@ifnotdocbook @example awk @r{[@var{options}]} -f progfile @r{[@code{--}]} @var{file} @dots{} awk @r{[@var{options}]} @r{[@code{--}]} '@var{program}' @var{file} @dots{} @end example +@end ifnotdocbook + +@c FIXME - find a better way to mark this up in docbook +@docbook +<screen>awk [<replaceable>options</replaceable>] -f progfile [<literal>--</literal>] <replaceable>file</replaceable> … +awk [<replaceable>options</replaceable>] [<literal>--</literal>] '<replaceable>program</replaceable>' <replaceable>file</replaceable> … +</screen> +@end docbook @cindex GNU long options @cindex long options @@ -13872,12 +13941,12 @@ The following elements (listed alphabetically) are guaranteed to be available: @table @code -@cindex effective group id of @command{gawk} user +@cindex effective group ID of @command{gawk} user @item PROCINFO["egid"] The value of the @code{getegid()} system call. @item PROCINFO["euid"] -@cindex effective user id of @command{gawk} user +@cindex effective user ID of @command{gawk} user The value of the @code{geteuid()} system call. @item PROCINFO["FS"] @@ -13916,19 +13985,19 @@ after it has finished parsing the program; they are @emph{not} updated while the program runs. @item PROCINFO["gid"] -@cindex group id of @command{gawk} user +@cindex group ID of @command{gawk} user The value of the @code{getgid()} system call. @item PROCINFO["pgrpid"] -@cindex process group id of @command{gawk} process +@cindex process group idIDof @command{gawk} process The process group ID of the current process. @item PROCINFO["pid"] -@cindex process id of @command{gawk} process +@cindex process ID of @command{gawk} process The process ID of the current process. @item PROCINFO["ppid"] -@cindex parent process id of @command{gawk} process +@cindex parent process ID of @command{gawk} process The parent process ID of the current process. @item PROCINFO["sorted_in"] @@ -15579,7 +15648,7 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item atan2(@var{y}, @var{x}) -@cindex @code{atan2()} function +@cindexawkfunc{atan2} @cindex arctangent Return the arctangent of @code{@var{y} / @var{x}} in radians. You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}. @@ -17233,7 +17302,18 @@ it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.@footnote{@xref{Glossary}, especially the entries ``Epoch'' and ``UTC.''} All known POSIX-compliant systems support timestamps from 0 through -@math{2^{31} - 1}, which is sufficient to represent times through +@iftex +@math{2^{31} - 1}, +@end iftex +@ifnottex +@ifnotdocbook +2^31 - 1, +@end ifnotdocbook +@end ifnottex +@docbook +2<superscript>31</superscript> − 1,  +@end docbook +which is sufficient to represent times through 2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps, including negative timestamps that represent times before the epoch. @@ -27582,15 +27662,16 @@ Without any argument, set a breakpoint at the next instruction to be executed in the selected stack frame. Arguments can be one of the following: +@c @asis for docbook @c nested table -@table @var -@item n +@table @asis +@item @var{n} Set a breakpoint at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Set a breakpoint at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Set a breakpoint at entry to (the first instruction of) function @var{function}. @end table @@ -27615,14 +27696,14 @@ a breakpoint, this deletes that breakpoint so that the program does not stop at that location again. Arguments can be one of the following: @c nested table -@table @var -@item n +@table @asis +@item @var{n} Delete breakpoint(s) set at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Delete breakpoint(s) set at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Delete breakpoint(s) set at entry to function @var{function}. @end table @@ -28091,6 +28172,7 @@ The maximum number of lines to keep in the history file @file{./.gawk_history}. The default is 100. @item listsize +@cindex debugger default list amount The number of lines that @code{list} prints. The default is 15. @item outfile @@ -28223,8 +28305,8 @@ about the command @var{command}. @cindex debugger commands, @code{list} @cindex @code{list} debugger command @cindex @code{l} debugger command (alias for @code{list}) -@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] -@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] +@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] +@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] Print the specified lines (default 15) from the current source file or the file named @var{filename}. The possible arguments to @code{list} are as follows: @@ -28244,7 +28326,7 @@ Print lines centered around line number @var{n}. @item @var{n}--@var{m} Print lines from @var{n} to @var{m}. -@item @var{filename@code{:}n} +@item @var{filename}@code{:}@var{n} Print lines centered around line number @var{n} in source file @var{filename}. This command may change the current source file. @@ -28714,23 +28796,38 @@ then the answer is @math{2^{53}}. @end iftex @ifnottex +@ifnotdocbook 2^53. +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript>.  +@end docbook The next representable number is the even number @iftex @math{2^{53} + 2}, @end iftex @ifnottex +@ifnotdocbook 2^53 + 2, +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 2, +@end docbook meaning it is unlikely that you will be able to make @command{gawk} print @iftex @math{2^{53} + 1} @end iftex @ifnottex +@ifnotdocbook 2^53 + 1 +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 1  +@end docbook in integer format. The range of integers exactly representable by a 64-bit double is @@ -28738,8 +28835,13 @@ is @math{[-2^{53}, 2^{53}]}. @end iftex @ifnottex +@ifnotdocbook [@minus{}2^53, 2^53]. +@end ifnotdocbook @end ifnottex +@docbook +[−2<superscript>53</superscript>, 2<superscript>53</superscript>].  +@end docbook If you ever see an integer outside this range in @command{awk} using 64-bit doubles, you have reason to be very suspicious about the accuracy of the output. Here is a simple program with erroneous output: @@ -28963,8 +29065,13 @@ number is then @math{s @cdot 2^e}. @end iftex @ifnottex +@ifnotdocbook @var{s * 2^e}. +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>s ċ 2<superscript>e</superscript></emphasis>.  +@end docbook The first bit of a non-zero binary significand is always one, so the significand in an IEEE-754 format only includes the fractional part, leaving the leading one implicit. @@ -29207,8 +29314,13 @@ numbers are not implemented.} (@math{emax = 2^{30} - 1, emin = -emax}) @end iftex @ifnottex +@ifnotdocbook (@var{emax} = 2^30 @minus{} 1, @var{emin} = @minus{}@var{emax}) +@end ifnotdocbook @end ifnottex +@docbook +(<emphasis>emax</emphasis> = 2<superscript>30</superscript> − 1, <emphasis>emin</emphasis> = −<emphasis>emax</emphasis>)  +@end docbook for all floating-point contexts. There is no explicit mechanism to adjust the exponent range. MPFR does not implement subnormal numbers by default, @@ -29280,8 +29392,15 @@ formula: @math{prec = 3.322 @cdot dps} @end iftex @ifnottex +@ifnotdocbook @var{prec} = 3.322 * @var{dps} +@end ifnotdocbook @end ifnottex +@docbook +<para> +<emphasis>prec</emphasis> = 3.322 ċ <emphasis>dps</emphasis> +</para> +@end docbook @noindent Here, @var{prec} denotes the binary precision @@ -29681,8 +29800,14 @@ Communication between @command{gawk} and an extension is two-way. First, when an extension is loaded, it is passed a pointer to a @code{struct} whose fields are function pointers. +@ifnotdocbook This is shown in @ref{load-extension}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="load-extension"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-extension @caption{Loading The Extension} @c FIXME: One day, it should not be necessary to have two cases, @@ -29695,13 +29820,27 @@ This is shown in @ref{load-extension}. @center @image{api-figure1, , , Loading the extension} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-extension"> +<title>Loading the extension</title> +<graphic fileref="api-figure1.eps"/> +</figure> +@end docbook The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a function for ``registering'' new built-in functions. +@ifnotdocbook This is shown in @ref{load-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docboook, <xref linkend="load-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-new-function @caption{Loading The New Function} @ifinfo @@ -29711,14 +29850,28 @@ This is shown in @ref{load-new-function}. @center @image{api-figure2, , , Loading the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-new-function"> +<title>Loading the new function</title> +<graphic fileref="api-figure2.eps"/> +</figure> +@end docbook In the other direction, the extension registers its new functions with @command{gawk} by passing function pointers to the functions that provide the new feature (@code{do_chdir()}, for example). @command{gawk} associates the function pointer with a name and can then call it, using a defined calling convention. +@ifnotdocbook This is shown in @ref{call-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="call-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,call-new-function @caption{Calling The New Function} @ifinfo @@ -29728,6 +29881,14 @@ This is shown in @ref{call-new-function}. @center @image{api-figure3, , , Calling the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="call-new-function"> +<title>Calling The New Function</title> +<graphic fileref="api-figure3.eps"/> +</figure> +@end docbook The @code{do_@var{xxx}()} function, in turn, then uses the function pointers in the API @code{struct} to do its work, such as updating @@ -30101,7 +30262,94 @@ print an error message, or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. +@c FIXME: Try to do this with spans... +@ifdocbook +@anchor{table-value-types-returned} +@end ifdocbook +@docbook +<informaltable> +<tgroup cols="2"> + <colspec colwidth="50*"/><colspec colwidth="50*"/> + <thead> + <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> + </thead> + <tbody> + <row><entry></entry><entry></entry></row> + </tbody> +</tgroup> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*"/> + <colspec colwidth="15*"/> + <colspec colwidth="15*"/> + <colspec colwidth="16.6*"/> + <thead> + <row> + <entry></entry> + <entry></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> + <entry><para>Scalar</para></entry> + <entry><para>Scalar</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + @ifnotplaintext +@ifnotdocbook @float Table,table-value-types-returned @caption{Value Types Returned} @multitable @columnfractions .50 .50 @@ -30117,6 +30365,7 @@ value type, as appropriate. This behavior is summarized in @item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false @end multitable @end float +@end ifnotdocbook @end ifnotplaintext @ifplaintext @float Table,table-value-types-returned @@ -31262,7 +31511,7 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -36274,22 +36523,23 @@ file should be considered authoritative if it conflicts with this The people maintaining the non-Unix ports of @command{gawk} are as follows: -@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} +@c put the index entries outside the table, for docbook @cindex Deifik, Scott +@cindex Zaretskii, Eli +@cindex Buening, Andreas +@cindex Rankin, Pat +@cindex Malmberg, John +@cindex Pitts, Dave +@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} @item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. -@cindex Zaretskii, Eli @item MS-Windows with MINGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. -@cindex Buening, Andreas @item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. -@cindex Rankin, Pat -@cindex Malmberg, John @item VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin at gmail.com}, and John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. -@cindex Pitts, Dave @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable @@ -37441,8 +37691,15 @@ other introductory texts that you should refer to instead.) @cindex processing data At the most basic level, the job of a program is to process -some input data and produce results. See @ref{figure-general-flow}. +some input data and produce results. +@ifnotdocbook +See @ref{figure-general-flow}. +@end ifnotdocbook +@ifdocbook +See @inlineraw{docbook, <xref linkend="figure-general-flow"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,figure-general-flow @caption{General Program Flow} @ifinfo @@ -37452,6 +37709,14 @@ some input data and produce results. See @ref{figure-general-flow}. @center @image{general-program, , , General program flow} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-general-flow"> +<title>General Program Flow</title> +<graphic fileref="general-program.eps"/> +</figure> +@end docbook @cindex compiled programs @cindex interpreted programs @@ -37467,9 +37732,15 @@ instructions in your program to process the data. @cindex programming, basic steps When you write a program, it usually consists -of the following, very basic set of steps, as shown -in @ref{figure-process-flow}: +of the following, very basic set of steps, +@ifnotdocbook +as shown in @ref{figure-process-flow}: +@end ifnotdocbook +@ifdocbook +as shown in @inlineraw{docbook <xref linkend="figure-process-flow"/>}: +@end ifdocbook +@ifnotdocbook @float Figure,figure-process-flow @caption{Basic Program Steps} @ifinfo @@ -37479,6 +37750,14 @@ in @ref{figure-process-flow}: @center @image{process-flow, , , Basic Program Stages} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-process-flow"> +<title>Basic Program Stages</title> +<graphic fileref="process-flow.eps"/> +</figure> +@end docbook @table @asis @item Initialization @@ -37955,7 +38234,7 @@ ordinary expression. It could be a string constant, such as (@xref{Computed Regexps}.) @item Environment -A collection of strings, of the form @var{name@code{=}val}, that each +A collection of strings, of the form @var{name}@code{=}@code{val}, that each program has available to it. Users generally place values into the environment in order to provide information to various programs. Typical examples are the environment variables @env{HOME} and @env{PATH}. @@ -38411,7 +38690,12 @@ record or a string. @c The GNU General Public License. @node Copying @unnumbered GNU General Public License +@ifnotdocbook @center Version 3, 29 June 2007 +@end ifnotdocbook +@docbook +<subtitle>Version 3, 29 June 2007</subtitle> +@end docbook @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -39136,10 +39420,17 @@ first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. @c The GNU Free Documentation License. @node GNU Free Documentation License @unnumbered GNU Free Documentation License +@ifnotdocbook +@center Version 1.3, 3 November 2008 +@end ifnotdocbook + +@docbook +<subtitle>Version 1.3, 3 November 2008</subtitle> +@end docbook + @cindex FDL (Free Documentation License) @cindex Free Documentation License (FDL) @cindex GNU Free Documentation License -@center Version 1.3, 3 November 2008 @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -39644,8 +39935,10 @@ to permit their use in free software. @c ispell-local-pdict: "ispell-dict" @c End: +@ifnotdocbook @node Index @unnumbered Index +@end ifnotdocbook @printindex cp @bye diff --git a/doc/gawktexi.in b/doc/gawktexi.in index cb35e37c..66df3784 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -111,11 +111,19 @@ @end ifnottex @ifnottex +@ifnotdocbook @macro ii{text} @i{\text\} @end macro +@end ifnotdocbook @end ifnottex +@ifdocbook +@macro ii{text} +@inlineraw{docbook,<lineannotation>\text\</lineannotation>} +@end macro +@end ifdocbook + @c For HTML, spell out email addresses, to avoid problems with @c address harvesters for spammers. @ifhtml @@ -171,6 +179,10 @@ Some comments on the layout for TeX. @syncodeindex fn cp @syncodeindex vr cp @end ifxml +@ifdocbook +@synindex fn cp +@synindex vr cp +@end ifdocbook @c If "finalout" is commented out, the printed output will show @c black boxes that mark lines that are too long. Thus, it is @@ -182,10 +194,26 @@ Some comments on the layout for TeX. @end iftex @copying -Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013, -2014 +@docbook +<para>Published by:</para> + +<literallayout class="normal">Free Software Foundation +51 Franklin Street, Fifth Floor +Boston, MA 02110-1301 USA +Phone: +1-617-542-5942 +Fax: +1-617-542-2652 +Email: <email>gnu@@gnu.org</email> +URL: <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></literallayout> + +<literallayout class="normal">Copyright © 1989, 1991, 1992, 1993, 1996–2005, 2007, 2009–2014 +Free Software Foundation, Inc. +All Rights Reserved.</literallayout> +@end docbook + +@ifnotdocbook +Copyright @copyright{} 1989, 1991, 1992, 1993, 1996--2005, 2007, 2009--2014 @* Free Software Foundation, Inc. +@end ifnotdocbook @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}}, @@ -233,6 +261,7 @@ supports it in developing GNU and promoting software freedom.'' @subtitle @value{UPDATE-MONTH} @author Arnold D. Robbins +@ifnotdocbook @c Include the Distribution inside the titlepage environment so @c that headings are turned off. Headings on and off do not work. @@ -257,6 +286,7 @@ URL: @uref{http://www.gnu.org/} @* ISBN 1-882114-28-0 @* @sp 2 @insertcopying +@end ifnotdocbook @end titlepage @c Thanks to Bob Chassell for directions on doing dedications. @@ -281,6 +311,18 @@ ISBN 1-882114-28-0 @* @headings on @end iftex +@docbook +<dedication> +<simplelist> +<member>To Miriam, for making me complete.</member> +<member>To Chana, for the joy you bring us.</member> +<member>To Rivka, for the exponential increase.</member> +<member>To Nachum, for the added dimension.</member> +<member>To Malka, for the new beginning.</member> +</simplelist> +</dedication> +@end docbook + @iftex @headings off @evenheading @thispage@ @ @ @strong{@value{TITLE}} @| @| @@ -289,6 +331,7 @@ ISBN 1-882114-28-0 @* @ifnottex @ifnotxml +@ifnotdocbook @node Top @top General Introduction @c Preface node should come right after the Top @@ -300,6 +343,7 @@ particular records in a file and perform operations upon them. @insertcopying +@end ifnotdocbook @end ifnotxml @end ifnottex @@ -996,21 +1040,37 @@ and the AWK prototype becomes the product. The new @command{pgawk} (profiling @command{gawk}), produces program execution counts. I recently experimented with an algorithm that for -@math{n} lines of input, exhibited +@ifnotdocbook +@math{n} +@end ifnotdocbook +@ifdocbook +@i{n} +@end ifdocbook +lines of input, exhibited @tex $\sim\! Cn^2$ @end tex @ifnottex +@ifnotdocbook ~ C n^2 +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn<superscript>2</superscript></emphasis>  +@end docbook performance, while theory predicted @tex $\sim\! Cn\log n$ @end tex @ifnottex +@ifnotdocbook ~ C n log n +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>∼ Cn log n</emphasis>  +@end docbook behavior. A few minutes poring over the @file{awkprof.out} profile pinpointed the problem to a single line of code. @command{pgawk} is a welcome addition to @@ -3104,10 +3164,19 @@ There are two ways to run @command{awk}---with an explicit program or with one or more program files. Here are templates for both of them; items enclosed in [@dots{}] in these templates are optional: +@ifnotdocbook @example awk @r{[@var{options}]} -f progfile @r{[@code{--}]} @var{file} @dots{} awk @r{[@var{options}]} @r{[@code{--}]} '@var{program}' @var{file} @dots{} @end example +@end ifnotdocbook + +@c FIXME - find a better way to mark this up in docbook +@docbook +<screen>awk [<replaceable>options</replaceable>] -f progfile [<literal>--</literal>] <replaceable>file</replaceable> … +awk [<replaceable>options</replaceable>] [<literal>--</literal>] '<replaceable>program</replaceable>' <replaceable>file</replaceable> … +</screen> +@end docbook @cindex GNU long options @cindex long options @@ -13249,12 +13318,12 @@ The following elements (listed alphabetically) are guaranteed to be available: @table @code -@cindex effective group id of @command{gawk} user +@cindex effective group ID of @command{gawk} user @item PROCINFO["egid"] The value of the @code{getegid()} system call. @item PROCINFO["euid"] -@cindex effective user id of @command{gawk} user +@cindex effective user ID of @command{gawk} user The value of the @code{geteuid()} system call. @item PROCINFO["FS"] @@ -13293,19 +13362,19 @@ after it has finished parsing the program; they are @emph{not} updated while the program runs. @item PROCINFO["gid"] -@cindex group id of @command{gawk} user +@cindex group ID of @command{gawk} user The value of the @code{getgid()} system call. @item PROCINFO["pgrpid"] -@cindex process group id of @command{gawk} process +@cindex process group idIDof @command{gawk} process The process group ID of the current process. @item PROCINFO["pid"] -@cindex process id of @command{gawk} process +@cindex process ID of @command{gawk} process The process ID of the current process. @item PROCINFO["ppid"] -@cindex parent process id of @command{gawk} process +@cindex parent process ID of @command{gawk} process The parent process ID of the current process. @item PROCINFO["sorted_in"] @@ -14910,7 +14979,7 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item atan2(@var{y}, @var{x}) -@cindex @code{atan2()} function +@cindexawkfunc{atan2} @cindex arctangent Return the arctangent of @code{@var{y} / @var{x}} in radians. You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}. @@ -16403,7 +16472,18 @@ it is the number of seconds since 1970-01-01 00:00:00 UTC, not counting leap seconds.@footnote{@xref{Glossary}, especially the entries ``Epoch'' and ``UTC.''} All known POSIX-compliant systems support timestamps from 0 through -@math{2^{31} - 1}, which is sufficient to represent times through +@iftex +@math{2^{31} - 1}, +@end iftex +@ifnottex +@ifnotdocbook +2^31 - 1, +@end ifnotdocbook +@end ifnottex +@docbook +2<superscript>31</superscript> − 1,  +@end docbook +which is sufficient to represent times through 2038-01-19 03:14:07 UTC. Many systems support a wider range of timestamps, including negative timestamps that represent times before the epoch. @@ -26723,15 +26803,16 @@ Without any argument, set a breakpoint at the next instruction to be executed in the selected stack frame. Arguments can be one of the following: +@c @asis for docbook @c nested table -@table @var -@item n +@table @asis +@item @var{n} Set a breakpoint at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Set a breakpoint at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Set a breakpoint at entry to (the first instruction of) function @var{function}. @end table @@ -26756,14 +26837,14 @@ a breakpoint, this deletes that breakpoint so that the program does not stop at that location again. Arguments can be one of the following: @c nested table -@table @var -@item n +@table @asis +@item @var{n} Delete breakpoint(s) set at line number @var{n} in the current source file. -@item filename@code{:}n +@item @var{filename}@code{:}@var{n} Delete breakpoint(s) set at line number @var{n} in source file @var{filename}. -@item function +@item @var{function} Delete breakpoint(s) set at entry to function @var{function}. @end table @@ -27232,6 +27313,7 @@ The maximum number of lines to keep in the history file @file{./.gawk_history}. The default is 100. @item listsize +@cindex debugger default list amount The number of lines that @code{list} prints. The default is 15. @item outfile @@ -27364,8 +27446,8 @@ about the command @var{command}. @cindex debugger commands, @code{list} @cindex @code{list} debugger command @cindex @code{l} debugger command (alias for @code{list}) -@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] -@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename@code{:}n} | @var{n}--@var{m} | @var{function}] +@item @code{list} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] +@itemx @code{l} [@code{-} | @code{+} | @var{n} | @var{filename}@code{:}@var{n} | @var{n}--@var{m} | @var{function}] Print the specified lines (default 15) from the current source file or the file named @var{filename}. The possible arguments to @code{list} are as follows: @@ -27385,7 +27467,7 @@ Print lines centered around line number @var{n}. @item @var{n}--@var{m} Print lines from @var{n} to @var{m}. -@item @var{filename@code{:}n} +@item @var{filename}@code{:}@var{n} Print lines centered around line number @var{n} in source file @var{filename}. This command may change the current source file. @@ -27855,23 +27937,38 @@ then the answer is @math{2^{53}}. @end iftex @ifnottex +@ifnotdocbook 2^53. +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript>.  +@end docbook The next representable number is the even number @iftex @math{2^{53} + 2}, @end iftex @ifnottex +@ifnotdocbook 2^53 + 2, +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 2, +@end docbook meaning it is unlikely that you will be able to make @command{gawk} print @iftex @math{2^{53} + 1} @end iftex @ifnottex +@ifnotdocbook 2^53 + 1 +@end ifnotdocbook @end ifnottex +@docbook +2<superscript>53</superscript> + 1  +@end docbook in integer format. The range of integers exactly representable by a 64-bit double is @@ -27879,8 +27976,13 @@ is @math{[-2^{53}, 2^{53}]}. @end iftex @ifnottex +@ifnotdocbook [@minus{}2^53, 2^53]. +@end ifnotdocbook @end ifnottex +@docbook +[−2<superscript>53</superscript>, 2<superscript>53</superscript>].  +@end docbook If you ever see an integer outside this range in @command{awk} using 64-bit doubles, you have reason to be very suspicious about the accuracy of the output. Here is a simple program with erroneous output: @@ -28104,8 +28206,13 @@ number is then @math{s @cdot 2^e}. @end iftex @ifnottex +@ifnotdocbook @var{s * 2^e}. +@end ifnotdocbook @end ifnottex +@docbook +<emphasis>s ċ 2<superscript>e</superscript></emphasis>.  +@end docbook The first bit of a non-zero binary significand is always one, so the significand in an IEEE-754 format only includes the fractional part, leaving the leading one implicit. @@ -28348,8 +28455,13 @@ numbers are not implemented.} (@math{emax = 2^{30} - 1, emin = -emax}) @end iftex @ifnottex +@ifnotdocbook (@var{emax} = 2^30 @minus{} 1, @var{emin} = @minus{}@var{emax}) +@end ifnotdocbook @end ifnottex +@docbook +(<emphasis>emax</emphasis> = 2<superscript>30</superscript> − 1, <emphasis>emin</emphasis> = −<emphasis>emax</emphasis>)  +@end docbook for all floating-point contexts. There is no explicit mechanism to adjust the exponent range. MPFR does not implement subnormal numbers by default, @@ -28421,8 +28533,15 @@ formula: @math{prec = 3.322 @cdot dps} @end iftex @ifnottex +@ifnotdocbook @var{prec} = 3.322 * @var{dps} +@end ifnotdocbook @end ifnottex +@docbook +<para> +<emphasis>prec</emphasis> = 3.322 ċ <emphasis>dps</emphasis> +</para> +@end docbook @noindent Here, @var{prec} denotes the binary precision @@ -28822,8 +28941,14 @@ Communication between @command{gawk} and an extension is two-way. First, when an extension is loaded, it is passed a pointer to a @code{struct} whose fields are function pointers. +@ifnotdocbook This is shown in @ref{load-extension}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="load-extension"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-extension @caption{Loading The Extension} @c FIXME: One day, it should not be necessary to have two cases, @@ -28836,13 +28961,27 @@ This is shown in @ref{load-extension}. @center @image{api-figure1, , , Loading the extension} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-extension"> +<title>Loading the extension</title> +<graphic fileref="api-figure1.eps"/> +</figure> +@end docbook The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a function for ``registering'' new built-in functions. +@ifnotdocbook This is shown in @ref{load-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docboook, <xref linkend="load-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,load-new-function @caption{Loading The New Function} @ifinfo @@ -28852,14 +28991,28 @@ This is shown in @ref{load-new-function}. @center @image{api-figure2, , , Loading the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="load-new-function"> +<title>Loading the new function</title> +<graphic fileref="api-figure2.eps"/> +</figure> +@end docbook In the other direction, the extension registers its new functions with @command{gawk} by passing function pointers to the functions that provide the new feature (@code{do_chdir()}, for example). @command{gawk} associates the function pointer with a name and can then call it, using a defined calling convention. +@ifnotdocbook This is shown in @ref{call-new-function}. +@end ifnotdocbook +@ifdocbook +This is shown in @inlineraw{docbook, <xref linkend="call-new-function"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,call-new-function @caption{Calling The New Function} @ifinfo @@ -28869,6 +29022,14 @@ This is shown in @ref{call-new-function}. @center @image{api-figure3, , , Calling the new function} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="call-new-function"> +<title>Calling The New Function</title> +<graphic fileref="api-figure3.eps"/> +</figure> +@end docbook The @code{do_@var{xxx}()} function, in turn, then uses the function pointers in the API @code{struct} to do its work, such as updating @@ -29242,7 +29403,94 @@ print an error message, or reissue the request for the actual value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. +@c FIXME: Try to do this with spans... +@ifdocbook +@anchor{table-value-types-returned} +@end ifdocbook +@docbook +<informaltable> +<tgroup cols="2"> + <colspec colwidth="50*"/><colspec colwidth="50*"/> + <thead> + <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> + </thead> + <tbody> + <row><entry></entry><entry></entry></row> + </tbody> +</tgroup> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*"/> + <colspec colwidth="15*"/> + <colspec colwidth="15*"/> + <colspec colwidth="16.6*"/> + <thead> + <row> + <entry></entry> + <entry></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> + <entry><para>Scalar</para></entry> + <entry><para>Scalar</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + @ifnotplaintext +@ifnotdocbook @float Table,table-value-types-returned @caption{Value Types Returned} @multitable @columnfractions .50 .50 @@ -29258,6 +29506,7 @@ value type, as appropriate. This behavior is summarized in @item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false @end multitable @end float +@end ifnotdocbook @end ifnotplaintext @ifplaintext @float Table,table-value-types-returned @@ -30403,7 +30652,7 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -35415,22 +35664,23 @@ file should be considered authoritative if it conflicts with this The people maintaining the non-Unix ports of @command{gawk} are as follows: -@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} +@c put the index entries outside the table, for docbook @cindex Deifik, Scott +@cindex Zaretskii, Eli +@cindex Buening, Andreas +@cindex Rankin, Pat +@cindex Malmberg, John +@cindex Pitts, Dave +@multitable {MS-Windows with MINGW} {123456789012345678901234567890123456789001234567890} @item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. -@cindex Zaretskii, Eli @item MS-Windows with MINGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. -@cindex Buening, Andreas @item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. -@cindex Rankin, Pat -@cindex Malmberg, John @item VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin at gmail.com}, and John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. -@cindex Pitts, Dave @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable @@ -36582,8 +36832,15 @@ other introductory texts that you should refer to instead.) @cindex processing data At the most basic level, the job of a program is to process -some input data and produce results. See @ref{figure-general-flow}. +some input data and produce results. +@ifnotdocbook +See @ref{figure-general-flow}. +@end ifnotdocbook +@ifdocbook +See @inlineraw{docbook, <xref linkend="figure-general-flow"/>}. +@end ifdocbook +@ifnotdocbook @float Figure,figure-general-flow @caption{General Program Flow} @ifinfo @@ -36593,6 +36850,14 @@ some input data and produce results. See @ref{figure-general-flow}. @center @image{general-program, , , General program flow} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-general-flow"> +<title>General Program Flow</title> +<graphic fileref="general-program.eps"/> +</figure> +@end docbook @cindex compiled programs @cindex interpreted programs @@ -36608,9 +36873,15 @@ instructions in your program to process the data. @cindex programming, basic steps When you write a program, it usually consists -of the following, very basic set of steps, as shown -in @ref{figure-process-flow}: +of the following, very basic set of steps, +@ifnotdocbook +as shown in @ref{figure-process-flow}: +@end ifnotdocbook +@ifdocbook +as shown in @inlineraw{docbook <xref linkend="figure-process-flow"/>}: +@end ifdocbook +@ifnotdocbook @float Figure,figure-process-flow @caption{Basic Program Steps} @ifinfo @@ -36620,6 +36891,14 @@ in @ref{figure-process-flow}: @center @image{process-flow, , , Basic Program Stages} @end ifnotinfo @end float +@end ifnotdocbook + +@docbook +<figure id="figure-process-flow"> +<title>Basic Program Stages</title> +<graphic fileref="process-flow.eps"/> +</figure> +@end docbook @table @asis @item Initialization @@ -37096,7 +37375,7 @@ ordinary expression. It could be a string constant, such as (@xref{Computed Regexps}.) @item Environment -A collection of strings, of the form @var{name@code{=}val}, that each +A collection of strings, of the form @var{name}@code{=}@code{val}, that each program has available to it. Users generally place values into the environment in order to provide information to various programs. Typical examples are the environment variables @env{HOME} and @env{PATH}. @@ -37552,7 +37831,12 @@ record or a string. @c The GNU General Public License. @node Copying @unnumbered GNU General Public License +@ifnotdocbook @center Version 3, 29 June 2007 +@end ifnotdocbook +@docbook +<subtitle>Version 3, 29 June 2007</subtitle> +@end docbook @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -38277,10 +38561,17 @@ first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. @c The GNU Free Documentation License. @node GNU Free Documentation License @unnumbered GNU Free Documentation License +@ifnotdocbook +@center Version 1.3, 3 November 2008 +@end ifnotdocbook + +@docbook +<subtitle>Version 1.3, 3 November 2008</subtitle> +@end docbook + @cindex FDL (Free Documentation License) @cindex Free Documentation License (FDL) @cindex GNU Free Documentation License -@center Version 1.3, 3 November 2008 @c This file is intended to be included within another document, @c hence no sectioning command or @node. @@ -38785,8 +39076,10 @@ to permit their use in free software. @c ispell-local-pdict: "ispell-dict" @c End: +@ifnotdocbook @node Index @unnumbered Index +@end ifnotdocbook @printindex cp @bye |