diff options
| -rw-r--r-- | doc/ChangeLog | 8 | ||||
| -rw-r--r-- | doc/gawk.info | 846 | ||||
| -rw-r--r-- | doc/gawk.texi | 50 | ||||
| -rw-r--r-- | doc/gawktexi.in | 50 |
4 files changed, 505 insertions, 449 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 6401d898..e4449087 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2021-10-09 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Clarify that initialization and increment parts of + a for loop can't use the C comma operator. Thanks to J Naman + <jnaman2@gmail.com> for pointing out the doc was too subtle. + Unrelated: further expand the bug reporting text and discussion + about comp.lang.awk. + 2021-10-03 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Continue clarifying typeof() usage. And other fixes. diff --git a/doc/gawk.info b/doc/gawk.info index 0c5f8040..b499464c 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -10578,18 +10578,21 @@ desired number of iterations. For example: This prints the first three fields of each input record, with one input field per output line. - It isn't possible to set more than one variable in the INITIALIZATION -part without using a multiple assignment statement such as 'x = y = 0'. -This makes sense only if all the initial values are equal. (But it is -possible to initialize additional variables by writing their assignments -as separate statements preceding the 'for' loop.) - - The same is true of the INCREMENT part. Incrementing additional -variables requires separate statements at the end of the loop. The C -compound expression, using C's comma operator, is useful in this -context, but it is not supported in 'awk'. - - Most often, INCREMENT is an increment expression, as in the previous + C and C++ programmers might expect to be able to use the comma +operator to set more than one variable in the INITIALIZATION part of the +'for' loop, or to increment multiple variables in the INCREMEMNT part of +the loop, like so: + + for (i = 0, j = length(a); i < j; i++, j--) ... C/C++, not awk! + +You cannot do this; the comma operator is not supported in 'awk'. There +are workarounds, but they are nonobvious and can lead to code that is +difficult to read and understand. It is best, therefore, to simply +write additional initializations as separate statements preceding the +'for' loop and to place additional increment statements at the end of +the loop's body. + + Most often, INCREMENT is an increment expression, as in the earlier example. But this is not required; it can be any expression whatsoever. For example, the following statement prints all the powers of two between 1 and 100: @@ -31570,13 +31573,16 @@ what is not. the bug mailing list. You can ask about them on the "help" mailing list (*note Asking for help::), but don't be surprised if you get an answer of the form "that's how 'gawk' behaves and it isn't going to change." +Here's the list: * Missing features, for any definition of "feature". For example, additional built-in arithmetic functions, or additional ways to split fields or records, or anything else. The number of features that 'gawk' does _not_ have is by definition - infinite. It cannot be all things to all people. + infinite. It cannot be all things to all people. In short, just + because 'gawk' doesn't do what _you_ think it should, it's not + necessarily a bug. * Behaviors that are defined by the POSIX standard and/or for historical compatibility with Unix 'awk'. Even if you happen to @@ -31588,9 +31594,15 @@ of the form "that's how 'gawk' behaves and it isn't going to change." This is particularly true when the requested behavior change would break backwards compatibility. + This applies also to differences in behavior between 'gawk' and + other language compilers and interpreters, such as wishes for more + detailed descriptions of what the problem is when a syntax error is + encountered. + * Documentation issues of the form "the manual doesn't tell me how to do XYZ." The manual is not a cookbook to solve every little problem - you may have. + you may have. Its purpose is to teach you how to solve your + problems on your own. * General questions and discussion about 'awk' programming or why 'gawk' behaves the way it does. For that use the "help" mailing @@ -31616,7 +31628,7 @@ make both your life and the lives of the maintainers much easier. 2. Verify that you have the latest version of 'gawk'. Many bugs (usually subtle ones) are fixed at each release, and if yours is - out of date, the problem may already have been solved. + out-of-date, the problem may already have been solved. 3. Please see if setting the environment variable 'LC_ALL' to 'LC_ALL=C' causes things to behave as you expect. If so, it's a @@ -31697,6 +31709,10 @@ developers occasionally read this news group, the primary 'gawk' maintainer no longer does. Thus it's virtually guaranteed that he will _not_ see your posting. + If you really don't care about the previous paragraph and continue to +post bug reports in 'comp.lang.awk', then understand that you're not +reporting bugs, you're just whining. + Similarly, posting bug reports or questions in web forums (such as Stack Overflow (https://stackoverflow.com/)) may get you an answer, but it won't be from the 'gawk' maintainers, who do not spend their time in @@ -31792,7 +31808,7 @@ to that list. Please note: As with the bug list, we ask that you follow the GNU Kind Communication Guidelines (https://gnu.org/philosophy/kind-communication.html) in your -correspondence on the list (as well as off of it). +correspondence on the help list (as well as off of it). If you wish to the subscribe to the list, in order to help out others, or to learn from others, here are instructions, courtesy of Bob @@ -37009,7 +37025,7 @@ Index * in operator: Comparison Operators. (line 11) * in operator <1>: Precedence. (line 82) -* in operator <2>: For Statement. (line 75) +* in operator <2>: For Statement. (line 78) * in operator, testing if array element exists: Reference to Elements. (line 38) * in operator, use in loops: Scanning an Array. (line 17) @@ -37229,7 +37245,7 @@ Index * loops, while: While Statement. (line 6) * loops, do-while: Do Statement. (line 6) * loops, for, iterative: For Statement. (line 6) -* loops, continue statement and: For Statement. (line 64) +* loops, continue statement and: For Statement. (line 67) * loops, exiting: Break Statement. (line 6) * loops, break statement and: Break Statement. (line 6) * loops, for, array scanning: Scanning an Array. (line 6) @@ -38712,403 +38728,403 @@ Node: If Statement448334 Node: While Statement449829 Node: Do Statement451857 Node: For Statement453005 -Node: Switch Statement456176 -Node: Break Statement458617 -Node: Continue Statement460709 -Node: Next Statement462536 -Node: Nextfile Statement464919 -Node: Exit Statement467608 -Node: Built-in Variables470011 -Node: User-modified471144 -Node: Auto-set478911 -Ref: Auto-set-Footnote-1495718 -Ref: Auto-set-Footnote-2495924 -Node: ARGC and ARGV495980 -Node: Pattern Action Summary500193 -Node: Arrays502623 -Node: Array Basics503952 -Node: Array Intro504796 -Ref: figure-array-elements506771 -Ref: Array Intro-Footnote-1509475 -Node: Reference to Elements509603 -Node: Assigning Elements512067 -Node: Array Example512558 -Node: Scanning an Array514317 -Node: Controlling Scanning517339 -Ref: Controlling Scanning-Footnote-1523795 -Node: Numeric Array Subscripts524111 -Node: Uninitialized Subscripts526295 -Node: Delete527914 -Ref: Delete-Footnote-1530666 -Node: Multidimensional530723 -Node: Multiscanning533818 -Node: Arrays of Arrays535409 -Node: Arrays Summary540177 -Node: Functions542270 -Node: Built-in543308 -Node: Calling Built-in544389 -Node: Numeric Functions546385 -Ref: Numeric Functions-Footnote-1550413 -Ref: Numeric Functions-Footnote-2551061 -Ref: Numeric Functions-Footnote-3551109 -Node: String Functions551381 -Ref: String Functions-Footnote-1575896 -Ref: String Functions-Footnote-2576024 -Ref: String Functions-Footnote-3576272 -Node: Gory Details576359 -Ref: table-sub-escapes578150 -Ref: table-sub-proposed579669 -Ref: table-posix-sub581032 -Ref: table-gensub-escapes582573 -Ref: Gory Details-Footnote-1583396 -Node: I/O Functions583550 -Ref: table-system-return-values590004 -Ref: I/O Functions-Footnote-1592084 -Ref: I/O Functions-Footnote-2592232 -Node: Time Functions592352 -Ref: Time Functions-Footnote-1603023 -Ref: Time Functions-Footnote-2603091 -Ref: Time Functions-Footnote-3603249 -Ref: Time Functions-Footnote-4603360 -Ref: Time Functions-Footnote-5603472 -Ref: Time Functions-Footnote-6603699 -Node: Bitwise Functions603965 -Ref: table-bitwise-ops604559 -Ref: Bitwise Functions-Footnote-1610622 -Ref: Bitwise Functions-Footnote-2610795 -Node: Type Functions610986 -Node: I18N Functions614315 -Node: User-defined615966 -Node: Definition Syntax616778 -Ref: Definition Syntax-Footnote-1622472 -Node: Function Example622543 -Ref: Function Example-Footnote-1625465 -Node: Function Calling625487 -Node: Calling A Function626075 -Node: Variable Scope627033 -Node: Pass By Value/Reference630027 -Node: Function Caveats632671 -Ref: Function Caveats-Footnote-1634718 -Node: Return Statement634838 -Node: Dynamic Typing637817 -Node: Indirect Calls638747 -Ref: Indirect Calls-Footnote-1648999 -Node: Functions Summary649127 -Node: Library Functions651832 -Ref: Library Functions-Footnote-1655439 -Ref: Library Functions-Footnote-2655582 -Node: Library Names655753 -Ref: Library Names-Footnote-1659420 -Ref: Library Names-Footnote-2659643 -Node: General Functions659729 -Node: Strtonum Function660911 -Node: Assert Function663933 -Node: Round Function667259 -Node: Cliff Random Function668799 -Node: Ordinal Functions669815 -Ref: Ordinal Functions-Footnote-1672878 -Ref: Ordinal Functions-Footnote-2673130 -Node: Join Function673340 -Ref: Join Function-Footnote-1675110 -Node: Getlocaltime Function675310 -Node: Readfile Function679052 -Node: Shell Quoting681029 -Node: Isnumeric Function682457 -Node: Data File Management683845 -Node: Filetrans Function684477 -Node: Rewind Function688573 -Node: File Checking690482 -Ref: File Checking-Footnote-1691816 -Node: Empty Files692017 -Node: Ignoring Assigns693996 -Node: Getopt Function695546 -Ref: Getopt Function-Footnote-1710769 -Node: Passwd Functions710969 -Ref: Passwd Functions-Footnote-1719808 -Node: Group Functions719896 -Ref: Group Functions-Footnote-1727794 -Node: Walking Arrays728001 -Node: Library Functions Summary731009 -Node: Library Exercises732415 -Node: Sample Programs732880 -Node: Running Examples733650 -Node: Clones734378 -Node: Cut Program735602 -Node: Egrep Program745742 -Node: Id Program754743 -Node: Split Program764690 -Ref: Split Program-Footnote-1774583 -Node: Tee Program774756 -Node: Uniq Program777546 -Node: Wc Program785134 -Node: Bytes vs. Characters785521 -Node: Using extensions787069 -Node: wc program787823 -Node: Miscellaneous Programs792688 -Node: Dupword Program793901 -Node: Alarm Program795931 -Node: Translate Program800786 -Ref: Translate Program-Footnote-1805351 -Node: Labels Program805621 -Ref: Labels Program-Footnote-1808972 -Node: Word Sorting809056 -Node: History Sorting813128 -Node: Extract Program815353 -Node: Simple Sed823407 -Node: Igawk Program826481 -Ref: Igawk Program-Footnote-1840812 -Ref: Igawk Program-Footnote-2841014 -Ref: Igawk Program-Footnote-3841136 -Node: Anagram Program841251 -Node: Signature Program844313 -Node: Programs Summary845560 -Node: Programs Exercises846774 -Ref: Programs Exercises-Footnote-1850904 -Node: Advanced Features850990 -Node: Nondecimal Data853057 -Node: Array Sorting854648 -Node: Controlling Array Traversal855348 -Ref: Controlling Array Traversal-Footnote-1863716 -Node: Array Sorting Functions863834 -Ref: Array Sorting Functions-Footnote-1869208 -Node: Two-way I/O869404 -Ref: Two-way I/O-Footnote-1877130 -Ref: Two-way I/O-Footnote-2877317 -Node: TCP/IP Networking877399 -Node: Profiling880517 -Node: Extension Philosophy889826 -Node: Advanced Features Summary891305 -Node: Internationalization893320 -Node: I18N and L10N894994 -Node: Explaining gettext895681 -Ref: Explaining gettext-Footnote-1901573 -Ref: Explaining gettext-Footnote-2901758 -Node: Programmer i18n901923 -Ref: Programmer i18n-Footnote-1906872 -Node: Translator i18n906921 -Node: String Extraction907715 -Ref: String Extraction-Footnote-1908847 -Node: Printf Ordering908933 -Ref: Printf Ordering-Footnote-1911719 -Node: I18N Portability911783 -Ref: I18N Portability-Footnote-1914239 -Node: I18N Example914302 -Ref: I18N Example-Footnote-1917577 -Ref: I18N Example-Footnote-2917650 -Node: Gawk I18N917759 -Node: I18N Summary918408 -Node: Debugger919749 -Node: Debugging920749 -Node: Debugging Concepts921190 -Node: Debugging Terms922999 -Node: Awk Debugging925574 -Ref: Awk Debugging-Footnote-1926519 -Node: Sample Debugging Session926651 -Node: Debugger Invocation927185 -Node: Finding The Bug928571 -Node: List of Debugger Commands935045 -Node: Breakpoint Control936378 -Node: Debugger Execution Control940072 -Node: Viewing And Changing Data943434 -Node: Execution Stack946975 -Node: Debugger Info948612 -Node: Miscellaneous Debugger Commands952683 -Node: Readline Support957745 -Node: Limitations958641 -Node: Debugging Summary961195 -Node: Namespaces962474 -Node: Global Namespace963585 -Node: Qualified Names964983 -Node: Default Namespace965982 -Node: Changing The Namespace966723 -Node: Naming Rules968337 -Node: Internal Name Management970185 -Node: Namespace Example971227 -Node: Namespace And Features973789 -Node: Namespace Summary975224 -Node: Arbitrary Precision Arithmetic976701 -Node: Computer Arithmetic978188 -Ref: table-numeric-ranges981954 -Ref: table-floating-point-ranges982447 -Ref: Computer Arithmetic-Footnote-1983105 -Node: Math Definitions983162 -Ref: table-ieee-formats986478 -Ref: Math Definitions-Footnote-1987081 -Node: MPFR features987186 -Node: FP Math Caution988904 -Ref: FP Math Caution-Footnote-1989976 -Node: Inexactness of computations990345 -Node: Inexact representation991305 -Node: Comparing FP Values992665 -Node: Errors accumulate993906 -Node: Getting Accuracy995339 -Node: Try To Round998049 -Node: Setting precision998948 -Ref: table-predefined-precision-strings999645 -Node: Setting the rounding mode1001475 -Ref: table-gawk-rounding-modes1001849 -Ref: Setting the rounding mode-Footnote-11005780 -Node: Arbitrary Precision Integers1005959 -Ref: Arbitrary Precision Integers-Footnote-11009134 -Node: Checking for MPFR1009283 -Node: POSIX Floating Point Problems1010757 -Ref: POSIX Floating Point Problems-Footnote-11015042 -Node: Floating point summary1015080 -Node: Dynamic Extensions1017270 -Node: Extension Intro1018823 -Node: Plugin License1020089 -Node: Extension Mechanism Outline1020886 -Ref: figure-load-extension1021325 -Ref: figure-register-new-function1022890 -Ref: figure-call-new-function1023982 -Node: Extension API Description1026044 -Node: Extension API Functions Introduction1027757 -Ref: table-api-std-headers1029593 -Node: General Data Types1033842 -Ref: General Data Types-Footnote-11042472 -Node: Memory Allocation Functions1042771 -Ref: Memory Allocation Functions-Footnote-11047272 -Node: Constructor Functions1047371 -Node: API Ownership of MPFR and GMP Values1050837 -Node: Registration Functions1052150 -Node: Extension Functions1052850 -Node: Exit Callback Functions1058172 -Node: Extension Version String1059422 -Node: Input Parsers1060085 -Node: Output Wrappers1072806 -Node: Two-way processors1077318 -Node: Printing Messages1079583 -Ref: Printing Messages-Footnote-11080754 -Node: Updating ERRNO1080907 -Node: Requesting Values1081646 -Ref: table-value-types-returned1082383 -Node: Accessing Parameters1083319 -Node: Symbol Table Access1084556 -Node: Symbol table by name1085068 -Ref: Symbol table by name-Footnote-11088093 -Node: Symbol table by cookie1088221 -Ref: Symbol table by cookie-Footnote-11092406 -Node: Cached values1092470 -Ref: Cached values-Footnote-11096006 -Node: Array Manipulation1096159 -Ref: Array Manipulation-Footnote-11097250 -Node: Array Data Types1097287 -Ref: Array Data Types-Footnote-11099945 -Node: Array Functions1100037 -Node: Flattening Arrays1104535 -Node: Creating Arrays1111511 -Node: Redirection API1116278 -Node: Extension API Variables1119111 -Node: Extension Versioning1119822 -Ref: gawk-api-version1120251 -Node: Extension GMP/MPFR Versioning1121982 -Node: Extension API Informational Variables1123610 -Node: Extension API Boilerplate1124683 -Node: Changes from API V11128657 -Node: Finding Extensions1130229 -Node: Extension Example1130788 -Node: Internal File Description1131586 -Node: Internal File Ops1135666 -Ref: Internal File Ops-Footnote-11147016 -Node: Using Internal File Ops1147156 -Ref: Using Internal File Ops-Footnote-11149539 -Node: Extension Samples1149813 -Node: Extension Sample File Functions1151342 -Node: Extension Sample Fnmatch1158991 -Node: Extension Sample Fork1160478 -Node: Extension Sample Inplace1161696 -Node: Extension Sample Ord1165322 -Node: Extension Sample Readdir1166158 -Ref: table-readdir-file-types1167047 -Node: Extension Sample Revout1168114 -Node: Extension Sample Rev2way1168703 -Node: Extension Sample Read write array1169443 -Node: Extension Sample Readfile1171385 -Node: Extension Sample Time1172480 -Node: Extension Sample API Tests1174232 -Node: gawkextlib1174724 -Node: Extension summary1177642 -Node: Extension Exercises1181344 -Node: Language History1182586 -Node: V7/SVR3.11184242 -Node: SVR41186394 -Node: POSIX1187828 -Node: BTL1189209 -Node: POSIX/GNU1189938 -Node: Feature History1195716 -Node: Common Extensions1212891 -Node: Ranges and Locales1214174 -Ref: Ranges and Locales-Footnote-11218790 -Ref: Ranges and Locales-Footnote-21218817 -Ref: Ranges and Locales-Footnote-31219052 -Node: Contributors1219275 -Node: History summary1225272 -Node: Installation1226652 -Node: Gawk Distribution1227596 -Node: Getting1228080 -Node: Extracting1229043 -Node: Distribution contents1230681 -Node: Unix Installation1237823 -Node: Quick Installation1238627 -Node: Compiling with MPFR1241103 -Node: Shell Startup Files1241795 -Node: Additional Configuration Options1242884 -Node: Configuration Philosophy1245199 -Node: Compiling from Git1247595 -Node: Building the Documentation1248150 -Node: Non-Unix Installation1249534 -Node: PC Installation1249994 -Node: PC Binary Installation1250832 -Node: PC Compiling1251267 -Node: PC Using1252384 -Node: Cygwin1255937 -Node: MSYS1257161 -Node: VMS Installation1257763 -Node: VMS Compilation1258482 -Ref: VMS Compilation-Footnote-11259711 -Node: VMS Dynamic Extensions1259769 -Node: VMS Installation Details1261454 -Node: VMS Running1263716 -Node: VMS GNV1267995 -Node: Bugs1268709 -Node: Bug definition1269621 -Node: Bug address1272125 -Node: Usenet1275513 -Node: Performance bugs1276522 -Node: Asking for help1279443 -Node: Maintainers1281405 -Node: Other Versions1282599 -Node: Installation summary1290451 -Node: Notes1291815 -Node: Compatibility Mode1292609 -Node: Additions1293391 -Node: Accessing The Source1294316 -Node: Adding Code1295753 -Node: New Ports1301972 -Node: Derived Files1306347 -Ref: Derived Files-Footnote-11312007 -Ref: Derived Files-Footnote-21312042 -Ref: Derived Files-Footnote-31312640 -Node: Future Extensions1312754 -Node: Implementation Limitations1313412 -Node: Extension Design1314622 -Node: Old Extension Problems1315766 -Ref: Old Extension Problems-Footnote-11317284 -Node: Extension New Mechanism Goals1317341 -Ref: Extension New Mechanism Goals-Footnote-11320705 -Node: Extension Other Design Decisions1320894 -Node: Extension Future Growth1323007 -Node: Notes summary1323613 -Node: Basic Concepts1324771 -Node: Basic High Level1325452 -Ref: figure-general-flow1325734 -Ref: figure-process-flow1326419 -Ref: Basic High Level-Footnote-11329720 -Node: Basic Data Typing1329905 -Node: Glossary1333233 -Node: Copying1365118 -Node: GNU Free Documentation License1402661 -Node: Index1427781 +Node: Switch Statement456261 +Node: Break Statement458702 +Node: Continue Statement460794 +Node: Next Statement462621 +Node: Nextfile Statement465004 +Node: Exit Statement467693 +Node: Built-in Variables470096 +Node: User-modified471229 +Node: Auto-set478996 +Ref: Auto-set-Footnote-1495803 +Ref: Auto-set-Footnote-2496009 +Node: ARGC and ARGV496065 +Node: Pattern Action Summary500278 +Node: Arrays502708 +Node: Array Basics504037 +Node: Array Intro504881 +Ref: figure-array-elements506856 +Ref: Array Intro-Footnote-1509560 +Node: Reference to Elements509688 +Node: Assigning Elements512152 +Node: Array Example512643 +Node: Scanning an Array514402 +Node: Controlling Scanning517424 +Ref: Controlling Scanning-Footnote-1523880 +Node: Numeric Array Subscripts524196 +Node: Uninitialized Subscripts526380 +Node: Delete527999 +Ref: Delete-Footnote-1530751 +Node: Multidimensional530808 +Node: Multiscanning533903 +Node: Arrays of Arrays535494 +Node: Arrays Summary540262 +Node: Functions542355 +Node: Built-in543393 +Node: Calling Built-in544474 +Node: Numeric Functions546470 +Ref: Numeric Functions-Footnote-1550498 +Ref: Numeric Functions-Footnote-2551146 +Ref: Numeric Functions-Footnote-3551194 +Node: String Functions551466 +Ref: String Functions-Footnote-1575981 +Ref: String Functions-Footnote-2576109 +Ref: String Functions-Footnote-3576357 +Node: Gory Details576444 +Ref: table-sub-escapes578235 +Ref: table-sub-proposed579754 +Ref: table-posix-sub581117 +Ref: table-gensub-escapes582658 +Ref: Gory Details-Footnote-1583481 +Node: I/O Functions583635 +Ref: table-system-return-values590089 +Ref: I/O Functions-Footnote-1592169 +Ref: I/O Functions-Footnote-2592317 +Node: Time Functions592437 +Ref: Time Functions-Footnote-1603108 +Ref: Time Functions-Footnote-2603176 +Ref: Time Functions-Footnote-3603334 +Ref: Time Functions-Footnote-4603445 +Ref: Time Functions-Footnote-5603557 +Ref: Time Functions-Footnote-6603784 +Node: Bitwise Functions604050 +Ref: table-bitwise-ops604644 +Ref: Bitwise Functions-Footnote-1610707 +Ref: Bitwise Functions-Footnote-2610880 +Node: Type Functions611071 +Node: I18N Functions614400 +Node: User-defined616051 +Node: Definition Syntax616863 +Ref: Definition Syntax-Footnote-1622557 +Node: Function Example622628 +Ref: Function Example-Footnote-1625550 +Node: Function Calling625572 +Node: Calling A Function626160 +Node: Variable Scope627118 +Node: Pass By Value/Reference630112 +Node: Function Caveats632756 +Ref: Function Caveats-Footnote-1634803 +Node: Return Statement634923 +Node: Dynamic Typing637902 +Node: Indirect Calls638832 +Ref: Indirect Calls-Footnote-1649084 +Node: Functions Summary649212 +Node: Library Functions651917 +Ref: Library Functions-Footnote-1655524 +Ref: Library Functions-Footnote-2655667 +Node: Library Names655838 +Ref: Library Names-Footnote-1659505 +Ref: Library Names-Footnote-2659728 +Node: General Functions659814 +Node: Strtonum Function660996 +Node: Assert Function664018 +Node: Round Function667344 +Node: Cliff Random Function668884 +Node: Ordinal Functions669900 +Ref: Ordinal Functions-Footnote-1672963 +Ref: Ordinal Functions-Footnote-2673215 +Node: Join Function673425 +Ref: Join Function-Footnote-1675195 +Node: Getlocaltime Function675395 +Node: Readfile Function679137 +Node: Shell Quoting681114 +Node: Isnumeric Function682542 +Node: Data File Management683930 +Node: Filetrans Function684562 +Node: Rewind Function688658 +Node: File Checking690567 +Ref: File Checking-Footnote-1691901 +Node: Empty Files692102 +Node: Ignoring Assigns694081 +Node: Getopt Function695631 +Ref: Getopt Function-Footnote-1710854 +Node: Passwd Functions711054 +Ref: Passwd Functions-Footnote-1719893 +Node: Group Functions719981 +Ref: Group Functions-Footnote-1727879 +Node: Walking Arrays728086 +Node: Library Functions Summary731094 +Node: Library Exercises732500 +Node: Sample Programs732965 +Node: Running Examples733735 +Node: Clones734463 +Node: Cut Program735687 +Node: Egrep Program745827 +Node: Id Program754828 +Node: Split Program764775 +Ref: Split Program-Footnote-1774668 +Node: Tee Program774841 +Node: Uniq Program777631 +Node: Wc Program785219 +Node: Bytes vs. Characters785606 +Node: Using extensions787154 +Node: wc program787908 +Node: Miscellaneous Programs792773 +Node: Dupword Program793986 +Node: Alarm Program796016 +Node: Translate Program800871 +Ref: Translate Program-Footnote-1805436 +Node: Labels Program805706 +Ref: Labels Program-Footnote-1809057 +Node: Word Sorting809141 +Node: History Sorting813213 +Node: Extract Program815438 +Node: Simple Sed823492 +Node: Igawk Program826566 +Ref: Igawk Program-Footnote-1840897 +Ref: Igawk Program-Footnote-2841099 +Ref: Igawk Program-Footnote-3841221 +Node: Anagram Program841336 +Node: Signature Program844398 +Node: Programs Summary845645 +Node: Programs Exercises846859 +Ref: Programs Exercises-Footnote-1850989 +Node: Advanced Features851075 +Node: Nondecimal Data853142 +Node: Array Sorting854733 +Node: Controlling Array Traversal855433 +Ref: Controlling Array Traversal-Footnote-1863801 +Node: Array Sorting Functions863919 +Ref: Array Sorting Functions-Footnote-1869293 +Node: Two-way I/O869489 +Ref: Two-way I/O-Footnote-1877215 +Ref: Two-way I/O-Footnote-2877402 +Node: TCP/IP Networking877484 +Node: Profiling880602 +Node: Extension Philosophy889911 +Node: Advanced Features Summary891390 +Node: Internationalization893405 +Node: I18N and L10N895079 +Node: Explaining gettext895766 +Ref: Explaining gettext-Footnote-1901658 +Ref: Explaining gettext-Footnote-2901843 +Node: Programmer i18n902008 +Ref: Programmer i18n-Footnote-1906957 +Node: Translator i18n907006 +Node: String Extraction907800 +Ref: String Extraction-Footnote-1908932 +Node: Printf Ordering909018 +Ref: Printf Ordering-Footnote-1911804 +Node: I18N Portability911868 +Ref: I18N Portability-Footnote-1914324 +Node: I18N Example914387 +Ref: I18N Example-Footnote-1917662 +Ref: I18N Example-Footnote-2917735 +Node: Gawk I18N917844 +Node: I18N Summary918493 +Node: Debugger919834 +Node: Debugging920834 +Node: Debugging Concepts921275 +Node: Debugging Terms923084 +Node: Awk Debugging925659 +Ref: Awk Debugging-Footnote-1926604 +Node: Sample Debugging Session926736 +Node: Debugger Invocation927270 +Node: Finding The Bug928656 +Node: List of Debugger Commands935130 +Node: Breakpoint Control936463 +Node: Debugger Execution Control940157 +Node: Viewing And Changing Data943519 +Node: Execution Stack947060 +Node: Debugger Info948697 +Node: Miscellaneous Debugger Commands952768 +Node: Readline Support957830 +Node: Limitations958726 +Node: Debugging Summary961280 +Node: Namespaces962559 +Node: Global Namespace963670 +Node: Qualified Names965068 +Node: Default Namespace966067 +Node: Changing The Namespace966808 +Node: Naming Rules968422 +Node: Internal Name Management970270 +Node: Namespace Example971312 +Node: Namespace And Features973874 +Node: Namespace Summary975309 +Node: Arbitrary Precision Arithmetic976786 +Node: Computer Arithmetic978273 +Ref: table-numeric-ranges982039 +Ref: table-floating-point-ranges982532 +Ref: Computer Arithmetic-Footnote-1983190 +Node: Math Definitions983247 +Ref: table-ieee-formats986563 +Ref: Math Definitions-Footnote-1987166 +Node: MPFR features987271 +Node: FP Math Caution988989 +Ref: FP Math Caution-Footnote-1990061 +Node: Inexactness of computations990430 +Node: Inexact representation991390 +Node: Comparing FP Values992750 +Node: Errors accumulate993991 +Node: Getting Accuracy995424 +Node: Try To Round998134 +Node: Setting precision999033 +Ref: table-predefined-precision-strings999730 +Node: Setting the rounding mode1001560 +Ref: table-gawk-rounding-modes1001934 +Ref: Setting the rounding mode-Footnote-11005865 +Node: Arbitrary Precision Integers1006044 +Ref: Arbitrary Precision Integers-Footnote-11009219 +Node: Checking for MPFR1009368 +Node: POSIX Floating Point Problems1010842 +Ref: POSIX Floating Point Problems-Footnote-11015127 +Node: Floating point summary1015165 +Node: Dynamic Extensions1017355 +Node: Extension Intro1018908 +Node: Plugin License1020174 +Node: Extension Mechanism Outline1020971 +Ref: figure-load-extension1021410 +Ref: figure-register-new-function1022975 +Ref: figure-call-new-function1024067 +Node: Extension API Description1026129 +Node: Extension API Functions Introduction1027842 +Ref: table-api-std-headers1029678 +Node: General Data Types1033927 +Ref: General Data Types-Footnote-11042557 +Node: Memory Allocation Functions1042856 +Ref: Memory Allocation Functions-Footnote-11047357 +Node: Constructor Functions1047456 +Node: API Ownership of MPFR and GMP Values1050922 +Node: Registration Functions1052235 +Node: Extension Functions1052935 +Node: Exit Callback Functions1058257 +Node: Extension Version String1059507 +Node: Input Parsers1060170 +Node: Output Wrappers1072891 +Node: Two-way processors1077403 +Node: Printing Messages1079668 +Ref: Printing Messages-Footnote-11080839 +Node: Updating ERRNO1080992 +Node: Requesting Values1081731 +Ref: table-value-types-returned1082468 +Node: Accessing Parameters1083404 +Node: Symbol Table Access1084641 +Node: Symbol table by name1085153 +Ref: Symbol table by name-Footnote-11088178 +Node: Symbol table by cookie1088306 +Ref: Symbol table by cookie-Footnote-11092491 +Node: Cached values1092555 +Ref: Cached values-Footnote-11096091 +Node: Array Manipulation1096244 +Ref: Array Manipulation-Footnote-11097335 +Node: Array Data Types1097372 +Ref: Array Data Types-Footnote-11100030 +Node: Array Functions1100122 +Node: Flattening Arrays1104620 +Node: Creating Arrays1111596 +Node: Redirection API1116363 +Node: Extension API Variables1119196 +Node: Extension Versioning1119907 +Ref: gawk-api-version1120336 +Node: Extension GMP/MPFR Versioning1122067 +Node: Extension API Informational Variables1123695 +Node: Extension API Boilerplate1124768 +Node: Changes from API V11128742 +Node: Finding Extensions1130314 +Node: Extension Example1130873 +Node: Internal File Description1131671 +Node: Internal File Ops1135751 +Ref: Internal File Ops-Footnote-11147101 +Node: Using Internal File Ops1147241 +Ref: Using Internal File Ops-Footnote-11149624 +Node: Extension Samples1149898 +Node: Extension Sample File Functions1151427 +Node: Extension Sample Fnmatch1159076 +Node: Extension Sample Fork1160563 +Node: Extension Sample Inplace1161781 +Node: Extension Sample Ord1165407 +Node: Extension Sample Readdir1166243 +Ref: table-readdir-file-types1167132 +Node: Extension Sample Revout1168199 +Node: Extension Sample Rev2way1168788 +Node: Extension Sample Read write array1169528 +Node: Extension Sample Readfile1171470 +Node: Extension Sample Time1172565 +Node: Extension Sample API Tests1174317 +Node: gawkextlib1174809 +Node: Extension summary1177727 +Node: Extension Exercises1181429 +Node: Language History1182671 +Node: V7/SVR3.11184327 +Node: SVR41186479 +Node: POSIX1187913 +Node: BTL1189294 +Node: POSIX/GNU1190023 +Node: Feature History1195801 +Node: Common Extensions1212976 +Node: Ranges and Locales1214259 +Ref: Ranges and Locales-Footnote-11218875 +Ref: Ranges and Locales-Footnote-21218902 +Ref: Ranges and Locales-Footnote-31219137 +Node: Contributors1219360 +Node: History summary1225357 +Node: Installation1226737 +Node: Gawk Distribution1227681 +Node: Getting1228165 +Node: Extracting1229128 +Node: Distribution contents1230766 +Node: Unix Installation1237908 +Node: Quick Installation1238712 +Node: Compiling with MPFR1241188 +Node: Shell Startup Files1241880 +Node: Additional Configuration Options1242969 +Node: Configuration Philosophy1245284 +Node: Compiling from Git1247680 +Node: Building the Documentation1248235 +Node: Non-Unix Installation1249619 +Node: PC Installation1250079 +Node: PC Binary Installation1250917 +Node: PC Compiling1251352 +Node: PC Using1252469 +Node: Cygwin1256022 +Node: MSYS1257246 +Node: VMS Installation1257848 +Node: VMS Compilation1258567 +Ref: VMS Compilation-Footnote-11259796 +Node: VMS Dynamic Extensions1259854 +Node: VMS Installation Details1261539 +Node: VMS Running1263801 +Node: VMS GNV1268080 +Node: Bugs1268794 +Node: Bug definition1269706 +Node: Bug address1272642 +Node: Usenet1276030 +Node: Performance bugs1277219 +Node: Asking for help1280140 +Node: Maintainers1282107 +Node: Other Versions1283301 +Node: Installation summary1291153 +Node: Notes1292517 +Node: Compatibility Mode1293311 +Node: Additions1294093 +Node: Accessing The Source1295018 +Node: Adding Code1296455 +Node: New Ports1302674 +Node: Derived Files1307049 +Ref: Derived Files-Footnote-11312709 +Ref: Derived Files-Footnote-21312744 +Ref: Derived Files-Footnote-31313342 +Node: Future Extensions1313456 +Node: Implementation Limitations1314114 +Node: Extension Design1315324 +Node: Old Extension Problems1316468 +Ref: Old Extension Problems-Footnote-11317986 +Node: Extension New Mechanism Goals1318043 +Ref: Extension New Mechanism Goals-Footnote-11321407 +Node: Extension Other Design Decisions1321596 +Node: Extension Future Growth1323709 +Node: Notes summary1324315 +Node: Basic Concepts1325473 +Node: Basic High Level1326154 +Ref: figure-general-flow1326436 +Ref: figure-process-flow1327121 +Ref: Basic High Level-Footnote-11330422 +Node: Basic Data Typing1330607 +Node: Glossary1333935 +Node: Copying1365820 +Node: GNU Free Documentation License1403363 +Node: Index1428483 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 3f79cd9f..e4262229 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -15309,20 +15309,25 @@ awk ' This prints the first three fields of each input record, with one input field per output line. -It isn't possible to -set more than one variable in the -@var{initialization} part without using a multiple assignment statement -such as @samp{x = y = 0}. This makes sense only if all the initial values -are equal. (But it is possible to initialize additional variables by writing -their assignments as separate statements preceding the @code{for} loop.) - @c @cindex comma operator, not supported -The same is true of the @var{increment} part. Incrementing additional -variables requires separate statements at the end of the loop. -The C compound expression, using C's comma operator, is useful in -this context, but it is not supported in @command{awk}. +C and C++ programmers might expect to be able to use the comma +operator to set more than one variable in the @var{initialization} +part of the @code{for} loop, or to increment multiple variables in the +@var{incrememnt} part of the loop, like so: + +@example +for (i = 0, j = length(a); i < j; i++, j--) @dots{} @ii{C/C++, not awk!} +@end example + +@noindent +You cannot do this; the comma operator is not supported in @command{awk}. +There are workarounds, but they are nonobvious and can lead to +code that is difficult to read and understand. It is best, therefore, +to simply write additional initializations as separate statements +preceding the @code{for} loop and to place additional increment statements +at the end of the loop's body. -Most often, @var{increment} is an increment expression, as in the previous +Most often, @var{increment} is an increment expression, as in the earlier example. But this is not required; it can be any expression whatsoever. For example, the following statement prints all the powers of two between 1 and 100: @@ -42948,7 +42953,7 @@ The following things are @emph{not} bugs, and should not be reported to the bug mailing list. You can ask about them on the ``help'' mailing list (@pxref{Asking for help}), but don't be surprised if you get an answer of the form ``that's how @command{gawk} behaves and it isn't -going to change.'' +going to change.'' Here's the list: @itemize @bullet @item @@ -42958,6 +42963,8 @@ fields or records, or anything else. The number of features that @command{gawk} does @emph{not} have is by definition infinite. It cannot be all things to all people. +In short, just because @command{gawk} doesn't do what @emph{you} +think it should, it's not necessarily a bug. @item Behaviors that are defined by the POSIX standard and/or for historical @@ -42971,10 +42978,16 @@ and @command{gawk} stand on their own and do not have to follow the crowd. This is particularly true when the requested behavior change would break backwards compatibility. +This applies also to differences in behavior between @command{gawk} +and other language compilers and interpreters, such as wishes for more +detailed descriptions of what the problem is when a syntax error is +encountered. + @item Documentation issues of the form ``the manual doesn't tell me how to do XYZ.'' The manual is not a cookbook to solve every little problem -you may have. +you may have. Its purpose is to teach you how to solve your problems +on your own. @item General questions and discussion about @command{awk} programming or @@ -43003,7 +43016,7 @@ time and ours. @item Verify that you have the latest version of @command{gawk}. Many bugs (usually subtle ones) are fixed at each release, and if yours -is out of date, the problem may already have been solved. +is out-of-date, the problem may already have been solved. @item Please see if setting the environment variable @env{LC_ALL} @@ -43109,6 +43122,10 @@ Usenet/Internet newsgroup @code{comp.lang.awk}. Although some of the @command{gawk} maintainer no longer does. Thus it's virtually guaranteed that he will @emph{not} see your posting. +If you really don't care about the previous paragraph and continue to +post bug reports in @code{comp.lang.awk}, then understand that you're +not reporting bugs, you're just whining. + Similarly, posting bug reports or questions in web forums (such as @uref{https://stackoverflow.com/, Stack Overflow}) may get you an answer, but it won't be from the @command{gawk} maintainers, @@ -43233,7 +43250,7 @@ After two such requests you will be silently @emph{blacklisted} from the bug lis Please note: As with the bug list, we ask that you follow the @uref{https://gnu.org/philosophy/kind-communication.html, -GNU Kind Communication Guidelines} in your correspondence on the +GNU Kind Communication Guidelines} in your correspondence on the help list (as well as off of it). @cindex Proulx, Bob @@ -43241,7 +43258,6 @@ If you wish to the subscribe to the list, in order to help out others, or to learn from others, here are instructions, courtesy of Bob Proulx: - @table @emph @item Subscribe by email diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 2c69cc51..58886495 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -14496,20 +14496,25 @@ awk ' This prints the first three fields of each input record, with one input field per output line. -It isn't possible to -set more than one variable in the -@var{initialization} part without using a multiple assignment statement -such as @samp{x = y = 0}. This makes sense only if all the initial values -are equal. (But it is possible to initialize additional variables by writing -their assignments as separate statements preceding the @code{for} loop.) - @c @cindex comma operator, not supported -The same is true of the @var{increment} part. Incrementing additional -variables requires separate statements at the end of the loop. -The C compound expression, using C's comma operator, is useful in -this context, but it is not supported in @command{awk}. +C and C++ programmers might expect to be able to use the comma +operator to set more than one variable in the @var{initialization} +part of the @code{for} loop, or to increment multiple variables in the +@var{incrememnt} part of the loop, like so: + +@example +for (i = 0, j = length(a); i < j; i++, j--) @dots{} @ii{C/C++, not awk!} +@end example + +@noindent +You cannot do this; the comma operator is not supported in @command{awk}. +There are workarounds, but they are nonobvious and can lead to +code that is difficult to read and understand. It is best, therefore, +to simply write additional initializations as separate statements +preceding the @code{for} loop and to place additional increment statements +at the end of the loop's body. -Most often, @var{increment} is an increment expression, as in the previous +Most often, @var{increment} is an increment expression, as in the earlier example. But this is not required; it can be any expression whatsoever. For example, the following statement prints all the powers of two between 1 and 100: @@ -41791,7 +41796,7 @@ The following things are @emph{not} bugs, and should not be reported to the bug mailing list. You can ask about them on the ``help'' mailing list (@pxref{Asking for help}), but don't be surprised if you get an answer of the form ``that's how @command{gawk} behaves and it isn't -going to change.'' +going to change.'' Here's the list: @itemize @bullet @item @@ -41801,6 +41806,8 @@ fields or records, or anything else. The number of features that @command{gawk} does @emph{not} have is by definition infinite. It cannot be all things to all people. +In short, just because @command{gawk} doesn't do what @emph{you} +think it should, it's not necessarily a bug. @item Behaviors that are defined by the POSIX standard and/or for historical @@ -41814,10 +41821,16 @@ and @command{gawk} stand on their own and do not have to follow the crowd. This is particularly true when the requested behavior change would break backwards compatibility. +This applies also to differences in behavior between @command{gawk} +and other language compilers and interpreters, such as wishes for more +detailed descriptions of what the problem is when a syntax error is +encountered. + @item Documentation issues of the form ``the manual doesn't tell me how to do XYZ.'' The manual is not a cookbook to solve every little problem -you may have. +you may have. Its purpose is to teach you how to solve your problems +on your own. @item General questions and discussion about @command{awk} programming or @@ -41846,7 +41859,7 @@ time and ours. @item Verify that you have the latest version of @command{gawk}. Many bugs (usually subtle ones) are fixed at each release, and if yours -is out of date, the problem may already have been solved. +is out-of-date, the problem may already have been solved. @item Please see if setting the environment variable @env{LC_ALL} @@ -41952,6 +41965,10 @@ Usenet/Internet newsgroup @code{comp.lang.awk}. Although some of the @command{gawk} maintainer no longer does. Thus it's virtually guaranteed that he will @emph{not} see your posting. +If you really don't care about the previous paragraph and continue to +post bug reports in @code{comp.lang.awk}, then understand that you're +not reporting bugs, you're just whining. + Similarly, posting bug reports or questions in web forums (such as @uref{https://stackoverflow.com/, Stack Overflow}) may get you an answer, but it won't be from the @command{gawk} maintainers, @@ -42076,7 +42093,7 @@ After two such requests you will be silently @emph{blacklisted} from the bug lis Please note: As with the bug list, we ask that you follow the @uref{https://gnu.org/philosophy/kind-communication.html, -GNU Kind Communication Guidelines} in your correspondence on the +GNU Kind Communication Guidelines} in your correspondence on the help list (as well as off of it). @cindex Proulx, Bob @@ -42084,7 +42101,6 @@ If you wish to the subscribe to the list, in order to help out others, or to learn from others, here are instructions, courtesy of Bob Proulx: - @table @emph @item Subscribe by email |