diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 27 | ||||
| -rw-r--r-- | doc/Makefile.in | 15 | ||||
| -rw-r--r-- | doc/ad.block | 9 | ||||
| -rw-r--r-- | doc/awkcard.in | 25 | ||||
| -rw-r--r-- | doc/cardfonts | 2 | ||||
| -rw-r--r-- | doc/colors | 4 | ||||
| -rw-r--r-- | doc/gawk.1 | 16 | ||||
| -rw-r--r-- | doc/gawk.info | 1242 | ||||
| -rw-r--r-- | doc/gawk.texi | 222 | ||||
| -rw-r--r-- | doc/igawk.1 | 2 | ||||
| -rw-r--r-- | doc/no.colors | 2 | ||||
| -rw-r--r-- | doc/texinfo.tex | 954 |
12 files changed, 1481 insertions, 1039 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 660436a1..17f2844b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,30 @@ +Wed Jun 30 16:14:36 1999 Arnold D. Robbins <arnold@gnu.org> + + * Release 3.0.4: Release tar file made. This time for sure. + +Wed Oct 7 21:59:33 1998 Arnold D. Robbins <arnold@gnu.org> + + * texinfo.tex: Updated to version 2.227, from Texinfo 3.12. + +Sun Oct 19 12:26:08 1997 Arnold D. Robbins <arnold@gnu.org> + + * ALL: change references to arnold@gnu.ai.mit.edu to arnold@gnu.org. + +Tue Sep 23 10:31:17 1997 Arnold D. Robbins <arnold@gnu.org> + + * texinfo.tex: Updated to version 2.218, from Texinfo 3.11. + +Fri Jul 4 08:19:00 1997 Arnold D. Robbins <arnold@gnu.org> + + * Makefile.in ($(infodir)/gawk.info): Don't make dependent upon + gawk.info, in case installed one is newer. Instead, check that + an installed gawk.info exists and is identical to current one. + If so, just exit; otherwise do the install. + +Wed Jul 2 14:55:12 1997 Arnold D. Robbins <arnold@gnu.org> + + * Makefile.in ($(infodir)/gawk.info): typo fix. + Thu May 15 12:49:08 1997 Arnold D. Robbins <arnold@skeeve.atl.ga.us> * Release 3.0.3: Release tar file made. diff --git a/doc/Makefile.in b/doc/Makefile.in index 293676b5..989903cb 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,6 +1,6 @@ # Makefile for GNU Awk documentation. # -# Copyright (C) 1993-1997 the Free Software Foundation, Inc. +# Copyright (C) 1993-1999 the Free Software Foundation, Inc. # # This file is part of GAWK, the GNU implementation of the # AWK Programming Language. @@ -71,20 +71,25 @@ all: $(DOCS) info install: $(mandir)/gawk$(manext) $(mandir)/igawk$(manext) $(infodir)/gawk.info -$(infodir)/gawk.info: gawk.info +$(infodir)/gawk.info:: -if test -f gawk.info; then d=.; \ else d=$(srcdir); fi; \ + if [ -f $(infodir)/dir -a -f $(infodir)/gawk.info ] \ + && cmp $$d/gawk.info $(infodir)/gawk.info > /dev/null \ + && grep '(gawk\.info)' $(infodir)/dir > /dev/null; then \ + exit 0; \ + fi; \ for i in $$d/gawk.info*; do \ - $(INSTALL_DATA) $$i $(infodir)/$i ; \ + $(INSTALL_DATA) $$i $(infodir)/$$i ; \ done; \ if $(SHELL) -c 'install-info --version' > /dev/null 2>&1 ; \ then install-info --info-dir=$(infodir) gawk.info ; \ else true ; fi; exit 0 -$(mandir)/gawk$(manext): gawk.1 +$(mandir)/gawk$(manext):: gawk.1 $(INSTALL_DATA) $(srcdir)/gawk.1 $(mandir)/gawk$(manext) -$(mandir)/igawk$(manext): igawk.1 +$(mandir)/igawk$(manext):: igawk.1 $(INSTALL_DATA) $(srcdir)/igawk.1 $(mandir)/igawk$(manext) uninstall: diff --git a/doc/ad.block b/doc/ad.block index 16a4de0f..d31f5d50 100644 --- a/doc/ad.block +++ b/doc/ad.block @@ -1,7 +1,7 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" This file is the Ad block (included in cover) .\" -.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" Copyright (C) 1996, 98 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of .\" this reference card provided the copyright notice and this permission @@ -27,14 +27,15 @@ .vs 12 .ES .nf -.ce 6 +.ce 7 \*(CBFree Software Foundation, Inc. .ft H 59 Temple Place \(em Suite 330 Boston, MA 02111-1307 USA Phone: +1-617-542-5942 Fax (including Japan): +1-617-542-2652 -E-mail: gnu@prep.ai.mit.edu +E-mail: gnu@gnu.org +URL: http://www.gnu.org .ce 7 .ft HB diff --git a/doc/awkcard.in b/doc/awkcard.in index 4a02c878..c3e262df 100644 --- a/doc/awkcard.in +++ b/doc/awkcard.in @@ -1,6 +1,6 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" -.\" Copyright (C) 1996, 97 Free Software Foundation, Inc. +.\" Copyright (C) 1996, 97, 98, 99 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of .\" this reference card provided the copyright notice and this permission @@ -95,7 +95,7 @@ for their help. \*(CD .SL .nf -\*(FR\(co Copyright, 1996, 1997 Free Software Foundation +\*(FR\(co Copyright 1996-1999, Free Software Foundation 59 Temple Place \(em Suite 330 Boston, MA 02111-1307 USA .nf @@ -934,10 +934,12 @@ construction.\*(CB .EB "\s+2\f(HBLOCALIZATION\*(FR\s0" .. +.ig .ps +2 .ce 1 \*(CD\fHISBN: 0-916151-97-2\*(FR .ps -2 +.. .BT @@ -1128,7 +1130,10 @@ T} pad the field to this width. The field is normally padded with spaces. If the \*(FC0\fP flag has been used, pad with zeroes. -The meaning of the \*(FIwidth\*(FR varies by control letter: +T} +\*(FC.\fP\*(FIprec\fP T{ +precision. +The meaning varies by control letter: T} \*(FC%d\*(FR, \*(FC%o\*(FR, \*(FC%i\*(FR, \*(FC%u\*(FR, \*(FC%x\*(FR, \*(FC%X\fP T{ @@ -1433,6 +1438,10 @@ Functions may call each other and may be recursive. Function parameters used as local variables are initialized to the null string and the number zero upon function invocation. .sp .5 +Use \*(FCreturn\fP to return a value from a function. The return value +is undefined if no value is provided, or if the function returns by +``falling off'' the end. +.sp .5 \*(CLThe word \*(FCfunc\fP may be used in place of @@ -1446,7 +1455,7 @@ may be used in place of .ES .fi \*(CDIf you find a bug in this reference card, please report it via electronic -mail to \*(FCarnold@gnu.ai.mit.edu\*(FR.\*(CX +mail to \*(FCarnold@gnu.org\*(FR.\*(CX .EB "\s+2\f(HBBUG REPORTS\*(FR\s0" .BT @@ -1493,8 +1502,8 @@ has been specified.\*(CB .\" --- FTP Information .ES .nf -\*(CDHost: \*(FCftp.gnu.ai.mit.edu\*(FR -File: \*(FC/pub/gnu/gawk-3.0.3.tar.gz\fP +\*(CDHost: \*(FCgnudist.gnu.org\*(FR +File: \*(FC/gnu/gawk/gawk-3.0.4.tar.gz\fP .in +.2i .fi GNU \*(AK (\*(GK). There may be a later version. @@ -1502,7 +1511,7 @@ GNU \*(AK (\*(GK). There may be a later version. .nf .sp .5 Host: \*(FCnetlib.bell-labs.com\*(FR -File: \*(FC/netlib/research/awk.bundle.Z\fP +File: \*(FC/netlib/research/awk.bundle.gz\fP .in +.2i .fi \*(NK. This version requires an ANSI C compiler; diff --git a/doc/cardfonts b/doc/cardfonts index 66367eef..5529ba98 100644 --- a/doc/cardfonts +++ b/doc/cardfonts @@ -1,4 +1,4 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" cardfonts --- this file sets the fonts to use for the reference card .\" .\" Copyright (C) 1996 Free Software Foundation, Inc. @@ -1,7 +1,7 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" This file sets the colors to use. .\" -.\" Copyright (C) 1996,97 Free Software Foundation, Inc. +.\" Copyright (C) 1996,97,99 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of .\" this reference card provided the copyright notice and this permission @@ -1,7 +1,7 @@ .ds PX \s-1POSIX\s+1 .ds UX \s-1UNIX\s+1 .ds AN \s-1ANSI\s+1 -.TH GAWK 1 "Dec 19 1996" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Apr 28 1999" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -2150,6 +2150,12 @@ Functions may call each other and may be recursive. Function parameters used as local variables are initialized to the null string and the number zero upon function invocation. .PP +Use +.BI return " expr" +to return a value from a function. The return value is undefined if no +value is provided, or if the function returns by ``falling off'' the +end. +.PP If .B \-\^\-lint has been provided, @@ -2535,7 +2541,7 @@ and the effort to do so really is not worth it. .SH VERSION INFORMATION This man page documents .IR gawk , -version 3.0.2. +version 3.0.4. .SH AUTHORS The original version of \*(UX .I awk @@ -2566,10 +2572,10 @@ help from Darrel Hankerson. Fred Fish supplied support for the Amiga. If you find a bug in .IR gawk , please send electronic mail to -.BR bug-gnu-utils@prep.ai.mit.edu , +.BR bug-gnu-utils@gnu.org , .I with a carbon copy to -.BR arnold@gnu.ai.mit.edu . +.BR arnold@gnu.org . Please include your operating system and its revision, the version of .IR gawk , what C compiler you used to compile it, and a test program @@ -2598,7 +2604,7 @@ Brian Kernighan of Bell Labs provided valuable assistance during testing and debugging. We thank him. .SH COPYING PERMISSIONS -Copyright \(co) 1996 Free Software Foundation, Inc. +Copyright \(co) 1996,97,98,99 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission diff --git a/doc/gawk.info b/doc/gawk.info index a9242e2b..e39a483b 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1,4 +1,4 @@ -This is Info file gawk.info, produced by Makeinfo version 1.67 from the +This is Info file gawk.info, produced by Makeinfo version 1.68 from the input file ./gawk.texi. INFO-DIR-SECTION Programming Languages @@ -9,11 +9,11 @@ END-INFO-DIR-ENTRY This file documents `awk', a program that you can use to select particular records in a file and perform operations upon them. - This is Edition 1.0.3 of `Effective AWK Programming', for the -3.0.3 version of the GNU implementation of AWK. + This is Edition 1.0.4 of `Effective AWK Programming', for the +3.0.4 version of the GNU implementation of AWK. - Copyright (C) 1989, 1991, 92, 93, 96, 97 Free Software Foundation, -Inc. + Copyright (C) 1989, 1991, 92, 93, 96, 97, 98, 99 Free Software +Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -38,8 +38,8 @@ General Introduction This file documents `awk', a program that you can use to select particular records in a file and perform operations upon them. - This is Edition 1.0.3 of `Effective AWK Programming', -for the 3.0.3 version of the GNU implementation + This is Edition 1.0.4 of `Effective AWK Programming', +for the 3.0.4 version of the GNU implementation of AWK. * Menu: @@ -382,8 +382,8 @@ to MS-DOS and OS/2 PC's, Atari and Amiga micro-computers, and VMS. ---------- Footnotes ---------- - (1) These commands are available on POSIX compliant systems, as -well as on traditional Unix based systems. If you are using some other + (1) These commands are available on POSIX compliant systems, as well +as on traditional Unix based systems. If you are using some other operating system, you still need to be familiar with the ideas of I/O redirection and pipes. @@ -849,7 +849,7 @@ specific to the GNU implementation, we use the term `gawk'. ---------- Footnotes ---------- - (1) Often, these systems use `gawk' for their `awk' implementation! + (1) Often, these systems use `gawk' for their `awk' implementation! File: gawk.info, Node: Running gawk, Next: Very Simple, Prev: Names, Up: Getting Started @@ -1030,6 +1030,12 @@ Self-contained `awk' scripts are useful when you want to write a program which users can invoke without their having to know that the program is written in `awk'. + *Caution:* You should not put more than one argument on the `#!' +line after the path to `awk'. This will not work. The operating system +treats the rest of the line as a single agument, and passes it to `awk'. +Doing this will lead to confusing behavior: most likely a usage +diagnostic of some sort from `awk'. + Some older systems do not support the `#!' mechanism. You can get a similar effect using a regular shell script. It would look something like this: @@ -1049,11 +1055,11 @@ systems obey this convention, but many do.) ---------- Footnotes ---------- - (1) The `#!' mechanism works on Linux systems, Unix systems derived + (1) The `#!' mechanism works on Linux systems, Unix systems derived from Berkeley Unix, System V Release 4, and some System V Release 3 systems. - (2) The line beginning with `#!' lists the full file name of an + (2) The line beginning with `#!' lists the full file name of an interpreter to be run, and an optional initial command line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the @@ -1088,6 +1094,18 @@ programs also, but this usually isn't very useful; the purpose of a comment is to help you or another person understand the program at a later time. + *Caution:* As mentioned in *Note One-shot Throw-away `awk' Programs: +One-shot, you can enclose small to medium programs in single quotes, in +order to keep your shell scripts self-contained. When doing so, +*don't* put an apostrophe (i.e., a single quote) into a comment (or +anywhere else in your program). The shell will interpret the quote as +the closing quote for the entire program. As a result, usually the +shell will print a message about mismatched quotes, and if `awk' +actually runs, it will probably print strange messages about syntax +errors. For example: + + awk 'BEGIN { print "hello" } # let's be cute' + File: gawk.info, Node: Very Simple, Next: Two Rules, Prev: Running gawk, Up: Getting Started @@ -1670,7 +1688,7 @@ character not listed in the table above. Another interesting question arises. Suppose you use an octal or hexadecimal escape to represent a regexp metacharacter (*note Regular Expression Operators: Regexp Operators.). Does `awk' treat the -character as literal character, or as a regexp operator? +character as a literal character, or as a regexp operator? It turns out that historically, such characters were taken literally (d.c.). However, the POSIX standard indicates that they should be @@ -2066,7 +2084,7 @@ current method of using `\y' for the GNU `\b' appears to be the lesser of two evils. The various command line options (*note Command Line Options: -Options.) control how `gawk' interprets characters in regexps. +Options.) control how `gawk' interprets characters in regexps. No options In the default case, `gawk' provide all the facilities of POSIX @@ -2169,8 +2187,8 @@ How Much Text Matches? echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' This example uses the `sub' function (which we haven't discussed yet, -*note Built-in Functions for String Manipulation: String Functions.) to -make a change to the input record. Here, the regexp `/a+/' indicates +*note Built-in Functions for String Manipulation: String Functions.) +to make a change to the input record. Here, the regexp `/a+/' indicates "one or more `a' characters," and the replacement text is `<A>'. The input contains four `a' characters. What will the output be? @@ -2512,7 +2530,7 @@ record containing a match. ---------- Footnotes ---------- - (1) In POSIX `awk', newlines are not considered whitespace for + (1) In POSIX `awk', newlines are not considered whitespace for separating fields. @@ -2584,7 +2602,7 @@ input file.) The `-' sign represents subtraction, so this program reassigns field three, `$3', to be the value of field two minus ten, `$2 - 10'. (*Note -Arithmetic Operators: Arithmetic Ops.) Then field two, and the new +Arithmetic Operators: Arithmetic Ops.) Then field two, and the new value for field three, are printed. In order for this to work, the text in field `$2' must make sense as @@ -2954,7 +2972,7 @@ should reflect the old value of `FS', not the new one. However, many implementations of `awk' do not work this way. Instead, they defer splitting the fields until a field is actually referenced. The fields will be split using the *current* value of -`FS'! (d.c.) This behavior can be difficult to diagnose. The following +`FS'! (d.c.) This behavior can be difficult to diagnose. The following example illustrates the difference between the two methods. (The `sed'(1) command prints just the first line of `/etc/passwd'.) @@ -2992,7 +3010,7 @@ value of `FS'. (`==' means "is equal to.") ---------- Footnotes ---------- - (1) The `sed' utility is a "stream editor." Its behavior is also + (1) The `sed' utility is a "stream editor." Its behavior is also defined by the POSIX standard. @@ -3512,7 +3530,9 @@ EXPRESSION contains unparenthesized operators other than `$'; for example, `"echo " "date" | getline' is ambiguous because the concatenation operator is not parenthesized, and you should write it as `("echo " "date") | getline' if you want your program to be portable to -other `awk' implementations. +other `awk' implementations. (It happens that `gawk' gets it right, +but you should not rely on this. Parentheses make it easier to read, +anyway.) File: gawk.info, Node: Getline/Variable/Pipe, Next: Getline Summary, Prev: Getline/Pipe, Up: Getline @@ -3540,7 +3560,9 @@ EXPRESSION contains unparenthesized operators other than `$'; for example, `"echo " "date" | getline VAR' is ambiguous because the concatenation operator is not parenthesized, and you should write it as `("echo " "date") | getline VAR' if you want your program to be -portable to other `awk' implementations. +portable to other `awk' implementations. (It happens that `gawk' gets +it right, but you should not rely on this. Parentheses make it easier +to read, anyway.) File: gawk.info, Node: Getline Summary, Prev: Getline/Variable/Pipe, Up: Getline @@ -3640,7 +3662,7 @@ expressions. Numeric values are converted to strings, and then printed. values to print. However, with two exceptions, you cannot specify *how* to print them--how many columns, whether to use exponential notation or not, and so on. (For the exceptions, *note Output Separators::., and -*Note Controlling Numeric Output with `print': OFMT.) For that, you +*Note Controlling Numeric Output with `print': OFMT.) For that, you need the `printf' statement (*note Using `printf' Statements for Fancier Printing: Printf.). @@ -3667,7 +3689,7 @@ Examples of `print' Statements Here is an example of printing a string that contains embedded newlines (the `\n' is an escape sequence, used to represent the newline -character; see *Note Escape Sequences::): +character; *note Escape Sequences::.): $ awk 'BEGIN { print "line one\nline two\nline three" }' -| line one @@ -3699,7 +3721,7 @@ Here is the same program, without the comma: example's output makes much sense. A heading line at the beginning would make it clearer. Let's add some headings to our table of months (`$1') and green crates shipped (`$2'). We do this using the `BEGIN' -pattern (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.) to +pattern (*note The `BEGIN' and `END' Special Patterns: BEGIN/END.) to force the headings to be printed only once: awk 'BEGIN { print "Month Crates" @@ -4104,7 +4126,7 @@ last things on their lines. We don't need to put spaces after them. We could make our table look even nicer by adding headings to the tops of the columns. To do this, we use the `BEGIN' pattern (*note The -`BEGIN' and `END' Special Patterns: BEGIN/END.) to force the header to +`BEGIN' and `END' Special Patterns: BEGIN/END.) to force the header to be printed only once, at the beginning of the `awk' program: awk 'BEGIN { print "Name Number" @@ -4377,7 +4399,7 @@ Closing Input and Output Files and Pipes ======================================== If the same file name or the same shell command is used with -`getline' (*note Explicit Input with `getline': Getline.) more than +`getline' (*note Explicit Input with `getline': Getline.) more than once during the execution of an `awk' program, the file is opened (or the command is executed) only the first time. At that time, the first record of input is read from that file or command. The next time the @@ -4551,9 +4573,8 @@ implementations may have difficulty with some character codes. ---------- Footnotes ---------- - (1) The internal representation uses double-precision floating -point numbers. If you don't know what that means, then don't worry -about it. + (1) The internal representation uses double-precision floating point +numbers. If you don't know what that means, then don't worry about it. File: gawk.info, Node: Regexp Constants, Prev: Scalar Constants, Up: Constants @@ -5506,7 +5527,8 @@ not. *Note Arrays in `awk': Arrays, for more information about arrays. `?:' simply by putting a newline after either character. However, you cannot put a newline in front of either character without using backslash continuation (*note `awk' Statements Versus Lines: -Statements/Lines.). +Statements/Lines.). If `--posix' is specified (*note Command Line +Options: Options.), then this extension is disabled. File: gawk.info, Node: Function Calls, Next: Precedence, Prev: Conditional Exp, Up: Expressions @@ -5789,7 +5811,7 @@ whose first field is precisely `foo'. $ awk '$1 == "foo" { print $2 }' BBS-list -(There is no output, since there is no BBS site named "foo".) Contrast +(There is no output, since there is no BBS site named "foo".) Contrast this with the following regular expression match, which would accept any record with a first field that contains `foo': @@ -6199,7 +6221,7 @@ running. The first thing the `while' statement does is test CONDITION. If CONDITION is true, it executes the statement BODY. (The CONDITION is -true when the value is not zero and not a null string.) After BODY has +true when the value is not zero and not a null string.) After BODY has been executed, CONDITION is tested again, and if it is still true, BODY is executed again. This process repeats until CONDITION is no longer true. If CONDITION is initially false, the body of the loop is never @@ -6602,7 +6624,7 @@ by exiting with a non-zero status. Your `awk' program can do this using an `exit' statement with a non-zero argument. Here is an example: BEGIN { - if (("date" | getline date_now) < 0) { + if (("date" | getline date_now) <= 0) { print "Can't get system date" > "/dev/stderr" exit 1 } @@ -6743,7 +6765,7 @@ specific to `gawk' are marked with an asterisk, `*'. ---------- Footnotes ---------- - (1) In POSIX `awk', newline does not count as whitespace. + (1) In POSIX `awk', newline does not count as whitespace. File: gawk.info, Node: Auto-set, Next: ARGC and ARGV, Prev: User-modified, Up: Built-in Variables @@ -6896,7 +6918,7 @@ zero when `FILENAME' changed. ---------- Footnotes ---------- - (1) Some early implementations of Unix `awk' initialized `FILENAME' + (1) Some early implementations of Unix `awk' initialized `FILENAME' to `"-"', even if there were data files to be processed. This behavior was incorrect, and should not be relied upon in your programs. @@ -6923,8 +6945,24 @@ In this example, `ARGV[0]' contains `"awk"', `ARGV[1]' contains Notice that the `awk' program is not entered in `ARGV'. The other special command line options, with their arguments, are also not -entered. But variable assignments on the command line *are* treated as -arguments, and do show up in the `ARGV' array. +entered. This includes variable assignments done with the `-v' option +(*note Command Line Options: Options.). Normal variable assignments on +the command line *are* treated as arguments, and do show up in the +`ARGV' array. + + $ cat showargs.awk + -| BEGIN { + -| printf "A=%d, B=%d\n", A, B + -| for (i = 0; i < ARGC; i++) + -| printf "\tARGV[%d] = %s\n", i, ARGV[i] + -| } + -| END { printf "A=%d, B=%d\n", A, B } + $ awk -v A=1 -f showargs.awk B=2 /dev/null + -| A=1, B=0 + -| ARGV[0] = awk + -| ARGV[1] = B=2 + -| ARGV[2] = /dev/null + -| A=1, B=2 Your program can alter `ARGC' and the elements of `ARGV'. Each time `awk' reaches the end of an input file, it uses the next element of @@ -7355,11 +7393,17 @@ clear out an array. split("", array) The `split' function (*note Built-in Functions for String -Manipulation: String Functions.) clears out the target array first. +Manipulation: String Functions.) clears out the target array first. This call asks it to split apart the null string. Since there is no data to split out, the function simply clears the array and then returns. + *Caution:* Deleting an array does not change its type; you cannot +delete an array and then use the array's name as a scalar. For example, +this will not work: + + a[1] = 3; delete a; a = 3 + File: gawk.info, Node: Numeric Array Subscripts, Next: Uninitialized Subscripts, Prev: Delete, Up: Arrays @@ -7748,7 +7792,7 @@ Optional parameters are enclosed in square brackets ("[" and "]"). ---------- Footnotes ---------- - (1) Computer generated random numbers really are not truly random. + (1) Computer generated random numbers really are not truly random. They are technically known as "pseudo-random." This means that while the numbers in a sequence appear to be random, you can in fact generate the same sequence of random numbers over and over again. @@ -7873,6 +7917,9 @@ and "]"). Before splitting the string, `split' deletes any previously existing elements in the array ARRAY (d.c.). + If STRING does not match FIELDSEP at all, ARRAY will have one + element. The value of that element will be the original STRING. + `sprintf(FORMAT, EXPRESSION1,...)' This returns (without printing) the string that `printf' would have printed out with the same arguments (*note Using `printf' @@ -7954,6 +8001,10 @@ and "]"). non-changeable object as the third parameter will cause a fatal error, and your program will not run. + Finally, if the REGEXP is not a regexp constant, it is converted + into a string and then the value of that string is treated as the + regexp to match. + `gsub(REGEXP, REPLACEMENT [, TARGET])' This is similar to the `sub' function, except `gsub' replaces *all* of the longest, leftmost, *non-overlapping* matching @@ -8018,6 +8069,9 @@ and "]"). `G', or if it is a number that is less than zero, only one substitution is performed. + If REGEXP does not match TARGET, `gensub''s return value is the + original, unchanged value of TARGET. + `gensub' is a `gawk' extension; it is not available in compatibility mode (*note Command Line Options: Options.). @@ -8179,10 +8233,10 @@ the use of `gawk' and `gensub' for when you have to do substitutions. ---------- Footnotes ---------- - (1) This consequence was certainly unintended. + (1) This consequence was certainly unintended. - (2) As of February 1997, with final approval and publication -hopefully sometime in 1997. + (2) As of April, 1999, with final approval and publication hopefully +sometime in 1997. File: gawk.info, Node: I/O Functions, Next: Time Functions, Prev: String Functions, Up: Built-in @@ -8231,7 +8285,7 @@ parameters are enclosed in square brackets ("[" and "]"). nonzero otherwise. `system(COMMAND)' - The system function allows the user to execute operating system + The `system' function allows the user to execute operating system commands and then return to the `awk' program. The `system' function executes the command given by the string COMMAND. It returns, as its value, the status returned by the command that was @@ -8248,9 +8302,17 @@ parameters are enclosed in square brackets ("[" and "]"). finishes processing input and begins its end-of-input processing. Note that redirecting `print' or `printf' into a pipe is often - enough to accomplish your task. However, if your `awk' program is - interactive, `system' is useful for cranking up large - self-contained programs, such as a shell or an editor. + enough to accomplish your task. If you need to run many commands, + it will be more efficient to simply print them to a pipe to the + shell: + + while (MORE STUFF TO DO) + print COMMAND | "/bin/sh" + close("/bin/sh") + + However, if your `awk' program is interactive, `system' is useful + for cranking up large self-contained programs, such as a shell or + an editor. Some operating systems cannot implement the `system' function. `system' causes a fatal error if it is not supported. @@ -8334,7 +8396,7 @@ latter (undesirable) output is what you would see. ---------- Footnotes ---------- - (1) A program is interactive if the standard output is connected to + (1) A program is interactive if the standard output is connected to a terminal device. @@ -8590,17 +8652,16 @@ if the time zone was set to UTC. ---------- Footnotes ---------- - (1) Occasionally there are minutes in a year with a leap second, + (1) Occasionally there are minutes in a year with a leap second, which is why the seconds can go up to 60. - (2) This is because ANSI C leaves the behavior of the C version of + (2) This is because ANSI C leaves the behavior of the C version of `strftime' undefined, and `gawk' will use the system's version of `strftime' if it's there. Typically, the conversion specifier will either not appear in the returned string, or it will appear literally. - (3) If you don't understand any of this, don't worry about it; -these facilities are meant to make it easier to "internationalize" -programs. + (3) If you don't understand any of this, don't worry about it; these +facilities are meant to make it easier to "internationalize" programs. File: gawk.info, Node: User-defined, Next: Invoking Gawk, Prev: Built-in, Up: Top @@ -8774,7 +8835,7 @@ way: Here is an example that uses the built-in function `strftime'. (*Note Functions for Dealing with Time Stamps: Time Functions, for more -information on `strftime'.) The C `ctime' function takes a timestamp +information on `strftime'.) The C `ctime' function takes a timestamp and returns it in a string, formatted in a well known fashion. Here is an `awk' version: @@ -8889,8 +8950,8 @@ program calls an undefined function. Options.), `gawk' will report about calls to undefined functions. Some `awk' implementations generate a run-time error if you use the -`next' statement (*note The `next' Statement: Next Statement.) inside a -user-defined function. `gawk' does not have this problem. +`next' statement (*note The `next' Statement: Next Statement.) inside +a user-defined function. `gawk' does not have this problem. File: gawk.info, Node: Return Statement, Prev: Function Caveats, Up: User-defined @@ -9222,7 +9283,7 @@ to the `.profile' file in your home directory. ---------- Footnotes ---------- - (1) Not recommended. + (1) Not recommended. File: gawk.info, Node: Other Arguments, Next: AWKPATH Variable, Prev: Options, Up: Invoking Gawk @@ -9331,7 +9392,7 @@ path `gawk' will use. ---------- Footnotes ---------- - (1) Your version of `gawk' may use a directory that is different + (1) Your version of `gawk' may use a directory that is different than `/usr/local/share/awk'; it will depend upon how `gawk' was built and installed. The actual directory will be the value of `$(datadir)' generated when `gawk' was configured. You probably don't need to worry @@ -9348,7 +9409,7 @@ previous releases of `gawk' that are either not available in the current version, or that are still supported but deprecated (meaning that they will *not* be in the next release). - For version 3.0.3 of `gawk', there are no command line options or + For version 3.0.4 of `gawk', there are no command line options or other deprecated features from the previous version of `gawk'. This node is thus essentially a place holder, in case some option becomes obsolete in a future version of `gawk'. @@ -9371,8 +9432,9 @@ Known Bugs in `gawk' ==================== * The `-F' option for changing the value of `FS' (*note Command Line - Options: Options.) is not necessary given the command line variable - assignment feature; it remains only for backwards compatibility. + Options: Options.) is not necessary given the command line + variable assignment feature; it remains only for backwards + compatibility. * If your system actually has support for `/dev/fd' and the associated `/dev/stdin', `/dev/stdout', and `/dev/stderr' files, @@ -9396,7 +9458,7 @@ A Library of `awk' Functions This chapter presents a library of useful `awk' functions. The sample programs presented later (*note Practical `awk' Programs: Sample -Programs.) use these functions. The functions are presented here in a +Programs.) use these functions. The functions are presented here in a progression from simple to complex. *Note Extracting Programs from Texinfo Source Files: Extract Program, @@ -9519,7 +9581,7 @@ problem. # nextfile --- skip remaining records in current file # correctly handle successive occurrences of the same file - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May, 1993 # this should be read in before the "main" awk program @@ -9569,9 +9631,9 @@ computations). ---------- Footnotes ---------- - (1) Some implementations of `awk' do not allow you to execute -`next' from within a function body. Some other work-around will be -necessary if you use such a version. + (1) Some implementations of `awk' do not allow you to execute `next' +from within a function body. Some other work-around will be necessary +if you use such a version. File: gawk.info, Node: Assert Function, Next: Round Function, Prev: Nextfile Function, Up: Library Functions @@ -9608,7 +9670,7 @@ possible in `awk', so this `assert' function also requires a string version of the condition that is being tested. # assert --- assert that a condition is true. Otherwise exit. - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May, 1993 function assert(condition, string) @@ -9653,13 +9715,13 @@ If the assertion failed, you would see a message like this: mydata:1357: assertion failed: a <= 5 && b >= 17 There is a problem with this version of `assert', that it may not be -possible to work around. An `END' rule is automatically added to the -program calling `assert'. Normally, if a program consists of just a -`BEGIN' rule, the input files and/or standard input are not read. -However, now that the program has an `END' rule, `awk' will attempt to -read the input data files, or standard input (*note Startup and Cleanup -Actions: Using BEGIN/END.), most likely causing the program to hang, -waiting for input. +possible to work around with standard `awk'. An `END' rule is +automatically added to the program calling `assert'. Normally, if a +program consists of just a `BEGIN' rule, the input files and/or +standard input are not read. However, now that the program has an `END' +rule, `awk' will attempt to read the input data files, or standard input +(*note Startup and Cleanup Actions: Using BEGIN/END.), most likely +causing the program to hang, waiting for input. File: gawk.info, Node: Round Function, Next: Ordinal Functions, Prev: Assert Function, Up: Library Functions @@ -9668,7 +9730,7 @@ Rounding Numbers ================ The way `printf' and `sprintf' (*note Using `printf' Statements for -Fancier Printing: Printf.) do rounding will often depend upon the +Fancier Printing: Printf.) do rounding will often depend upon the system's C `sprintf' subroutine. On many machines, `sprintf' rounding is "unbiased," which means it doesn't always round a trailing `.5' up, contrary to naive expectations. In unbiased rounding, `.5' rounds to @@ -9680,7 +9742,7 @@ function does traditional rounding; it might be useful if your awk's # round --- do normal rounding # - # Arnold Robbins, arnold@gnu.ai.mit.edu, August, 1996 + # Arnold Robbins, arnold@gnu.org, August, 1996 # Public Domain function round(x, ival, aval, fraction) @@ -9736,7 +9798,7 @@ reason to build them into the `awk' interpreter. # _ord_init: function to initialize _ord_ # # Arnold Robbins - # arnold@gnu.ai.mit.edu + # arnold@gnu.org # Public Domain # 16 January, 1992 # 20 July, 1992, revised @@ -9809,10 +9871,10 @@ function. It is commented out for production use. ---------- Footnotes ---------- - (1) ASCII has been extended in many countries to use the values -from 128 to 255 for country-specific characters. If your system uses -these extensions, you can simplify `_ord_init' to simply loop from zero -to 255. + (1) ASCII has been extended in many countries to use the values from +128 to 255 for country-specific characters. If your system uses these +extensions, you can simplify `_ord_init' to simply loop from zero to +255. File: gawk.info, Node: Join Function, Next: Mktime Function, Prev: Ordinal Functions, Up: Library Functions @@ -9835,7 +9897,7 @@ created with `split' (*note Built-in Functions for String Manipulation: String Functions.). # join.awk --- join an array into a string - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 function join(array, start, end, sep, result, i) @@ -9902,7 +9964,7 @@ multiple assignment. # mktime.awk --- convert a canonical date representation # into a timestamp - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 BEGIN \ @@ -9923,7 +9985,7 @@ multiple assignment. } The benefit of merging multiple `BEGIN' rules (*note The `BEGIN' and -`END' Special Patterns: BEGIN/END.) is particularly clear when writing +`END' Special Patterns: BEGIN/END.) is particularly clear when writing library files. Functions in library files can cleanly initialize their own private data and also provide clean-up actions in private `END' rules. @@ -10124,7 +10186,7 @@ output is to standard error, and test output is to standard output.) as UTC--four hours ahead of the local time zone. The second line shows that the difference is 14400 seconds, which is four hours. (The difference is only four hours, since daylight savings time is in effect -during May.) The final line of test output shows that the timezone +during May.) The final line of test output shows that the timezone compensation algorithm works; the returned time is the same as the entered time. @@ -10137,7 +10199,7 @@ months, and AM/PM times into 24-hour clocks, to generate the ---------- Footnotes ---------- - (1) This is the Epoch on POSIX systems. It may be different on + (1) This is the Epoch on POSIX systems. It may be different on other systems. @@ -10158,7 +10220,7 @@ array with pre-formatted time information. It returns a string with the current time formatted in the same way as the `date' utility. # gettimeofday --- get the time of day in a usable format - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain, May 1993 + # Arnold Robbins, arnold@gnu.org, Public Domain, May 1993 # # Returns a string in the format of output of date(1) # Populates the array argument time with individual values: @@ -10258,7 +10320,7 @@ Besides solving the problem in only nine(!) lines of code, it does so # that each take the name of the file being started or # finished, respectively. # - # Arnold Robbins, arnold@gnu.ai.mit.edu, January 1992 + # Arnold Robbins, arnold@gnu.org, January 1992 # Public Domain FILENAME != _oldfilename \ @@ -10302,7 +10364,7 @@ problem. # # user supplies beginfile() and endfile() functions # - # Arnold Robbins, arnold@gnu.ai.mit.edu. November 1992 + # Arnold Robbins, arnold@gnu.org, November 1992 # Public Domain FNR == 1 { @@ -10428,7 +10490,7 @@ Functions.). # getopt --- do C library getopt(3) function in awk # - # arnold@gnu.ai.mit.edu + # arnold@gnu.org # Public domain # # Initial version: March, 1991 @@ -10616,7 +10678,7 @@ Reading the User Database ========================= The `/dev/user' special file (*note Special File Names in `gawk': -Special Files.) provides access to the current user's real and +Special Files.) provides access to the current user's real and effective user and group id numbers, and if available, the user's supplementary group set. However, since these are numbers, they do not provide very useful information to the average user. There needs to be @@ -10629,7 +10691,7 @@ information from the group database. The POSIX standard does not define the file where user information is kept. Instead, it provides the `<pwd.h>' header file and several C language subroutines for obtaining user information. The primary -function is `getpwent', for "get password entry." The "password" comes +function is `getpwent', for "get password entry." The "password" comes from the original user database file, `/etc/passwd', which kept user information, along with the encrypted passwords (hence the name). @@ -10653,7 +10715,7 @@ password database. * Generate a printable version of the password database * * Arnold Robbins - * arnold@gnu.ai.mit.edu + * arnold@gnu.org * May 1993 * Public Domain */ @@ -10724,7 +10786,7 @@ information. There are several functions here, corresponding to the C functions of the same name. # passwd.awk --- access password file information - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 BEGIN { @@ -10868,7 +10930,7 @@ have a small C program that generates the group database as its output. * * Generate a printable version of the group database * - * Arnold Robbins, arnold@gnu.ai.mit.edu + * Arnold Robbins, arnold@gnu.org * May 1993 * Public Domain */ @@ -10936,7 +10998,7 @@ database. There are several, modeled after the C library functions of the same names. # group.awk --- functions for dealing with the group file - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 BEGIN \ @@ -11059,7 +11121,7 @@ member. function getgrent() { _gr_init() - if (++gr_count in _gr_bycount) + if (++_gr_count in _gr_bycount) return _gr_bycount[_gr_count] return "" } @@ -11261,7 +11323,7 @@ Function.). is called if invalid arguments are supplied. # cut.awk --- implement cut in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # Options: @@ -11531,7 +11593,7 @@ rule that processes the command line arguments with `getopt'. The `-i' `IGNORECASE' built in variable (*note Built-in Variables::.). # egrep.awk --- simulate egrep in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # Options: @@ -11736,7 +11798,7 @@ field. Similar code is used for the effective user-id number, and the group numbers. # id.awk --- implement id in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # output is: @@ -11833,7 +11895,7 @@ skipped over, and the final argument is used as the prefix for the output file names. # split.awk --- do split in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # usage: split [-num] [file] [outname] @@ -11930,7 +11992,7 @@ usage message and exits. Finally, `awk' is forced to read the standard input by setting `ARGV[1]' to `"-"', and `ARGC' to two. # tee.awk --- tee in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # Revised December 1995 @@ -12061,7 +12123,7 @@ assigned to `outputfile'. Earlier, `outputfile' was initialized to the standard output, `/dev/stdout'. # uniq.awk --- do uniq in awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 function usage( e) @@ -12265,7 +12327,7 @@ order. command line. # wc.awk --- count lines, words, characters - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # Options: @@ -12355,9 +12417,9 @@ line.(1) ---------- Footnotes ---------- - (1) Examine the code in *Note Noting Data File Boundaries: -Filetrans Function. Why must `wc' use a separate `lines' variable, -instead of using the value of `FNR' in `endfile'? + (1) Examine the code in *Note Noting Data File Boundaries: Filetrans +Function. Why must `wc' use a separate `lines' variable, instead of +using the value of `FNR' in `endfile'? File: gawk.info, Node: Miscellaneous Programs, Prev: Clones, Up: Sample Programs @@ -12407,7 +12469,7 @@ comparison either. This sometimes leads to reports of duplicated words that really are different, but this is unusual. # dupword --- find duplicate words in text - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # December 1991 { @@ -12448,7 +12510,7 @@ the system calls attention to itself, in case the user is not looking at their computer or terminal.) # alarm --- set an alarm - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # usage: alarm time [ "message" [ count [ delay ] ] ] @@ -12522,7 +12584,7 @@ between the two is how long to wait before setting off the alarm. } Finally, the program uses the `system' function (*note Built-in -Functions for Input/Output: I/O Functions.) to call the `sleep' +Functions for Input/Output: I/O Functions.) to call the `sleep' utility. The `sleep' utility simply pauses for the given number of seconds. If the exit status is not zero, the program assumes that `sleep' was interrupted, and exits. If `sleep' exited with an OK status @@ -12606,7 +12668,7 @@ from the standard input. record. # translate --- do tr like stuff - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # August 1989 # bugs: does not handle things like: tr A-Z a-z, it has @@ -12668,10 +12730,10 @@ program. ---------- Footnotes ---------- - (1) On older, non-POSIX systems, `tr' often does not require that + (1) On older, non-POSIX systems, `tr' often does not require that the lists be enclosed in square brackets and quoted. This is a feature. - (2) This program was written before `gawk' acquired the ability to + (2) This program was written before `gawk' acquired the ability to split each character in a string into separate array elements. How might this ability simplify the program? @@ -12723,7 +12785,7 @@ lines at the bottom. not have been an even multiple of 20 labels in the data. # labels.awk - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # June 1992 # Program to print labels. Each label is 5 lines of data @@ -12778,7 +12840,7 @@ not have been an even multiple of 20 labels in the data. ---------- Footnotes ---------- - (1) "Real world" is defined as "a program actually used to get + (1) "Real world" is defined as "a program actually used to get something done." @@ -12920,7 +12982,7 @@ indices of `lines' indicate the order in which those lines were encountered. The `END' rule simply prints out the lines, in order. # histsort.awk --- compact a shell history file - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 # Thanks to Byron Rakitzis for the general idea @@ -12992,7 +13054,27 @@ an Array Into a String: Join Function.). AWK Programming' (`gawk.texi') have all been bracketed inside `file', and `endfile' lines. The `gawk' distribution uses a copy of `extract.awk' to extract the sample programs and install many of them -in a standard directory, where `gawk' can find them. +in a standard directory, where `gawk' can find them. The Texinfo file +looks something like this: + + ... + This program has a @code{BEGIN} block, + which prints a nice message: + + @example + @c file examples/messages.awk + BEGIN @{ print "Don't panic!" @} + @c end file + @end example + + It also prints some final advice: + + @example + @c file examples/messages.awk + END @{ print "Always avoid bored archeologists!" @} + @c end file + @end example + ... `extract.awk' begins by setting `IGNORECASE' to one, so that mixed upper-case and lower-case letters in the directives won't matter. @@ -13003,7 +13085,7 @@ exited with a zero exit status, signifying OK. # extract.awk --- extract files and run programs # from texinfo files - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # May 1993 BEGIN { IGNORECASE = 1 } @@ -13039,7 +13121,9 @@ Explicit Input with `getline': Getline.). For an unexpected end of file, it calls the `unexpected_eof' function. If the line is an "endfile" line, then it breaks out of the loop. If the line is an `@group' or `@end group' line, then it ignores it, and goes on to the -next line. +next line. (These Texinfo control lines keep blocks of code together +on one page; unfortunately, TeX isn't always smart enough to do things +exactly right, and we have to give it some advice.) Most of the work is in the following few lines. If the line has no `@' symbols, it can be printed directly. Otherwise, each leading `@' @@ -13149,7 +13233,7 @@ process. If none are provided, the standard input is used. # awksed.awk --- do s/foo/bar/g using just print # Thanks to Michael Brennan for the idea - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # August 1995 function usage() @@ -13338,7 +13422,7 @@ temporary file names will clash. #! /bin/sh # igawk --- like gawk but do @include processing - # Arnold Robbins, arnold@gnu.ai.mit.edu, Public Domain + # Arnold Robbins, arnold@gnu.org, Public Domain # July 1993 if [ "$1" = debug ] @@ -13567,7 +13651,7 @@ for the desired library functions. ---------- Footnotes ---------- - (1) On some very old versions of `awk', the test `getline junk < t' + (1) On some very old versions of `awk', the test `getline junk < t' can loop forever if the file exists but is empty. Caveat Emptor. @@ -14051,7 +14135,7 @@ matches, the associated ACTION is executed. ---------- Footnotes ---------- - (1) The path may use a directory other than `/usr/local/share/awk', + (1) The path may use a directory other than `/usr/local/share/awk', depending upon how `gawk' was built and installed. @@ -14087,7 +14171,7 @@ special case that `FS' is a single space, fields are separated by runs of spaces, tabs and/or newlines.(1) If `FS' is the null string (`""'), then each individual character in the record becomes a separate field. Note that the value of `IGNORECASE' (*note Case-sensitivity in -Matching: Case-sensitivity.) also affects how fields are split when +Matching: Case-sensitivity.) also affects how fields are split when `FS' is a regular expression. Each field in the input line may be referenced by its position, `$1', @@ -14112,7 +14196,7 @@ Files: Reading Files. ---------- Footnotes ---------- - (1) In POSIX `awk', newline does not separate fields. + (1) In POSIX `awk', newline does not separate fields. File: gawk.info, Node: Built-in Summary, Next: Arrays Summary, Prev: Fields Summary, Up: Variables/Fields @@ -15207,13 +15291,13 @@ Getting the `gawk' Distribution Boston, MA 02111-1307 USA Phone: +1-617-542-5942 Fax (including Japan): +1-617-542-2652 - E-mail: `gnu@prep.ai.mit.edu' + E-mail: `gnu@gnu.org' Ordering from the FSF directly contributes to the support of the foundation and to the production of more free software. 3. You can get `gawk' by using anonymous `ftp' to the Internet host - `ftp.gnu.ai.mit.edu', in the directory `/pub/gnu'. + `gnudist.gnu.org', in the directory `/gnu/gawk'. Here is a list of alternate `ftp' sites from which you can obtain GNU software. When a site is listed as "SITE`:'DIRECTORY" the @@ -15221,19 +15305,27 @@ Getting the `gawk' Distribution should use a site that is geographically close to you. Asia: + `cair-archive.kaist.ac.kr:/pub/gnu' `ftp.cs.titech.ac.jp' `ftp.nectec.or.th:/pub/mirrors/gnu' `utsun.s.u-tokyo.ac.jp:/ftpsync/prep' + Australia: + `archie.au:/gnu' (`archie.oz' or `archie.oz.au' for ACSnet) Africa: + `ftp.sun.ac.za:/pub/gnu' + Middle East: + `ftp.technion.ac.il:/pub/unsupported/gnu' + Europe: + `archive.eu.net' `ftp.denet.dk' `ftp.eunet.ch' @@ -15252,12 +15344,18 @@ Getting the `gawk' Distribution `nic.switch.ch:/mirror/gnu' `src.doc.ic.ac.uk:/gnu' `unix.hensa.ac.uk:/pub/uunet/systems/gnu' + South America: + `ftp.inf.utfsm.cl:/pub/gnu' `ftp.unicamp.br:/pub/gnu' + Western Canada: + `ftp.cs.ubc.ca:/mirror2/gnu' + USA: + `col.hp.com:/mirrors/gnu' `f.ms.uky.edu:/pub3/gnu' `ftp.cc.gatech.edu:/pub/gnu' @@ -15265,6 +15363,7 @@ Getting the `gawk' Distribution `ftp.digex.net:/pub/gnu' `ftp.hawaii.edu:/mirrors/gnu' `ftp.kpc.com:/pub/mirror/gnu' + USA (continued): `ftp.uu.net:/systems/gnu' `gatekeeper.dec.com:/pub/GNU' @@ -15283,21 +15382,21 @@ Extracting the Distribution `gawk' is distributed as a `tar' file compressed with the GNU Zip program, `gzip'. - Once you have the distribution (for example, `gawk-3.0.3.tar.gz'), + Once you have the distribution (for example, `gawk-3.0.4.tar.gz'), first use `gzip' to expand the file, and then use `tar' to extract it. You can use the following pipeline to produce the `gawk' distribution: # Under System V, add 'o' to the tar flags - gzip -d -c gawk-3.0.3.tar.gz | tar -xvpf - + gzip -d -c gawk-3.0.4.tar.gz | tar -xvpf - -This will create a directory named `gawk-3.0.3' in the current +This will create a directory named `gawk-3.0.4' in the current directory. The distribution file name is of the form `gawk-V.R.N.tar.gz'. The V represents the major version of `gawk', the R represents the current release of version V, and the N represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch -level is 3, but when retrieving distributions, you should get the +level is 4, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note that release levels greater than or equal to 90 denote "beta," or non-production software; you may not wish to retrieve such a version @@ -15470,7 +15569,7 @@ Compiling `gawk' for Unix ------------------------- After you have extracted the `gawk' distribution, `cd' to -`gawk-3.0.3'. Like most GNU software, `gawk' is configured +`gawk-3.0.4'. Like most GNU software, `gawk' is configured automatically for your Unix system by running the `configure' program. This program is a Bourne shell script that was generated automatically using GNU `autoconf'. (The `autoconf' software is described fully @@ -15958,15 +16057,15 @@ us decide whether the problem was really in the documentation. can send mail to. Internet: - `bug-gnu-utils@prep.ai.mit.edu' + `bug-gnu-utils@gnu.org' UUCP: - `uunet!prep.ai.mit.edu!bug-gnu-utils' + `uunet!gnu.org!bug-gnu-utils' Please include the version number of `gawk' you are using. You can get this information with the command `gawk --version'. You should send a carbon copy of your mail to Arnold Robbins, who can be reached -at `arnold@gnu.ai.mit.edu'. +at `arnold@gnu.org'. *Important!* Do *not* try to report bugs in `gawk' by posting to the Usenet/Internet newsgroup `comp.lang.awk'. While the `gawk' developers @@ -16024,12 +16123,14 @@ section briefly describes where to get them. Unix `awk' Brian Kernighan has been able to make his implementation of `awk' freely available. You can get it via anonymous `ftp' to the host - `netlib.att.com'. Change directory to `/netlib/research'. Use - "binary" or "image" mode, and retrieve `awk.bundle.Z'. + `netlib.bell-labs.com'. Change directory to `/netlib/research'. + Use "binary" or "image" mode, and retrieve `awk.bundle.gz'. - This is a shell archive that has been compressed with the - `compress' utility. It can be uncompressed with either - `uncompress' or the GNU `gunzip' utility. + This is a shell archive that has been compressed with the GNU + `gzip' utility. It can be uncompressed with the `gunzip' utility. + + You can also retrieve this version via the World Wide Web from + Brian Kernighan's home page (http://cm.bell-labs.com/who/bwk). This version requires an ANSI C compiler; GCC (the GNU C compiler) works quite nicely. @@ -16116,7 +16217,7 @@ Adding New Features You are free to add any new features you like to `gawk'. However, if you want your changes to be incorporated into the `gawk' distribution, there are several steps that you need to take in order to -make it possible for me to include to your changes. +make it possible for me to include your changes. 1. Get the latest version. It is much easier for me to integrate changes if they are relative to the most recent distributed @@ -16125,7 +16226,7 @@ make it possible for me to include to your changes. Distribution: Getting, for information on getting the latest version of `gawk'. - 2. See *note : (Version)Top standards, GNU Coding Standards. This + 2. See *note (Version)Top:: standards, GNU Coding Standards. This document describes how GNU software should be written. If you haven't read it, please do so, preferably *before* starting to modify `gawk'. (The `GNU Coding Standards' are available as part @@ -16194,7 +16295,7 @@ make it possible for me to include to your changes. effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do, and *many* people have done so already. If you have questions, please contact me (*note Reporting - Problems and Bugs: Bugs.), or `gnu@prep.ai.mit.edu'. + Problems and Bugs: Bugs.), or `gnu@gnu.org'. 5. Update the documentation. Along with your new code, please supply new sections and or chapters for this Info file. If at all @@ -16211,10 +16312,10 @@ make it possible for me to include to your changes. 6. Submit changes as context diffs or unified diffs. Use `diff -c -r -N' or `diff -u -r -N' to compare the original `gawk' source tree with your version. (I find context diffs to be more readable, but - unified diffs are more compact.) I recommend using the GNU version - of `diff'. Send the output produced by either run of `diff' to me - when you submit your changes. *Note Reporting Problems and Bugs: - Bugs, for the electronic mail information. + unified diffs are more compact.) I recommend using the GNU + version of `diff'. Send the output produced by either run of + `diff' to me when you submit your changes. *Note Reporting + Problems and Bugs: Bugs, for the electronic mail information. Using this format makes it easy for me to apply your changes to the master version of the `gawk' source code (using `patch'). If I @@ -16298,7 +16399,7 @@ several steps to follow. the public domain, and submit a signed statement to that effect, or assign the copyright in your code to the FSF. Both of these actions are easy to do, and *many* people have done so already. If - you have questions, please contact me, or `gnu@prep.ai.mit.edu'. + you have questions, please contact me, or `gnu@gnu.org'. Following these steps will make it much easier to integrate your changes into `gawk', and have them co-exist happily with the code for @@ -16340,9 +16441,9 @@ Databases A `PROCINFO' Array The special files that provide process-related information (*note - Special File Names in `gawk': Special Files.) may be superseded by - a `PROCINFO' array that would provide the same information, in an - easier to access fashion. + Special File Names in `gawk': Special Files.) may be superseded + by a `PROCINFO' array that would provide the same information, in + an easier to access fashion. More `lint' warnings There are more things that could be checked for portability. @@ -16363,12 +16464,6 @@ Use of GNU `malloc' The GNU version of `malloc' could potentially speed up `gawk', since it relies heavily on the use of dynamic memory allocation. -Use of the `rx' regexp library - The `rx' regular expression library could potentially speed up all - regexp operations that require knowing the exact location of - matches. This includes record termination, field and array - splitting, and the `sub', `gsub', `gensub' and `match' functions. - File: gawk.info, Node: Improvements, Prev: Future Extensions, Up: Notes @@ -16515,7 +16610,7 @@ CHEM A preprocessor for `pic' that reads descriptions of molecules and produces `pic' input for drawing them. It was written in `awk' by Brian Kernighan and Jon Bentley, and is available from - `netlib@research.att.com'. + <netlib@research.bell-labs.com>. Compound Statement A series of `awk' statements, enclosed in curly braces. Compound @@ -17200,11 +17295,11 @@ Index * ! operator: Boolean Ops. * != operator: Typing and Comparison. -* !~ operator <1>: Regexp Constants. -* !~ operator <2>: Typing and Comparison. -* !~ operator <3>: Regexp Usage. +* !~ operator <1>: Typing and Comparison. +* !~ operator <2>: Regexp Constants. +* !~ operator <3>: Computed Regexps. * !~ operator <4>: Case-sensitivity. -* !~ operator: Computed Regexps. +* !~ operator: Regexp Usage. * # (comment): Comments. * #! (executable scripts): Executable Scripts. * $ (field operator): Fields. @@ -17223,10 +17318,10 @@ Index * --traditional option: Options. * --usage option: Options. * --version option: Options. -* -f option: Long. -* -F option <1>: Command Line Field Separator. -* -F option: Options. * -f option: Options. +* -F option <1>: Options. +* -F option: Command Line Field Separator. +* -f option: Long. * -v option: Options. * -W option: Options. * /dev/fd: Special Files. @@ -17236,8 +17331,8 @@ Index * /dev/stderr: Special Files. * /dev/stdin: Special Files. * /dev/stdout: Special Files. -* /dev/user <1>: Special Files. -* /dev/user: Passwd Functions. +* /dev/user <1>: Passwd Functions. +* /dev/user: Special Files. * < operator: Typing and Comparison. * <= operator: Typing and Comparison. * == operator: Typing and Comparison. @@ -17256,8 +17351,8 @@ Index * _tm_addup: Mktime Function. * _tm_isleap: Mktime Function. * accessing fields: Fields. -* account information <1>: Passwd Functions. -* account information: Group Functions. +* account information <1>: Group Functions. +* account information: Passwd Functions. * acronym: History. * action, curly braces: Action Overview. * action, default: Very Simple. @@ -17272,17 +17367,17 @@ Index * amiga: Amiga Installation. * anchors in regexps: Regexp Operators. * and operator: Boolean Ops. -* anonymous ftp <1>: Getting. -* anonymous ftp: Other Versions. +* anonymous ftp <1>: Other Versions. +* anonymous ftp: Getting. * applications of awk: When. * ARGC: Auto-set. -* ARGIND <1>: Auto-set. -* ARGIND: Other Arguments. +* ARGIND <1>: Other Arguments. +* ARGIND: Auto-set. * argument processing: Getopt Function. * arguments in function call: Function Calls. * arguments, command line: Invoking Gawk. -* ARGV <1>: Auto-set. -* ARGV: Other Arguments. +* ARGV <1>: Other Arguments. +* ARGV: Auto-set. * arithmetic operators: Arithmetic Ops. * array assignment: Assigning Elements. * array reference: Reference to Elements. @@ -17309,33 +17404,30 @@ Index * atan2: Numeric Functions. * atari: Atari Installation. * automatic initialization: More Complex. -* awk language, POSIX version <1>: OFMT. -* awk language, POSIX version <2>: Next Statement. -* awk language, POSIX version <3>: Continue Statement. -* awk language, POSIX version <4>: Format Modifiers. -* awk language, POSIX version <5>: Field Splitting Summary. -* awk language, POSIX version <6>: Arithmetic Ops. -* awk language, POSIX version <7>: User-modified. -* awk language, POSIX version <8>: Precedence. -* awk language, POSIX version <9>: Assignment Ops. -* awk language, POSIX version <10>: String Functions. -* awk language, POSIX version <11>: Regexp Operators. -* awk language, POSIX version <12>: Escape Sequences. -* awk language, POSIX version <13>: Regexp Operators. -* awk language, POSIX version <14>: String Functions. -* awk language, POSIX version <15>: Definition Syntax. -* awk language, POSIX version <16>: Break Statement. -* awk language, POSIX version <17>: Regexp Operators. -* awk language, POSIX version: Conversion. +* awk language, POSIX version <1>: Definition Syntax. +* awk language, POSIX version <2>: String Functions. +* awk language, POSIX version <3>: User-modified. +* awk language, POSIX version <4>: Next Statement. +* awk language, POSIX version <5>: Continue Statement. +* awk language, POSIX version <6>: Break Statement. +* awk language, POSIX version <7>: Precedence. +* awk language, POSIX version <8>: Assignment Ops. +* awk language, POSIX version <9>: Arithmetic Ops. +* awk language, POSIX version <10>: Conversion. +* awk language, POSIX version <11>: Format Modifiers. +* awk language, POSIX version <12>: OFMT. +* awk language, POSIX version <13>: Field Splitting Summary. +* awk language, POSIX version <14>: Regexp Operators. +* awk language, POSIX version: Escape Sequences. * awk language, V.4 version <1>: SVR4. * awk language, V.4 version: Escape Sequences. * AWKPATH environment variable: AWKPATH Variable. * awksed: Simple Sed. -* backslash continuation <1>: Statements/Lines. -* backslash continuation: Egrep Program. +* backslash continuation <1>: Egrep Program. +* backslash continuation: Statements/Lines. * backslash continuation and comments: Statements/Lines. -* backslash continuation in csh <1>: More Complex. -* backslash continuation in csh: Statements/Lines. +* backslash continuation in csh <1>: Statements/Lines. +* backslash continuation in csh: More Complex. * basic function of awk: Getting Started. * BBS-list file: Sample Data Files. * BEGIN special pattern: BEGIN/END. @@ -17347,9 +17439,8 @@ Index * break statement: Break Statement. * break, outside of loops: Break Statement. * Brennan, Michael <1>: Other Versions. -* Brennan, Michael <2>: Delete. -* Brennan, Michael <3>: Other Versions. -* Brennan, Michael: Simple Sed. +* Brennan, Michael <2>: Simple Sed. +* Brennan, Michael: Delete. * buffer matching operators: GNU Regexp Operators. * buffering output: I/O Functions. * buffering, interactive vs. non-interactive: I/O Functions. @@ -17393,8 +17484,8 @@ Index * comp.lang.awk: Bugs. * comparison expressions: Typing and Comparison. * comparisons, string vs. regexp: Typing and Comparison. -* compatibility mode <1>: Options. -* compatibility mode: POSIX/GNU. +* compatibility mode <1>: POSIX/GNU. +* compatibility mode: Options. * complemented character list: Regexp Operators. * compound statement: Statements. * computed regular expressions: Computed Regexps. @@ -17411,42 +17502,40 @@ Index * conversions, during subscripting: Numeric Array Subscripts. * converting dates to timestamps: Mktime Function. * CONVFMT <1>: Numeric Array Subscripts. -* CONVFMT <2>: Conversion. -* CONVFMT: User-modified. +* CONVFMT <2>: User-modified. +* CONVFMT: Conversion. * cos: Numeric Functions. -* csh, backslash continuation <1>: More Complex. -* csh, backslash continuation: Statements/Lines. +* csh, backslash continuation <1>: Statements/Lines. +* csh, backslash continuation: More Complex. * curly braces: Action Overview. * custom.h configuration file: Configuration Philosophy. * cut utility: Cut Program. * cut.awk: Cut Program. * d.c., see "dark corner": This Manual. -* dark corner <1>: Control Letters. -* dark corner <2>: Continue Statement. -* dark corner <3>: Using Constant Regexps. -* dark corner <4>: Single Character Fields. -* dark corner <5>: OFMT. -* dark corner <6>: Auto-set. -* dark corner <7>: Truth Values. -* dark corner <8>: Field Splitting Summary. -* dark corner <9>: Assignment Options. -* dark corner <10>: This Manual. -* dark corner <11>: Escape Sequences. -* dark corner <12>: Format Modifiers. -* dark corner <13>: Break Statement. -* dark corner <14>: Invoking Gawk. -* dark corner <15>: Plain Getline. -* dark corner <16>: Using Constant Regexps. +* dark corner <1>: Other Arguments. +* dark corner <2>: Invoking Gawk. +* dark corner <3>: String Functions. +* dark corner <4>: Uninitialized Subscripts. +* dark corner <5>: Auto-set. +* dark corner <6>: Exit Statement. +* dark corner <7>: Continue Statement. +* dark corner <8>: Break Statement. +* dark corner <9>: Using BEGIN/END. +* dark corner <10>: Truth Values. +* dark corner <11>: Conversion. +* dark corner <12>: Assignment Options. +* dark corner <13>: Using Constant Regexps. +* dark corner <14>: Format Modifiers. +* dark corner <15>: Control Letters. +* dark corner <16>: OFMT. * dark corner <17>: Getline Summary. -* dark corner <18>: Multiple Line. -* dark corner <19>: String Functions. -* dark corner <20>: Conversion. -* dark corner <21>: Uninitialized Subscripts. -* dark corner <22>: Auto-set. -* dark corner <23>: Records. -* dark corner <24>: Exit Statement. -* dark corner <25>: Other Arguments. -* dark corner: Using BEGIN/END. +* dark corner <18>: Plain Getline. +* dark corner <19>: Multiple Line. +* dark corner <20>: Field Splitting Summary. +* dark corner <21>: Single Character Fields. +* dark corner <22>: Records. +* dark corner <23>: Escape Sequences. +* dark corner: This Manual. * data-driven languages: Getting Started. * dates, converting to timestamps: Mktime Function. * decrement operators: Increment Ops. @@ -17460,28 +17549,25 @@ Index * deleting entire arrays: Delete. * deprecated features: Obsolete. * deprecated options: Obsolete. -* differences between gawk and awk <1>: Records. -* differences between gawk and awk <2>: Scalar Constants. -* differences between gawk and awk <3>: Getline Summary. -* differences between gawk and awk <4>: ARGC and ARGV. -* differences between gawk and awk <5>: Calling Built-in. +* differences between gawk and awk <1>: AWKPATH Variable. +* differences between gawk and awk <2>: String Functions. +* differences between gawk and awk <3>: Calling Built-in. +* differences between gawk and awk <4>: Delete. +* differences between gawk and awk <5>: ARGC and ARGV. * differences between gawk and awk <6>: Nextfile Statement. -* differences between gawk and awk <7>: AWKPATH Variable. -* differences between gawk and awk <8>: Getline Intro. -* differences between gawk and awk <9>: Special Files. -* differences between gawk and awk <10>: Conditional Exp. -* differences between gawk and awk <11>: Arithmetic Ops. -* differences between gawk and awk <12>: String Functions. -* differences between gawk and awk <13>: I/O And BEGIN/END. +* differences between gawk and awk <7>: I/O And BEGIN/END. +* differences between gawk and awk <8>: Conditional Exp. +* differences between gawk and awk <9>: Arithmetic Ops. +* differences between gawk and awk <10>: Using Constant Regexps. +* differences between gawk and awk <11>: Scalar Constants. +* differences between gawk and awk <12>: Close Files And Pipes. +* differences between gawk and awk <13>: Special Files. * differences between gawk and awk <14>: Redirection. -* differences between gawk and awk <15>: Case-sensitivity. -* differences between gawk and awk <16>: Using Constant Regexps. -* differences between gawk and awk <17>: Close Files And Pipes. -* differences between gawk and awk <18>: String Functions. -* differences between gawk and awk <19>: Close Files And Pipes. -* differences between gawk and awk <20>: Delete. -* differences between gawk and awk <21>: Single Character Fields. -* differences between gawk and awk: Records. +* differences between gawk and awk <15>: Getline Summary. +* differences between gawk and awk <16>: Getline Intro. +* differences between gawk and awk <17>: Single Character Fields. +* differences between gawk and awk <18>: Records. +* differences between gawk and awk: Case-sensitivity. * directory search: AWKPATH Variable. * division: Arithmetic Ops. * documenting awk programs <1>: Library Names. @@ -17489,8 +17575,8 @@ Index * dupword.awk: Dupword Program. * dynamic regular expressions: Computed Regexps. * EBCDIC: Ordinal Functions. -* egrep <1>: One-shot. -* egrep: Regexp Operators. +* egrep <1>: Regexp Operators. +* egrep: One-shot. * egrep utility: Egrep Program. * egrep.awk: Egrep Program. * element assignment: Assigning Elements. @@ -17510,13 +17596,13 @@ Index * environment variable, AWKPATH: AWKPATH Variable. * environment variable, POSIXLY_CORRECT: Options. * equivalence classes: Regexp Operators. -* ERRNO <1>: Getline Intro. +* ERRNO <1>: Auto-set. * ERRNO <2>: Close Files And Pipes. -* ERRNO: Auto-set. +* ERRNO: Getline Intro. * errors, common <1>: Typing and Comparison. -* errors, common <2>: Computed Regexps. +* errors, common <2>: Print Examples. * errors, common <3>: Basic Field Splitting. -* errors, common: Print Examples. +* errors, common: Computed Regexps. * escape processing, sub et. al.: String Functions. * escape sequence notation: Escape Sequences. * evaluation, order of: Calling Built-in. @@ -17545,9 +17631,9 @@ Index * FIELDWIDTHS: User-modified. * file descriptors: Special Files. * file, awk program: Long. -* FILENAME <1>: Reading Files. +* FILENAME <1>: Auto-set. * FILENAME <2>: Getline Summary. -* FILENAME: Auto-set. +* FILENAME: Reading Files. * FILENAME, being set by getline: Getline Summary. * Fish, Fred: Bugs. * flushing buffers: I/O Functions. @@ -17561,16 +17647,15 @@ Index * formatted output: Printf. * formatted timestamps: Gettimeofday Function. * Free Software Foundation <1>: Getting. -* Free Software Foundation <2>: Manual History. -* Free Software Foundation: Getting. +* Free Software Foundation: Manual History. * FreeBSD: Manual History. * Friedl, Jeffrey: Acknowledgements. -* FS <1>: Basic Field Splitting. -* FS: User-modified. -* ftp, anonymous <1>: Getting. -* ftp, anonymous: Other Versions. -* function call <1>: Function Calls. -* function call: Function Caveats. +* FS <1>: User-modified. +* FS: Basic Field Splitting. +* ftp, anonymous <1>: Other Versions. +* ftp, anonymous: Getting. +* function call <1>: Function Caveats. +* function call: Function Calls. * function definition: Definition Syntax. * function, recursive: Definition Syntax. * functions, undefined: Function Caveats. @@ -17602,11 +17687,11 @@ Index * gsub, third argument of: String Functions. * Hankerson, Darrel <1>: Bugs. * Hankerson, Darrel: Acknowledgements. -* historical features <1>: Command Line Field Separator. +* historical features <1>: Historical Features. * historical features <2>: String Functions. -* historical features <3>: Break Statement. -* historical features <4>: Continue Statement. -* historical features: Historical Features. +* historical features <3>: Continue Statement. +* historical features <4>: Break Statement. +* historical features: Command Line Field Separator. * history of awk: History. * histsort.awk: History Sorting. * how awk works: Two Rules. @@ -17616,13 +17701,13 @@ Index * id.awk: Id Program. * if-else statement: If Statement. * igawk.sh: Igawk Program. -* IGNORECASE <1>: User-modified. -* IGNORECASE <2>: Array Intro. +* IGNORECASE <1>: Array Intro. +* IGNORECASE <2>: User-modified. * IGNORECASE: Case-sensitivity. * IGNORECASE and array subscripts: Array Intro. * ignoring case: Case-sensitivity. -* implementation limits <1>: Getline Summary. -* implementation limits: Redirection. +* implementation limits <1>: Redirection. +* implementation limits: Getline Summary. * in operator: Typing and Comparison. * increment operators: Increment Ops. * index: String Functions. @@ -17648,17 +17733,17 @@ Index * inventory-shipped file: Sample Data Files. * invocation of gawk: Invoking Gawk. * ISO 8601: Time Functions. -* ISO 8859-1 <1>: Case-sensitivity. -* ISO 8859-1: Glossary. +* ISO 8859-1 <1>: Glossary. +* ISO 8859-1: Case-sensitivity. * ISO Latin-1 <1>: Glossary. * ISO Latin-1: Case-sensitivity. -* Jaegermann, Michal <1>: Acknowledgements. -* Jaegermann, Michal: Bugs. +* Jaegermann, Michal <1>: Bugs. +* Jaegermann, Michal: Acknowledgements. * join: Join Function. -* Kernighan, Brian <1>: Concatenation. -* Kernighan, Brian <2>: Acknowledgements. -* Kernighan, Brian <3>: Other Versions. -* Kernighan, Brian <4>: BTL. +* Kernighan, Brian <1>: Other Versions. +* Kernighan, Brian <2>: BTL. +* Kernighan, Brian <3>: Concatenation. +* Kernighan, Brian <4>: Acknowledgements. * Kernighan, Brian: History. * known bugs: Known Bugs. * labels.awk: Labels Program. @@ -17671,12 +17756,12 @@ Index * limitations <1>: Redirection. * limitations: Getline Summary. * line break: Statements/Lines. -* line continuation <1>: Boolean Ops. -* line continuation <2>: Print Examples. -* line continuation <3>: Statements/Lines. -* line continuation: Conditional Exp. -* Linux <1>: Manual History. -* Linux: Atari Compiling. +* line continuation <1>: Conditional Exp. +* line continuation <2>: Boolean Ops. +* line continuation <3>: Print Examples. +* line continuation: Statements/Lines. +* Linux <1>: Atari Compiling. +* Linux: Manual History. * locale, definition of: Time Functions. * log: Numeric Functions. * logical false: Truth Values. @@ -17695,10 +17780,10 @@ Index * mawk: Other Versions. * merging strings: Join Function. * metacharacters: Regexp Operators. -* mistakes, common <1>: Basic Field Splitting. -* mistakes, common <2>: Typing and Comparison. -* mistakes, common <3>: Computed Regexps. -* mistakes, common: Print Examples. +* mistakes, common <1>: Typing and Comparison. +* mistakes, common <2>: Print Examples. +* mistakes, common <3>: Basic Field Splitting. +* mistakes, common: Computed Regexps. * mktime: Mktime Function. * modifiers (in format specifiers): Format Modifiers. * multi-dimensional subscripts: Multi-dimensional. @@ -17718,15 +17803,15 @@ Index * next, inside a user-defined function: Next Statement. * nextfile function: Nextfile Function. * nextfile statement: Nextfile Statement. -* NF <1>: Fields. -* NF: Auto-set. +* NF <1>: Auto-set. +* NF: Fields. * non-interactive buffering vs. interactive: I/O Functions. * not operator: Boolean Ops. * NR <1>: Auto-set. * NR: Records. -* null string <1>: Conversion. -* null string <2>: Regexp Field Splitting. -* null string: Truth Values. +* null string <1>: Truth Values. +* null string <2>: Conversion. +* null string: Regexp Field Splitting. * null string, as array subscript: Uninitialized Subscripts. * number of fields, NF: Fields. * number of records, NR, FNR: Records. @@ -17739,10 +17824,10 @@ Index * obsolete features: Obsolete. * obsolete options: Obsolete. * OFMT <1>: User-modified. -* OFMT <2>: OFMT. -* OFMT: Conversion. -* OFS <1>: Output Separators. -* OFS: User-modified. +* OFMT <2>: Conversion. +* OFMT: OFMT. +* OFS <1>: User-modified. +* OFS: Output Separators. * old awk: History. * old awk vs. new awk: Names. * one-liners: One-liners. @@ -17763,8 +17848,8 @@ Index * or operator: Boolean Ops. * ord: Ordinal Functions. * order of evaluation: Calling Built-in. -* ORS <1>: Output Separators. -* ORS: User-modified. +* ORS <1>: User-modified. +* ORS: Output Separators. * output: Printing. * output field separator, OFS: Output Separators. * output format specifier, OFMT: OFMT. @@ -17788,33 +17873,30 @@ Index * PERL: Future Extensions. * pipeline, input: Getline/Pipe. * pipes for output: Redirection. -* portability issues <1>: Delete. -* portability issues <2>: Statements/Lines. -* portability issues <3>: String Functions. -* portability issues <4>: Close Files And Pipes. -* portability issues <5>: Definition Syntax. -* portability issues <6>: I/O Functions. -* portability issues <7>: Portability Notes. -* portability issues: Escape Sequences. +* portability issues <1>: Portability Notes. +* portability issues <2>: Definition Syntax. +* portability issues <3>: I/O Functions. +* portability issues <4>: String Functions. +* portability issues <5>: Delete. +* portability issues <6>: Close Files And Pipes. +* portability issues <7>: Escape Sequences. +* portability issues: Statements/Lines. * porting gawk: New Ports. -* POSIX awk <1>: Assignment Ops. -* POSIX awk <2>: Field Splitting Summary. -* POSIX awk <3>: Format Modifiers. -* POSIX awk <4>: String Functions. -* POSIX awk <5>: OFMT. -* POSIX awk <6>: Escape Sequences. -* POSIX awk <7>: Definition Syntax. -* POSIX awk <8>: Arithmetic Ops. -* POSIX awk <9>: Precedence. +* POSIX awk <1>: Definition Syntax. +* POSIX awk <2>: String Functions. +* POSIX awk <3>: User-modified. +* POSIX awk <4>: Next Statement. +* POSIX awk <5>: Continue Statement. +* POSIX awk <6>: Break Statement. +* POSIX awk <7>: Precedence. +* POSIX awk <8>: Assignment Ops. +* POSIX awk <9>: Arithmetic Ops. * POSIX awk <10>: Conversion. -* POSIX awk <11>: User-modified. -* POSIX awk <12>: Next Statement. -* POSIX awk <13>: Continue Statement. -* POSIX awk <14>: Break Statement. -* POSIX awk <15>: Regexp Operators. -* POSIX awk <16>: String Functions. -* POSIX awk <17>: Precedence. -* POSIX awk: Regexp Operators. +* POSIX awk <11>: Format Modifiers. +* POSIX awk <12>: OFMT. +* POSIX awk <13>: Field Splitting Summary. +* POSIX awk <14>: Regexp Operators. +* POSIX awk: Escape Sequences. * POSIX mode: Options. * POSIXLY_CORRECT environment variable: Options. * precedence: Precedence. @@ -17831,8 +17913,8 @@ Index * program, awk: This Manual. * program, definition of: Getting Started. * program, self contained: Executable Scripts. -* programs, documenting <1>: Comments. -* programs, documenting: Library Names. +* programs, documenting <1>: Library Names. +* programs, documenting: Comments. * pwcat program: Passwd Functions. * pwcat.c: Passwd Functions. * quotient: Arithmetic Ops. @@ -17842,9 +17924,9 @@ Index * rand: Numeric Functions. * random numbers, seed of: Numeric Functions. * range pattern: Ranges. -* Rankin, Pat <1>: Acknowledgements. -* Rankin, Pat <2>: Bugs. -* Rankin, Pat: Assignment Ops. +* Rankin, Pat <1>: Bugs. +* Rankin, Pat <2>: Assignment Ops. +* Rankin, Pat: Acknowledgements. * reading files: Reading Files. * reading files, getline command: Getline. * reading files, multiple line records: Multiple Line. @@ -17861,8 +17943,8 @@ Index * regexp comparison vs. string comparison: Typing and Comparison. * regexp constant: Regexp Usage. * regexp constants, difference between slashes and quotes: Computed Regexps. -* regexp match/non-match operators <1>: Regexp Usage. -* regexp match/non-match operators: Typing and Comparison. +* regexp match/non-match operators <1>: Typing and Comparison. +* regexp match/non-match operators: Regexp Usage. * regexp matching operators: Regexp Usage. * regexp operators: Regexp Operators. * regexp operators, GNU specific: GNU Regexp Operators. @@ -17893,9 +17975,9 @@ Index * RS: Records. * RSTART <1>: String Functions. * RSTART: Auto-set. -* RT <1>: Records. -* RT <2>: Auto-set. -* RT: Multiple Line. +* RT <1>: Auto-set. +* RT <2>: Multiple Line. +* RT: Records. * rule, definition of: Getting Started. * running awk programs: Running gawk. * running long programs: Long. @@ -17907,13 +17989,13 @@ Index * scripts, shell: Executable Scripts. * search path: AWKPATH Variable. * search path, for source files: AWKPATH Variable. -* sed utility <1>: Simple Sed. -* sed utility <2>: Igawk Program. +* sed utility <1>: Igawk Program. +* sed utility <2>: Simple Sed. * sed utility: Field Splitting Summary. * seed for random numbers: Numeric Functions. * self contained programs: Executable Scripts. -* shell quoting <1>: Read Terminal. -* shell quoting: Long. +* shell quoting <1>: Long. +* shell quoting: Read Terminal. * shell scripts: Executable Scripts. * short-circuit operators: Boolean Ops. * side effect: Assignment Ops. @@ -17948,8 +18030,8 @@ Index * sub: String Functions. * sub, third argument of: String Functions. * subscripts in arrays: Multi-dimensional. -* SUBSEP <1>: User-modified. -* SUBSEP: Multi-dimensional. +* SUBSEP <1>: Multi-dimensional. +* SUBSEP: User-modified. * substr: String Functions. * subtraction: Arithmetic Ops. * system: I/O Functions. @@ -17996,244 +18078,244 @@ Index * wordfreq.sh: Word Sorting. * || operator: Boolean Ops. * ~ operator <1>: Typing and Comparison. -* ~ operator <2>: Regexp Usage. -* ~ operator <3>: Case-sensitivity. -* ~ operator <4>: Computed Regexps. -* ~ operator: Regexp Constants. +* ~ operator <2>: Regexp Constants. +* ~ operator <3>: Computed Regexps. +* ~ operator <4>: Case-sensitivity. +* ~ operator: Regexp Usage. Tag Table: -Node: Top1230 -Node: Preface20719 -Node: History22069 -Node: Manual History23427 -Node: Acknowledgements26869 -Node: What Is Awk30496 -Node: This Manual32150 -Node: Conventions34849 -Node: Sample Data Files36141 -Node: Getting Started39224 -Node: Names41532 -Node: Running gawk43102 -Node: One-shot44263 -Node: Read Terminal45650 -Node: Long47262 -Node: Executable Scripts48655 -Node: Comments50910 -Node: Very Simple52070 -Node: Two Rules54117 -Node: More Complex56296 -Node: Statements/Lines59412 -Node: Other Features63685 -Node: When64411 -Node: One-liners66346 -Node: Regexp69233 -Node: Regexp Usage70559 -Node: Escape Sequences72709 -Node: Regexp Operators78161 -Node: GNU Regexp Operators89194 -Node: Case-sensitivity92898 -Node: Leftmost Longest96014 -Node: Computed Regexps97549 -Node: Reading Files100206 -Node: Records101974 -Node: Fields108469 -Node: Non-Constant Fields111538 -Node: Changing Fields113825 -Node: Field Separators118232 -Node: Basic Field Splitting118934 -Node: Regexp Field Splitting122163 -Node: Single Character Fields124730 -Node: Command Line Field Separator125799 -Node: Field Splitting Summary129040 -Node: Constant Size131059 -Node: Multiple Line135096 -Node: Getline140504 -Node: Getline Intro141578 -Node: Plain Getline142541 -Node: Getline/Variable144805 -Node: Getline/File145947 -Node: Getline/Variable/File147257 -Node: Getline/Pipe149231 -Node: Getline/Variable/Pipe151321 -Node: Getline Summary152439 -Node: Printing154033 -Node: Print155101 -Node: Print Examples157201 -Node: Output Separators159811 -Node: OFMT161709 -Node: Printf163111 -Node: Basic Printf164015 -Node: Control Letters165549 -Node: Format Modifiers168237 -Node: Printf Examples172386 -Node: Redirection175164 -Node: Special Files179803 -Node: Close Files And Pipes185040 -Node: Expressions189100 -Node: Constants191296 -Node: Scalar Constants191775 -Node: Regexp Constants192780 -Node: Using Constant Regexps193242 -Node: Variables196443 -Node: Using Variables197097 -Node: Assignment Options198532 -Node: Conversion200477 -Node: Arithmetic Ops203659 -Node: Concatenation205793 -Node: Assignment Ops207215 -Node: Increment Ops212811 -Node: Truth Values215339 -Node: Typing and Comparison216387 -Node: Boolean Ops222394 -Node: Conditional Exp226087 -Node: Function Calls227764 -Node: Precedence230644 -Node: Patterns and Actions234032 -Node: Pattern Overview234458 -Node: Kinds of Patterns235233 -Node: Regexp Patterns236370 -Node: Expression Patterns236924 -Node: Ranges240575 -Node: BEGIN/END243299 -Node: Using BEGIN/END243768 -Node: I/O And BEGIN/END246731 -Node: Empty248747 -Node: Action Overview249046 -Node: Statements251618 -Node: If Statement253324 -Node: While Statement254827 -Node: Do Statement256857 -Node: For Statement257959 -Node: Break Statement261216 -Node: Continue Statement263487 -Node: Next Statement265483 -Node: Nextfile Statement267980 -Node: Exit Statement269894 -Node: Built-in Variables271904 -Node: User-modified273000 -Node: Auto-set277922 -Node: ARGC and ARGV284452 -Node: Arrays287798 -Node: Array Intro289261 -Node: Reference to Elements293301 -Node: Assigning Elements295251 -Node: Array Example295753 -Node: Scanning an Array297472 -Node: Delete299802 -Node: Numeric Array Subscripts301861 -Node: Uninitialized Subscripts303767 -Node: Multi-dimensional305411 -Node: Multi-scanning308506 -Node: Built-in310149 -Node: Calling Built-in311138 -Node: Numeric Functions313109 -Node: String Functions316928 -Node: I/O Functions335860 -Node: Time Functions341445 -Node: User-defined350298 -Node: Definition Syntax351011 -Node: Function Example355260 -Node: Function Caveats357589 -Node: Return Statement361459 -Node: Invoking Gawk364114 -Node: Options365349 -Node: Other Arguments374179 -Node: AWKPATH Variable376827 -Node: Obsolete379576 -Node: Undocumented380242 -Node: Known Bugs380491 -Node: Library Functions381623 -Node: Portability Notes384041 -Node: Nextfile Function385325 -Node: Assert Function390201 -Node: Round Function393540 -Node: Ordinal Functions395184 -Node: Join Function398636 -Node: Mktime Function400688 -Node: Gettimeofday Function412261 -Node: Filetrans Function416273 -Node: Getopt Function419950 -Node: Passwd Functions431306 -Node: Group Functions439639 -Node: Library Names447536 -Node: Sample Programs451461 -Node: Clones451952 -Node: Cut Program453046 -Node: Egrep Program463075 -Node: Id Program470738 -Node: Split Program474009 -Node: Tee Program477377 -Node: Uniq Program480173 -Node: Wc Program487718 -Node: Miscellaneous Programs492136 -Node: Dupword Program493046 -Node: Alarm Program494717 -Node: Translate Program499261 -Node: Labels Program504073 -Node: Word Sorting507617 -Node: History Sorting511962 -Node: Extract Program513931 -Node: Simple Sed520889 -Node: Igawk Program524233 -Node: Language History537554 -Node: V7/SVR3.1538787 -Node: SVR4541442 -Node: POSIX542964 -Node: BTL544584 -Node: POSIX/GNU545347 -Node: Gawk Summary549779 -Node: Command Line Summary550601 -Node: Language Summary553577 -Node: Variables/Fields555958 -Node: Fields Summary556692 -Node: Built-in Summary558478 -Node: Arrays Summary562193 -Node: Data Type Summary563486 -Node: Rules Summary565312 -Node: Pattern Summary566840 -Node: Regexp Summary569025 -Node: Actions Summary572408 -Node: Operator Summary574240 -Node: Control Flow Summary575467 -Node: I/O Summary576024 -Node: Printf Summary579013 -Node: Special File Summary582351 -Node: Built-in Functions Summary584029 -Node: Time Functions Summary588029 -Node: String Constants Summary588920 -Node: Functions Summary590240 -Node: Historical Features591301 -Node: Installation592799 -Node: Gawk Distribution594014 -Node: Getting594517 -Node: Extracting597463 -Node: Distribution contents598850 -Node: Unix Installation603626 -Node: Quick Installation604135 -Node: Configuration Philosophy605653 -Node: VMS Installation608055 -Node: VMS Compilation608594 -Node: VMS Installation Details610198 -Node: VMS Running611840 -Node: VMS POSIX613430 -Node: PC Installation614710 -Node: Atari Installation618113 -Node: Atari Compiling619297 -Node: Atari Using621206 -Node: Amiga Installation624053 -Node: Bugs625164 -Node: Other Versions628240 -Node: Notes629814 -Node: Compatibility Mode630421 -Node: Additions631264 -Node: Adding Code631962 -Node: New Ports637302 -Node: Future Extensions641470 -Node: Improvements643718 -Node: Glossary645586 -Node: Copying662651 -Node: Index681843 +Node: Top1238 +Node: Preface20727 +Node: History22076 +Node: Manual History23434 +Node: Acknowledgements26876 +Node: What Is Awk30503 +Node: This Manual32157 +Node: Conventions34856 +Node: Sample Data Files36148 +Node: Getting Started39231 +Node: Names41539 +Node: Running gawk43108 +Node: One-shot44269 +Node: Read Terminal45656 +Node: Long47268 +Node: Executable Scripts48661 +Node: Comments51227 +Node: Very Simple53009 +Node: Two Rules55056 +Node: More Complex57235 +Node: Statements/Lines60351 +Node: Other Features64624 +Node: When65350 +Node: One-liners67285 +Node: Regexp70172 +Node: Regexp Usage71498 +Node: Escape Sequences73648 +Node: Regexp Operators79102 +Node: GNU Regexp Operators90135 +Node: Case-sensitivity93840 +Node: Leftmost Longest96956 +Node: Computed Regexps98491 +Node: Reading Files101148 +Node: Records102916 +Node: Fields109411 +Node: Non-Constant Fields112479 +Node: Changing Fields114766 +Node: Field Separators119174 +Node: Basic Field Splitting119876 +Node: Regexp Field Splitting123105 +Node: Single Character Fields125672 +Node: Command Line Field Separator126741 +Node: Field Splitting Summary129982 +Node: Constant Size132002 +Node: Multiple Line136039 +Node: Getline141447 +Node: Getline Intro142521 +Node: Plain Getline143484 +Node: Getline/Variable145748 +Node: Getline/File146890 +Node: Getline/Variable/File148200 +Node: Getline/Pipe150174 +Node: Getline/Variable/Pipe152382 +Node: Getline Summary153618 +Node: Printing155212 +Node: Print156280 +Node: Print Examples158381 +Node: Output Separators160989 +Node: OFMT162887 +Node: Printf164289 +Node: Basic Printf165193 +Node: Control Letters166727 +Node: Format Modifiers169415 +Node: Printf Examples173564 +Node: Redirection176343 +Node: Special Files180982 +Node: Close Files And Pipes186219 +Node: Expressions190280 +Node: Constants192476 +Node: Scalar Constants192955 +Node: Regexp Constants193959 +Node: Using Constant Regexps194421 +Node: Variables197622 +Node: Using Variables198276 +Node: Assignment Options199711 +Node: Conversion201656 +Node: Arithmetic Ops204838 +Node: Concatenation206972 +Node: Assignment Ops208394 +Node: Increment Ops213990 +Node: Truth Values216518 +Node: Typing and Comparison217566 +Node: Boolean Ops223573 +Node: Conditional Exp227266 +Node: Function Calls229043 +Node: Precedence231923 +Node: Patterns and Actions235311 +Node: Pattern Overview235737 +Node: Kinds of Patterns236512 +Node: Regexp Patterns237649 +Node: Expression Patterns238203 +Node: Ranges241855 +Node: BEGIN/END244579 +Node: Using BEGIN/END245048 +Node: I/O And BEGIN/END248011 +Node: Empty250027 +Node: Action Overview250326 +Node: Statements252898 +Node: If Statement254604 +Node: While Statement256107 +Node: Do Statement258138 +Node: For Statement259240 +Node: Break Statement262497 +Node: Continue Statement264768 +Node: Next Statement266764 +Node: Nextfile Statement269261 +Node: Exit Statement271175 +Node: Built-in Variables273186 +Node: User-modified274282 +Node: Auto-set279203 +Node: ARGC and ARGV285732 +Node: Arrays289571 +Node: Array Intro291034 +Node: Reference to Elements295074 +Node: Assigning Elements297024 +Node: Array Example297526 +Node: Scanning an Array299245 +Node: Delete301575 +Node: Numeric Array Subscripts303829 +Node: Uninitialized Subscripts305735 +Node: Multi-dimensional307379 +Node: Multi-scanning310474 +Node: Built-in312117 +Node: Calling Built-in313106 +Node: Numeric Functions315077 +Node: String Functions318895 +Node: I/O Functions338236 +Node: Time Functions344046 +Node: User-defined352896 +Node: Definition Syntax353609 +Node: Function Example357858 +Node: Function Caveats360188 +Node: Return Statement364059 +Node: Invoking Gawk366714 +Node: Options367949 +Node: Other Arguments376778 +Node: AWKPATH Variable379426 +Node: Obsolete382174 +Node: Undocumented382840 +Node: Known Bugs383089 +Node: Library Functions384227 +Node: Portability Notes386646 +Node: Nextfile Function387930 +Node: Assert Function392798 +Node: Round Function396150 +Node: Ordinal Functions397788 +Node: Join Function401232 +Node: Mktime Function403277 +Node: Gettimeofday Function414844 +Node: Filetrans Function418849 +Node: Getopt Function422512 +Node: Passwd Functions433861 +Node: Group Functions442182 +Node: Library Names450066 +Node: Sample Programs453991 +Node: Clones454482 +Node: Cut Program455576 +Node: Egrep Program465598 +Node: Id Program473254 +Node: Split Program476518 +Node: Tee Program479879 +Node: Uniq Program482668 +Node: Wc Program490206 +Node: Miscellaneous Programs494616 +Node: Dupword Program495526 +Node: Alarm Program497190 +Node: Translate Program501728 +Node: Labels Program506531 +Node: Word Sorting510067 +Node: History Sorting514412 +Node: Extract Program516374 +Node: Simple Sed523969 +Node: Igawk Program527306 +Node: Language History540619 +Node: V7/SVR3.1541852 +Node: SVR4544507 +Node: POSIX546029 +Node: BTL547649 +Node: POSIX/GNU548412 +Node: Gawk Summary552844 +Node: Command Line Summary553666 +Node: Language Summary556642 +Node: Variables/Fields559022 +Node: Fields Summary559756 +Node: Built-in Summary561542 +Node: Arrays Summary565257 +Node: Data Type Summary566550 +Node: Rules Summary568376 +Node: Pattern Summary569904 +Node: Regexp Summary572089 +Node: Actions Summary575472 +Node: Operator Summary577304 +Node: Control Flow Summary578531 +Node: I/O Summary579088 +Node: Printf Summary582077 +Node: Special File Summary585415 +Node: Built-in Functions Summary587093 +Node: Time Functions Summary591093 +Node: String Constants Summary591984 +Node: Functions Summary593304 +Node: Historical Features594365 +Node: Installation595863 +Node: Gawk Distribution597078 +Node: Getting597581 +Node: Extracting600532 +Node: Distribution contents601919 +Node: Unix Installation606695 +Node: Quick Installation607204 +Node: Configuration Philosophy608722 +Node: VMS Installation611124 +Node: VMS Compilation611663 +Node: VMS Installation Details613267 +Node: VMS Running614909 +Node: VMS POSIX616499 +Node: PC Installation617779 +Node: Atari Installation621182 +Node: Atari Compiling622366 +Node: Atari Using624275 +Node: Amiga Installation627122 +Node: Bugs628233 +Node: Other Versions631286 +Node: Notes632972 +Node: Compatibility Mode633579 +Node: Additions634422 +Node: Adding Code635120 +Node: New Ports640450 +Node: Future Extensions644610 +Node: Improvements646553 +Node: Glossary648421 +Node: Copying665492 +Node: Index684684 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 8c2aad2f..3e8e102f 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -21,10 +21,10 @@ @c applies to, and when the document was updated. @set TITLE Effective AWK Programming @set SUBTITLE A User's Guide for GNU Awk -@set PATCHLEVEL 3 +@set PATCHLEVEL 4 @set EDITION 1.0.@value{PATCHLEVEL} @set VERSION 3.0 -@set UPDATE-MONTH February 1997 +@set UPDATE-MONTH April, 1999 @iftex @set DOCUMENT book @end iftex @@ -74,7 +74,7 @@ particular records in a file and perform operations upon them. This is Edition @value{EDITION} of @cite{@value{TITLE}}, for the @value{VERSION}.@value{PATCHLEVEL} version of the GNU implementation of AWK. -Copyright (C) 1989, 1991, 92, 93, 96, 97 Free Software Foundation, Inc. +Copyright (C) 1989, 1991, 92, 93, 96, 97, 98, 99 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -138,7 +138,7 @@ Corporation. @* Registered Trademark of Paramount Pictures Corporation. @* @c sorry, i couldn't resist @sp 3 -Copyright @copyright{} 1989, 1991, 92, 93, 96, 97 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1991, 92, 93, 96, 97, 98, 99 Free Software Foundation, Inc. @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}}, @* @@ -153,16 +153,16 @@ for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU impleme @item Seattle, WA 98155 USA @tab Boston, MA 02111-1307 USA @item Phone: +1-206-782-7733 @tab Phone: +1-617-542-5942 @item Fax: +1-206-782-7191 @tab Fax: +1-617-542-2652 -@item E-mail: @code{sales@@ssc.com} @tab E-mail: @code{gnu@@prep.ai.mit.edu} +@item E-mail: @code{sales@@ssc.com} @tab E-mail: @code{gnu@@gnu.org} @item URL: @code{http://www.ssc.com/} @tab URL: @code{http://www.fsf.org/} @end multitable @sp 1 @c this ISBN can change! Check with SSC @c This one is correct for gawk 3.0 and edition 1.0 from the FSF -@c ISBN 1-882114-26-4 @* +ISBN 1-882114-26-4 @* @c This one is correct for gawk 3.0.3 and edition 1.0.3 from SSC -ISBN 1-57831-000-8 @* +@c ISBN 1-57831-000-8 @* Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -1387,6 +1387,12 @@ Self-contained @code{awk} scripts are useful when you want to write a program which users can invoke without their having to know that the program is written in @code{awk}. +@strong{Caution:} You should not put more than one argument on the @samp{#!} +line after the path to @code{awk}. This will not work. The operating system +treats the rest of the line as a single agument, and passes it to @code{awk}. +Doing this will lead to confusing behavior: most likely a usage diagnostic +of some sort from @code{awk}. + @cindex shell scripts @cindex scripts, shell Some older systems do not support the @samp{#!} mechanism. You can get a @@ -1441,6 +1447,21 @@ programs also, but this usually isn't very useful; the purpose of a comment is to help you or another person understand the program at a later time. +@strong{Caution:} As mentioned in +@ref{One-shot, ,One-shot Throw-away @code{awk} Programs}, +you can enclose small to medium programs in single quotes, in order to keep +your shell scripts self-contained. When doing so, @emph{don't} put +an apostrophe (i.e., a single quote) into a comment (or anywhere else +in your program). The shell will interpret the quote as the closing +quote for the entire program. As a result, usually the shell will +print a message about mismatched quotes, and if @code{awk} actually +runs, it will probably print strange messages about syntax errors. +For example: + +@example +awk 'BEGIN @{ print "hello" @} # let's be cute' +@end example + @node Very Simple, Two Rules, Running gawk, Getting Started @section A Very Simple Example @@ -2142,7 +2163,7 @@ listed in the table above. Another interesting question arises. Suppose you use an octal or hexadecimal escape to represent a regexp metacharacter (@pxref{Regexp Operators, , Regular Expression Operators}). -Does @code{awk} treat the character as literal character, or as a regexp +Does @code{awk} treat the character as a literal character, or as a regexp operator? @cindex dark corner @@ -4450,6 +4471,8 @@ According to POSIX, @samp{@var{expression} | getline} is ambiguous if because the concatenation operator is not parenthesized, and you should write it as @samp{("echo " "date") | getline} if you want your program to be portable to other @code{awk} implementations. +(It happens that @code{gawk} gets it right, but you should not +rely on this. Parentheses make it easier to read, anyway.) @node Getline/Variable/Pipe, Getline Summary, Getline/Pipe, Getline @subsection Using @code{getline} Into a Variable from a Pipe @@ -4482,6 +4505,8 @@ According to POSIX, @samp{@var{expression} | getline @var{var}} is ambiguous if because the concatenation operator is not parenthesized, and you should write it as @samp{("echo " "date") | getline @var{var}} if you want your program to be portable to other @code{awk} implementations. +(It happens that @code{gawk} gets it right, but you should not +rely on this. Parentheses make it easier to read, anyway.) @end ifinfo @node Getline Summary, , Getline/Variable/Pipe, Getline @@ -4616,7 +4641,7 @@ single @code{print} can make any number of lines this way. Here is an example of printing a string that contains embedded newlines (the @samp{\n} is an escape sequence, used to represent the newline -character; see @ref{Escape Sequences}): +character; @pxref{Escape Sequences}): @example @group @@ -6975,6 +7000,8 @@ by putting a newline after either character. However, you cannot put a newline in front of either character without using backslash continuation (@pxref{Statements/Lines, ,@code{awk} Statements Versus Lines}). +If @samp{--posix} is specified +(@pxref{Options, , Command Line Options}), then this extension is disabled. @node Function Calls, Precedence, Conditional Exp, Expressions @section Function Calls @@ -8264,7 +8291,7 @@ example: @example @group BEGIN @{ - if (("date" | getline date_now) < 0) @{ + if (("date" | getline date_now) <= 0) @{ print "Can't get system date" > "/dev/stderr" exit 1 @} @@ -8627,9 +8654,27 @@ contains @code{"inventory-shipped"}, and @code{ARGV[2]} contains Notice that the @code{awk} program is not entered in @code{ARGV}. The other special command line options, with their arguments, are also not -entered. But variable assignments on the command line @emph{are} +entered. This includes variable assignments done with the @samp{-v} +option (@pxref{Options, ,Command Line Options}). +Normal variable assignments on the command line @emph{are} treated as arguments, and do show up in the @code{ARGV} array. +@example +$ cat showargs.awk +@print{} BEGIN @{ +@print{} printf "A=%d, B=%d\n", A, B +@print{} for (i = 0; i < ARGC; i++) +@print{} printf "\tARGV[%d] = %s\n", i, ARGV[i] +@print{} @} +@print{} END @{ printf "A=%d, B=%d\n", A, B @} +$ awk -v A=1 -f showargs.awk B=2 /dev/null +@print{} A=1, B=0 +@print{} ARGV[0] = awk +@print{} ARGV[1] = B=2 +@print{} ARGV[2] = /dev/null +@print{} A=1, B=2 +@end example + Your program can alter @code{ARGC} and the elements of @code{ARGV}. Each time @code{awk} reaches the end of an input file, it uses the next element of @code{ARGV} as the name of the next input file. By storing a @@ -9172,6 +9217,14 @@ clears out the target array first. This call asks it to split apart the null string. Since there is no data to split out, the function simply clears the array and then returns. +@strong{Caution:} Deleting an array does not change its type; you cannot +delete an array and then use the array's name as a scalar. For +example, this will not work: + +@example +a[1] = 3; delete a; a = 3 +@end example + @node Numeric Array Subscripts, Uninitialized Subscripts, Delete, Arrays @section Using Numbers to Subscript Arrays @@ -9785,6 +9838,10 @@ string (d.c.). The POSIX standard allows this as well. Before splitting the string, @code{split} deletes any previously existing elements in the array @var{array} (d.c.). +If @var{string} does not match @var{fieldsep} at all, @var{array} will have +one element. The value of that element will be the original +@var{string}. + @item sprintf(@var{format}, @var{expression1},@dots{}) @findex sprintf This returns (without printing) the string that @code{printf} would @@ -9901,6 +9958,9 @@ such as in the above example. However, using any other non-changeable object as the third parameter will cause a fatal error, and your program will not run. +Finally, if the @var{regexp} is not a regexp constant, it is converted into a +string and then the value of that string is treated as the regexp to match. + @item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) @findex gsub This is similar to the @code{sub} function, except @code{gsub} replaces @@ -9980,6 +10040,9 @@ If the @var{how} argument is a string that does not begin with @samp{g} or @samp{G}, or if it is a number that is less than zero, only one substitution is performed. +If @var{regexp} does not match @var{target}, @code{gensub}'s return value +is the original, unchanged value of @var{target}. + @cindex differences between @code{gawk} and @code{awk} @code{gensub} is a @code{gawk} extension; it is not available in compatibility mode (@pxref{Options, ,Command Line Options}). @@ -10310,7 +10373,7 @@ and nonzero otherwise. @item system(@var{command}) @findex system @cindex interaction, @code{awk} and other programs -The system function allows the user to execute operating system commands +The @code{system} function allows the user to execute operating system commands and then return to the @code{awk} program. The @code{system} function executes the command given by the string @var{command}. It returns, as its value, the status returned by the command that was executed. @@ -10329,7 +10392,17 @@ the system administrator will be sent mail when the @code{awk} program finishes processing input and begins its end-of-input processing. Note that redirecting @code{print} or @code{printf} into a pipe is often -enough to accomplish your task. However, if your @code{awk} +enough to accomplish your task. If you need to run many commands, it +will be more efficient to simply print them to a pipe to the shell: + +@example +while (@var{more stuff to do}) + print @var{command} | "/bin/sh" +close("/bin/sh") +@end example + +@noindent +However, if your @code{awk} program is interactive, @code{system} is useful for cranking up large self-contained programs, such as a shell or an editor. @@ -11889,7 +11962,7 @@ Here is a second version of @code{nextfile} that remedies this problem. @c file eg/lib/nextfile.awk # nextfile --- skip remaining records in current file # correctly handle successive occurrences of the same file -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May, 1993 # this should be read in before the "main" awk program @@ -11983,7 +12056,7 @@ that is being tested. @c @group @c file eg/lib/assert.awk # assert --- assert that a condition is true. Otherwise exit. -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May, 1993 function assert(condition, string) @@ -12038,7 +12111,8 @@ mydata:1357: assertion failed: a <= 5 && b >= 17 @end example There is a problem with this version of @code{assert}, that it may not -be possible to work around. An @code{END} rule is automatically added +be possible to work around with standard @code{awk}. +An @code{END} rule is automatically added to the program calling @code{assert}. Normally, if a program consists of just a @code{BEGIN} rule, the input files and/or standard input are not read. However, now that the program has an @code{END} rule, @code{awk} @@ -12069,7 +12143,7 @@ it might be useful if your awk's @code{printf} does unbiased rounding. @c file eg/lib/round.awk # round --- do normal rounding # -# Arnold Robbins, arnold@@gnu.ai.mit.edu, August, 1996 +# Arnold Robbins, arnold@@gnu.org, August, 1996 # Public Domain function round(x, ival, aval, fraction) @@ -12130,7 +12204,7 @@ reason to build them into the @code{awk} interpreter. # _ord_init: function to initialize _ord_ # # Arnold Robbins -# arnold@@gnu.ai.mit.edu +# arnold@@gnu.org # Public Domain # 16 January, 1992 # 20 July, 1992, revised @@ -12254,7 +12328,7 @@ assumption since the array was likely created with @code{split} @group @c file eg/lib/join.awk # join.awk --- join an array into a string -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 function join(array, start, end, sep, result, i) @@ -12329,7 +12403,7 @@ assignment. @c file eg/lib/mktime.awk # mktime.awk --- convert a canonical date representation # into a timestamp -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 BEGIN \ @@ -12624,7 +12698,7 @@ time formatted in the same way as the @code{date} utility. @c @group @c file eg/lib/gettime.awk # gettimeofday --- get the time of day in a usable format -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain, May 1993 +# Arnold Robbins, arnold@@gnu.org, Public Domain, May 1993 # # Returns a string in the format of output of date(1) # Populates the array argument time with individual values: @@ -12732,7 +12806,7 @@ Besides solving the problem in only nine(!) lines of code, it does so # that each take the name of the file being started or # finished, respectively. # -# Arnold Robbins, arnold@@gnu.ai.mit.edu, January 1992 +# Arnold Robbins, arnold@@gnu.org, January 1992 # Public Domain FILENAME != _oldfilename \ @@ -12784,7 +12858,7 @@ This version solves the problem. # # user supplies beginfile() and endfile() functions # -# Arnold Robbins, arnold@@gnu.ai.mit.edu. November 1992 +# Arnold Robbins, arnold@@gnu.org, November 1992 # Public Domain FNR == 1 @{ @@ -12929,7 +13003,7 @@ The discussion walks through the code a bit at a time. @c file eg/lib/getopt.awk # getopt --- do C library getopt(3) function in awk # -# arnold@@gnu.ai.mit.edu +# arnold@@gnu.org # Public domain # # Initial version: March, 1991 @@ -13206,7 +13280,7 @@ Here is @code{pwcat}, a C program that ``cats'' the password database. * Generate a printable version of the password database * * Arnold Robbins - * arnold@@gnu.ai.mit.edu + * arnold@@gnu.org * May 1993 * Public Domain */ @@ -13289,7 +13363,7 @@ functions of the same name. @c file eg/lib/passwdawk.in @group # passwd.awk --- access password file information -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 BEGIN @{ @@ -13477,7 +13551,7 @@ Here is @code{grcat}, a C program that ``cats'' the group database. * * Generate a printable version of the group database * - * Arnold Robbins, arnold@@gnu.ai.mit.edu + * Arnold Robbins, arnold@@gnu.org * May 1993 * Public Domain */ @@ -13558,7 +13632,7 @@ There are several, modeled after the C library functions of the same names. @group @c file eg/lib/groupawk.in # group.awk --- functions for dealing with the group file -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 BEGIN \ @@ -13725,7 +13799,7 @@ user name, and returns the list of groups that have the user as a member. function getgrent() @{ _gr_init() - if (++gr_count in _gr_bycount) + if (++_gr_count in _gr_bycount) return _gr_bycount[_gr_count] return "" @} @@ -13947,7 +14021,7 @@ if invalid arguments are supplied. @c @group @c file eg/prog/cut.awk # cut.awk --- implement cut in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # Options: @@ -14275,7 +14349,7 @@ that processes the command line arguments with @code{getopt}. The @samp{-i} @c @group @c file eg/prog/egrep.awk # egrep.awk --- simulate egrep in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # Options: @@ -14558,7 +14632,7 @@ numbers. @c @group @c file eg/prog/id.awk # id.awk --- implement id in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # output is: @@ -14670,7 +14744,7 @@ is used as the prefix for the output file names. @c @group @c file eg/prog/split.awk # split.awk --- do split in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # usage: split [-num] [file] [outname] @@ -14798,7 +14872,7 @@ Finally, @code{awk} is forced to read the standard input by setting @group @c file eg/prog/tee.awk # tee.awk --- tee in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # Revised December 1995 @end group @@ -14961,7 +15035,7 @@ standard output, @file{/dev/stdout}. @c @group @c file eg/prog/uniq.awk # uniq.awk --- do uniq in awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 @group @@ -15197,7 +15271,7 @@ be true if more than one file was named on the command line. @c @group @c file eg/prog/wc.awk # wc.awk --- count lines, words, characters -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # Options: @@ -15354,7 +15428,7 @@ unusual. @group @c file eg/prog/dupword.awk # dupword --- find duplicate words in text -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # December 1991 @{ @@ -15398,7 +15472,7 @@ to itself, in case the user is not looking at their computer or terminal.) @c @group @c file eg/prog/alarm.awk # alarm --- set an alarm -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # usage: alarm time [ "message" [ count [ delay ] ] ] @@ -15585,7 +15659,7 @@ Finally, the processing rule simply calls @code{translate} for each record. @c @group @c file eg/prog/translate.awk # translate --- do tr like stuff -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # August 1989 # bugs: does not handle things like: tr A-Z a-z, it has @@ -15703,7 +15777,7 @@ not have been an even multiple of 20 labels in the data. @c @group @c file eg/prog/labels.awk # labels.awk -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # June 1992 # Program to print labels. Each label is 5 lines of data @@ -15919,7 +15993,7 @@ The @code{END} rule simply prints out the lines, in order. @group @c file eg/prog/histsort.awk # histsort.awk --- compact a shell history file -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 # Thanks to Byron Rakitzis for the general idea @@ -16016,6 +16090,28 @@ and @samp{endfile} lines. The @code{gawk} distribution uses a copy of @file{extract.awk} to extract the sample programs and install many of them in a standard directory, where @code{gawk} can find them. +The Texinfo file looks something like this: + +@example +@dots{} +This program has a @@code@{BEGIN@} block, +which prints a nice message: + +@@example +@@c file examples/messages.awk +BEGIN @@@{ print "Don't panic!" @@@} +@@c end file +@@end example + +It also prints some final advice: + +@@example +@@c file examples/messages.awk +END @@@{ print "Always avoid bored archeologists!" @@@} +@@c end file +@@end example +@dots{} +@end example @file{extract.awk} begins by setting @code{IGNORECASE} to one, so that mixed upper-case and lower-case letters in the directives won't matter. @@ -16030,7 +16126,7 @@ exited with a zero exit status, signifying OK. @c file eg/prog/extract.awk # extract.awk --- extract files and run programs # from texinfo files -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # May 1993 BEGIN @{ IGNORECASE = 1 @} @@ -16080,6 +16176,9 @@ function. If the line is an ``endfile'' line, then it breaks out of the loop. If the line is an @samp{@@group} or @samp{@@end group} line, then it ignores it, and goes on to the next line. +(These Texinfo control lines keep blocks of code together on one page; +unfortunately, @TeX{} isn't always smart enough to do things exactly right, +and we have to give it some advice.) Most of the work is in the following few lines. If the line has no @samp{@@} symbols, it can be printed directly. Otherwise, each leading @samp{@@} must be @@ -16213,7 +16312,7 @@ are provided, the standard input is used. # awksed.awk --- do s/foo/bar/g using just print # Thanks to Michael Brennan for the idea -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # August 1995 @group @@ -16447,7 +16546,7 @@ Here's the program: #! /bin/sh # igawk --- like gawk but do @@include processing -# Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain +# Arnold Robbins, arnold@@gnu.org, Public Domain # July 1993 if [ "$1" = debug ] @@ -18493,7 +18592,7 @@ Free Software Foundation @* Boston, MA 02111-1307 USA @* Phone: +1-617-542-5942 @* Fax (including Japan): +1-617-542-2652 @* -E-mail: @code{gnu@@prep.ai.mit.edu} @* +E-mail: @code{gnu@@gnu.org} @* @end quotation @noindent @@ -18502,7 +18601,7 @@ and to the production of more free software. @item You can get @code{gawk} by using anonymous @code{ftp} to the Internet host -@code{ftp.gnu.ai.mit.edu}, in the directory @file{/pub/gnu}. +@code{gnudist.gnu.org}, in the directory @file{/gnu/gawk}. Here is a list of alternate @code{ftp} sites from which you can obtain GNU software. When a site is listed as ``@var{site}@code{:}@var{directory}'' the @@ -19318,17 +19417,17 @@ can send mail to. @table @asis @item Internet: -@samp{bug-gnu-utils@@prep.ai.mit.edu} +@samp{bug-gnu-utils@@gnu.org} @item UUCP: -@samp{uunet!prep.ai.mit.edu!bug-gnu-utils} +@samp{uunet!gnu.org!bug-gnu-utils} @end table Please include the version number of @code{gawk} you are using. You can get this information with the command @samp{gawk --version}. You should send a carbon copy of your mail to Arnold Robbins, who can -be reached at @samp{arnold@@gnu.ai.mit.edu}. +be reached at @samp{arnold@@gnu.org}. @cindex @code{comp.lang.awk} @strong{Important!} Do @emph{not} try to report bugs in @code{gawk} by @@ -19408,13 +19507,15 @@ This section briefly describes where to get them. @item Unix @code{awk} Brian Kernighan has been able to make his implementation of @code{awk} freely available. You can get it via anonymous @code{ftp} -to the host @code{@w{netlib.att.com}}. Change directory to +to the host @code{@w{netlib.bell-labs.com}}. Change directory to @file{/netlib/research}. Use ``binary'' or ``image'' mode, and -retrieve @file{awk.bundle.Z}. +retrieve @file{awk.bundle.gz}. + +This is a shell archive that has been compressed with the GNU @code{gzip} +utility. It can be uncompressed with the @code{gunzip} utility. -This is a shell archive that has been compressed with the @code{compress} -utility. It can be uncompressed with either @code{uncompress} or the -GNU @code{gunzip} utility. +You can also retrieve this version via the World Wide Web from +@uref{http://cm.bell-labs.com/who/bwk, Brian Kernighan's home page}. This version requires an ANSI C compiler; GCC (the GNU C compiler) works quite nicely. @@ -19496,7 +19597,7 @@ and any considerations you should bear in mind. You are free to add any new features you like to @code{gawk}. However, if you want your changes to be incorporated into the @code{gawk} distribution, there are several steps that you need to take in order to -make it possible for me to include to your changes. +make it possible for me to include your changes. @enumerate 1 @item @@ -19598,7 +19699,7 @@ effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do, and @emph{many} people have done so already. If you have questions, please contact me (@pxref{Bugs, , Reporting Problems and Bugs}), -or @code{gnu@@prep.ai.mit.edu}. +or @code{gnu@@gnu.org}. @item Update the documentation. @@ -19718,7 +19819,7 @@ effect, or assign the copyright in your code to the FSF. @ifinfo Both of these actions are easy to do, and @emph{many} people have done so already. If you have questions, please contact me, or -@code{gnu@@prep.ai.mit.edu}. +@code{gnu@@gnu.org}. @end ifinfo @end enumerate @@ -19855,11 +19956,6 @@ important regexp matching issues. The GNU version of @code{malloc} could potentially speed up @code{gawk}, since it relies heavily on the use of dynamic memory allocation. -@item Use of the @code{rx} regexp library -The @code{rx} regular expression library could potentially speed up -all regexp operations that require knowing the exact location of matches. -This includes record termination, field and array splitting, -and the @code{sub}, @code{gsub}, @code{gensub} and @code{match} functions. @end table @node Improvements, , Future Extensions, Notes @@ -20006,7 +20102,7 @@ countries use an extension of ASCII known as ISO-8859-1 (ISO Latin-1). A preprocessor for @code{pic} that reads descriptions of molecules and produces @code{pic} input for drawing them. It was written in @code{awk} by Brian Kernighan and Jon Bentley, and is available from -@code{@w{netlib@@research.att.com}}. +@email{@w{netlib@@research.bell-labs.com}}. @item Compound Statement A series of @code{awk} statements, enclosed in curly braces. Compound diff --git a/doc/igawk.1 b/doc/igawk.1 index b3e19c20..30ca853c 100644 --- a/doc/igawk.1 +++ b/doc/igawk.1 @@ -70,4 +70,4 @@ igawk \-f test.awk Edition 1.0, published by the Free Software Foundation, 1995. .SH AUTHOR Arnold Robbins -.RB ( arnold@gnu.ai.mit.edu ). +.RB ( arnold@gnu.org ). diff --git a/doc/no.colors b/doc/no.colors index 4e0d0c62..974f985b 100644 --- a/doc/no.colors +++ b/doc/no.colors @@ -1,4 +1,4 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" This file is for troff which does not know what to do .\" with a literal Poscript and cannot use macros from 'colors'. .\" diff --git a/doc/texinfo.tex b/doc/texinfo.tex index f9254e77..3ce47154 100644 --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -1,32 +1,40 @@ -%% TeX macros to handle Texinfo files. -%% $Id: texinfo.tex,v 2.193 1996/11/19 21:11:43 karl Exp $ - -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, -% 94, 95, 1996 Free Software Foundation, Inc. - -%This texinfo.tex file is free software; you can redistribute it and/or -%modify it under the terms of the GNU General Public License as -%published by the Free Software Foundation; either version 2, or (at -%your option) any later version. - -%This texinfo.tex file is distributed in the hope that it will be -%useful, but WITHOUT ANY WARRANTY; without even the implied warranty -%of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -%General Public License for more details. - -%You should have received a copy of the GNU General Public License -%along with this texinfo.tex file; see the file COPYING. If not, write -%to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, -%Boston, MA 02111-1307, USA. - - -%In other words, you are welcome to use, share and improve this program. -%You are forbidden to forbid anyone else to use, share and improve -%what you give them. Help stamp out software-hoarding! - - -% Send bug reports to bug-texinfo@prep.ai.mit.edu. -% Please include a *precise* test case in each bug report. +% texinfo.tex -- TeX macros to handle Texinfo files. +% $Id: texinfo.tex,v 2.227 1998/02/25 22:54:34 karl Exp $ +% +% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98 +% Free Software Foundation, Inc. +% +% This texinfo.tex file is free software; you can redistribute it and/or +% modify it under the terms of the GNU General Public License as +% published by the Free Software Foundation; either version 2, or (at +% your option) any later version. +% +% This texinfo.tex file is distributed in the hope that it will be +% useful, but WITHOUT ANY WARRANTY; without even the implied warranty +% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this texinfo.tex file; see the file COPYING. If not, write +% to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +% Boston, MA 02111-1307, USA. +% +% In other words, you are welcome to use, share and improve this program. +% You are forbidden to forbid anyone else to use, share and improve +% what you give them. Help stamp out software-hoarding! +% +% Please try the latest version of texinfo.tex before submitting bug +% reports; you can get the latest version from: +% ftp://ftp.cs.umb.edu/pub/tex/texinfo.tex +% /home/gd/gnu/doc/texinfo.tex on the GNU machines. +% +% Send bug reports to bug-texinfo@gnu.org. +% Please include a precise test case in each bug report, +% including a complete document with which we can reproduce the problem. +% +% Texinfo macros (with @macro) are *not* supported by texinfo.tex. You +% have to run makeinfo -E to expand macros first; the texi2dvi script +% does this. % Make it possible to create a .fmt file just by loading this file: @@ -36,7 +44,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 2.193 $ +\deftexinfoversion$Revision: 2.227 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -54,13 +62,13 @@ \let\ptexdot=\. \let\ptexdots=\dots \let\ptexend=\end -\let\ptexequiv = \equiv +\let\ptexequiv=\equiv +\let\ptexexclam=\! \let\ptexi=\i \let\ptexlbrace=\{ \let\ptexrbrace=\} \let\ptexstar=\* \let\ptext=\t -\let\ptextilde=\~ % Be sure we're in horizontal mode when doing a tie, since we make space % equivalent to this in @example-like environments. Otherwise, a space @@ -73,7 +81,6 @@ \global\let\tiepenalty = \@M \gdef\tie{\leavevmode\penalty\tiepenalty\ } } -\let\~ = \tie % And make it available as @~. \message{Basics,} @@ -103,10 +110,11 @@ \hyphenation{ap-pen-dix} \hyphenation{mini-buf-fer mini-buf-fers} \hyphenation{eshell} +\hyphenation{white-space} % Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset -\newdimen \normaloffset +\newdimen \bindingoffset +\newdimen \normaloffset \newdimen\pagewidth \newdimen\pageheight % Sometimes it is convenient to have everything in the transcript file @@ -120,33 +128,37 @@ \showboxbreadth\maxdimen\showboxdepth\maxdimen }% -%---------------------Begin change----------------------- +% For @cropmarks command. +% Do @cropmarks to get crop marks. +% +\newif\ifcropmarks +\let\cropmarks = \cropmarkstrue % -%%%% For @cropmarks command. -% Dimensions to add cropmarks at corners Added by P. A. MacKay, 12 Nov. 1986 +% Dimensions to add cropmarks at corners. +% Added by P. A. MacKay, 12 Nov. 1986 % \newdimen\cornerlong \newdimen\cornerthick -\newdimen \topandbottommargin -\newdimen \outerhsize \newdimen \outervsize +\newdimen\topandbottommargin +\newdimen\outerhsize \newdimen\outervsize \cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks \outerhsize=7in %\outervsize=9.5in % Alternative @smallbook page size is 9.25in \outervsize=9.25in \topandbottommargin=.75in -% -%---------------------End change----------------------- % Main output routine. \chardef\PAGE = 255 \output = {\onepageout{\pagecontents\PAGE}} -\newbox\headlinebox \newbox\footlinebox +\newbox\headlinebox +\newbox\footlinebox % \onepageout takes a vbox as an argument. Note that \pagecontents % does insertions, but you have to call it yourself. \def\onepageout#1{% - \hoffset=\normaloffset + \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi + % \ifodd\pageno \advance\hoffset by \bindingoffset \else \advance\hoffset by -\bindingoffset\fi % @@ -165,53 +177,52 @@ \normalturnoffactive % \ in index entries must not stay \, e.g., if % the page break happens to be in the middle of an example. \shipout\vbox{% + \ifcropmarks \vbox to \outervsize\bgroup + \hsize = \outerhsize + \line{\ewtop\hfil\ewtop}% + \nointerlineskip + \line{% + \vbox{\moveleft\cornerthick\nstop}% + \hfill + \vbox{\moveright\cornerthick\nstop}% + }% + \vskip\topandbottommargin + \line\bgroup + \hfil % center the page within the outer (page) hsize. + \ifodd\pageno\hskip\bindingoffset\fi + \vbox\bgroup + \fi + % \unvbox\headlinebox \pagebody{#1}% - \unvbox\footlinebox - }% - }% + \ifdim\ht\footlinebox > 0pt + % Only leave this space if the footline is nonempty. + % (We lessened \vsize for it in \oddfootingxxx.) + % The \baselineskip=24pt in plain's \makefootline has no effect. + \vskip 2\baselineskip + \unvbox\footlinebox + \fi + % + \ifcropmarks + \egroup % end of \vbox\bgroup + \hfil\egroup % end of (centering) \line\bgroup + \vskip\topandbottommargin plus1fill minus1fill + \boxmaxdepth = \cornerthick + \line{% + \vbox{\moveleft\cornerthick\nsbot}% + \hfill + \vbox{\moveright\cornerthick\nsbot}% + }% + \nointerlineskip + \line{\ewbot\hfil\ewbot}% + \egroup % \vbox from first cropmarks clause + \fi + }% end of \shipout\vbox + }% end of group with \turnoffactive \advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi } -%%%% For @cropmarks command %%%% - -% Here is a modification of the main output routine for Near East Publications -% This provides right-angle cropmarks at all four corners. -% The contents of the page are centerlined into the cropmarks, -% and any desired binding offset is added as an \hskip on either -% site of the centerlined box. (P. A. MacKay, 12 November, 1986) -% -\def\croppageout#1{\hoffset=0pt % make sure this doesn't mess things up -{\escapechar=`\\\relax % makes sure backslash is used in output files. - \shipout - \vbox to \outervsize{\hsize=\outerhsize - \vbox{\line{\ewtop\hfill\ewtop}} - \nointerlineskip - \line{\vbox{\moveleft\cornerthick\nstop} - \hfill - \vbox{\moveright\cornerthick\nstop}} - \vskip \topandbottommargin - \centerline{\ifodd\pageno\hskip\bindingoffset\fi - \vbox{ - {\let\hsize=\pagewidth \makeheadline} - \pagebody{#1} - {\let\hsize=\pagewidth \makefootline}} - \ifodd\pageno\else\hskip\bindingoffset\fi} - \vskip \topandbottommargin plus1fill minus1fill - \boxmaxdepth\cornerthick - \line{\vbox{\moveleft\cornerthick\nsbot} - \hfill - \vbox{\moveright\cornerthick\nsbot}} - \nointerlineskip - \vbox{\line{\ewbot\hfill\ewbot}} - }} - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi} -% -% Do @cropmarks to get crop marks -\def\cropmarks{\let\onepageout=\croppageout } - \newinsert\margin \dimen\margin=\maxdimen \def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} @@ -225,7 +236,6 @@ \ifr@ggedbottom \kern-\dimen@ \vfil \fi} } -% % Here are the rules for the cropmarks. Note that they are % offset so that the space between them is truly \outerhsize or \outervsize % (P. A. MacKay, 12 November, 1986) @@ -440,14 +450,11 @@ % @. is an end-of-sentence period. \def\.{.\spacefactor=3000 } -% @enddots{} is an end-of-sentence ellipsis. -\gdef\enddots{$\mathinner{\ldotp\ldotp\ldotp\ldotp}$\spacefactor=3000} - % @! is an end-of-sentence bang. -\gdef\!{!\spacefactor=3000 } +\def\!{!\spacefactor=3000 } % @? is an end-of-sentence query. -\gdef\?{?\spacefactor=3000 } +\def\?{?\spacefactor=3000 } % @w prevents a word break. Without the \leavevmode, @w at the % beginning of a paragraph, when TeX is still in vertical mode, would @@ -572,9 +579,27 @@ where each line of input produces a line of output.} \let\br = \par -% @dots{} output some dots +% @dots{} output an ellipsis using the current font. +% We do .5em per period so that it has the same spacing in a typewriter +% font as three actual period characters. +% +\def\dots{\hbox to 1.5em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil +}} + +% @enddots{} is an end-of-sentence ellipsis. +% +\def\enddots{% + \hbox to 2em{% + \hskip 0pt plus 0.25fil minus 0.25fil + .\hss.\hss.\hss.% + \hskip 0pt plus 0.5fil minus 0.5fil + }% + \spacefactor=3000 +} -\def\dots{$\ldots$} % @page forces the start of a new page @@ -735,10 +760,11 @@ where each line of input produces a line of output.} % \def\ignore{\doignore{ignore}} -% Also ignore @ifinfo, @ifhtml, @html, @menu, and @direntry text. +% Ignore @ifinfo, @ifhtml, @ifnottex, @html, @menu, and @direntry text. % \def\ifinfo{\doignore{ifinfo}} \def\ifhtml{\doignore{ifhtml}} +\def\ifnottex{\doignore{ifnottex}} \def\html{\doignore{html}} \def\menu{\doignore{menu}} \def\direntry{\doignore{direntry}} @@ -765,6 +791,10 @@ where each line of input produces a line of output.} % Make sure that spaces turn into tokens that match what \doignoretext wants. \catcode32 = 10 % + % Ignore braces, too, so mismatched braces don't cause trouble. + \catcode`\{ = 9 + \catcode`\} = 9 + % % And now expand that command. \doignoretext } @@ -856,7 +886,7 @@ where each line of input produces a line of output.} \pretolerance = 10000 % % Do not execute instructions in @tex - \def\tex{\doignore{tex}} + \def\tex{\doignore{tex}}% } % @set VAR sets the variable VAR to an empty value. @@ -932,11 +962,16 @@ where each line of input produces a line of output.} \def\ifclearfail{\nestedignore{ifclear}} \defineunmatchedend{ifclear} -% @iftex always succeeds; we read the text following, through @end -% iftex). But `@end iftex' should be valid only after an @iftex. +% @iftex, @ifnothtml, @ifnotinfo always succeed; we read the text +% following, through the first @end iftex (etc.). Make `@end iftex' +% (etc.) valid only after an @iftex. % \def\iftex{\conditionalsucceed{iftex}} +\def\ifnothtml{\conditionalsucceed{ifnothtml}} +\def\ifnotinfo{\conditionalsucceed{ifnotinfo}} \defineunmatchedend{iftex} +\defineunmatchedend{ifnothtml} +\defineunmatchedend{ifnotinfo} % We can't just want to start a group at @iftex (for example) and end it % at @end iftex, since then @set commands inside the conditional have no @@ -1012,6 +1047,15 @@ where each line of input produces a line of output.} \openindices \fixbackslash % Turn off hack to swallow `\input texinfo'. \global\let\setfilename=\comment % Ignore extra @setfilename cmds. + % + % If texinfo.cnf is present on the system, read it. + % Useful for site-wide @afourpaper, etc. + % Just to be on the safe side, close the input stream before the \input. + \openin 1 texinfo.cnf + \ifeof1 \let\temp=\relax \else \def\temp{\input texinfo.cnf }\fi + \closein1 + \temp + % \comment % Ignore the actual filename. } @@ -1047,8 +1091,9 @@ where each line of input produces a line of output.} % We don't need math for this one. \def\ttsl{\tenttsl} -%% Try out Computer Modern fonts at \magstephalf -\let\mainmagstep=\magstephalf +% Use Computer Modern fonts at \magstephalf (11pt). +\newcount\mainmagstep +\mainmagstep=\magstephalf % Set the font macro #1 to the font named #2, adding on the % specified font prefix (normally `cm'). @@ -1120,13 +1165,26 @@ where each line of input produces a line of output.} \font\indi=cmmi9 \font\indsy=cmsy9 +% Fonts for title page: +\setfont\titlerm\rmbshape{12}{\magstep3} +\setfont\titleit\itbshape{10}{\magstep4} +\setfont\titlesl\slbshape{10}{\magstep4} +\setfont\titlett\ttbshape{12}{\magstep3} +\setfont\titlettsl\ttslshape{10}{\magstep4} +\setfont\titlesf\sfbshape{17}{\magstep1} +\let\titlebf=\titlerm +\setfont\titlesc\scbshape{10}{\magstep4} +\font\titlei=cmmi12 scaled \magstep3 +\font\titlesy=cmsy10 scaled \magstep4 +\def\authorrm{\secrm} + % Chapter (and unnumbered) fonts (17.28pt). \setfont\chaprm\rmbshape{12}{\magstep2} \setfont\chapit\itbshape{10}{\magstep3} \setfont\chapsl\slbshape{10}{\magstep3} \setfont\chaptt\ttbshape{12}{\magstep2} \setfont\chapttsl\ttslshape{10}{\magstep3} -\setfont\chapsf\sfbshape{12}{\magstep2} +\setfont\chapsf\sfbshape{17}{1000} \let\chapbf=\chaprm \setfont\chapsc\scbshape{10}{\magstep3} \font\chapi=cmmi12 scaled \magstep2 @@ -1163,19 +1221,15 @@ where each line of input produces a line of output.} \setfont\ssecit\itbshape{10}{1315} \setfont\ssecsl\slbshape{10}{1315} \setfont\ssectt\ttbshape{12}{\magstephalf} -\setfont\ssecttsl\ttslshape{10}{\magstep1} +\setfont\ssecttsl\ttslshape{10}{1315} \setfont\ssecsf\sfbshape{12}{\magstephalf} \let\ssecbf\ssecrm \setfont\ssecsc\scbshape{10}{\magstep1} \font\sseci=cmmi12 scaled \magstephalf -\font\ssecsy=cmsy10 scaled \magstep1 +\font\ssecsy=cmsy10 scaled 1315 % The smallcaps and symbol fonts should actually be scaled \magstep1.5, % but that is not a standard magnification. -% Fonts for title page: -\setfont\titlerm\rmbshape{12}{\magstep3} -\let\authorrm = \secrm - % In order for the font changes to affect most math symbols and letters, % we have to define the \textfont of the standard families. Since % texinfo doesn't allow for producing subscripts and superscripts, we @@ -1200,6 +1254,13 @@ where each line of input produces a line of output.} \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl \resetmathfonts} +\def\titlefonts{% + \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl + \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc + \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy + \let\tenttsl=\titlettsl + \resetmathfonts \setleading{25pt}} +\def\titlefont#1{{\titlefonts\rm #1}} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc @@ -1226,6 +1287,10 @@ where each line of input produces a line of output.} % \textfonts +% Define these so they can be easily changed for other fonts. +\def\angleleft{$\langle$} +\def\angleright{$\rangle$} + % Count depth in font-changes, for error checks \newcount\fontdepth \fontdepth=0 @@ -1263,22 +1328,20 @@ where each line of input produces a line of output.} \null } \let\ttfont=\t -\def\samp #1{`\tclose{#1}'\null} +\def\samp#1{`\tclose{#1}'\null} \setfont\smallrm\rmshape{8}{1000} \font\smallsy=cmsy9 \def\key#1{{\smallrm\textfont2=\smallsy \leavevmode\hbox{% - \raise0.4pt\hbox{$\langle$}\kern-.08em\vtop{% + \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% \vbox{\hrule\kern-0.4pt - \hbox{\raise0.4pt\hbox{\vphantom{$\langle$}}#1}}% + \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% \kern-0.4pt\hrule}% - \kern-.06em\raise0.4pt\hbox{$\rangle$}}}} + \kern-.06em\raise0.4pt\hbox{\angleright}}}} % The old definition, with no lozenge: %\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} \def\ctrl #1{{\tt \rawbackslash \hat}#1} \let\file=\samp -\let\url=\samp % perhaps include a hypertex \special eventually -\def\email#1{$\langle${\tt #1}$\rangle$} % @code is a modification of @t, % which makes spaces the same size as normal in the surrounding text. @@ -1331,25 +1394,69 @@ where each line of input produces a line of output.} \def\realdash{-} \def\codedash{-\discretionary{}{}{}} -\def\codeunder{\normalunderscore\discretionary{}{}{}} +\def\codeunder{\ifusingtt{\normalunderscore\discretionary{}{}{}}{\_}} \def\codex #1{\tclose{#1}\endgroup} %\let\exp=\tclose %Was temporary % @kbd is like @code, except that if the argument is just one @key command, % then @kbd has no effect. -% + +% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), +% `example' (@kbd uses ttsl only inside of @example and friends), +% or `code' (@kbd uses normal tty font always). +\def\kbdinputstyle{\parsearg\kbdinputstylexxx} +\def\kbdinputstylexxx#1{% + \def\arg{#1}% + \ifx\arg\worddistinct + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% + \else\ifx\arg\wordexample + \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% + \else\ifx\arg\wordcode + \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \fi\fi\fi +} +\def\worddistinct{distinct} +\def\wordexample{example} +\def\wordcode{code} + +% Default is kbdinputdistinct. (Too much of a hassle to call the macro, +% the catcodes are wrong for parsearg to work.) +\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl} + \def\xkey{\key} \def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% \ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\ttsl\look}}\fi -\else{\tclose{\ttsl\look}}\fi} +\else{\tclose{\kbdfont\look}}\fi +\else{\tclose{\kbdfont\look}}\fi} + +% @url. Quotes do not seem necessary, so use \code. +\let\url=\code + +% @uref (abbreviation for `urlref') takes an optional second argument +% specifying the text to display. First (mandatory) arg is the url. +% Perhaps eventually put in a hypertex \special here. +% +\def\uref#1{\urefxxx #1,,\finish} +\def\urefxxx#1,#2,#3\finish{% + \setbox0 = \hbox{\ignorespaces #2}% + \ifdim\wd0 > 0pt + \unhbox0\ (\code{#1})% + \else + \code{#1}% + \fi +} + +% rms does not like the angle brackets --karl, 17may97. +% So now @email is just like @uref. +%\def\email#1{\angleleft{\tt #1}\angleright} +\let\email=\uref % Check if we are currently using a typewriter font. Since all the % Computer Modern typewriter fonts have zero interword stretch (and % shrink), and it is reasonable to expect all typewriter fonts to have % this property, we can check that font parameter. -% +% \def\ifmonospace{\ifdim\fontdimen3\font=0pt } % Typeset a dimension, e.g., `in' or `pt'. The only reason for the @@ -1380,8 +1487,6 @@ where each line of input produces a line of output.} \newskip\titlepagebottomglue \titlepagebottomglue = 2pc % First the title page. Must do @settitle before @titlepage. -\def\titlefont#1{{\titlerm #1}} - \newif\ifseenauthor \newif\iffinishedtitlepage @@ -1403,7 +1508,7 @@ where each line of input produces a line of output.} % % Now you can print the title using @title. \def\title{\parsearg\titlezzz}% - \def\titlezzz##1{\leftline{\titlefont{##1}} + \def\titlezzz##1{\leftline{\titlefonts\rm ##1} % print a rule at the page bottom also. \finishedtitlepagefalse \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% @@ -1492,10 +1597,7 @@ where each line of input produces a line of output.} \gdef\oddheadingyyy #1@|#2@|#3@|#4\finish{% \global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} -\gdef\everyheadingxxx #1{\everyheadingyyy #1@|@|@|@|\finish} -\gdef\everyheadingyyy #1@|#2@|#3@|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +\gdef\everyheadingxxx#1{\oddheadingxxx{#1}\evenheadingxxx{#1}}% \gdef\evenfootingxxx #1{\evenfootingyyy #1@|@|@|@|\finish} \gdef\evenfootingyyy #1@|#2@|#3@|#4\finish{% @@ -1503,12 +1605,15 @@ where each line of input produces a line of output.} \gdef\oddfootingxxx #1{\oddfootingyyy #1@|@|@|@|\finish} \gdef\oddfootingyyy #1@|#2@|#3@|#4\finish{% -\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% + % + % Leave some space for the footline. Hopefully ok to assume + % @evenfooting will not be used by itself. + \global\advance\pageheight by -\baselineskip + \global\advance\vsize by -\baselineskip +} -\gdef\everyfootingxxx #1{\everyfootingyyy #1@|@|@|@|\finish} -\gdef\everyfootingyyy #1@|#2@|#3@|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}} -\global\oddfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} +\gdef\everyfootingxxx#1{\oddfootingxxx{#1}\evenfootingxxx{#1}} % }% unbind the catcode of @. @@ -1892,7 +1997,7 @@ July\or August\or September\or October\or November\or December\fi \def\itemizeitem{% \advance\itemno by 1 {\let\par=\endgraf \smallbreak}% -\ifhmode \errmessage{\in hmode at itemizeitem}\fi +\ifhmode \errmessage{In hmode at itemizeitem}\fi {\parskip=0in \hskip 0pt \hbox to 0pt{\hss \itemcontents\hskip \itemmargin}% \vadjust{\penalty 1200}}% @@ -1910,7 +2015,7 @@ July\or August\or September\or October\or November\or December\fi % To make preamble: % -% Either define widths of columns in terms of percent of \hsize: +% Either define widths of columns in terms of percent of \hsize: % @multitable @columnfractions .25 .3 .45 % @item ... % @@ -1928,13 +2033,13 @@ July\or August\or September\or October\or November\or December\fi % the preamble, break the line within one argument and it % will parse correctly, i.e., % -% @multitable {Column 1 template} {Column 2 template} {Column 3 +% @multitable {Column 1 template} {Column 2 template} {Column 3 % template} % Not: -% @multitable {Column 1 template} {Column 2 template} +% @multitable {Column 1 template} {Column 2 template} % {Column 3 template} -% Each new table line starts with @item, each subsequent new column +% Each new table line starts with @item, each subsequent new column % starts with @tab. Empty columns may be produced by supplying @tab's % with nothing between them for as many times as empty columns are needed, % ie, @tab@tab@tab will produce two empty columns. @@ -1946,15 +2051,15 @@ July\or August\or September\or October\or November\or December\fi % @multitable {Column 1 template} {Column 2 template} {Column 3 template} % @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff +% @item +% first col stuff +% @tab +% second col stuff +% @tab +% third col +% @item first col stuff @tab second col stuff % @tab Many paragraphs of text may be used in any column. -% +% % They will wrap at the width determined by the template. % @item@tab@tab This will be in third column. % @end multitable @@ -1966,10 +2071,7 @@ July\or August\or September\or October\or November\or December\fi % @multitablelinespace is space to leave between table items, baseline % to baseline. % 0pt means it depends on current normal line spacing. - -%%%% -% Dimensions - +% \newskip\multitableparskip \newskip\multitableparindent \newdimen\multitablecolspace @@ -1979,15 +2081,15 @@ July\or August\or September\or October\or November\or December\fi \multitablecolspace=12pt \multitablelinespace=0pt -%%%% % Macros used to set up halign preamble: +% \let\endsetuptable\relax \def\xendsetuptable{\endsetuptable} \let\columnfractions\relax \def\xcolumnfractions{\columnfractions} \newif\ifsetpercent -%% 2/1/96, to allow fractions to be given with more than one digit. +% 2/1/96, to allow fractions to be given with more than one digit. \def\pickupwholefraction#1 {\global\advance\colcount by1 % \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% \setuptable} @@ -2013,80 +2115,84 @@ July\or August\or September\or October\or November\or December\fi \ifx\go\pickupwholefraction\else\let\go\setuptable\fi% \fi\go} -%%%% % multitable syntax \def\tab{&\hskip1sp\relax} % 2/2/96 % tiny skip here makes sure this column space is % maintained, even if it is never used. - -%%%% % @multitable ... @end multitable definitions: \def\multitable{\parsearg\dotable} - \def\dotable#1{\bgroup -\let\item\cr -\tolerance=9500 -\hbadness=9500 -\setmultitablespacing -\parskip=\multitableparskip -\parindent=\multitableparindent -\overfullrule=0pt -\global\colcount=0\relax% -\def\Emultitable{\global\setpercentfalse\global\everycr{}\cr\egroup\egroup}% - % To parse everything between @multitable and @item : -\setuptable#1 \endsetuptable - % Need to reset this to 0 after \setuptable. -\global\colcount=0\relax% - % - % This preamble sets up a generic column definition, which will - % be used as many times as user calls for columns. - % \vtop will set a single line and will also let text wrap and - % continue for many paragraphs if desired. -\halign\bgroup&\global\advance\colcount by 1\relax% -\multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % If user has set preamble in terms of percent of \hsize - % we will use that dimension as the width of the column, and - % the \leftskip will keep entries from bumping into each other. - % Table will start at left margin and final column will justify at - % right margin. -\ifnum\colcount=1 -\else - \ifsetpercent + \vskip\parskip + \let\item\crcr + \tolerance=9500 + \hbadness=9500 + \setmultitablespacing + \parskip=\multitableparskip + \parindent=\multitableparindent + \overfullrule=0pt + \global\colcount=0 + \def\Emultitable{\global\setpercentfalse\cr\egroup\egroup}% + % + % To parse everything between @multitable and @item: + \setuptable#1 \endsetuptable + % + % \everycr will reset column counter, \colcount, at the end of + % each line. Every column entry will cause \colcount to advance by one. + % The table preamble + % looks at the current \colcount to find the correct column width. + \everycr{\noalign{% + % + % \filbreak%% keeps underfull box messages off when table breaks over pages. + % Maybe so, but it also creates really weird page breaks when the table + % breaks over pages. Wouldn't \vfil be better? Wait until the problem + % manifests itself, so it can be fixed for real --karl. + \global\colcount=0\relax}}% + % + % This preamble sets up a generic column definition, which will + % be used as many times as user calls for columns. + % \vtop will set a single line and will also let text wrap and + % continue for many paragraphs if desired. + \halign\bgroup&\global\advance\colcount by 1\relax + \multistrut\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname + % + % In order to keep entries from bumping into each other + % we will add a \leftskip of \multitablecolspace to all columns after + % the first one. + % + % If a template has been used, we will add \multitablecolspace + % to the width of each template entry. + % + % If the user has set preamble in terms of percent of \hsize we will + % use that dimension as the width of the column, and the \leftskip + % will keep entries from bumping into each other. Table will start at + % left margin and final column will justify at right margin. + % + % Make sure we don't inherit \rightskip from the outer environment. + \rightskip=0pt + \ifnum\colcount=1 + % The first column will be indented with the surrounding text. + \advance\hsize by\leftskip \else - % If user has <not> set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace - \advance\hsize by \multitablecolspace + \ifsetpercent \else + % If user has not set preamble in terms of percent of \hsize + % we will advance \hsize by \multitablecolspace. + \advance\hsize by \multitablecolspace + \fi + % In either case we will make \leftskip=\multitablecolspace: + \leftskip=\multitablecolspace \fi - % In either case we will make \leftskip=\multitablecolspace: -\leftskip=\multitablecolspace -\fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighing sequences respectively marking - % characters. - \noindent\ignorespaces##\unskip\multistrut}\cr - % \everycr will reset column counter, \colcount, at the end of - % each line. Every column entry will cause \colcount to advance by one. - % The table preamble - % looks at the current \colcount to find the correct column width. -\global\everycr{\noalign{% -% \filbreak%% keeps underfull box messages off when table breaks over pages. -% Maybe so, but it also creates really weird page breaks when the table -% breaks over pages Wouldn't \vfil be better? Wait until the problem -% manifests itself, so it can be fixed for real --karl. -\global\colcount=0\relax}} + % Ignoring space at the beginning and end avoids an occasional spurious + % blank line, when TeX decides to break the line at the space before the + % box from the multistrut, so the strut ends up on a line by itself. + % For example: + % @multitable @columnfractions .11 .89 + % @item @code{#} + % @tab Legal holiday which is valid in major parts of the whole country. + % Is automatically provided with highlighting sequences respectively marking + % characters. + \noindent\ignorespaces##\unskip\multistrut}\cr } \def\setmultitablespacing{% test to see if user has set \multitablelinespace. @@ -2097,7 +2203,7 @@ July\or August\or September\or October\or November\or December\fi %% to keep lines equally spaced \let\multistrut = \strut %% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. +%% table. If not, do nothing. %% If so, set to same dimension as multitablelinespace. \else \gdef\multistrut{\vrule height\multitablelinespace depth\dp0 @@ -2232,7 +2338,13 @@ width0pt\relax} \fi %\def\char{\realbackslash char}% \def\TeX{\realbackslash TeX}% \def\dots{\realbackslash dots }% -\def\copyright{\realbackslash copyright }% +\def\result{\realbackslash result}% +\def\equiv{\realbackslash equiv}% +\def\expansion{\realbackslash expansion}% +\def\print{\realbackslash print}% +\def\error{\realbackslash error}% +\def\point{\realbackslash point}% +\def\copyright{\realbackslash copyright}% \def\tclose##1{\realbackslash tclose {##1}}% \def\code##1{\realbackslash code {##1}}% \def\dotless##1{\realbackslash dotless {##1}}% @@ -2242,6 +2354,7 @@ width0pt\relax} \fi \def\r##1{\realbackslash r {##1}}% \def\i##1{\realbackslash i {##1}}% \def\b##1{\realbackslash b {##1}}% +\def\sc##1{\realbackslash sc {##1}}% \def\cite##1{\realbackslash cite {##1}}% \def\key##1{\realbackslash key {##1}}% \def\file##1{\realbackslash file {##1}}% @@ -2249,6 +2362,7 @@ width0pt\relax} \fi \def\kbd##1{\realbackslash kbd {##1}}% \def\dfn##1{\realbackslash dfn {##1}}% \def\emph##1{\realbackslash emph {##1}}% +\def\value##1{\realbackslash value {##1}}% \unsepspaces } @@ -2413,29 +2527,23 @@ width0pt\relax} \fi % Define the macros used in formatting output of the sorted index material. -% This is what you call to cause a particular index to get printed. -% Write -% @unnumbered Function Index -% @printindex fn - +% @printindex causes a particular index (the ??s file) to get printed. +% It does not print any chapter heading (usually an @unnumbered). +% \def\printindex{\parsearg\doprintindex} - \def\doprintindex#1{\begingroup \dobreak \chapheadingskip{10000}% % \indexfonts \rm \tolerance = 9500 \indexbreaks - \def\indexbackslash{\rawbackslashxx}% - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \catcode`\\ = 0 - \catcode`\@ = 11 - \escapechar = `\\ - \begindoublecolumns % % See if the index file exists and is nonempty. + % Change catcode of @ here so that if the index file contains + % \initial {@} + % as its first line, TeX doesn't complain about mismatched braces + % (because it thinks @} is a control sequence). + \catcode`\@ = 11 \openin 1 \jobname.#1s \ifeof 1 % \enddoublecolumns gets confused if there is no text in the index, @@ -2452,11 +2560,18 @@ width0pt\relax} \fi \ifeof 1 (Index is empty) \else + % Index files are almost Texinfo source, but we use \ as the escape + % character. It would be better to use @, but that's too big a change + % to make right now. + \def\indexbackslash{\rawbackslashxx}% + \catcode`\\ = 0 + \escapechar = `\\ + \begindoublecolumns \input \jobname.#1s + \enddoublecolumns \fi \fi \closein 1 - \enddoublecolumns \endgroup} % These macros are used by the sorted index file itself. @@ -2558,24 +2673,39 @@ width0pt\relax} \fi \def\begindoublecolumns{\begingroup % ended by \enddoublecolumns % Grab any single-column material above us. - \output = {\global\setbox\partialpage - =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% + \output = {\global\setbox\partialpage = \vbox{% + % + % Here is a possibility not foreseen in manmac: if we accumulate a + % whole lot of material, we might end up calling this \output + % routine twice in a row (see the doublecol-lose test, which is + % essentially a couple of indexes with @setchapternewpage off). In + % that case, we must prevent the second \partialpage from + % simply overwriting the first, causing us to lose the page. + % This will preserve it until a real output routine can ship it + % out. Generally, \partialpage will be empty when this runs and + % this will be a no-op. + \unvbox\partialpage + % + % Unvbox the main output page. + \unvbox255 + \kern-\topskip \kern\baselineskip + }}% \eject % - % Now switch to the double-column output routine. - \output={\doublecolumnout}% + % Use the double-column output routine for subsequent pages. + \output = {\doublecolumnout}% % % Change the page size parameters. We could do this once outside this % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 % format, but then we repeat the same computation. Repeating a couple % of assignments once per index is clearly meaningless for the - % execution time, so we may as well do it once. + % execution time, so we may as well do it in one place. % % First we halve the line length, less a little for the gutter between % the columns. We compute the gutter based on the line length, so it % changes automatically with the paper format. The magic constant - % below is chosen so that the gutter has the same value (well, +- < - % 1pt) as it did when we hard-coded it. + % below is chosen so that the gutter has the same value (well, +-<1pt) + % as it did when we hard-coded it. % % We put the result in a separate register, \doublecolumhsize, so we % can restore it in \pagesofar, after \hsize itself has (potentially) @@ -2596,100 +2726,109 @@ width0pt\relax} \fi % (undoubled) page height minus any material left over from the % previous page. \dimen@=\pageheight \advance\dimen@ by-\ht\partialpage - % box0 will be the left-hand column, box1 the right. + % box0 will be the left-hand column, box2 the right. \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ \onepageout\pagesofar - \unvbox255 \penalty\outputpenalty + \unvbox255 + \penalty\outputpenalty } \def\pagesofar{% - % The contents of the output page -- any previous material, + % Re-output the contents of the output page -- any previous material, % followed by the two boxes we just split. \unvbox\partialpage \hsize = \doublecolumnhsize \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}% } \def\enddoublecolumns{% - \output={\balancecolumns}\eject % split what we have - \endgroup + \output = {\balancecolumns}\eject % split what we have + \endgroup % started in \begindoublecolumns + % % Back to normal single-column typesetting, but take account of the % fact that we just accumulated some stuff on the output page. - \pagegoal=\vsize + \pagegoal = \vsize } \def\balancecolumns{% - % Called on the last page of the double column material. - \setbox0=\vbox{\unvbox255}% + % Called at the end of the double column material. + \setbox0 = \vbox{\unvbox255}% \dimen@ = \ht0 \advance\dimen@ by \topskip \advance\dimen@ by-\baselineskip \divide\dimen@ by 2 \splittopskip = \topskip % Loop until we get a decent breakpoint. - {\vbadness=10000 \loop \global\setbox3=\copy0 + {\vbadness=10000 \loop + \global\setbox3=\copy0 \global\setbox1=\vsplit3 to\dimen@ - \ifdim\ht3>\dimen@ \global\advance\dimen@ by1pt \repeat}% + \ifdim\ht3>\dimen@ \global\advance\dimen@ by1pt + \repeat}% \setbox0=\vbox to\dimen@{\unvbox1}% \setbox2=\vbox to\dimen@{\unvbox3}% \pagesofar } -\catcode `\@=\other +\catcode`\@ = \other \message{sectioning,} % Define chapters, sections, etc. -\newcount \chapno -\newcount \secno \secno=0 -\newcount \subsecno \subsecno=0 -\newcount \subsubsecno \subsubsecno=0 +\newcount\chapno +\newcount\secno \secno=0 +\newcount\subsecno \subsecno=0 +\newcount\subsubsecno \subsubsecno=0 % This counter is funny since it counts through charcodes of letters A, B, ... -\newcount \appendixno \appendixno = `\@ +\newcount\appendixno \appendixno = `\@ \def\appendixletter{\char\the\appendixno} -\newwrite \contentsfile +\newwrite\contentsfile % This is called from \setfilename. -\def\opencontents{\openout \contentsfile = \jobname.toc} +\def\opencontents{\openout\contentsfile = \jobname.toc } % Each @chapter defines this as the name of the chapter. % page headings and footings can use it. @section does likewise \def\thischapter{} \def\thissection{} -\def\seccheck#1{\if \pageno<0 % -\errmessage{@#1 not allowed after generating table of contents}\fi -% -} +\def\seccheck#1{\ifnum \pageno<0 + \errmessage{@#1 not allowed after generating table of contents}% +\fi} \def\chapternofonts{% -\let\rawbackslash=\relax% -\let\frenchspacing=\relax% -\def\result{\realbackslash result} -\def\equiv{\realbackslash equiv} -\def\expansion{\realbackslash expansion} -\def\print{\realbackslash print} -\def\TeX{\realbackslash TeX} -\def\dots{\realbackslash dots} -\def\copyright{\realbackslash copyright} -\def\tt{\realbackslash tt} -\def\bf{\realbackslash bf } -\def\w{\realbackslash w} -\def\less{\realbackslash less} -\def\gtr{\realbackslash gtr} -\def\hat{\realbackslash hat} -\def\char{\realbackslash char} -\def\tclose##1{\realbackslash tclose {##1}} -\def\code##1{\realbackslash code {##1}} -\def\samp##1{\realbackslash samp {##1}} -\def\r##1{\realbackslash r {##1}} -\def\b##1{\realbackslash b {##1}} -\def\key##1{\realbackslash key {##1}} -\def\file##1{\realbackslash file {##1}} -\def\kbd##1{\realbackslash kbd {##1}} -% These are redefined because @smartitalic wouldn't work inside xdef. -\def\i##1{\realbackslash i {##1}} -\def\cite##1{\realbackslash cite {##1}} -\def\var##1{\realbackslash var {##1}} -\def\emph##1{\realbackslash emph {##1}} -\def\dfn##1{\realbackslash dfn {##1}} + \let\rawbackslash=\relax + \let\frenchspacing=\relax + \def\result{\realbackslash result}% + \def\equiv{\realbackslash equiv}% + \def\expansion{\realbackslash expansion}% + \def\print{\realbackslash print}% + \def\TeX{\realbackslash TeX}% + \def\dots{\realbackslash dots}% + \def\result{\realbackslash result}% + \def\equiv{\realbackslash equiv}% + \def\expansion{\realbackslash expansion}% + \def\print{\realbackslash print}% + \def\error{\realbackslash error}% + \def\point{\realbackslash point}% + \def\copyright{\realbackslash copyright}% + \def\tt{\realbackslash tt}% + \def\bf{\realbackslash bf}% + \def\w{\realbackslash w}% + \def\less{\realbackslash less}% + \def\gtr{\realbackslash gtr}% + \def\hat{\realbackslash hat}% + \def\char{\realbackslash char}% + \def\tclose##1{\realbackslash tclose{##1}}% + \def\code##1{\realbackslash code{##1}}% + \def\samp##1{\realbackslash samp{##1}}% + \def\r##1{\realbackslash r{##1}}% + \def\b##1{\realbackslash b{##1}}% + \def\key##1{\realbackslash key{##1}}% + \def\file##1{\realbackslash file{##1}}% + \def\kbd##1{\realbackslash kbd{##1}}% + % These are redefined because @smartitalic wouldn't work inside xdef. + \def\i##1{\realbackslash i{##1}}% + \def\cite##1{\realbackslash cite{##1}}% + \def\var##1{\realbackslash var{##1}}% + \def\emph##1{\realbackslash emph{##1}}% + \def\dfn##1{\realbackslash dfn{##1}}% } \newcount\absseclevel % used to calculate proper heading level @@ -2776,7 +2915,8 @@ width0pt\relax} \fi % because we don't want its macros evaluated now. \xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% {\chapternofonts% -\edef\temp{{\realbackslash chapentry {#1}{\the\chapno}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash chapentry{\the\toks0}{\the\chapno}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \donoderef % @@ -2795,8 +2935,9 @@ width0pt\relax} \fi \gdef\thischaptername{#1}% \xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% {\chapternofonts% -\edef\temp{{\realbackslash chapentry - {#1}{\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash chapentry{\the\toks0}% + {\putwordAppendix{} \appendixletter}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \appendixnoderef % @@ -2830,7 +2971,8 @@ width0pt\relax} \fi \unnumbchapmacro {#1}% \gdef\thischapter{#1}\gdef\thissection{#1}% {\chapternofonts% -\edef\temp{{\realbackslash unnumbchapentry {#1}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbchapentry{\the\toks0}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \unnumbnoderef % @@ -2845,8 +2987,9 @@ width0pt\relax} \fi \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % \gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% {\chapternofonts% +\toks0 = {#1}% \edef\temp{{\realbackslash secentry % -{#1}{\the\chapno}{\the\secno}{\noexpand\folio}}}% +{\the\toks0}{\the\chapno}{\the\secno}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \donoderef % @@ -2860,8 +3003,9 @@ width0pt\relax} \fi \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % \gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% {\chapternofonts% +\toks0 = {#1}% \edef\temp{{\realbackslash secentry % -{#1}{\appendixletter}{\the\secno}{\noexpand\folio}}}% +{\the\toks0}{\appendixletter}{\the\secno}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \appendixnoderef % @@ -2873,7 +3017,8 @@ width0pt\relax} \fi \def\unnumberedseczzz #1{\seccheck{unnumberedsec}% \plainsecheading {#1}\gdef\thissection{#1}% {\chapternofonts% -\edef\temp{{\realbackslash unnumbsecentry{#1}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsecentry{\the\toks0}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \unnumbnoderef % @@ -2886,8 +3031,9 @@ width0pt\relax} \fi \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % \subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% {\chapternofonts% +\toks0 = {#1}% \edef\temp{{\realbackslash subsecentry % -{#1}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +{\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \donoderef % @@ -2900,8 +3046,9 @@ width0pt\relax} \fi \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % \subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% {\chapternofonts% +\toks0 = {#1}% \edef\temp{{\realbackslash subsecentry % -{#1}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% +{\the\toks0}{\appendixletter}{\the\secno}{\the\subsecno}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \appendixnoderef % @@ -2913,7 +3060,8 @@ width0pt\relax} \fi \def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% \plainsubsecheading {#1}\gdef\thissection{#1}% {\chapternofonts% -\edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsubsecentry{\the\toks0}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \unnumbnoderef % @@ -2927,8 +3075,8 @@ width0pt\relax} \fi \subsubsecheading {#1} {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% {\chapternofonts% -\edef\temp{{\realbackslash subsubsecentry % - {#1} +\toks0 = {#1}% +\edef\temp{{\realbackslash subsubsecentry{\the\toks0} {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno} {\noexpand\folio}}}% \escapechar=`\\% @@ -2944,7 +3092,8 @@ width0pt\relax} \fi \subsubsecheading {#1} {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% {\chapternofonts% -\edef\temp{{\realbackslash subsubsecentry{#1}% +\toks0 = {#1}% +\edef\temp{{\realbackslash subsubsecentry{\the\toks0}% {\appendixletter} {\the\secno}{\the\subsecno}{\the\subsubsecno}{\noexpand\folio}}}% \escapechar=`\\% @@ -2958,7 +3107,8 @@ width0pt\relax} \fi \def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% \plainsubsubsecheading {#1}\gdef\thissection{#1}% {\chapternofonts% -\edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% +\toks0 = {#1}% +\edef\temp{{\realbackslash unnumbsubsubsecentry{\the\toks0}{\noexpand\folio}}}% \escapechar=`\\% \write \contentsfile \temp % \unnumbnoderef % @@ -3139,7 +3289,7 @@ width0pt\relax} \fi % Print any size section title. -% +% % #1 is the section type (sec/subsec/subsubsec), #2 is the section % number (maybe empty), #3 the text. \def\sectionheading#1#2#3{% @@ -3183,7 +3333,9 @@ width0pt\relax} \fi \unnumbchapmacro{#1}\def\thischapter{}% \begingroup % Set up to handle contents files properly. \catcode`\\=0 \catcode`\{=1 \catcode`\}=2 \catcode`\@=11 - \catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi + % We can't do this, because then an actual ^ in a section + % title fails, e.g., @chapter ^ -- exponentiation. --karl, 9jul97. + %\catcode`\^=7 % to see ^^e4 as \"a etc. juha@piuha.ydi.vtt.fi \raggedbottom % Worry more about breakpoints than the bottom. \advance\hsize by -\contentsrightmargin % Don't use the full line length. } @@ -3308,11 +3460,12 @@ width0pt\relax} \fi % the index entries, but we want to suppress hyphenation here. (We % can't do that in the \entry macro, since index entries might consist % of hyphenated-identifiers-that-do-not-fit-on-a-line-and-nothing-else.) -% -% \turnoffactive is for the sake of @" used for umlauts. \def\tocentry#1#2{\begingroup \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks - \entry{\turnoffactive #1}{\turnoffactive #2}% + % Do not use \turnoffactive in these arguments. Since the toc is + % typeset in cmr, so characters such as _ would come out wrong; we + % have to do the usual translation tricks. + \entry{#1}{#2}% \endgroup} % Space between chapter (or whatever) number and the title. @@ -3378,31 +3531,35 @@ width0pt\relax} \fi % But \@ or @@ will get a plain tex @ character. \def\tex{\begingroup -\catcode `\\=0 \catcode `\{=1 \catcode `\}=2 -\catcode `\$=3 \catcode `\&=4 \catcode `\#=6 -\catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie -\catcode `\%=14 -\catcode 43=12 % plus -\catcode`\"=12 -\catcode`\==12 -\catcode`\|=12 -\catcode`\<=12 -\catcode`\>=12 -\escapechar=`\\ -% -\let\,=\ptexcomma -\let\~=\ptextilde -\let\{=\ptexlbrace -\let\}=\ptexrbrace -\let\.=\ptexdot -\let\*=\ptexstar -\let\dots=\ptexdots -\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}} -\def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi} -\def\@{@}% -\let\bullet=\ptexbullet -\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext -% + \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 + \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 + \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie + \catcode `\%=14 + \catcode 43=12 % plus + \catcode`\"=12 + \catcode`\==12 + \catcode`\|=12 + \catcode`\<=12 + \catcode`\>=12 + \escapechar=`\\ + % + \let\b=\ptexb + \let\bullet=\ptexbullet + \let\c=\ptexc + \let\,=\ptexcomma + \let\.=\ptexdot + \let\dots=\ptexdots + \let\equiv=\ptexequiv + \let\!=\ptexexclam + \let\i=\ptexi + \let\{=\ptexlbrace + \let\}=\ptexrbrace + \let\*=\ptexstar + \let\t=\ptext + % + \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% + \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% + \def\@{@}% \let\Etex=\endgroup} % Define @lisp ... @endlisp. @@ -3539,11 +3696,12 @@ width0pt\relax} \fi % \def\nonfillfinish{\afterenvbreak\endgroup}% -% This macro is \def\lisp{\begingroup \nonfillstart \let\Elisp = \nonfillfinish \tt + % Make @kbd do something special, if requested. + \let\kbdfont\kbdexamplefont \rawbackslash % have \ input char produce \ char from current font \gobble } @@ -3661,16 +3819,17 @@ width0pt\relax} \fi % Definitions of (, ) and & used in args for functions. % This is the definition of ( outside of all parentheses. -\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested % -\global\advance\parencount by 1 } +\gdef\oprm#1 {{\rm\char`\(}#1 \bf \let(=\opnested + \global\advance\parencount by 1 +} % % This is the definition of ( when already inside a level of parens. \gdef\opnested{\char`\(\global\advance\parencount by 1 } % \gdef\clrm{% Print a paren in roman if it is taking us back to depth of 0. -% also in that case restore the outer-level definition of (. -\ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi -\global\advance \parencount by -1 } + % also in that case restore the outer-level definition of (. + \ifnum \parencount=1 {\rm \char `\)}\sl \let(=\oprm \else \char `\) \fi + \global\advance \parencount by -1 } % If we encounter &foo, then turn on ()-hacking afterwards \gdef\amprm#1 {{\rm\}\let(=\oprm \let)=\clrm\ } % @@ -3678,8 +3837,11 @@ width0pt\relax} \fi } % End of definition inside \activeparens %% These parens (in \boldbrax) actually are a little bolder than the %% contained text. This is especially needed for [ and ] -\def\opnr{{\sf\char`\(}} \def\clnr{{\sf\char`\)}} \def\ampnr{\&} -\def\lbrb{{\bf\char`\[}} \def\rbrb{{\bf\char`\]}} +\def\opnr{{\sf\char`\(}\global\advance\parencount by 1 } +\def\clnr{{\sf\char`\)}\global\advance\parencount by -1 } +\def\ampnr{\&} +\def\lbrb{{\bf\char`\[}} +\def\rbrb{{\bf\char`\]}} % First, defname, which formats the header line itself. % #1 should be the function name. @@ -3772,7 +3934,7 @@ width0pt\relax} \fi % This is used for \def{tp,vr}parsebody. It could probably be used for % some of the others, too, with some judicious conditionals. -% +% \def\parsebodycommon#1#2#3{% \begingroup\inENV % \medbreak % @@ -3807,13 +3969,13 @@ width0pt\relax} \fi % Fine, but then we have to eventually remove the \empty *and* the % braces (if any). That's what this does. -% +% \def\removeemptybraces\empty#1\relax{#1} % After \spacesplit has done its work, this is called -- #1 is the final % thing to call, #2 the type name (which starts with \empty), and #3 % (which might be empty) the arguments. -% +% \def\parsetpheaderline#1#2#3{% #1{\removeemptybraces#2\relax}{#3}% }% @@ -3856,7 +4018,7 @@ width0pt\relax} \fi \hyphenchar\tensl=0 #1% \hyphenchar\tensl=45 -\ifnum\parencount=0 \else \errmessage{unbalanced parens in @def arguments}\fi% +\ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi% \interlinepenalty=10000 \advance\rightskip by 0pt plus 1fil \endgraf\penalty 10000\vskip -\parskip\penalty 10000% @@ -3957,6 +4119,7 @@ width0pt\relax} \fi \def\defmacx #1 {\errmessage{@defmacx in invalid context}} \def\defspecx #1 {\errmessage{@defspecx in invalid context}} \def\deftypefnx #1 {\errmessage{@deftypefnx in invalid context}} +\def\deftypemethodx #1 {\errmessage{@deftypemethodx in invalid context}} \def\deftypeunx #1 {\errmessage{@deftypeunx in invalid context}} % @defmethod, and so on @@ -3972,6 +4135,16 @@ width0pt\relax} \fi \defunargs {#3}\endgroup % } +% @deftypemethod foo-class return-type foo-method args +% +\def\deftypemethod{% + \defmethparsebody\Edeftypemethod\deftypemethodx\deftypemethodheader} +% +% #1 is the class name, #2 the data type, #3 the method name, #4 the args. +\def\deftypemethodheader#1#2#3#4{% + \deftypefnheaderx{Method on #1}{#2}#3 #4\relax +} + % @defmethod == @defop Method \def\defmethod{\defmethparsebody\Edefmethod\defmethodx\defmethodheader} @@ -4186,7 +4359,7 @@ width0pt\relax} \fi % Use \turnoffactive so that punctuation chars such as underscore % work in node names. -\def\dosetq #1#2{{\let\folio=0 \turnoffactive +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% \next}} @@ -4239,7 +4412,7 @@ width0pt\relax} \fi \def\refx#1#2{% \expandafter\ifx\csname X#1\endcsname\relax % If not defined, say something at least. - $\langle$un\-de\-fined$\rangle$% + \angleleft un\-de\-fined\angleright \ifhavexrefs \message{\linenumber Undefined cross reference `#1'.}% \else @@ -4256,37 +4429,38 @@ width0pt\relax} \fi } % This is the macro invoked by entries in the aux file. -\def\xrdef #1#2{{% - \catcode`\'=\other - \expandafter\gdef\csname X#1\endcsname{#2}% -}} +% +\def\xrdef#1{\begingroup + % Reenable \ as an escape while reading the second argument. + \catcode`\\ = 0 + \afterassignment\endgroup + \expandafter\gdef\csname X#1\endcsname +} % Read the last existing aux file, if any. No error if none exists. \def\readauxfile{\begingroup \catcode`\^^@=\other - \catcode`\=\other - \catcode`\=\other + \catcode`\^^A=\other + \catcode`\^^B=\other \catcode`\^^C=\other \catcode`\^^D=\other \catcode`\^^E=\other \catcode`\^^F=\other \catcode`\^^G=\other \catcode`\^^H=\other - \catcode`\ =\other + \catcode`\^^K=\other \catcode`\^^L=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode`\=\other - \catcode26=\other + \catcode`\^^N=\other + \catcode`\^^P=\other + \catcode`\^^Q=\other + \catcode`\^^R=\other + \catcode`\^^S=\other + \catcode`\^^T=\other + \catcode`\^^U=\other + \catcode`\^^V=\other + \catcode`\^^W=\other + \catcode`\^^X=\other + \catcode`\^^Z=\other \catcode`\^^[=\other \catcode`\^^\=\other \catcode`\^^]=\other @@ -4302,11 +4476,11 @@ width0pt\relax} \fi % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first % argument, and \hat is not an expandable control sequence. It could % all be worked out, but why? Either we support ^^ or we don't. - % + % % The other change necessary for this was to define \auxhat: % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter % and then to call \auxhat in \setq. - % + % \catcode`\~=\other \catcode`\[=\other \catcode`\]=\other @@ -4364,7 +4538,7 @@ width0pt\relax} \fi % space to prevent strange expansion errors.) \def\supereject{\par\penalty -20000\footnoteno =0 } -% @footnotestyle is meaningful for info output only.. +% @footnotestyle is meaningful for info output only. \let\footnotestyle=\comment \let\ptexfootnote=\footnote @@ -4389,7 +4563,7 @@ width0pt\relax} \fi % Don't bother with the trickery in plain.tex to not require the % footnote text as a parameter. Our footnotes don't need to be so general. -% +% % Oh yes, they do; otherwise, @ifset and anything else that uses % \parseargline fail inside footnotes because the tokens are fixed when % the footnote is read. --karl, 16nov96. @@ -4479,9 +4653,51 @@ width0pt\relax} \fi % \def\finalout{\overfullrule=0pt} +% @image. We use the macros from epsf.tex to support this. +% If epsf.tex is not installed and @image is used, we complain. +% +% Check for and read epsf.tex up front. If we read it only at @image +% time, we might be inside a group, and then its definitions would get +% undone and the next image would fail. +\openin 1 = epsf.tex +\ifeof 1 \else + \closein 1 + \def\epsfannounce{\toks0 = }% do not bother showing banner + \input epsf.tex +\fi +% +\newif\ifwarnednoepsf +\newhelp\noepsfhelp{epsf.tex must be installed for images to + work. It is also included in the Texinfo distribution, or you can get + it from ftp://ftp.tug.org/tex/epsf.tex.} +% +% Only complain once about lack of epsf.tex. +\def\image#1{% + \ifx\epsfbox\undefined + \ifwarnednoepsf \else + \errhelp = \noepsfhelp + \errmessage{epsf.tex not found, images will be ignored}% + \global\warnednoepsftrue + \fi + \else + \imagexxx #1,,,\finish + \fi +} +% +% Arguments to @image: +% #1 is (mandatory) image filename; we tack on .eps extension. +% #2 is (optional) width, #3 is (optional) height. +% #4 is just the usual extra ignored arg for parsing this stuff. +\def\imagexxx#1,#2,#3,#4\finish{% + % \epsfbox itself resets \epsf?size at each figure. + \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi + \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi + \epsfbox{#1.eps}% +} % End of control word definitions. + \message{and turning on texinfo input format.} \def\openindices{% |