diff options
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 606 | ||||
| -rw-r--r-- | doc/gawk.texi | 92 | ||||
| -rw-r--r-- | doc/gawktexi.in | 92 |
4 files changed, 403 insertions, 391 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index c0c382d3..012511be 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2014-05-16 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Edits through Chapter 14. + 2014-05-15 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Fix displays for docbook, edits through Chapter 11. diff --git a/doc/gawk.info b/doc/gawk.info index a9fcc117..5cf6129d 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -18171,8 +18171,8 @@ your data as numeric: The `print' statement treats its expressions as strings. Although the fields can act as numbers when necessary, they are still strings, so -`print' does not try to treat them numerically. You may need to add -zero to a field to force it to be treated as a number. For example: +`print' does not try to treat them numerically. You need to add zero +to a field to force it to be treated as a number. For example: $ echo 0123 123 0x123 | gawk --non-decimal-data ' > { print $1, $2, $3 @@ -18187,7 +18187,7 @@ request it. CAUTION: _Use of this option is not recommended._ It can break old programs very badly. Instead, use the `strtonum()' function to - convert your data (*note Nondecimal-numbers::). This makes your + convert your data (*note String Functions::). This makes your programs easier to write and easier to read, and leads to less surprising results. @@ -18226,7 +18226,7 @@ you do this. *note Controlling Scanning::, describes how you can assign special, pre-defined values to `PROCINFO["sorted_in"]' in order to control the -order in which `gawk' will traverse an array during a `for' loop. +order in which `gawk' traverses an array during a `for' loop. In addition, the value of `PROCINFO["sorted_in"]' can be a function name. This lets you traverse an array based on any custom criterion. @@ -18499,9 +18499,9 @@ become the values of the result array: So far, so good. Now it starts to get interesting. Both `asort()' and `asorti()' accept a third string argument to control comparison of -array elements. In *note String Functions::, we ignored this third -argument; however, the time has now come to describe how this argument -affects these two functions. +array elements. When we introduced `asort()' and `asorti()' in *note +String Functions::, we ignored this third argument; however, now is the +time to describe how this argument affects these two functions. Basically, the third argument specifies how the array is to be sorted. There are two possibilities. As with `PROCINFO["sorted_in"]', @@ -18649,7 +18649,8 @@ the `gawk' program. Once all of the data has been read, `gawk' terminates the coprocess and exits. As a side note, the assignment `LC_ALL=C' in the `sort' command -ensures traditional Unix (ASCII) sorting from `sort'. +ensures traditional Unix (ASCII) sorting from `sort'. This is not +strictly necessary here, but it's good to know how to do this. You may also use pseudo-ttys (ptys) for two-way communication instead of pipes, if your system supports them. This is done on a @@ -18661,10 +18662,10 @@ per-command basis, by setting a special element in the `PROCINFO' array print ... |& command # start two-way pipe ... -Using ptys avoids the buffer deadlock issues described earlier, at some -loss in performance. If your system does not have ptys, or if all the -system's ptys are in use, `gawk' automatically falls back to using -regular pipes. +Using ptys usually avoids the buffer deadlock issues described earlier, +at some loss in performance. If your system does not have ptys, or if +all the system's ptys are in use, `gawk' automatically falls back to +using regular pipes. ---------- Footnotes ---------- @@ -18945,7 +18946,7 @@ As usual, the profiled version of the program is written to `awkprof.out', or to a different file if one specified with the `--profile' option. - Along with the regular profile, as shown earlier, the profile + Along with the regular profile, as shown earlier, the profile file includes a trace of any active functions: # Function Call Stack: @@ -19029,6 +19030,7 @@ File: gawk.info, Node: Explaining gettext, Next: Programmer i18n, Prev: I18N 13.2 GNU `gettext' ================== +`gawk' uses GNU `gettext' to provide its internationalization features. The facilities in GNU `gettext' focus on messages; strings printed by a program, either directly or via formatting with `printf' or `sprintf()'.(1) @@ -19175,7 +19177,7 @@ internationalization: for translation at runtime. String constants without a leading underscore are not translated. -``dcgettext(STRING' [`,' DOMAIN [`,' CATEGORY ]]`)'' +``dcgettext(STRING' [`,' DOMAIN [`,' CATEGORY]]`)'' Return the translation of STRING in text domain DOMAIN for locale category CATEGORY. The default value for DOMAIN is the current value of `TEXTDOMAIN'. The default value for CATEGORY is @@ -19192,7 +19194,7 @@ internationalization: be simple and to allow for reasonable `awk'-style default arguments. -``dcngettext(STRING1, STRING2, NUMBER' [`,' DOMAIN [`,' CATEGORY ]]`)'' +``dcngettext(STRING1, STRING2, NUMBER' [`,' DOMAIN [`,' CATEGORY]]`)'' Return the plural form used for NUMBER of the translation of STRING1 and STRING2 in text domain DOMAIN for locale category CATEGORY. STRING1 is the English singular variant of a message, @@ -19508,19 +19510,20 @@ Following are the translations: msgstr "Like, the scoop is" The next step is to make the directory to hold the binary message -object file and then to create the `guide.gmo' file. The directory +object file and then to create the `guide.mo' file. We pretend that +our file is to be used in the `en_US.UTF-8' locale. The directory layout shown here is standard for GNU `gettext' on GNU/Linux systems. Other versions of `gettext' may use a different layout: - $ mkdir en_US en_US/LC_MESSAGES + $ mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES The `msgfmt' utility does the conversion from human-readable `.po' -file to machine-readable `.gmo' file. By default, `msgfmt' creates a +file to machine-readable `.mo' file. By default, `msgfmt' creates a file named `messages'. This file must be renamed and placed in the proper directory so that `gawk' can find it: $ msgfmt guide-mellow.po - $ mv messages en_US/LC_MESSAGES/guide.gmo + $ mv messages en_US.UTF-8/LC_MESSAGES/guide.mo Finally, we run the program to test it: @@ -19584,8 +19587,8 @@ program is easy. File: gawk.info, Node: Debugging, Next: Sample Debugging Session, Up: Debugger -14.1 Introduction to `gawk' Debugger -==================================== +14.1 Introduction to The `gawk' Debugger +======================================== This minor node introduces debugging in general and begins the discussion of debugging in `gawk'. @@ -19871,11 +19874,7 @@ typing `n' (for "next"): decides whether to give the lines the special "field skipping" treatment indicated by the `-f' command-line option. (Notice that we skipped from where we were before at line 64 to here, since the condition in -line 64 - - if (fcount == 0 && charcount == 0) - -was false.) +line 64 `if (fcount == 0 && charcount == 0)' was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -19981,7 +19980,7 @@ following descriptions, commands which may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to automatically repeat the previous command -when just hitting <Enter>. This works for the commands `list', `next', +just by hitting <Enter>. This works for the commands `list', `next', `nexti', `step', `stepi' and `continue' executed without any argument. * Menu: @@ -20241,7 +20240,7 @@ AWK STATEMENTS `set' VAR`='VALUE Assign a constant (number or string) value to an `awk' variable or field. String values must be enclosed between double quotes - (`"..."'). + (`"'...`"'). You can also set special `awk' variables, such as `FS', `NF', `NR', etc. @@ -20295,11 +20294,12 @@ are: `frame' [N] `f' [N] - Select and print (frame number, function and argument names, - source file, and the source line) stack frame N. Frame 0 is the - currently executing, or "innermost", frame (function call), frame - 1 is the frame that called the innermost one. The highest numbered - frame is the one for the main program. + Select and print stack frame N. Frame 0 is the currently + executing, or "innermost", frame (function call), frame 1 is the + frame that called the innermost one. The highest numbered frame is + the one for the main program. The printed information consists of + the frame number, function and argument names, source file, and + the source line. `up' [COUNT] Move COUNT (default 1) frames up the stack toward the outermost @@ -20538,9 +20538,10 @@ File: gawk.info, Node: Readline Support, Next: Limitations, Prev: List of Deb 14.4 Readline Support ===================== -If `gawk' is compiled with the `readline' library, you can take -advantage of that library's command completion and history expansion -features. The following types of completion are available: +If `gawk' is compiled with the `readline' library +(http://cnswww.cns.cwru.edu/php/chet/readline/readline.html), you can +take advantage of that library's command completion and history +expansion features. The following types of completion are available: Command completion Command names. @@ -20579,15 +20580,14 @@ some limitations. A few which are worth being aware of are: you will realize that much of the internal manipulation of data in `gawk', as in many interpreters, is done on a stack. `Op_push', `Op_pop', etc., are the "bread and butter" of most `gawk' code. - Unfortunately, as of now, the `gawk' debugger does not allow you - to examine the stack's contents. - That is, the intermediate results of expression evaluation are on - the stack, but cannot be printed. Rather, only variables which - are defined in the program can be printed. Of course, a - workaround for this is to use more explicit variables at the - debugging stage and then change back to obscure, perhaps more - optimal code later. + Unfortunately, as of now, the `gawk' debugger does not allow you + to examine the stack's contents. That is, the intermediate + results of expression evaluation are on the stack, but cannot be + printed. Rather, only variables which are defined in the program + can be printed. Of course, a workaround for this is to use more + explicit variables at the debugging stage and then change back to + obscure, perhaps more optimal code later. * There is no way to look "inside" the process of compiling regular expressions to see if you got it right. As an `awk' programmer, @@ -30289,14 +30289,14 @@ Index * -v option: Options. (line 32) * -W option: Options. (line 46) * . (period), regexp operator: Regexp Operators. (line 44) -* .gmo files: Explaining gettext. (line 41) -* .gmo files, converting from .po: I18N Example. (line 62) +* .gmo files: Explaining gettext. (line 42) * .gmo files, specifying directory of <1>: Programmer i18n. (line 47) -* .gmo files, specifying directory of: Explaining gettext. (line 53) +* .gmo files, specifying directory of: Explaining gettext. (line 54) +* .mo files, converting from .po: I18N Example. (line 63) * .po files <1>: Translator i18n. (line 6) -* .po files: Explaining gettext. (line 36) -* .po files, converting to .gmo: I18N Example. (line 62) -* .pot files: Explaining gettext. (line 30) +* .po files: Explaining gettext. (line 37) +* .po files, converting to .mo: I18N Example. (line 63) +* .pot files: Explaining gettext. (line 31) * / (forward slash) to enclose regular expressions: Regexp. (line 10) * / (forward slash), / operator: Precedence. (line 55) * / (forward slash), /= operator <1>: Precedence. (line 95) @@ -30401,7 +30401,7 @@ Index * ^ (caret), regexp operator <1>: GNU Regexp Operators. (line 59) * ^ (caret), regexp operator: Regexp Operators. (line 22) -* _ (underscore), C macro: Explaining gettext. (line 70) +* _ (underscore), C macro: Explaining gettext. (line 71) * _ (underscore), in names of private variables: Library Names. (line 29) * _ (underscore), translatable string: Programmer i18n. (line 69) @@ -30701,7 +30701,7 @@ Index * binary input/output: User-modified. (line 15) * bindtextdomain <1>: Programmer i18n. (line 47) * bindtextdomain: I18N Functions. (line 12) -* bindtextdomain() function (C library): Explaining gettext. (line 49) +* bindtextdomain() function (C library): Explaining gettext. (line 50) * bindtextdomain() function (gawk), portability and: I18N Portability. (line 33) * BINMODE variable <1>: PC Using. (line 33) @@ -30973,7 +30973,7 @@ Index * csh utility, POSIXLY_CORRECT environment variable: Options. (line 355) * csh utility, |& operator, comparison with: Two-way I/O. (line 44) * ctime() user-defined function: Function Example. (line 73) -* currency symbols, localization: Explaining gettext. (line 103) +* currency symbols, localization: Explaining gettext. (line 104) * current system time: Time Functions. (line 66) * custom.h file: Configuration Philosophy. (line 30) @@ -31035,7 +31035,7 @@ Index * date utility, POSIX: Time Functions. (line 254) * dates, converting to timestamps: Time Functions. (line 76) * dates, information related to, localization: Explaining gettext. - (line 115) + (line 116) * Davies, Stephen <1>: Contributors. (line 74) * Davies, Stephen: Acknowledgments. (line 60) * dcgettext <1>: Programmer i18n. (line 19) @@ -31138,7 +31138,7 @@ Index (line 83) * debugger commands, unwatch: Viewing And Changing Data. (line 84) -* debugger commands, up: Execution Stack. (line 33) +* debugger commands, up: Execution Stack. (line 34) * debugger commands, w (watch): Viewing And Changing Data. (line 67) * debugger commands, watch: Viewing And Changing Data. @@ -31477,14 +31477,14 @@ Index * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) -* files, .gmo: Explaining gettext. (line 41) -* files, .gmo, converting from .po: I18N Example. (line 62) +* files, .gmo: Explaining gettext. (line 42) * files, .gmo, specifying directory of <1>: Programmer i18n. (line 47) -* files, .gmo, specifying directory of: Explaining gettext. (line 53) +* files, .gmo, specifying directory of: Explaining gettext. (line 54) +* files, .mo, converting from .po: I18N Example. (line 63) * files, .po <1>: Translator i18n. (line 6) -* files, .po: Explaining gettext. (line 36) -* files, .po, converting to .gmo: I18N Example. (line 62) -* files, .pot: Explaining gettext. (line 30) +* files, .po: Explaining gettext. (line 37) +* files, .po, converting to .mo: I18N Example. (line 63) +* files, .pot: Explaining gettext. (line 31) * files, /dev/... special files: Special FD. (line 46) * files, /inet/... (gawk): TCP/IP Networking. (line 6) * files, /inet4/... (gawk): TCP/IP Networking. (line 6) @@ -31501,23 +31501,23 @@ Index * files, managing: Data File Management. (line 6) * files, managing, data file boundaries: Filetrans Function. (line 6) -* files, message object: Explaining gettext. (line 41) +* files, message object: Explaining gettext. (line 42) * files, message object, converting from portable object files: I18N Example. - (line 62) + (line 63) * files, message object, specifying directory of <1>: Programmer i18n. (line 47) * files, message object, specifying directory of: Explaining gettext. - (line 53) + (line 54) * files, multiple passes over: Other Arguments. (line 49) * files, multiple, duplicating output into: Tee Program. (line 6) * files, output, See output files: Close Files And Pipes. (line 6) * files, password: Passwd Functions. (line 16) * files, portable object <1>: Translator i18n. (line 6) -* files, portable object: Explaining gettext. (line 36) -* files, portable object template: Explaining gettext. (line 30) +* files, portable object: Explaining gettext. (line 37) +* files, portable object template: Explaining gettext. (line 31) * files, portable object, converting to message object files: I18N Example. - (line 62) + (line 63) * files, portable object, generating: Options. (line 147) * files, processing, ARGIND variable and: Auto-set. (line 51) * files, reading: Rewind Function. (line 6) @@ -31712,7 +31712,7 @@ Index * gawk, newlines in: Statements/Lines. (line 12) * gawk, octal numbers and: Nondecimal-numbers. (line 42) * gawk, OS/2 version of: PC Using. (line 16) -* gawk, PROCINFO array in <1>: Two-way I/O. (line 116) +* gawk, PROCINFO array in <1>: Two-way I/O. (line 117) * gawk, PROCINFO array in <2>: Time Functions. (line 47) * gawk, PROCINFO array in: Auto-set. (line 128) * gawk, regexp constants and: Using Constant Regexps. @@ -31783,8 +31783,8 @@ Index * getpwuid() function (C library): Passwd Functions. (line 188) * getpwuid() user-defined function: Passwd Functions. (line 192) * gettext library: Explaining gettext. (line 6) -* gettext library, locale categories: Explaining gettext. (line 80) -* gettext() function (C library): Explaining gettext. (line 62) +* gettext library, locale categories: Explaining gettext. (line 81) +* gettext() function (C library): Explaining gettext. (line 63) * gettimeofday() extension function: Extension Sample Time. (line 13) * git utility <1>: Adding Code. (line 111) @@ -31936,7 +31936,7 @@ Index * internationalization, localization, gawk and: Internationalization. (line 13) * internationalization, localization, locale categories: Explaining gettext. - (line 80) + (line 81) * internationalization, localization, marked strings: Programmer i18n. (line 14) * internationalization, localization, portability and: I18N Portability. @@ -31985,16 +31985,16 @@ Index * labels.awk program: Labels Program. (line 51) * languages, data-driven: Basic High Level. (line 85) * Laurie, Dirk: Changing Precision. (line 6) -* LC_ALL locale category: Explaining gettext. (line 120) -* LC_COLLATE locale category: Explaining gettext. (line 93) -* LC_CTYPE locale category: Explaining gettext. (line 97) -* LC_MESSAGES locale category: Explaining gettext. (line 87) +* LC_ALL locale category: Explaining gettext. (line 121) +* LC_COLLATE locale category: Explaining gettext. (line 94) +* LC_CTYPE locale category: Explaining gettext. (line 98) +* LC_MESSAGES locale category: Explaining gettext. (line 88) * LC_MESSAGES locale category, bindtextdomain() function (gawk): Programmer i18n. (line 88) -* LC_MONETARY locale category: Explaining gettext. (line 103) -* LC_NUMERIC locale category: Explaining gettext. (line 107) -* LC_RESPONSE locale category: Explaining gettext. (line 111) -* LC_TIME locale category: Explaining gettext. (line 115) +* LC_MONETARY locale category: Explaining gettext. (line 104) +* LC_NUMERIC locale category: Explaining gettext. (line 108) +* LC_RESPONSE locale category: Explaining gettext. (line 112) +* LC_TIME locale category: Explaining gettext. (line 116) * left angle bracket (<), < operator <1>: Precedence. (line 65) * left angle bracket (<), < operator: Comparison Operators. (line 11) @@ -32063,7 +32063,7 @@ Index * list function definitions, in debugger: Debugger Info. (line 30) * loading, extensions: Options. (line 173) * local variables, in a function: Variable Scope. (line 6) -* locale categories: Explaining gettext. (line 80) +* locale categories: Explaining gettext. (line 81) * locale decimal point character: Options. (line 270) * locale, definition of: Locales. (line 6) * localization: I18N and L10N. (line 6) @@ -32114,23 +32114,23 @@ Index * mawk utility: Escape Sequences. (line 124) * maximum precision supported by MPFR library: Auto-set. (line 213) * McPhee, Patrick: Contributors. (line 100) -* message object files: Explaining gettext. (line 41) +* message object files: Explaining gettext. (line 42) * message object files, converting from portable object files: I18N Example. - (line 62) + (line 63) * message object files, specifying directory of <1>: Programmer i18n. (line 47) * message object files, specifying directory of: Explaining gettext. - (line 53) + (line 54) * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 130) * minimum precision supported by MPFR library: Auto-set. (line 216) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) -* monetary information, localization: Explaining gettext. (line 103) +* monetary information, localization: Explaining gettext. (line 104) * Moore, Duncan: Getline Notes. (line 40) * MPFR: Gawk and MPFR. (line 6) -* msgfmt utility: I18N Example. (line 62) +* msgfmt utility: I18N Example. (line 63) * multiple precision: Arbitrary Precision Arithmetic. (line 6) * multiple-line records: Multiple Line. (line 6) @@ -32362,7 +32362,7 @@ Index * portability, example programs: Library Functions. (line 42) * portability, functions, defining: Definition Syntax. (line 99) * portability, gawk: New Ports. (line 6) -* portability, gettext library and: Explaining gettext. (line 10) +* portability, gettext library and: Explaining gettext. (line 11) * portability, internationalization and: I18N Portability. (line 6) * portability, length() function: String Functions. (line 176) * portability, new awk vs. old awk: Conversion. (line 55) @@ -32374,11 +32374,11 @@ Index * portability, POSIXLY_CORRECT environment variable: Options. (line 360) * portability, substr() function: String Functions. (line 510) * portable object files <1>: Translator i18n. (line 6) -* portable object files: Explaining gettext. (line 36) +* portable object files: Explaining gettext. (line 37) * portable object files, converting to message object files: I18N Example. - (line 62) + (line 63) * portable object files, generating: Options. (line 147) -* portable object template files: Explaining gettext. (line 30) +* portable object template files: Explaining gettext. (line 31) * porting gawk: New Ports. (line 6) * positional specifiers, printf statement <1>: Printf Ordering. (line 6) @@ -32476,7 +32476,7 @@ Index * PROCINFO array <1>: Passwd Functions. (line 6) * PROCINFO array <2>: Time Functions. (line 47) * PROCINFO array: Auto-set. (line 128) -* PROCINFO array, and communications via ptys: Two-way I/O. (line 116) +* PROCINFO array, and communications via ptys: Two-way I/O. (line 117) * PROCINFO array, and group membership: Group Functions. (line 6) * PROCINFO array, and user and group ID numbers: Id Program. (line 15) * PROCINFO array, testing the field splitting: Passwd Functions. @@ -32844,7 +32844,7 @@ Index * sort utility: Word Sorting. (line 50) * sort utility, coprocesses and: Two-way I/O. (line 83) * sorting characters in different languages: Explaining gettext. - (line 93) + (line 94) * source code, awka: Other Versions. (line 64) * source code, Brian Kernighan's awk: Other Versions. (line 13) * source code, Busybox Awk: Other Versions. (line 88) @@ -32982,7 +32982,7 @@ Index * TEXTDOMAIN variable: User-modified. (line 152) * TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60) * TEXTDOMAIN variable, portability and: I18N Portability. (line 20) -* textdomain() function (C library): Explaining gettext. (line 27) +* textdomain() function (C library): Explaining gettext. (line 28) * tilde (~), ~ operator <1>: Expression Patterns. (line 24) * tilde (~), ~ operator <2>: Precedence. (line 80) * tilde (~), ~ operator <3>: Comparison Operators. @@ -32993,7 +32993,7 @@ Index * tilde (~), ~ operator: Regexp Usage. (line 19) * time functions: Time Functions. (line 6) * time, alarm clock example program: Alarm Program. (line 11) -* time, localization and: Explaining gettext. (line 115) +* time, localization and: Explaining gettext. (line 116) * time, managing: Getlocaltime Function. (line 6) * time, retrieving: Time Functions. (line 17) @@ -33056,7 +33056,7 @@ Index (line 18) * undefined functions: Pass By Value/Reference. (line 71) -* underscore (_), C macro: Explaining gettext. (line 70) +* underscore (_), C macro: Explaining gettext. (line 71) * underscore (_), in names of private variables: Library Names. (line 29) * underscore (_), translatable string: Programmer i18n. (line 69) @@ -33084,7 +33084,7 @@ Index (line 83) * unwatch debugger command: Viewing And Changing Data. (line 84) -* up debugger command: Execution Stack. (line 33) +* up debugger command: Execution Stack. (line 34) * user database, reading: Passwd Functions. (line 6) * user-defined functions: User-defined. (line 6) * user-defined, functions, counts, in a profile: Profiling. (line 137) @@ -33540,213 +33540,213 @@ Node: Anagram Program729137 Node: Signature Program732205 Node: Advanced Features733452 Node: Nondecimal Data735338 -Node: Array Sorting736921 -Node: Controlling Array Traversal737618 -Node: Array Sorting Functions745902 -Ref: Array Sorting Functions-Footnote-1749771 -Node: Two-way I/O749965 -Ref: Two-way I/O-Footnote-1755397 -Node: TCP/IP Networking755479 -Node: Profiling758323 -Node: Internationalization765826 -Node: I18N and L10N767251 -Node: Explaining gettext767937 -Ref: Explaining gettext-Footnote-1773005 -Ref: Explaining gettext-Footnote-2773189 -Node: Programmer i18n773354 -Node: Translator i18n777581 -Node: String Extraction778375 -Ref: String Extraction-Footnote-1779336 -Node: Printf Ordering779422 -Ref: Printf Ordering-Footnote-1782204 -Node: I18N Portability782268 -Ref: I18N Portability-Footnote-1784717 -Node: I18N Example784780 -Ref: I18N Example-Footnote-1787418 -Node: Gawk I18N787490 -Node: Debugger788111 -Node: Debugging789082 -Node: Debugging Concepts789515 -Node: Debugging Terms791371 -Node: Awk Debugging793968 -Node: Sample Debugging Session794860 -Node: Debugger Invocation795380 -Node: Finding The Bug796713 -Node: List of Debugger Commands803200 -Node: Breakpoint Control804534 -Node: Debugger Execution Control808198 -Node: Viewing And Changing Data811558 -Node: Execution Stack814914 -Node: Debugger Info816381 -Node: Miscellaneous Debugger Commands820375 -Node: Readline Support825559 -Node: Limitations826390 -Node: Arbitrary Precision Arithmetic828642 -Ref: Arbitrary Precision Arithmetic-Footnote-1830291 -Node: General Arithmetic830439 -Node: Floating Point Issues832159 -Node: String Conversion Precision833040 -Ref: String Conversion Precision-Footnote-1834745 -Node: Unexpected Results834854 -Node: POSIX Floating Point Problems837007 -Ref: POSIX Floating Point Problems-Footnote-1840832 -Node: Integer Programming840870 -Node: Floating-point Programming842609 -Ref: Floating-point Programming-Footnote-1848940 -Ref: Floating-point Programming-Footnote-2849210 -Node: Floating-point Representation849474 -Node: Floating-point Context850639 -Ref: table-ieee-formats851478 -Node: Rounding Mode852862 -Ref: table-rounding-modes853341 -Ref: Rounding Mode-Footnote-1856356 -Node: Gawk and MPFR856535 -Node: Arbitrary Precision Floats857944 -Ref: Arbitrary Precision Floats-Footnote-1860387 -Node: Setting Precision860703 -Ref: table-predefined-precision-strings861389 -Node: Setting Rounding Mode863534 -Ref: table-gawk-rounding-modes863938 -Node: Floating-point Constants865125 -Node: Changing Precision866554 -Ref: Changing Precision-Footnote-1867951 -Node: Exact Arithmetic868125 -Node: Arbitrary Precision Integers871263 -Ref: Arbitrary Precision Integers-Footnote-1874278 -Node: Dynamic Extensions874425 -Node: Extension Intro875883 -Node: Plugin License877148 -Node: Extension Mechanism Outline877833 -Ref: load-extension878250 -Ref: load-new-function879728 -Ref: call-new-function880723 -Node: Extension API Description882738 -Node: Extension API Functions Introduction884025 -Node: General Data Types888952 -Ref: General Data Types-Footnote-1894647 -Node: Requesting Values894946 -Ref: table-value-types-returned895683 -Node: Memory Allocation Functions896637 -Ref: Memory Allocation Functions-Footnote-1899383 -Node: Constructor Functions899479 -Node: Registration Functions901237 -Node: Extension Functions901922 -Node: Exit Callback Functions904224 -Node: Extension Version String905473 -Node: Input Parsers906123 -Node: Output Wrappers915880 -Node: Two-way processors920390 -Node: Printing Messages922598 -Ref: Printing Messages-Footnote-1923675 -Node: Updating `ERRNO'923827 -Node: Accessing Parameters924566 -Node: Symbol Table Access925796 -Node: Symbol table by name926310 -Node: Symbol table by cookie928286 -Ref: Symbol table by cookie-Footnote-1932418 -Node: Cached values932481 -Ref: Cached values-Footnote-1935971 -Node: Array Manipulation936062 -Ref: Array Manipulation-Footnote-1937160 -Node: Array Data Types937199 -Ref: Array Data Types-Footnote-1939902 -Node: Array Functions939994 -Node: Flattening Arrays943830 -Node: Creating Arrays950682 -Node: Extension API Variables955407 -Node: Extension Versioning956043 -Node: Extension API Informational Variables957944 -Node: Extension API Boilerplate959030 -Node: Finding Extensions962834 -Node: Extension Example963394 -Node: Internal File Description964124 -Node: Internal File Ops968215 -Ref: Internal File Ops-Footnote-1979724 -Node: Using Internal File Ops979864 -Ref: Using Internal File Ops-Footnote-1982211 -Node: Extension Samples982477 -Node: Extension Sample File Functions984001 -Node: Extension Sample Fnmatch992488 -Node: Extension Sample Fork994257 -Node: Extension Sample Inplace995470 -Node: Extension Sample Ord997248 -Node: Extension Sample Readdir998084 -Node: Extension Sample Revout999616 -Node: Extension Sample Rev2way1000209 -Node: Extension Sample Read write array1000899 -Node: Extension Sample Readfile1002782 -Node: Extension Sample API Tests1003882 -Node: Extension Sample Time1004407 -Node: gawkextlib1005771 -Node: Language History1008552 -Node: V7/SVR3.11010145 -Node: SVR41012465 -Node: POSIX1013907 -Node: BTL1015293 -Node: POSIX/GNU1016027 -Node: Feature History1021626 -Node: Common Extensions1034602 -Node: Ranges and Locales1035914 -Ref: Ranges and Locales-Footnote-11040531 -Ref: Ranges and Locales-Footnote-21040558 -Ref: Ranges and Locales-Footnote-31040792 -Node: Contributors1041013 -Node: Installation1046394 -Node: Gawk Distribution1047288 -Node: Getting1047772 -Node: Extracting1048598 -Node: Distribution contents1050290 -Node: Unix Installation1056011 -Node: Quick Installation1056628 -Node: Additional Configuration Options1059074 -Node: Configuration Philosophy1060810 -Node: Non-Unix Installation1063164 -Node: PC Installation1063622 -Node: PC Binary Installation1064933 -Node: PC Compiling1066781 -Node: PC Testing1069741 -Node: PC Using1070917 -Node: Cygwin1075085 -Node: MSYS1075894 -Node: VMS Installation1076408 -Node: VMS Compilation1077204 -Ref: VMS Compilation-Footnote-11078456 -Node: VMS Dynamic Extensions1078514 -Node: VMS Installation Details1079887 -Node: VMS Running1082138 -Node: VMS GNV1084972 -Node: VMS Old Gawk1085695 -Node: Bugs1086165 -Node: Other Versions1090083 -Node: Notes1096167 -Node: Compatibility Mode1096967 -Node: Additions1097750 -Node: Accessing The Source1098677 -Node: Adding Code1100117 -Node: New Ports1106162 -Node: Derived Files1110297 -Ref: Derived Files-Footnote-11115618 -Ref: Derived Files-Footnote-21115652 -Ref: Derived Files-Footnote-31116252 -Node: Future Extensions1116350 -Node: Implementation Limitations1116933 -Node: Extension Design1118181 -Node: Old Extension Problems1119335 -Ref: Old Extension Problems-Footnote-11120843 -Node: Extension New Mechanism Goals1120900 -Ref: Extension New Mechanism Goals-Footnote-11124265 -Node: Extension Other Design Decisions1124451 -Node: Extension Future Growth1126557 -Node: Old Extension Mechanism1127393 -Node: Basic Concepts1129133 -Node: Basic High Level1129814 -Ref: figure-general-flow1130086 -Ref: figure-process-flow1130685 -Ref: Basic High Level-Footnote-11133914 -Node: Basic Data Typing1134099 -Node: Glossary1137454 -Node: Copying1162685 -Node: GNU Free Documentation License1200241 -Node: Index1225377 +Node: Array Sorting736915 +Node: Controlling Array Traversal737612 +Node: Array Sorting Functions745892 +Ref: Array Sorting Functions-Footnote-1749799 +Node: Two-way I/O749993 +Ref: Two-way I/O-Footnote-1755509 +Node: TCP/IP Networking755591 +Node: Profiling758435 +Node: Internationalization765943 +Node: I18N and L10N767368 +Node: Explaining gettext768054 +Ref: Explaining gettext-Footnote-1773194 +Ref: Explaining gettext-Footnote-2773378 +Node: Programmer i18n773543 +Node: Translator i18n777768 +Node: String Extraction778562 +Ref: String Extraction-Footnote-1779523 +Node: Printf Ordering779609 +Ref: Printf Ordering-Footnote-1782391 +Node: I18N Portability782455 +Ref: I18N Portability-Footnote-1784904 +Node: I18N Example784967 +Ref: I18N Example-Footnote-1787689 +Node: Gawk I18N787761 +Node: Debugger788382 +Node: Debugging789353 +Node: Debugging Concepts789794 +Node: Debugging Terms791650 +Node: Awk Debugging794247 +Node: Sample Debugging Session795139 +Node: Debugger Invocation795659 +Node: Finding The Bug796992 +Node: List of Debugger Commands803474 +Node: Breakpoint Control804806 +Node: Debugger Execution Control808470 +Node: Viewing And Changing Data811830 +Node: Execution Stack815188 +Node: Debugger Info816701 +Node: Miscellaneous Debugger Commands820695 +Node: Readline Support825879 +Node: Limitations826771 +Node: Arbitrary Precision Arithmetic829019 +Ref: Arbitrary Precision Arithmetic-Footnote-1830668 +Node: General Arithmetic830816 +Node: Floating Point Issues832536 +Node: String Conversion Precision833417 +Ref: String Conversion Precision-Footnote-1835122 +Node: Unexpected Results835231 +Node: POSIX Floating Point Problems837384 +Ref: POSIX Floating Point Problems-Footnote-1841209 +Node: Integer Programming841247 +Node: Floating-point Programming842986 +Ref: Floating-point Programming-Footnote-1849317 +Ref: Floating-point Programming-Footnote-2849587 +Node: Floating-point Representation849851 +Node: Floating-point Context851016 +Ref: table-ieee-formats851855 +Node: Rounding Mode853239 +Ref: table-rounding-modes853718 +Ref: Rounding Mode-Footnote-1856733 +Node: Gawk and MPFR856912 +Node: Arbitrary Precision Floats858321 +Ref: Arbitrary Precision Floats-Footnote-1860764 +Node: Setting Precision861080 +Ref: table-predefined-precision-strings861766 +Node: Setting Rounding Mode863911 +Ref: table-gawk-rounding-modes864315 +Node: Floating-point Constants865502 +Node: Changing Precision866931 +Ref: Changing Precision-Footnote-1868328 +Node: Exact Arithmetic868502 +Node: Arbitrary Precision Integers871640 +Ref: Arbitrary Precision Integers-Footnote-1874655 +Node: Dynamic Extensions874802 +Node: Extension Intro876260 +Node: Plugin License877525 +Node: Extension Mechanism Outline878210 +Ref: load-extension878627 +Ref: load-new-function880105 +Ref: call-new-function881100 +Node: Extension API Description883115 +Node: Extension API Functions Introduction884402 +Node: General Data Types889329 +Ref: General Data Types-Footnote-1895024 +Node: Requesting Values895323 +Ref: table-value-types-returned896060 +Node: Memory Allocation Functions897014 +Ref: Memory Allocation Functions-Footnote-1899760 +Node: Constructor Functions899856 +Node: Registration Functions901614 +Node: Extension Functions902299 +Node: Exit Callback Functions904601 +Node: Extension Version String905850 +Node: Input Parsers906500 +Node: Output Wrappers916257 +Node: Two-way processors920767 +Node: Printing Messages922975 +Ref: Printing Messages-Footnote-1924052 +Node: Updating `ERRNO'924204 +Node: Accessing Parameters924943 +Node: Symbol Table Access926173 +Node: Symbol table by name926687 +Node: Symbol table by cookie928663 +Ref: Symbol table by cookie-Footnote-1932795 +Node: Cached values932858 +Ref: Cached values-Footnote-1936348 +Node: Array Manipulation936439 +Ref: Array Manipulation-Footnote-1937537 +Node: Array Data Types937576 +Ref: Array Data Types-Footnote-1940279 +Node: Array Functions940371 +Node: Flattening Arrays944207 +Node: Creating Arrays951059 +Node: Extension API Variables955784 +Node: Extension Versioning956420 +Node: Extension API Informational Variables958321 +Node: Extension API Boilerplate959407 +Node: Finding Extensions963211 +Node: Extension Example963771 +Node: Internal File Description964501 +Node: Internal File Ops968592 +Ref: Internal File Ops-Footnote-1980101 +Node: Using Internal File Ops980241 +Ref: Using Internal File Ops-Footnote-1982588 +Node: Extension Samples982854 +Node: Extension Sample File Functions984378 +Node: Extension Sample Fnmatch992865 +Node: Extension Sample Fork994634 +Node: Extension Sample Inplace995847 +Node: Extension Sample Ord997625 +Node: Extension Sample Readdir998461 +Node: Extension Sample Revout999993 +Node: Extension Sample Rev2way1000586 +Node: Extension Sample Read write array1001276 +Node: Extension Sample Readfile1003159 +Node: Extension Sample API Tests1004259 +Node: Extension Sample Time1004784 +Node: gawkextlib1006148 +Node: Language History1008929 +Node: V7/SVR3.11010522 +Node: SVR41012842 +Node: POSIX1014284 +Node: BTL1015670 +Node: POSIX/GNU1016404 +Node: Feature History1022003 +Node: Common Extensions1034979 +Node: Ranges and Locales1036291 +Ref: Ranges and Locales-Footnote-11040908 +Ref: Ranges and Locales-Footnote-21040935 +Ref: Ranges and Locales-Footnote-31041169 +Node: Contributors1041390 +Node: Installation1046771 +Node: Gawk Distribution1047665 +Node: Getting1048149 +Node: Extracting1048975 +Node: Distribution contents1050667 +Node: Unix Installation1056388 +Node: Quick Installation1057005 +Node: Additional Configuration Options1059451 +Node: Configuration Philosophy1061187 +Node: Non-Unix Installation1063541 +Node: PC Installation1063999 +Node: PC Binary Installation1065310 +Node: PC Compiling1067158 +Node: PC Testing1070118 +Node: PC Using1071294 +Node: Cygwin1075462 +Node: MSYS1076271 +Node: VMS Installation1076785 +Node: VMS Compilation1077581 +Ref: VMS Compilation-Footnote-11078833 +Node: VMS Dynamic Extensions1078891 +Node: VMS Installation Details1080264 +Node: VMS Running1082515 +Node: VMS GNV1085349 +Node: VMS Old Gawk1086072 +Node: Bugs1086542 +Node: Other Versions1090460 +Node: Notes1096544 +Node: Compatibility Mode1097344 +Node: Additions1098127 +Node: Accessing The Source1099054 +Node: Adding Code1100494 +Node: New Ports1106539 +Node: Derived Files1110674 +Ref: Derived Files-Footnote-11115995 +Ref: Derived Files-Footnote-21116029 +Ref: Derived Files-Footnote-31116629 +Node: Future Extensions1116727 +Node: Implementation Limitations1117310 +Node: Extension Design1118558 +Node: Old Extension Problems1119712 +Ref: Old Extension Problems-Footnote-11121220 +Node: Extension New Mechanism Goals1121277 +Ref: Extension New Mechanism Goals-Footnote-11124642 +Node: Extension Other Design Decisions1124828 +Node: Extension Future Growth1126934 +Node: Old Extension Mechanism1127770 +Node: Basic Concepts1129510 +Node: Basic High Level1130191 +Ref: figure-general-flow1130463 +Ref: figure-process-flow1131062 +Ref: Basic High Level-Footnote-11134291 +Node: Basic Data Typing1134476 +Node: Glossary1137831 +Node: Copying1163062 +Node: GNU Free Documentation License1200618 +Node: Index1225754 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 88098df3..1b8d003f 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -131,9 +131,15 @@ @set LEQ @math{@leq} @set PI @math{@pi} @end iftex +@ifdocbook +@set LEQ @inlineraw{docbook, ≤} +@set PI @inlineraw{docbook, &pgr;} +@end ifdocbook @ifnottex +@ifnotdocbook @set LEQ <= @set PI @i{pi} +@end ifnotdocbook @end ifnottex @ifnottex @@ -16043,13 +16049,7 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @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 -@ifnotdocbook @value{PI}. -@end ifnotdocbook -@docbook -&pgr;. - -@end docbook @item @code{cos(@var{x})} @cindexawkfunc{cos} @@ -25744,7 +25744,7 @@ $ @kbd{echo 0123 123 0x123 | gawk '@{ print $1, $2, $3 @}'} The @code{print} statement treats its expressions as strings. Although the fields can act as numbers when necessary, they are still strings, so @code{print} does not try to treat them -numerically. You may need to add zero to a field to force it to +numerically. You need to add zero to a field to force it to be treated as a number. For example: @example @@ -25766,7 +25766,7 @@ disabled. If you want it, you must explicitly request it. @emph{Use of this option is not recommended.} It can break old programs very badly. Instead, use the @code{strtonum()} function to convert your data -(@pxref{Nondecimal-numbers}). +(@pxref{String Functions}). This makes your programs easier to write and easier to read, and leads to less surprising results. @end quotation @@ -25800,7 +25800,7 @@ lets you do this. @ref{Controlling Scanning}, describes how you can assign special, pre-defined values to @code{PROCINFO["sorted_in"]} in order to -control the order in which @command{gawk} will traverse an array +control the order in which @command{gawk} traverses an array during a @code{for} loop. In addition, the value of @code{PROCINFO["sorted_in"]} can be a function name. @@ -26124,9 +26124,9 @@ END @{ So far, so good. Now it starts to get interesting. Both @code{asort()} and @code{asorti()} accept a third string argument to control comparison -of array elements. In @ref{String Functions}, we ignored this third -argument; however, the time has now come to describe how this argument -affects these two functions. +of array elements. When we introduced @code{asort()} and @code{asorti()} +in @ref{String Functions}, we ignored this third argument; however, +now is the time to describe how this argument affects these two functions. Basically, the third argument specifies how the array is to be sorted. There are two possibilities. As with @code{PROCINFO["sorted_in"]}, @@ -26322,6 +26322,7 @@ has been read, @command{gawk} terminates the coprocess and exits. As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. +This is not strictly necessary here, but it's good to know how to do this. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array, and communications via ptys @@ -26340,7 +26341,7 @@ print @dots{} |& command # start two-way pipe @end example @noindent -Using ptys avoids the buffer deadlock issues described earlier, at some +Using ptys usually avoids the buffer deadlock issues described earlier, at some loss in performance. If your system does not have ptys, or if all the system's ptys are in use, @command{gawk} automatically falls back to using regular pipes. @@ -26444,7 +26445,9 @@ See @inforef{Top, , General Introduction, gawkinet, TCP/IP Internetworking with @command{gawk}}, @end ifinfo @ifnotinfo -See @cite{TCP/IP Internetworking with @command{gawk}}, +See +@uref{http://www.gnu.org/software/gawk/manual/gawkinet/, +@cite{TCP/IP Internetworking with @command{gawk}}}, which comes as part of the @command{gawk} distribution, @end ifnotinfo for a much more complete introduction and discussion, as well as @@ -26723,7 +26726,7 @@ As usual, the profiled version of the program is written to @file{awkprof.out}, or to a different file if one specified with the @option{--profile} option. -Along with the regular profile, as shown earlier, the profile +Along with the regular profile, as shown earlier, the profile file includes a trace of any active functions: @example @@ -26830,6 +26833,8 @@ monetary values are printed and read. @cindex internationalizing a program @c STARTOFRANGE gettex @cindex @code{gettext} library +@command{gawk} uses GNU @code{gettext} to provide its internationalization +features. The facilities in GNU @code{gettext} focus on messages; strings printed by a program, either directly or via formatting with @code{printf} or @code{sprintf()}.@footnote{For some operating systems, the @command{gawk} @@ -27040,7 +27045,7 @@ are candidates for translation at runtime. String constants without a leading underscore are not translated. @cindexgawkfunc{dcgettext} -@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)} +@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. @@ -27066,7 +27071,7 @@ default arguments. @end quotation @cindexgawkfunc{dcngettext} -@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)} +@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the @@ -27494,33 +27499,34 @@ msgstr "Like, the scoop is" @cindex Linux @cindex GNU/Linux The next step is to make the directory to hold the binary message object -file and then to create the @file{guide.gmo} file. +file and then to create the @file{guide.mo} file. +We pretend that our file is to be used in the @code{en_US.UTF-8} locale. The directory layout shown here is standard for GNU @code{gettext} on GNU/Linux systems. Other versions of @code{gettext} may use a different layout: @example -$ @kbd{mkdir en_US en_US/LC_MESSAGES} +$ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} @end example -@cindex @code{.po} files, converting to @code{.gmo} -@cindex files, @code{.po}, converting to @code{.gmo} -@cindex @code{.gmo} files, converting from @code{.po} -@cindex files, @code{.gmo}, converting from @code{.po} +@cindex @code{.po} files, converting to @code{.mo} +@cindex files, @code{.po}, converting to @code{.mo} +@cindex @code{.mo} files, converting from @code{.po} +@cindex files, @code{.mo}, converting from @code{.po} @cindex portable object files, converting to message object files @cindex files, portable object, converting to message object files @cindex message object files, converting from portable object files @cindex files, message object, converting from portable object files @cindex @command{msgfmt} utility The @command{msgfmt} utility does the conversion from human-readable -@file{.po} file to machine-readable @file{.gmo} file. +@file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. This file must be renamed and placed in the proper directory so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po} -$ @kbd{mv messages en_US/LC_MESSAGES/guide.gmo} +$ @kbd{mv messages en_US.UTF-8/LC_MESSAGES/guide.mo} @end example Finally, we run the program to test it: @@ -27592,7 +27598,7 @@ how to use @command{gawk} for debugging your program is easy. @end menu @node Debugging -@section Introduction to @command{gawk} Debugger +@section Introduction to The @command{gawk} Debugger This @value{SECTION} introduces debugging in general and begins the discussion of debugging in @command{gawk}. @@ -27907,13 +27913,7 @@ This tells us that @command{gawk} is now ready to execute line 67, which decides whether to give the lines the special ``field skipping'' treatment indicated by the @option{-f} command-line option. (Notice that we skipped from where we were before at line 64 to here, since the condition in line 64 - -@example -if (fcount == 0 && charcount == 0) -@end example - -@noindent -was false.) +@samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -28048,7 +28048,7 @@ In the following descriptions, commands which may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to -automatically repeat the previous command when just hitting @key{Enter}. +automatically repeat the previous command just by hitting @key{Enter}. This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi} and @code{continue} executed without any argument. @@ -28410,7 +28410,7 @@ No newline is printed unless one is specified. @item @code{set} @var{var}@code{=}@var{value} Assign a constant (number or string) value to an @command{awk} variable or field. -String values must be enclosed between double quotes (@code{"@dots{}"}). +String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, @code{NF}, @code{NR}, etc. @@ -28485,10 +28485,11 @@ Then select and print the frame. @cindex @code{f} debugger command (alias for @code{frame}) @item @code{frame} [@var{n}] @itemx @code{f} [@var{n}] -Select and print (frame number, function and argument names, source file, -and the source line) stack frame @var{n}. Frame 0 is the currently executing, -or @dfn{innermost}, frame (function call), frame 1 is the frame that called the -innermost one. The highest numbered frame is the one for the main program. +Select and print stack frame @var{n}. Frame 0 is the currently executing, +or @dfn{innermost}, frame (function call), frame 1 is the frame that +called the innermost one. The highest numbered frame is the one for the +main program. The printed information consists of the frame number, +function and argument names, source file, and the source line. @cindex debugger commands, @code{up} @cindex @code{up} debugger command @@ -28788,9 +28789,11 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @cindex command completion, in debugger @cindex history expansion, in debugger -If @command{gawk} is compiled with the @code{readline} library, you -can take advantage of that library's command completion and history expansion -features. The following types of completion are available: +If @command{gawk} is compiled with +@uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, +the @code{readline} library}, you can take advantage of that library's +command completion and history expansion features. The following types +of completion are available: @table @asis @item Command completion @@ -28840,9 +28843,10 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}, you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. @code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of -most @command{gawk} code. Unfortunately, as of now, the @command{gawk} -debugger does not allow you to examine the stack's contents. +most @command{gawk} code. +Unfortunately, as of now, the @command{gawk} +debugger does not allow you to examine the stack's contents. That is, the intermediate results of expression evaluation are on the stack, but cannot be printed. Rather, only variables which are defined in the program can be printed. Of course, a workaround for diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 599bd098..c905e1d5 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -126,9 +126,15 @@ @set LEQ @math{@leq} @set PI @math{@pi} @end iftex +@ifdocbook +@set LEQ @inlineraw{docbook, ≤} +@set PI @inlineraw{docbook, &pgr;} +@end ifdocbook @ifnottex +@ifnotdocbook @set LEQ <= @set PI @i{pi} +@end ifnotdocbook @end ifnottex @ifnottex @@ -15377,13 +15383,7 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):} @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 -@ifnotdocbook @value{PI}. -@end ifnotdocbook -@docbook -&pgr;. - -@end docbook @item @code{cos(@var{x})} @cindexawkfunc{cos} @@ -24888,7 +24888,7 @@ $ @kbd{echo 0123 123 0x123 | gawk '@{ print $1, $2, $3 @}'} The @code{print} statement treats its expressions as strings. Although the fields can act as numbers when necessary, they are still strings, so @code{print} does not try to treat them -numerically. You may need to add zero to a field to force it to +numerically. You need to add zero to a field to force it to be treated as a number. For example: @example @@ -24910,7 +24910,7 @@ disabled. If you want it, you must explicitly request it. @emph{Use of this option is not recommended.} It can break old programs very badly. Instead, use the @code{strtonum()} function to convert your data -(@pxref{Nondecimal-numbers}). +(@pxref{String Functions}). This makes your programs easier to write and easier to read, and leads to less surprising results. @end quotation @@ -24944,7 +24944,7 @@ lets you do this. @ref{Controlling Scanning}, describes how you can assign special, pre-defined values to @code{PROCINFO["sorted_in"]} in order to -control the order in which @command{gawk} will traverse an array +control the order in which @command{gawk} traverses an array during a @code{for} loop. In addition, the value of @code{PROCINFO["sorted_in"]} can be a function name. @@ -25268,9 +25268,9 @@ END @{ So far, so good. Now it starts to get interesting. Both @code{asort()} and @code{asorti()} accept a third string argument to control comparison -of array elements. In @ref{String Functions}, we ignored this third -argument; however, the time has now come to describe how this argument -affects these two functions. +of array elements. When we introduced @code{asort()} and @code{asorti()} +in @ref{String Functions}, we ignored this third argument; however, +now is the time to describe how this argument affects these two functions. Basically, the third argument specifies how the array is to be sorted. There are two possibilities. As with @code{PROCINFO["sorted_in"]}, @@ -25466,6 +25466,7 @@ has been read, @command{gawk} terminates the coprocess and exits. As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. +This is not strictly necessary here, but it's good to know how to do this. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array, and communications via ptys @@ -25484,7 +25485,7 @@ print @dots{} |& command # start two-way pipe @end example @noindent -Using ptys avoids the buffer deadlock issues described earlier, at some +Using ptys usually avoids the buffer deadlock issues described earlier, at some loss in performance. If your system does not have ptys, or if all the system's ptys are in use, @command{gawk} automatically falls back to using regular pipes. @@ -25588,7 +25589,9 @@ See @inforef{Top, , General Introduction, gawkinet, TCP/IP Internetworking with @command{gawk}}, @end ifinfo @ifnotinfo -See @cite{TCP/IP Internetworking with @command{gawk}}, +See +@uref{http://www.gnu.org/software/gawk/manual/gawkinet/, +@cite{TCP/IP Internetworking with @command{gawk}}}, which comes as part of the @command{gawk} distribution, @end ifnotinfo for a much more complete introduction and discussion, as well as @@ -25867,7 +25870,7 @@ As usual, the profiled version of the program is written to @file{awkprof.out}, or to a different file if one specified with the @option{--profile} option. -Along with the regular profile, as shown earlier, the profile +Along with the regular profile, as shown earlier, the profile file includes a trace of any active functions: @example @@ -25974,6 +25977,8 @@ monetary values are printed and read. @cindex internationalizing a program @c STARTOFRANGE gettex @cindex @code{gettext} library +@command{gawk} uses GNU @code{gettext} to provide its internationalization +features. The facilities in GNU @code{gettext} focus on messages; strings printed by a program, either directly or via formatting with @code{printf} or @code{sprintf()}.@footnote{For some operating systems, the @command{gawk} @@ -26184,7 +26189,7 @@ are candidates for translation at runtime. String constants without a leading underscore are not translated. @cindexgawkfunc{dcgettext} -@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)} +@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the translation of @var{string} in text domain @var{domain} for locale category @var{category}. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. @@ -26210,7 +26215,7 @@ default arguments. @end quotation @cindexgawkfunc{dcngettext} -@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)} +@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category}]]@code{)} Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the @@ -26638,33 +26643,34 @@ msgstr "Like, the scoop is" @cindex Linux @cindex GNU/Linux The next step is to make the directory to hold the binary message object -file and then to create the @file{guide.gmo} file. +file and then to create the @file{guide.mo} file. +We pretend that our file is to be used in the @code{en_US.UTF-8} locale. The directory layout shown here is standard for GNU @code{gettext} on GNU/Linux systems. Other versions of @code{gettext} may use a different layout: @example -$ @kbd{mkdir en_US en_US/LC_MESSAGES} +$ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} @end example -@cindex @code{.po} files, converting to @code{.gmo} -@cindex files, @code{.po}, converting to @code{.gmo} -@cindex @code{.gmo} files, converting from @code{.po} -@cindex files, @code{.gmo}, converting from @code{.po} +@cindex @code{.po} files, converting to @code{.mo} +@cindex files, @code{.po}, converting to @code{.mo} +@cindex @code{.mo} files, converting from @code{.po} +@cindex files, @code{.mo}, converting from @code{.po} @cindex portable object files, converting to message object files @cindex files, portable object, converting to message object files @cindex message object files, converting from portable object files @cindex files, message object, converting from portable object files @cindex @command{msgfmt} utility The @command{msgfmt} utility does the conversion from human-readable -@file{.po} file to machine-readable @file{.gmo} file. +@file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. This file must be renamed and placed in the proper directory so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po} -$ @kbd{mv messages en_US/LC_MESSAGES/guide.gmo} +$ @kbd{mv messages en_US.UTF-8/LC_MESSAGES/guide.mo} @end example Finally, we run the program to test it: @@ -26736,7 +26742,7 @@ how to use @command{gawk} for debugging your program is easy. @end menu @node Debugging -@section Introduction to @command{gawk} Debugger +@section Introduction to The @command{gawk} Debugger This @value{SECTION} introduces debugging in general and begins the discussion of debugging in @command{gawk}. @@ -27051,13 +27057,7 @@ This tells us that @command{gawk} is now ready to execute line 67, which decides whether to give the lines the special ``field skipping'' treatment indicated by the @option{-f} command-line option. (Notice that we skipped from where we were before at line 64 to here, since the condition in line 64 - -@example -if (fcount == 0 && charcount == 0) -@end example - -@noindent -was false.) +@samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and last records: @@ -27192,7 +27192,7 @@ In the following descriptions, commands which may be abbreviated show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to -automatically repeat the previous command when just hitting @key{Enter}. +automatically repeat the previous command just by hitting @key{Enter}. This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi} and @code{continue} executed without any argument. @@ -27554,7 +27554,7 @@ No newline is printed unless one is specified. @item @code{set} @var{var}@code{=}@var{value} Assign a constant (number or string) value to an @command{awk} variable or field. -String values must be enclosed between double quotes (@code{"@dots{}"}). +String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, @code{NF}, @code{NR}, etc. @@ -27629,10 +27629,11 @@ Then select and print the frame. @cindex @code{f} debugger command (alias for @code{frame}) @item @code{frame} [@var{n}] @itemx @code{f} [@var{n}] -Select and print (frame number, function and argument names, source file, -and the source line) stack frame @var{n}. Frame 0 is the currently executing, -or @dfn{innermost}, frame (function call), frame 1 is the frame that called the -innermost one. The highest numbered frame is the one for the main program. +Select and print stack frame @var{n}. Frame 0 is the currently executing, +or @dfn{innermost}, frame (function call), frame 1 is the frame that +called the innermost one. The highest numbered frame is the one for the +main program. The printed information consists of the frame number, +function and argument names, source file, and the source line. @cindex debugger commands, @code{up} @cindex @code{up} debugger command @@ -27932,9 +27933,11 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @cindex command completion, in debugger @cindex history expansion, in debugger -If @command{gawk} is compiled with the @code{readline} library, you -can take advantage of that library's command completion and history expansion -features. The following types of completion are available: +If @command{gawk} is compiled with +@uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, +the @code{readline} library}, you can take advantage of that library's +command completion and history expansion features. The following types +of completion are available: @table @asis @item Command completion @@ -27984,9 +27987,10 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}, you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. @code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of -most @command{gawk} code. Unfortunately, as of now, the @command{gawk} -debugger does not allow you to examine the stack's contents. +most @command{gawk} code. +Unfortunately, as of now, the @command{gawk} +debugger does not allow you to examine the stack's contents. That is, the intermediate results of expression evaluation are on the stack, but cannot be printed. Rather, only variables which are defined in the program can be printed. Of course, a workaround for |