diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 48 | ||||
| -rw-r--r-- | doc/Makefile.in | 55 | ||||
| -rw-r--r-- | doc/README.card | 19 | ||||
| -rw-r--r-- | doc/ad.block | 48 | ||||
| -rw-r--r-- | doc/awkcard.in | 1353 | ||||
| -rw-r--r-- | doc/awkforai.txt | 150 | ||||
| -rw-r--r-- | doc/cardfonts | 37 | ||||
| -rw-r--r-- | doc/colors | 42 | ||||
| -rw-r--r-- | doc/gawk.1 | 109 | ||||
| -rw-r--r-- | doc/gawk.texi | 675 | ||||
| -rw-r--r-- | doc/macros | 211 | ||||
| -rw-r--r-- | doc/no.colors | 31 | ||||
| -rw-r--r-- | doc/setter.outline | 77 | ||||
| -rw-r--r-- | doc/texinfo.tex | 1378 |
14 files changed, 3450 insertions, 783 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog new file mode 100644 index 00000000..ee017484 --- /dev/null +++ b/doc/ChangeLog @@ -0,0 +1,48 @@ +Mon Dec 9 12:48:54 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * no.colors: new file from Michal for old troffs. + * Makefile.in [AWKCARD]: changes to parameterize old/new troff. + +Sun Dec 1 15:04:56 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * texinfo.tex: Updated to version 2.193, from Karl Berry. + +Tue Nov 26 22:57:15 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in ($(infodir)/gawk.info): Change option in call + to `install-info' to `--info-dir' from `--infodir'. + +Mon Nov 4 13:30:39 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in: updates for reference card. + (ad.block, awkcard.in, cardfonts, colors, macros, setter.outline): + new files for reference card. + +Wed Oct 16 12:43:02 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * texinfo.tex: Updated to version 2.185, from texinfo-3.9 dist. + +Sun Aug 11 23:12:08 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in ($(infodir)/gawk.info): correct use of + $(INSTALL_DATA) and remove chmod command. + +Thu Jul 11 22:06:50 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in ($(mandir)/gawk.$(ext), $(mandir)/igawk.$(ext)): + made dependant on files in $(srcdir). + +Fri Mar 15 06:45:35 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in (clean): add `*~' to list of files to be removed. + +Thu Jan 25 23:40:15 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in (dvi): run texindex and tex an extra time. + This gets the cross references right. Sigh. + +Wed Jan 24 11:51:54 1996 Arnold D. Robbins <arnold@skeeve.atl.ga.us> + + * Makefile.in (maintainer-clean): + Depend on distclean, not the other way around. + Output warning message as per GNU standards. diff --git a/doc/Makefile.in b/doc/Makefile.in index 93278178..d634020e 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,6 +1,6 @@ # Makefile for GNU Awk documentation. # -# Copyright (C) 1993-1995 the Free Software Foundation, Inc. +# Copyright (C) 1993-1996 the Free Software Foundation, Inc. # # This file is part of GAWK, the GNU implementation of the # AWK Programming Language. @@ -41,14 +41,31 @@ infodir = @infodir@ datadir = @datadir@/awk TEXI2DVI = texi2dvi +TEX = tex MAKEINFO = makeinfo --no-split +TROFF = groff -t -Tps +SEDME = sed -e "s/^level0 restore/level0 restore flashme 100 72 moveto (Copyright `date '+%m-%d-%y %T'`, FSF, Inc. (all)) show/" \ + -e "s/^\/level0 save def/\/level0 save def 30 -48 translate/" DOCS= gawk.1 igawk.1 gawk.texi TEXFILES= gawk.aux gawk.cp gawk.cps gawk.fn gawk.fns gawk.ky gawk.kys \ gawk.pg gawk.pgs gawk.toc gawk.tp gawk.tps gawk.vr gawk.vrs -ALLDOC= gawk.dvi $(TEXFILES) +ALLDOC= gawk.dvi $(TEXFILES) gawk.log awkcard.tr + +CARDSRC = $(srcdir)/macros $(srcdir)/cardfonts $(srcdir)/colors awkcard.tr +CARDSRC_N = $(srcdir)/macros $(srcdir)/cardfonts $(srcdir)/no.colors awkcard.tr +CARDFILES= $(CARDSRC) ad.block awkcard.in setter.outline + +# Use this if your troff can correctly handle macros from 'colors' file +AWKCARD = awkcard.ps + +# Uncomment the following definition of AWKCARD if your troff can produce +# Postscript but still has troubles with macros from 'colors'. As this +# is not groff you will have to change TROFF macro as well. Do not forget +# to ensure that awkcard.tr is processed by tbl. +#AWKCARD = awkcard.nc all: $(DOCS) info @@ -58,18 +75,17 @@ $(infodir)/gawk.info: gawk.info -if test -f gawk.info; then d=.; \ else d=$(srcdir); fi; \ for i in $$d/gawk.info*; do \ - $(INSTALL_DATA) $$i $(infodir) ; \ + $(INSTALL_DATA) $$i $(infodir)/$i ; \ done; \ - chmod 644 $(infodir)/gawk.info* ; \ if $(SHELL) -c 'install-info --version' > /dev/null 2>&1 ; \ then install-info --infodir=$(infodir) gawk.info ; \ else true ; fi $(mandir)/gawk$(manext): gawk.1 - $(INSTALL_DATA) gawk.1 $(mandir)/gawk$(manext) && chmod 644 $(mandir)/gawk$(manext) + $(INSTALL_DATA) $(srcdir)/gawk.1 $(mandir)/gawk$(manext) && chmod 644 $(mandir)/gawk$(manext) $(mandir)/igawk$(manext): igawk.1 - $(INSTALL_DATA) igawk.1 $(mandir)/igawk$(manext) && chmod 644 $(mandir)/igawk$(manext) + $(INSTALL_DATA) $(srcdir)/igawk.1 $(mandir)/igawk$(manext) && chmod 644 $(mandir)/igawk$(manext) uninstall: rm -f $(mandir)/gawk$(manext) $(mandir)/igawk$(manext) $(infodir)/gawk.info* @@ -77,23 +93,36 @@ uninstall: dvi: gawk.dvi gawk.dvi: gawk.texi - TEXINPUTS=$$TEXINPUTS:$(srcdir) $(TEXI2DVI) gawk.texi + -TEXINPUTS=$$TEXINPUTS:$(srcdir) $(TEXI2DVI) gawk.texi + texindex gawk.?? + TEXINPUTS=$$TEXINPUTS:$(srcdir) $(TEX) gawk.texi info: gawk.info gawk.info: gawk.texi $(MAKEINFO) gawk.texi -postscript: dvi gawk.1 igawk.1 +postscript: dvi gawk.1 igawk.1 $(AWKCARD) -groff -man gawk.1 > gawk.1.ps -groff -man igawk.1 > igawk.1.ps dvips -o gawk.ps gawk.dvi -clean: - rm -f *.ps $(ALLDOC) gawk.log +awkcard.tr: awkcard.in + sed 's/SRCDIR/$(srcdir)/' < $(srcdir)/awkcard.in > awkcard.tr -maintainer-clean: clean - rm -f gawk.info +awkcard.ps: $(CARDFILES) + $(TROFF) $(CARDSRC) | $(SEDME) | cat $(srcdir)/setter.outline - > awkcard.ps -distclean: maintainer-clean +awkcard.nc: $(CARDFILES) + $(TROFF) $(CARDSRC_N) | $(SEDME) | cat $(srcdir)/setter.outline - > awkcard.ps && touch awkcard.nc + +clean: + rm -f *.ps $(ALLDOC) *~ awkcard.nc + +distclean: clean rm -f Makefile + +maintainer-clean: distclean + @echo "This command is intended for maintainers to use; it" + @echo "deletes files that may require special tools to rebuild." + rm -f gawk.info diff --git a/doc/README.card b/doc/README.card new file mode 100644 index 00000000..ef77cdac --- /dev/null +++ b/doc/README.card @@ -0,0 +1,19 @@ +Mon Dec 9 12:45:48 EST 1996 + +The AWK reference card included here requires a modern version of troff +(ditroff). GNU Troff (groff) is known to work. + +If your troff is able to produce Postscript but does not know how to +properly use the macros from `colors' file then try to uncomment in +Makefile the defintion which sets AWKCARD to awkcard.nc (no colors). +This will definitely require changes to the TROFF macro and you have to +ensure that the tbl preprocessor is called. For example, the following +modifications on NeXT: + +TROFF = tbl +SEDME = ptroff -t | sed -e \ + "s/^level0 restore/level0 restore flashme 100 72 moveto\ + (Copyright `date`, FSF, Inc. (all)) show/" \ + -e "s/^\/level0 save def/\/level0 save def 30 -48 translate/" + +will produce a correctly formatted, albeit monochromatic, reference card. diff --git a/doc/ad.block b/doc/ad.block new file mode 100644 index 00000000..16a4de0f --- /dev/null +++ b/doc/ad.block @@ -0,0 +1,48 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" This file is the Ad block (included in cover) +.\" +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of +.\" this reference card provided the copyright notice and this permission +.\" notice are preserved on all copies. +.\" +.\" Permission is granted to process this file through troff and print the +.\" results, provided the printed document carries copying permission +.\" notice identical to this one except for the removal of this paragraph +.\" (this paragraph not being relevant to the printed reference card). +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" reference card under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" reference card into another language, under the above conditions for +.\" modified versions, except that this permission notice may be stated in +.\" a translation approved by the Foundation. +.\" +.ft HB +.ps 10 +.vs 12 +.ES +.nf +.ce 6 +\*(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 + +.ce 7 +.ft HB +\*(CGFree Software +Source Distributions on CD-ROM +Deluxe Distributions +Emacs, Gawk, Make and GDB Manuals +Emacs and GDB References\*(CX +.EB "\f(HBOTHER FSF PRODUCTS:\*(FR" +.ps +.vs diff --git a/doc/awkcard.in b/doc/awkcard.in new file mode 100644 index 00000000..50af4aae --- /dev/null +++ b/doc/awkcard.in @@ -0,0 +1,1353 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of +.\" this reference card provided the copyright notice and this permission +.\" notice are preserved on all copies. +.\" +.\" Permission is granted to process this file through troff and print the +.\" results, provided the printed document carries copying permission +.\" notice identical to this one except for the removal of this paragraph +.\" (this paragraph not being relevant to the printed reference card). +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" reference card under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" reference card into another language, under the above conditions for +.\" modified versions, except that this permission notice may be stated in +.\" a translation approved by the Foundation. +.\" +.\" Strings to save typing +.ds AK \*(FCawk\*(FR +.ds GK \*(FCgawk\*(FR +.ds NK Bell Labs \*(FCawk\*(FR +.ds MK \*(FCmawk\*(FR +.\" +.\" + + +.sp +.ce +\*(CD\f(HB\s+8AWK REFERENCE\s0\*(FR +.sp +.\" --- Table Of Contents +.ta 2.4i 2.6iR +.lc . +.ES +.in +.2i +.nf +\*(FRAWK Program Execution 4 +Action Statements 7 +Arrays 9 +Bug Reports 15 +Command Line Arguments (standard) 2 +Command Line Arguments (\*(GK) 3 +Command Line Arguments (\*(MK) 4 +Conversions And Comparisons 10 +Copying Permissions 16 +Definitions 2 +Environment Variables (\*(GK) 16 +Escape Sequences 7 +Expressions 9 +Fields 6 +FTP Information 16 +Historical Features 16 +Input Control 11 +Lines And Statements 5 +.ig +Localization 10 +.. +Numeric Functions 13 +Output Control 11 +Pattern Elements 7 +POSIX Character Classes (\*(GK) 6 +Printf Formats 12 +Records 6 +Regular Expressions 5 +Special Filenames 13 +String Functions 14 +Time Functions 15 +User-defined Functions 15 +Variables 8\*(CX +.in -.2i +.EB "\s+2\f(HBCONTENTS\*(FR\s0" +.sp +.ta .2i .78i 1i 1.2i 1.4i 1.7i +.fi +\*(CD\*(FRThis reference card was written by Arnold Robbins. +Brian Kernighan and Michael Brennan reviewed it; we thank them +them for their help. +.sp +.SL +.sp +.so SRCDIR/ad.block +.\" a subtlety here; this line changes color. We rely on it +.\" also to provide a blank line. +\*(CD +.SL +.nf +\*(FR\(co Copyright, 1996 Free Software Foundation +59 Temple Place \(em Suite 330 +Boston, MA 02111-1307 USA +.nf +.BT + + +.\" +.\" +.\" --- Definitions +.fi +.ES +\*(CDThis card describes POSIX AWK, as well as the three +freely available \*(AK implementations +(see \fHFTP Information\fP, below). +\*(CLCommon extensions (in two or more versions) are printed in light blue. +\*(CBFeatures specific to just one version\(emusually GNU AWK (\*(GK)\(emare +printed in dark blue. +\*(CRExceptions and deprecated features are printed in red. +\*(CDFeatures mandated by POSIX are printed in black. +.sp .5 +Several type faces are used to clarify the meaning: +.br +\(bu \*(FC\*(CN\fP is used for computer input. +.br +\(bu\|\^\*(FI\*(IN\fP is used to indicate user input and for syntactic +.br +\0\|\^placeholders, such as \*(FIvariable\fP or \*(FIaction\fP. +.br +\(bu \*(RN is used for explanatory text. +.sp .5 +\*(FInumber\fP \- a floating point number as in ANSI C, such as +\*(FC3\*(FR, +\*(FC2.3\*(FR, +\*(FC.4\*(FR, +\*(FC1.4e2\*(FR, +or +\*(FC4.1E5\*(FR. +.sp .5 +\*(FIescape sequences\fP \- a special sequence of characters beginning +with a backslash, used to describe otherwise unprintable characters. +See \fHEscape Sequences\fP, below. +.sp .5 +\*(FIstring\fP \- a group of characters enclosed in double quotes. +Strings may contain \*(FIescape sequences\*(FR. +.sp .5 +\*(FIregexp\fP \- a regular expression, either a regexp constant +enclosed in forward slashes, or a dynamic regexp computed at run-time. +Regexp constants may contain \*(FIescape sequences\*(FR. +.sp .5 +\*(FIname\fP \- a variable, array, or function name. +.sp .5 +\*(FIentry\fP(\*(FIN\fP) \- entry \*(FIentry\fP in section \*(FIN\fP of the +UNIX reference manual. +.sp .5 +\*(FIpattern\fP \- an expression describing an input record to be matched. +.sp .5 +\*(FIaction\fP \- statements to execute when an input record is matched. +.sp .5 +\*(FIrule\fP \- a pattern-action pair, where the pattern or action may +be missing.\*(CX +.EB \s+2\f(HBDEFINITIONS\*(FR\s0 + + +.\" --- Command Line Arguments +.ES +.fi +\*(CDCommand line arguments control setting the field separator, +setting variables before the \*(FCBEGIN\fP rule is run, and +the location of AWK program source code. +Implementation-specific command line arguments change +the behaviour of the running interpreter. +.sp .5 +.nf +\*(FC\-F \*(FIfs\*(FR use \*(FIfs\fP for the input field separator +\*(FC\-v\*(FI var\*(FC\^=\^\*(FIval\*(FR assign the value \*(FIval\*(FR, to the variable \*(FIvar\*(FR, + before execution of the program begins. Such + variable values are available to the \*(FCBEGIN\fP rule +\*(FC\-f \*(FIprog-file\*(FR read the AWK program source from the file + \*(FIprog-file\*(FR, instead of from the first command + line argument. Multiple \*(FC\-f\*(FR options may be used +\*(FC\-\^\-\*(FR signal the end of options +.sp .5 +.fi +\*(CLThe following options are accepted by both \*(NK and \*(GK +\*(CR(ignored by \*(GK, not in \*(MK).\*(CL +.sp .5 +.nf +\*(FC\-mf \*(FIval\*(FR set the maximum number of fields to \*(FIval\fP +\*(FC\-mr \*(FIval\*(FR set the maximum record size to \*(FIval\fP\*(CX +.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (standard)\*(FR\s0" + +.BT + + + +.ES +.fi +\*(CDThe following options are specific to \*(GK. The \*(FC\-W\*(FR +forms are for full POSIX compliance. +.sp .5 +.nf +\*(FC\-\^\-field-separator \*(FIfs\*(FR + just like \*(FC\-F\fP +\*(FC\-\^\-assign \*(FIvar\*(FC\^=\^\*(FIval\*(FR just like \*(FC\-v\fP +\*(FC\-\^\-file \*(FIprog-file \*(FRjust like \*(FC\-f\fP +\*(FC\-\^\-traditional\*(FR +\*(FC\-\^\-compat\*(FR +\*(FC\-W compat\*(FR +\*(FC\-W traditional\*(FR turn off \*(GK-specific extensions + (\*(FC\-\^\-traditional\*(FR preferred) +\*(FC\-\^\-copyleft\*(FR +\*(FC\-\^\-copyright\*(FR +\*(FC\-W copyleft\*(FR +\*(FC\-W copyright\*(FR print the short version of the GNU + copyright information on \*(FCstdout\*(FR +\*(FC\-\^\-help\*(FR +\*(FC\-\^\-usage\*(FR +\*(FC\-W help\*(FR +\*(FC\-W usage\*(FR Print a short summary of the available + options on \*(FCstdout\*(FR, then exit zero +\*(FC\-\^\-lint\*(FR +\*(FC\-W lint\*(FR warn about constructs that are dubious + or non-portable to other \*(AKs +\*(FC\-\^\-lint\-old\*(FR +\*(FC\-W lint\-old\*(FR warn about constructs that are not + portable to the original version of + Unix \*(AK +.ig +.\" This option is left undocumented, on purpose. +\*(FC\-\^\-nostalgia\*(FR +\*(FC\-W nostalgia\*(FR provide a moment of nostalgia for + long time \*(AK users +.. +\*(FC\-\^\-posix\*(FR +\*(FC\-W posix\*(FR disable common and GNU extensions. + Enable \*(FIinterval expressions\*(FR in regular + expression matching (see \fHRegular + Expressions\fP, below) +\*(FC\-\^\-re\-interval\*(FR +\*(FC\-W re\-interval\*(FR enable \*(FIinterval expressions\*(FR in regular + expression matching (see \fHRegular + Expressions\fP, below). Useful if + \*(FC\-\^\-posix\*(FR is not specified +\*(FC\-\^\-source '\*(FItext\*(FC'\*(FR +\*(FC\-W source '\*(FItext\*(FC'\*(FR use \*(FItext\*(FR as AWK program source code +\*(FC\-\^\-version\*(FR +\*(FC\-W version\*(FR print version information on \*(FCstdout\fP + and exit zero +.sp .5 +.fi +In compatibility mode, +any other options are flagged as illegal, but are otherwise ignored. +In normal operation, as long as program text has been supplied, unknown +options are passed on to the AWK program in +\*(FCARGV\*(FR +for processing. This is most useful for running AWK +programs via the \*(FC#!\*(FR executable interpreter mechanism.\*(CB +.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0" + +.BT + +.ES +.fi +\*(CDThe following options are specific to \*(MK. +.sp .5 +.nf +\*(FC\-W dump\*(FR print an assembly listing of the program to + \*(FCstdout\fP and exit zero +\*(FC\-W exec \*(FIfile\*(FR read program text from \*(FIfile\fP. No other + options are processed. Useful with \*(FC#!\fP +\*(FC\-W interactive\*(FR unbuffer \*(FCstdout\fP and line buffer \*(FCstdin\fP. + Lines are always records, ignoriing \*(FCRS\fP +\*(FC\-W posix_space\*(FR make \*(FC\en\*(FR separate fields when \*(FCRS = "\^"\fP +\*(FC\-W sprintf=\*(FInum\*(FR adjust the size of \*(MK's internal + \*(FCsprintf\*(FR buffer +\*(FC\-W version\*(FR print version and copyright information on + \*(FCstdout\fP and limit information on \*(FCstderr\fP + and exit zero +.sp .5 +.fi +The options may be abbreviated using just the first letter, e.g., +\*(FC\-We\*(FR, +\*(FC\-Wv\*(FR, +and so on.\*(CB +.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(MK\f(HB)\*(FR\s0" + + +.\" --- Awk Program Execution +.ES +.fi +\*(CDAWK programs are a sequence of pattern-action statements +and optional function definitions. +.sp .5 + \*(FIpattern\*(FC { \*(FIaction statements\*(FC }\*(FR +.br + \*(FCfunction \*(FIname\*(FC(\*(FIparameter list\*(FC) { \*(FIstatements\*(FC }\*(FR +.sp .5 +\*(AK first reads the program source from the +\*(FIprog-file\*(FR(s) if specified, +\*(CBfrom arguments to \*(FC\-\^\-source\*(FR,\*(CD +or from the first non-option argument on the command line. +The program text is read as if all the \*(FIprog-file\*(FR(s) +\*(CBand command line +source texts\*(CD had been concatenated together. +.sp .5 +AWK programs execute in the following order. +First, all variable assignments specified via the \*(FC\-v\fP +option are performed. +Next, \*(AK executes the code in the +\*(FCBEGIN\fP rules(s) (if any), and then proceeds to read +the files \*(FC1\fP through \*(FCARGC \- 1\fP in the \*(FCARGV\fP array. +(Adjusting \*(FCARGC\fP and \*(FCARGV\fP thus provides control over +the input files that will be processed.) +If there are no files named on the command line, +\*(AK reads the standard input. +.sp .5 +If a command line argument has the form +\*(FIvar\*(FC=\*(FIval\*(FR +it is treated as a variable assignment. The variable +\*(FIvar\fP will be assigned the value \*(FIval\*(FR. +(This happens after any \*(FCBEGIN\fP rule(s) have been run.) +... delete this paragraph if no space +Command line variable assignment +is most useful for dynamically assigning values to the variables +\*(AK uses to control how input is broken into fields and records. It +is also useful for controlling state if multiple passes are needed over +a single data file. +.sp .5 +If the value of a particular element of \*(FCARGV\fP is empty +(\*(FC"\^"\*(FR), \*(AK skips over it. +.sp .5 +For each record in the input, \*(AK tests to see if it matches any +\*(FIpattern\fP in the AWK program. +For each pattern that the record matches, the associated +\*(FIaction\fP is executed. +The patterns are tested in the order they occur in the program. +.sp .5 +Finally, after all the input is exhausted, +\*(AK executes the code in the \*(FCEND\fP rule(s) (if any). +.sp .5 +If a program only has a \*(FCBEGIN\fP rule, no input files are processed. +If a program only has an \*(FCEND\fP rule, the input will be read. +\*(CX +.EB "\s+2\f(HBAWK PROGRAM EXECUTION\*(FR\s0" + + +.BT + +.\" --- Lines And Statements +.ES +.fi +\*(CDAWK is a line oriented language. The pattern comes first, and then the +action. Action statements are enclosed in \*(FC{\fP and \*(FC}\*(FR. +Either the pattern may be missing, or the action may be missing, but +not both. If the pattern is missing, the action will be +executed for every input record. +A missing action is equivalent to +.sp .5 + \*(FC{ print }\fP +.sp .5 +which prints the entire record. +.sp .5 +Comments begin with the \*(FC#\*(FR character, and continue until the +end of the line. +Normally, a statement ends with a newline, but lines ending in +a ``,'', +\*(FC{\*(FR, +\*(CB\*(FC?\*(FR, +\*(FC:\*(FR,\*(CD +\*(FC&&\*(FR, +or +\*(FC||\*(FR +are automatically continued. +Lines ending in \*(FCdo\fP or \*(FCelse\fP +also have their statements automatically continued on the following line. +In other cases, a line can be continued by ending it with a ``\e'', +in which case the newline will be ignored. However a ``\e'' after a +\*(FC#\*(FR is not special. +.sp .5 +Multiple statements may be put on one line by separating them with a ``;''. +This applies to both the statements within the action part of a +pattern-action pair (the usual case), +and to the pattern-action statements themselves.\*(CX +.EB "\s+2\f(HBLINES AND STATEMENTS\*(FR\s0" + + + +.\" --- Regular Expressions +.ES +.fi +\*(CDRegular expressions are the extended kind originally defined by +\*(FCegrep\fP. +\*(CBAdditional GNU regexp operators are supported by \*(GK. +A \*(FIword-constituent\fP character is a letter, digit, or +underscore (\*(FC_\fP).\*(CD +.sp .5 +.TS +center, tab(~); +cp8 sp8 +cp8 sp8 +lp8|lp8. +.\" .vs 10 +_ +Summary of Regular Expressions +In Decreasing Precedence +_ +\*(FC(\^\*(FIr\*(FC)\*(FR~regular expression (for grouping) +\*(FIc\*(FR~if non-special char, matches itself +\*(FC\e\*(FI\^c\*(FR~turn off special meaning of \*(FIc\fP +\*(FC^\*(FR~beginning of string (note: \*(FInot\fP line) +\*(FC$\*(FR~end of string (note: \*(FInot\fP line) +\*(FC.\*(FR~any single character, including newline +\*(FC[\*(FR...\*(FC]\*(FR~any one character in ... or range +\*(FC[^\*(FR...\*(FC]\*(FR~any one character not in ... or range +\*(CB\*(FC\ey\*(FR~word boundary +\*(FC\eB\*(FR~middle of a word +\*(FC\e<\*(FR~beginning of a word +\*(FC\e>\*(FR~end of a word +\*(FC\ew\*(FR~any word-constituent character +\*(FC\eW\*(FR~any non-word-constituent character +\*(FC\e`\*(FR~beginning of a buffer (string) +\*(FC\e'\*(FR~end of a buffer (string)\*(CD +\*(FIr\*(FC*\*(FR~zero or more occurrences of \*(FIr\*(FR +\*(FIr\*(FC+\*(FR~one or more occurrences of \*(FIr\*(FR +\*(FIr\*(FC?\*(FR~zero or one occurrences of \*(FIr\*(FR +\*(FIr\*(FC{\*(FIn\*(FC,\*(FIm\*(FC}\*(FR~\*(FIn\fP to \*(FIm\fP occurrences of \*(FIr\*(FR \*(CR(POSIX: see note below)\*(CD +\*(FIr1\*(FC|\|\*(FIr2\*(FR~\*(FIr1\*(FR or \*(FIr2\*(FR +.TE +.sp .5 +.fi +\*(CRThe \*(FIr\*(FC{\*(FIn\*(FC,\*(FIm\*(FC}\*(FR notation is called an +\*(FIinterval expression\fP. POSIX mandates it for AWK regexps, but +most \*(AKs don't implement it. \*(CBUse \*(FC\-\^\-re\-interval\*(FR +or \*(FC\-\^\-posix\*(FR to enable +this feature in \*(GK.\*(CX +.EB "\s+2\f(HBREGULAR EXPRESSIONS\*(FR\s0" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + +.BT + +.\" --- POSIX Character Classes (gawk) +.ES +.fi +\*(CDIn regular expressions, within character ranges +(\*(FC[\*(FR...\*(FC]\*(FR), +the notation \*(FC[[:\*(FIclass\*(FC:]]\*(FR defines characters classes: +.sp .5 +.TS +center, tab(~); +lp8 lp8 lp8 lp8. +\*(FCalnum\*(FR~alphanumeric~\*(FClower\*(FR~lower-case +\*(FCalpha\*(FR~alphabetic~\*(FCprint\*(FR~printable +\*(FCblank\*(FR~space or tab~\*(FCpunct\*(FR~punctuation +\*(FCcntrl\*(FR~control~\*(FCspace\*(FR~whitespace +\*(FCdigit\*(FR~decimal~\*(FCupper\*(FR~upper-case +\*(FCgraph\*(FR~non-spaces~\*(FCxdigit\*(FR~hexadecimal\*(CB +.TE +.fi +.EB "\s+2\f(HBPOSIX CHARACTER CLASSES (\*(GK\f(HB)\*(FR\s0" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + + +.\" --- Records +.ES +.fi +\*(CDNormally, records are separated by newline characters. +Assigning values to the built-in variable \*(FCRS\*(FR +controls how records are separated. +If \*(FCRS\fP is any single character, that character separates records. +\*(CLOtherwise, \*(FCRS\fP is a regular expression. +\*(CR(Not \*(NK.)\*(CL +Text in the input that matches this +regular expression will separate the record. +\*(CB\*(GK sets \*(FCRT\*(FR to the value of the +input text that matched the regular expression. +The value of \*(FCIGNORECASE\fP +will also affect how records are separated when +\*(FCRS\fP is a regular expression.\*(CD +If \*(FCRS\fP is set to the null string, +then records are separated by one or more blank lines. +When \*(FCRS\fP is set to the null string, +the newline character always acts as +a field separator, in addition to whatever value +\*(FCFS\fP may have. +\*(CB\*(MK does not apply exceptional rules to \*(FCFS\fP +when \*(FCRS = "\^"\fP.\*(CX +.EB \s+2\f(HBRECORDS\*(FR\s0 + + + +.\" --- Fields +.ES +.fi +\*(CDAs each input record is read, \*(AK splits the record into +\*(FIfields\*(FR, using the value of the \*(FCFS\fP +variable as the field separator. +If \*(FCFS\fP is a single character, +fields are separated by that character. +\*(CLIf \*(FCFS\fP is the null string, +then each individual character becomes a separate field.\*(CD +Otherwise, \*(FCFS\fP is expected to be a full regular expression. +In the special case that \*(FCFS\fP +is a single space, fields are separated +by runs of spaces and/or tabs +\*(CLand/or newlines\*(CD. +Leading and trailing whitespace are ignored. +\*(CBThe value of \*(FCIGNORECASE\fP +will also affect how fields are split when +\*(FCFS\fP is a regular expression.\*(CD +.sp .5 +\*(CBIf the \*(FCFIELDWIDTHS\fP +variable is set to a space separated list of numbers, each field is +expected to have a fixed width, and \*(GK +will split up the record using the specified widths. +The value of \*(FCFS\fP is ignored. +Assigning a new value to \*(FCFS\fP +overrides the use of \*(FCFIELDWIDTHS\*(FR, +and restores the default behavior.\*(CD +.sp .5 +Each field in the input record may be referenced by its position, +\*(FC$1\*(FR, \*(FC$2\*(FR, and so on. +\*(FC$0\fP is the whole record. +The value of a field may be assigned to as well. +.sp .5 +The variable \*(FCNF\fP +is set to the total number of fields in the input record. +.sp .5 +References to non-existent fields (i.e. fields after \*(FC$NF\*(FR) +produce the null-string. However, assigning to a non-existent field +(e.g., \*(FC$(NF+2) = 5\*(FR) will increase the value of +\*(FCNF\*(FR, create any intervening fields with the null string as their value, +and cause the value of \*(FC$0\fP +to be recomputed, with the fields being separated by the +value of \*(FCOFS\*(FR. +References to negative numbered fields cause a fatal error. +Decreasing the value of \*(FCNF\fP causes the trailing fields to be lost +\*(CR(not \*(NK).\*(CX +.EB \s+2\f(HBFIELDS\*(FR\s0 + +.BT + +.\" --- Pattern Elements +.ES +.fi +\*(CDAWK patterns may be one of the following. +.sp .5 +.nf + \*(FCBEGIN + END + \*(FIexpression + pat1\*(FC,\*(FIpat2\*(FR +.sp .5 +.fi +\*(FCBEGIN\fP and \*(FCEND\fP are special patterns that provide start-up +and clean-up actions respectively. They must have actions. There can +be multiple \*(FCBEGIN\fP and \*(FCEND\fP rules; they are merged and +executed as if there had just been one large rule. They may occur anywhere +in a program, including different source files. +.sp .5 +Expression patterns can be any expression, as described +under \fHExpressions\fP. +.sp .5 +The \*(FIpat1\*(FC,\*(FIpat2\*(FR pattern +is called a \*(FIrange pattern\*(FR. +It matches all input records starting with a record that matches +\*(FIpat1\*(FR, and continuing until a record that matches +\*(FIpat2\*(FR, inclusive. +It does not combine with any other pattern expression.\*(CX +.EB "\s+2\f(HBPATTERN ELEMENTS\*(FR\s0" + + +.\" --- Action Statements +.ES +.nf +\*(CD\*(FCif (\*(FIcondition\*(FC) \*(FIstatement\*(FR [ \*(FCelse\*(FI statement \*(FR] +\*(FCwhile (\*(FIcondition\*(FC) \*(FIstatement \*(FR +\*(FCdo \*(FIstatement \*(FCwhile (\*(FIcondition\*(FC)\*(FR +\*(FCfor (\*(FIexpr1\*(FC; \*(FIexpr2\*(FC; \*(FIexpr3\*(FC) \*(FIstatement\*(FR +\*(FCfor (\*(FIvar \*(FCin\*(FI array\*(FC) \*(FIstatement\*(FR +.ig +\*(CB\*(FCabort\*(FR [ \*(FIexpression\*(FR ]\*(CD +.. +\*(FCbreak\*(FR +\*(FCcontinue\*(FR +\*(FCdelete \*(FIarray\^\*(FC[\^\*(FIindex\^\*(FC]\*(FR +\*(CL\*(FCdelete \*(FIarray\^\*(FR\*(CD +\*(FCexit\*(FR [ \*(FIexpression\*(FR ] +\*(FCnext\*(FR +\*(CL\*(FCnextfile\*(FR \*(CR(not \*(MK)\*(CD +\*(FC{ \*(FIstatements \*(FC}\*(CX +.EB "\s+2\f(HBACTION STATEMENTS\*(FR\s0" + + + +.\" --- Escape Sequences +.ES +.fi +\*(CDWithin strings constants (\*(FC"..."\fP) and regexp +constants (\*(FC/.../\fP), escape sequences may be used to +generate otherwise unprintable characters. This table lists +the available escape sequences. +.sp .5 +.TS +center, tab(~); +lp8 lp8 lp8 lp8. +\*(FC\ea\fP~alert (bell)~\*(FC\er\fP~carriage return +\*(FC\eb\fP~backspace~\*(FC\et\fP~horizontal tab +\*(FC\ef\fP~form feed~\*(FC\ev\fP~vertical tab +\*(FC\en\fP~newline~\*(FC\e\e\fP~backslash +\*(FC\e\*(FIddd\*(FR~octal value \*(FIddd\fP~\*(CL\*(FC\ex\*(FIhh\*(FR~hex value \*(FIhh\fP\*(CD +\*(FC\e"\fP~double quote~\*(FC\e/\fP~forward slash\*(CX +.TE +.EB "\s+2\f(HBESCAPE SEQUENCES\*(FR\s0" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + +.BT + +.\" --- Variables +.ES +.nf +\*(FCARGC\fP number of command line arguments +\*(CB\*(FCARGIND\fP index in \*(FCARGV\fP of current data file\*(CD +\*(FCARGV\fP array of command line arguments. Indexed from + 0 to \*(FCARGC\fP \- 1. Dynamically changing the + contents of \*(FCARGV\fP can control the files used + for data +\*(FCCONVFMT\fP conversion format for numbers, default value + is \*(FC"%.6g"\*(FR +\*(FCENVIRON\fP array containing the the current environment. + The array is indexed by the environment + variables, each element being the value of + that variable +\*(CB\*(FCERRNO\fP contains a string describing the error when a + redirection or read for \*(FCgetline\*(FR fails, or if + \*(FCclose()\*(FR fails +\*(CB\*(FCFIELDWIDTHS\fP white-space separated list of fieldwidths. Used + to parse the input into fields of fixed width, + instead of the value of \*(FCFS\fP\*(CD +\*(FCFILENAME\fP name of the current input file. If no files given + on the command line, \*(FCFILENAME\fP is ``\-''. + \*(FCFILENAME\fP is undefined inside the \*(FCBEGIN\fP rule + (unless set by \*(FCgetline\fP) +\*(FCFNR\fP number of the input record in current input file +\*(FCFS\fP input field separator, a space by default. + See \fHFields\fP, above +\*(CB\*(FCIGNORECASE\fP if non-zero, all regular expression and string + operations ignore case. \*(CRIn versions of \*(GK + prior to 3.0, \*(FCIGNORECASE\fP only affected + regular expression operations and \*(FCindex()\*(FR\*(CD +\*(FCNF\fP number of fields in the current input record +\*(FCNR\fP total number of input records seen so far +\*(FCOFMT\fP output format for numbers, \*(FC"%.6g"\*(FR, by default. + \*(CROld versions of \*(AK also used this for number + to string conversion instead of \*(FCCONVFMT\fP\*(CD +\*(FCOFS\fP output field separator, a space by default +\*(FCORS\fP output record separator, a newline by default +.ig +\*(CB\*(FCPROCINFO\fP elements of this array provide access to info + about the running AWK program. See + \*(AM for details\*(CD +.. +\*(FCRS\fP input record separator, a newline by default. + See \fHRecords\fP, above +\*(CB\*(FCRT\fP record terminator. \*(GK sets \*(FCRT\fP to the input + text that matched the character or regular + expression specified by \*(FCRS\*(FR\*(CD +\*(FCRSTART\fP index of the first character matched by + \*(FCmatch()\*(FR; 0 if no match +\*(FCRLENGTH\fP length of the string matched by \*(FCmatch()\*(FR; + \-1 if no match +\*(FCSUBSEP\fP character(s) used to separate multiple subscripts + in array elements, by default \*(FC"\e034"\*(FR. See + \fHArrays\fP, below\*(CX +.EB \s+2\f(HBVARIABLES\*(FR\s0 + +.BT + +.\" --- Arrays +.ES +.fi +\*(CDArrays are subscripted with an expression between square brackets +(\*(FC[ \*(FRand \*(FC]\*(FR). +If the expression is an expression list +\*(FC(\*(FIexpr\*(FC, \*(FIexpr \*(FC...)\*(FR +then the array subscript is a string consisting of the +concatenation of the (string) value of each expression, +separated by the value of the \*(FCSUBSEP\fP variable. +This facility simulates multiply dimensioned +arrays. For example: +.nf +.sp .5 + \*(FCi = "A";\^ j = "B";\^ k = "C" + x[i, j, k] = "hello, world\en"\*(FR +.sp .5 +.fi +assigns the string \*(FC"hello, world\en"\*(FR to the element of the array +\*(FCx\fP +which is indexed by the string \*(FC"A\e034B\e034C"\*(FR. All arrays in AWK +are associative, i.e. indexed by string values. +.sp .5 +The special operator \*(FCin\fP may be used in an \*(FCif\fP +or \*(FCwhile\fP statement to see if an array has an index consisting +of a particular value. +.sp .5 +.nf + \*(FCif (val in array) + print array[val]\*(FR +.sp .5 +.fi +If the array has multiple subscripts, use +\*(FC(i, j) in array\*(FR. +.sp .5 +The \*(FCin\fP construct may also be used in a \*(FCfor\fP +loop to iterate over all the elements of an array. +.sp .5 +An element may be deleted from an array using the +\*(FCdelete\fP statement. +\*(CLThe \*(FCdelete\fP +statement can also delete the entire contents of an array, +just by specifying the array name without a subscript.\*(CX +.EB \s+2\f(HBARRAYS\*(FR\s0 + + +.\" --- Expressions +.ES +.fi +\*(CDExpressions are used as patterns, for controlling conditional +statements, and to produce parameter values when calling functions. +Expressions may also be used as simple statements, +particularly if they have side-effects, such as assignment. +Expressions mix \*(FIoperands\fP and \*(FIoperators\fP. Operands are +constants, fields, variables, array elements, and the return +values from function calls (both built-in and user-defined). +.sp .5 +Regexp constants (\*(FC/\*(FIpat\*(FC/\*(FR), when used as simple expressions, +i.e., not used on the right-hand side of +\*(FC~\fP and \*(FC!~\fP, or as arguments to the +\*(CB\*(FCgensub()\fP,\*(CD +\*(FCgsub()\fP, +\*(FCmatch()\fP, +\*(FCsplit()\fP, +and +\*(FCsub()\fP, +functions, mean \*(FC$0 ~ /\*(FIpat\*(FC/\*(FR. +.sp .5 +The AWK operators, in order of decreasing precedence, are +.sp .5 +.nf +\*(FC(\&...)\*(FR grouping +\*(FC$\fP field reference +\*(FC++ \-\^\-\fP increment and decrement, both prefix and postfix +\*(FC^\fP \*(CL\*(FC**\*(FR\*(CD exponentiation +\*(FC+ \- !\fP unary plus, unary minus, and logical negation +\*(FC* / %\fP multiplication, division, and modulus +\*(FC+ \-\fP addition and subtraction +\*(FIspace\fP string concatenation +\*(FC< >\fP less than, greater than +\*(FC<= >=\fP less than or equal, greater than or equal +\*(FC!= ==\fP not equal, equal +\*(FC~ !~\fP regular expression match, negated match +\*(FCin\fP array membership +\*(FC&&\fP logical AND, short circuit +\*(FC||\fP logical OR, short circuit +\*(FC?\^:\fP in-line conditional expression +\*(FC=\0+=\0\-=\0*=\0/=\0%=\0^=\0\*(CL**=\*(CD\fP + assignment operators\*(CX +.EB \s+2\f(HBEXPRESSIONS\*(FR\s0 + + +.BT + +.\" --- Conversions and Comparisons +.ES +.fi +\*(CDVariables and fields may be (floating point) numbers, or strings, or both. +Context determines how the value of a variable is interpreted. If used in +a numeric expression, it will be treated as a number, if used as a string +it will be treated as a string. +.sp .5 +To force a variable to be treated as a number, add 0 to it; to force it +to be treated as a string, concatenate it with the null string. +.sp .5 +When a string must be converted to a number, the conversion is accomplished +using \*(FIatof\*(FR(3). +A number is converted to a string by using the value of \*(FCCONVFMT\fP +as a format string for \*(FIsprintf\*(FR(3), +with the numeric value of the variable as the argument. +However, even though all numbers in AWK are floating-point, +integral values are \*(FIalways\fP converted as integers. +.sp .5 +Comparisons are performed as follows: +If two variables are numeric, they are compared numerically. +If one value is numeric and the other has a string value that is a +``numeric string,'' then comparisons are also done numerically. +Otherwise, the numeric value is converted to a string and a string +comparison is performed. +Two strings are compared, of course, as strings. +\*(CRAccording to the POSIX standard, even if two strings are +numeric strings, a numeric comparison is performed. However, this is +clearly incorrect, and none of the three free \*(AK\*(FRs do this.\*(CD +.sp .5 +Note that string constants, such as \*(FC"57"\fP, are \*(FInot\fP +numeric strings, they are string constants. The idea of ``numeric string'' +only applies to fields, \*(FCgetline\fP input, +\*(FCFILENAME\*(FR, \*(FCARGV\fP elements, \*(FCENVIRON\fP +elements and the elements of an array created by +\*(FCsplit()\fP that are numeric strings. +The basic idea is that \*(FIuser input\*(FR, +and only user input, that looks numeric, +should be treated that way. +.sp .5 +Uninitialized variables have the numeric value 0 and the string value +\*(FC"\^"\fP +(the null, or empty, string).\*(CX +.EB "\s+2\f(HBCONVERSIONS AND COMPARISONS\*(FR\s0" + +.ig +.\" --- Localization +.ES +.nf +.ce 100 +\*(CDThis +section +is +under +construction. +.sp .5 +This +section +is +under +construction.\*(CB +.ce 0 +.EB "\s+2\f(HBLOCALIZATION\*(FR\s0" +.. + +.BT + + +.\" --- Input Control +.ES +.nf +\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR close input file or pipe +\*(FCgetline\fP set \*(FC$0\fP from next input record; + set \*(FCNF\*(FR, \*(FCNR\*(FR, \*(FCFNR\*(FR +\*(FCgetline < \*(FIfile\*(FR set \*(FC$0\fP from next record of \*(FIfile\*(FR; set \*(FCNF\*(FR +\*(FCgetline \*(FIv\*(FR set \*(FIv\fP from next input record; + set \*(FCNR\*(FR, \*(FCFNR\*(FR +\*(FCgetline \*(FIv \*(FC< \*(FIfile\*(FR set \*(FIv\fP from next record of \*(FIfile\*(FR +\*(FIcmd \*(FC| getline\*(FR pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR +\*(FIcmd \*(FC| getline \*(FIv\*(FR pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR +\*(FCnext\fP stop processing the current input + record. Read next input record and + start over with the first pattern in the + program. Upon end of the input data, + execute any \*(FCEND\fP rule(s) +\*(CL\*(FCnextfile\fP stop processing the current input file. + The next input record comes from the + next input file. \*(FCFILENAME\fP \*(CBand + \*(FCARGIND\fP\*(CL are updated, \*(FCFNR\fP is reset to 1, + and processing starts over with the first + pattern in the AWK program. Upon end + of input data, execute any \*(FCEND\fP rule(s). + \*(CREarlier versions of \*(GK used + \*(FCnext file\*(FR, as two words. This + generates a warning message and will + eventually be removed. \*(CR\*(MK does not + currently support \*(FCnextfile\*(FR\*(CD +.sp .5 +.fi +The \*(FCgetline\*(FR command returns 0 on end of file, and \-1 on an +error.\*(CX +.EB "\s+2\f(HBINPUT CONTROL\*(FR\s0" + +.\" --- Output Control +.ES +.fi +.in +.2i +.ti -.2i +\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR +.br +close output file or pipe +.ti -.2i +\*(CL\*(FCfflush(\*(FR[\*(FIfile\^\*(FR]\*(FC)\*(FR +.br +flush any buffers associated +with the open output file or pipe \*(FIfile\*(FR.\*(CD +\*(CBIf \*(FIfile\fP is missing, then standard output is flushed. +If \*(FIfile\fP is the null string, then all open output files and pipes +are flushed \*(CR(not \*(NK)\*(CD +.ti -.2i +\*(FCprint\fP +.br +print the current record. The output record is terminated +with the value of \*(FCORS\fP +.ti -.2i +\*(FCprint \*(FIexpr-list\*(FR +.br +print expressions. Each expression is separated +by the value of \*(FCOFS\fP. The output record is +terminated with the value of \*(FCORS\fP +.ti -.2i +\*(FCprintf \*(FIfmt\*(FC, \*(FIexpr-list\*(FR +.br +format and print (see \fHPrintf Formats\fP, below) +.ti -.2i +\*(FCsystem(\*(FIcmd\*(FC)\*(FR +.br +execute the command \*(FIcmd\*(FR, +and return the exit status +\*(CR(may not be available on non-POSIX systems)\*(CD +.sp .5 +.in -.2i +I/O redirections may be used with both \*(FCprint\fP and \*(FCprintf\fP. +.sp .5 +.in +.2i +.ti -.2i +\*(CD\*(FCprint "hello" > \*(FIfile\*(FR +.br +Print data to \*(FIfile\fP. The first time the file is written to, it +will be truncated. Subsequent commands append data. +.ti -.2i +\*(FCprint "hello" >> \*(FIfile\*(FR +.br +Append data to \*(FIfile\fP. The previous contents of the file are not lost. +.ti -.2i +\*(FCprint "hello" | \*(FIcmd\*(FR +.br +Print data down a pipeline to \*(FIcmd\*(FR.\*(CX +.in -.2i +.EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0" + +.BT + + +.\" --- Printf Formats +.ES +.fi +\*(CDThe \*(FCprintf\fP statement and +\*(FCsprintf()\fP function +accept the following conversion specification formats: +.sp .5 +.nf +\*(FC%c\fP an \s-1ASCII\s+1 character +\*(FC%d\fP a decimal number (the integer part) +\*(FC%i\fP a decimal number (the integer part) +\*(FC%e\fP a floating point number of the form + \*(FC[\-]d.dddddde[+\^\-]dd\*(FR +\*(FC%E\fP like \*(FC%e\fP, but use \*(FCE\fP instead of \*(FCe\*(FR +\*(FC%f\fP a floating point number of the form + \*(FC[\-]ddd.dddddd\*(FR +\*(FC%g\fP use \*(FC%e\fP or \*(FC%f\fP, whichever is shorter, with + nonsignificant zeros suppressed +\*(FC%G\fP like \*(FC%g\fP, but use \*(FC%E\fP instead of \*(FC%e\*(FR +\*(FC%o\fP an unsigned octal number (the integer part) +\*(FC%s\fP a character string +\*(FC%x\fP an unsigned hexadecimal number (integer part) +\*(FC%X\fP like \*(FC%x\fP, but use \*(FCABCDEF\fP instead of \*(FCabcdef\*(FR +\*(FC%%\fP A single \*(FC%\fP character; no argument is converted +.sp .5 +.fi +Optional, additional parameters may lie between the \*(FC%\fP +and the control letter: +.sp .5 +.nf +\*(FC\-\fP left-justify the expression within its field +\*(FIspace\fP for numeric conversions, prefix positive values + with a space, and negative values with a + minus sign +\*(FC+\fP used before the \*(FIwidth\fP modifier means to always + supply a sign for numeric conversions, even if + the data to be formatted is positive. The \*(FC+\fP + overrides the space modifier +\*(FC#\fP use an ``alternate form'' for some control letters. + For \*(FC%o\*(FR, supply a leading zero. + For \*(FC%x\*(FR, and \*(FC%X\*(FR, supply a leading \*(FC0x\*(FR or \*(FC0X\*(FR for a + nonzero result. + For \*(FC%e\*(FR, \*(FC%E\*(FR, and \*(FC%f\*(FR, the result will always + contain a decimal point. + For \*(FC%g\*(FR, and \*(FC%G\*(FR, trailing zeros are not removed +\*(FC0\fP a leading zero acts as a flag, indicating output + should be padded with zeroes instead of spaces. + This applies even to non-numeric output formats. + Only has an effect when the field width is wider + than the value to be printed +\*(FIwidth\fP pad the field to this width. The field is normally + padded with spaces. If the \*(FC0\fP flag has been used, + pad with zeroes +\*(FC\&.\*(FIprec\*(FR specifies the precision to use when printing. + For the \*(FC%e\*(FR, \*(FC%E\*(FR, and \*(FC%f\*(FR formats, the number of + digits to print to the right of the decimal point. + For the \*(FC%g\*(FR and \*(FC%G\fP formats, the maximum + number of significant digits. + For the \*(FC%d\*(FR, \*(FC%o\*(FR, \*(FC%i\*(FR, \*(FC%u\*(FR, \*(FC%x\*(FR, and \*(FC%X\fP formats, the + minimum number of digits to print. + For the \*(FC%s\fP format, the maximum number of + characters to print +.sp .5 +.fi +The dynamic \*(FIwidth\fP and \*(FIprec\fP capabilities of the ANSI C +\*(FCprintf()\fP routines are supported. +A \*(FC*\fP in place of either the \*(FIwidth\fP or \*(FIprec\fP +specifications will cause their values to be taken from +the argument list to \*(FCprintf\fP or \*(FCsprintf()\*(FR.\*(CX +.EB "\s+2\f(HBPRINTF FORMATS\*(FR\s0" + + + +.BT + +.\" --- Special Filenames +.ES +.fi +\*(CDWhen doing I/O redirection from either \*(FCprint\fP +or \*(FCprintf\fP into a file, or via \*(FCgetline\fP +from a file, all three implementations of \*(FCawk\fP +recognize certain special filenames internally. These filenames +allow access to open file descriptors inherited from the +parent process (usually the shell). +These file names may also be used on the command line to name data files. +The filenames are: +.sp .5 +.nf +\*(FC"-"\fP standard input +\*(FC/dev/stdin\fP standard input \*(CR(not \*(MK)\*(CD +\*(FC/dev/stdout\fP standard output +\*(FC/dev/stderr\fP standard error output +.sp .5 +.fi +\*(CBThe following names are specific to \*(GK. +.sp .5 +.nf +\*(FC/dev/fd/\^\*(FIn\*(FR file associated with the open file descriptor \*(FIn\*(FR +.sp .5 +.fi +Other special filenames provide access to information about the running +\*(FCgawk\fP process. +The filenames are:\*(FR +.sp .5 +.nf +\*(FC/dev/pid\fP returns process ID of current process +\*(FC/dev/ppid\fP returns parent process ID of current process +\*(FC/dev/pgrpid\fP returns process group ID of current process +\*(FC/dev/user\fP returns a single newline-terminated record. + The fields are separated with spaces. + \*(FC$1\fP is the return value of \*(FIgetuid\*(FR(2), + \*(FC$2\fP is the return value of \*(FIgeteuid\*(FR(2), + \*(FC$3\fP is the return value of \*(FIgetgid\*(FR(2) , and + \*(FC$4\fP is the return value of \*(FIgetegid\*(FR(2). + Any additional fields are the group IDs returned + by \*(FIgetgroups\*(FR(2). Multiple groups may not be + supported on all systems +.sp .5 +.fi +.ig +\*(CRThese filenames are now obsolete. +Use the \*(FCPROCINFO\fP array to obtain the information they provide.\*(CL +.. +.\" BEGIN FOR 3.0.x +\*(CRThese filenames will become obsolete in \*(GK 3.1. +Be aware that you will have to change your programs.\*(CL +.\" END FOR 3.0.x +.EB "\s+2\f(HBSPECIAL FILENAMES\*(FR\s0" + + + + +.\" --- Builtin Numeric Functions +.ES +.nf +\*(CD\*(FCatan2(\*(FIy\*(FC, \*(FIx\*(FC)\*(FR returns the arctangent of \*(FIy/x\fP in radians +\*(FCcos(\*(FIexpr\*(FC)\*(FR the cosine of \*(FIexpr\fP, which is in radians +\*(FCexp(\*(FIexpr\*(FC)\*(FR the exponential function (\*(FIe \*(FC^ \*(FIx\*(FR) +\*(FCint(\*(FIexpr\*(FC)\*(FR truncates to integer +\*(FClog(\*(FIexpr\*(FC)\*(FR the natural logarithm function (base \*(FIe\^\*(FR) +\*(FCrand()\fP returns a random number between 0 and 1 +\*(FCsin(\*(FIexpr\*(FC)\*(FR the sine of \*(FIexpr\fP, which is in radians +\*(FCsqrt(\*(FIexpr\*(FC)\*(FR the square root function +\&\*(FCsrand(\*(FR[\*(FIexpr\^\*(FR]\*(FC)\*(FR uses \*(FIexpr\fP as a new seed for the random number + generator. If no \*(FIexpr\fP, the time of day is used. + Returns previous seed for the random number + generator\*(CX +.EB "\s+2\f(HBNUMERIC FUNCTIONS\*(FR\s0" + + +.BT + + +.\" --- Builtin String Functions +.ES +.fi +.in +.2i +.ti -.2i +\*(CB\*(FCgensub(\*(FIr\*(FC, \*(FIs\*(FC, \*(FIh \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR +.br +search the target string +\*(FIt\fP for matches of the regular expression \*(FIr\*(FR. If +\*(FIh\fP is a string beginning with \*(FCg\fP or \*(FCG\*(FR, +replace all matches of \*(FIr\fP with \*(FIs\*(FR. Otherwise, \*(FIh\fP +is a number indicating which match of \*(FIr\fP to replace. If no +\*(FIt\fP is supplied, \*(FC$0\fP is used instead. Within the +replacement text \*(FIs\*(FR, the sequence \*(FC\e\*(FIn\*(FR, +where \*(FIn\fP is a digit from 1 to 9, may be used to indicate just +the text that matched the \*(FIn\*(FR'th parenthesized subexpression. +The sequence \*(FC\e0\fP represents the entire matched text, as does +the character \*(FC&\*(FR. Unlike \*(FCsub()\fP and \*(FCgsub()\*(FR, +the modified string is returned as the result of the function, +and the original target string is \*(FInot\fP changed\*(CD +.ti -.2i +\*(FCgsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR +.br +for each substring matching the +regular expression \*(FIr\fP in the string \*(FIt\*(FR, substitute the +string \*(FIs\*(FR, and return the number of substitutions. If +\*(FIt\fP is not supplied, use \*(FC$0\*(FR. An \*(FC&\fP in the +replacement text is replaced with the text that was actually matched. +Use \*(FC\e&\fP to get a literal \*(FC&\*(FR. See \*(AM +for a fuller discussion of the rules for \*(FC&\*(FR's and backslashes +in the replacement text of \*(CB\*(FCgensub()\*(FR,\*(CD \*(FCsub()\*(FR, +and \*(FCgsub()\*(FR +.ti -.2i +\*(FCindex(\*(FIs\*(FC, \*(FIt\*(FC)\*(FR +.br +returns the index of the string +\*(FIt\fP in the string \*(FIs\*(FR, or 0 if \*(FIt\fP is not present +.ti -.2i +\*(FClength(\*(FR[\*(FIs\*(FR]\*(FC)\*(FR +.br +returns the length of the string +\*(FIs\*(FR, or the length of \*(FC$0\fP if \*(FIs\fP is not supplied +.ti -.2i +\*(FCmatch(\*(FIs\*(FC, \*(FIr\*(FC)\*(FR +.br +returns the position in +\*(FIs\fP where the regular expression \*(FIr\fP occurs, or 0 if +\*(FIr\fP is not present, and sets the values of \*(FCRSTART\fP +and \*(FCRLENGTH\*(FR +.ti -.2i +\*(FCsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr\*(FR]\*(FC)\*(FR +.br +splits the string +\*(FIs\fP into the array \*(FIa\fP on the regular expression \*(FIr\*(FR, +and returns the number of fields. If \*(FIr\fP is omitted, \*(FCFS\fP +is used instead. The array \*(FIa\fP is cleared first. +Splitting behaves identically to field splitting. +See \fHFields\fP, above +.ti -.2i +\*(FCsprintf(\*(FIfmt\*(FC, \*(FIexpr-list\*(FC)\*(FR +.br +prints \*(FIexpr-list\fP +according to \*(FIfmt\*(FR, and returns the resulting string +.ti -.2i +\*(FCsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR +.br +just like +\*(FCgsub()\*(FR, but only the first matching substring is replaced +.ti -.2i +\*(FCsubstr(\*(FIs\*(FC, \*(FIi \*(FR[\*(FC, \*(FIn\*(FR]\*(FC)\*(FR +.br +returns the at most +\*(FIn\*(FR-character substring of \*(FIs\fP starting at \*(FIi\*(FR. +If \*(FIn\fP is omitted, the rest of \*(FIs\fP is used +.ti -.2i +\*(FCtolower(\*(FIstr\*(FC)\*(FR +.br +returns a copy of the string \*(FIstr\*(FR, +with all the upper-case characters in \*(FIstr\fP translated to their +corresponding lower-case counterparts. Non-alphabetic characters are +left unchanged +.ti -.2i +\*(FCtoupper(\*(FIstr\*(FC)\*(FR +.br +returns a copy of the string \*(FIstr\*(FR, +with all the lower-case characters in \*(FIstr\fP translated to their +corresponding upper-case counterparts. Non-alphabetic characters are +left unchanged\*(CX +.in -.2i +.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0" + + + +.BT + + +.\" --- Builtin Time Functions +.ES +.fi +\*(CD\*(GK +provides the following functions for obtaining time stamps and +formatting them. +.sp .5 +.fi +.in +.2i +.ig +.ti -.2i +\*(FCmktime(\*(FIdatespec\*(FC)\*(FR +.br +turns \*(FIdatespec\fP into a time +stamp of the same form as returned by \*(FCsystime()\*(FR. +The \*(FIdatespec\fP is a string of the form +\*(FC"\*(FIYYYY MM DD HH MM SS\*(FC"\*(FR +.. +.ti -.2i +\*(FCstrftime(\*(FR[\*(FIformat \*(FR[\*(FC, \*(FItimestamp\*(FR]]\*(FC)\*(FR +.br +formats \*(FItimestamp\fP +according to the specification in \*(FIformat\*(FR. The +\*(FItimestamp\fP should be of the same form as returned by +\*(FCsystime()\*(FR. +If \*(FItimestamp\fP is missing, the current time of day is used. If +\*(FIformat\fP is missing, a default format equivalent to the output +of \*(FIdate\*(FR(1) will be used +.ti -.2i +\*(FCsystime()\fP +.br +returns the current time of day as the number of +seconds since the Epoch\*(CB +.in -.2i +.EB "\s+2\f(HBTIME FUNCTIONS\*(FR\s0" + + + +.\" --- User-defined Functions +.ES +.fi +\*(CDFunctions in AWK are defined as follows: +.sp .5 +.nf + \*(FCfunction \*(FIname\*(FC(\*(FIparameter list\*(FC) + { + \*(FIstatements + \*(FC}\*(FR +.sp .5 +.fi +Functions are executed when they are called from within expressions +in either patterns or actions. Actual parameters supplied in the function +call instantiate the formal parameters declared in the function. +Arrays are passed by reference, other variables are passed by value. +.sp .5 +Local variables are declared as extra parameters +in the parameter list. The convention is to separate local variables from +real parameters by extra spaces in the parameter list. For example: +.sp .5 +.nf + \*(FC# a & b are local + function f(p, q, a, b) + { + \&..... + } +.sp .3 + /abc/ { ... ; f(1, 2) ; ... }\*(FR +.fi +.sp .5 +The left parenthesis in a function call is required +to immediately follow the function name, +without any intervening white space. +This is to avoid a syntactic ambiguity with the concatenation operator. +This restriction does not apply to the built-in functions. +.sp .5 +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 +\*(CLThe word +\*(FCfunc\fP +may be used in place of +\*(FCfunction\*(FR. +\*(CRNote: This usage is deprecated.\*(CX +.EB "\s+2\f(HBUSER-DEFINED FUNCTIONS\*(FR\s0" + + + +.\" --- Bug Reports +.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 +.EB "\s+2\f(HBBUG REPORTS\*(FR\s0" + +.BT + +.\" --- Environment Variables +.ES +.fi +\*(CDThe environment variable \*(FCAWKPATH\fP specifies a search path to use +when finding source files named with the \*(FC\-f\fP +option. +The default path is +\*(FC".:/usr/local/share/awk"\*(FR, +if this variable does not exist. +(The actual directory may vary, +depending upon how \*(GK was built and installed.) +If a file name given to the \*(FC\-f\fP option contains a ``/'' character, +no path search is performed. +.sp .5 +If \*(FCPOSIXLY_CORRECT\fP exists in the environment, then \*(GK +behaves exactly as if \*(FC\-\^\-posix\fP had been specified on the +command line.\*(CB +.EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0" + +.\" --- Historical Features +.ES +.fi +\*(CD\*(GK supports two features of historical AWK implementations. +First, it is possible to call the \*(FClength()\fP +built-in function not only with no argument, but even without parentheses. +This feature is marked as ``deprecated'' in the POSIX standard, and \*(GK +will issue a warning about its use if \*(FC\-\^\-lint\fP +is specified on the command line. +.sp .5 +The other feature is the use of \*(FCcontinue\fP +or \*(FCbreak\fP statements outside the body of a +\*(FCwhile\*(FR, \*(FCfor\*(FR, or \*(FCdo\fP loop. +Historical AWK implementations have treated such usage as +equivalent to the \*(FCnext\fP statement. +\*(GK will support this usage if \*(FC\-\^\-traditional\fP +has been specified.\*(CB +.EB "\s+2\f(HBHISTORICAL FEATURES\*(FR\s0" + + +.\" --- FTP Information +.ES +.nf +\*(CDHost: \*(FCftp.gnu.ai.mit.edu\*(FR +File: \*(FC/pub/gnu/gawk-3.0.1.tar.gz\fP + GNU \*(AK (\*(GK). There may be a later version +.sp .5 +Host: \*(FCnetlib.bell-labs.com\*(FR +File: \*(FC/netlib/research/awk.bundle.Z\fP + \*(NK. This version requires an ANSI C compiler; + GCC (the GNU C compiler) works well +.sp .5 +Host: \*(FCftp.whidbey.net\*(FR +File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP + Michael Brennan's \*(MK. There may be a newer version\*(CX +.EB "\s+2\f(HBFTP INFORMATION\*(FR\s0" + +.\" --- Copying Permissions +.ES +.fi +\*(CDCopyright \(co 1996 Free Software Foundation, Inc. +.sp .5 +Permission is granted to make and distribute verbatim copies of this +reference card provided the copyright notice and this permission notice +are preserved on all copies. +.sp .5 +Permission is granted to copy and distribute modified versions of this +reference card under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.sp .5 +Permission is granted to copy and distribute translations of this +reference card into another language, under the above conditions for +modified versions, except that this permission notice may be stated in a +translation approved by the Foundation.\*(CX +.EB "\s+2\f(HBCOPYING PERMISSIONS\*(FR\s0" +.BT diff --git a/doc/awkforai.txt b/doc/awkforai.txt new file mode 100644 index 00000000..3fca3204 --- /dev/null +++ b/doc/awkforai.txt @@ -0,0 +1,150 @@ +Draft for ACM SIGPLAN Patterns (Language Trends) + +1996 + +Why GAWK for AI? + +Ronald P. Loui + +Most people are surprised when I tell them what language we use in our +undergraduate AI programming class. That's understandable. We use +GAWK. GAWK, Gnu's version of Aho, Weinberger, and Kernighan's old +pattern scanning language isn't even viewed as a programming language by +most people. Like PERL and TCL, most prefer to view it as a "scripting +language." It has no objects; it is not functional; it does no built-in +logic programming. Their surprise turns to puzzlement when I confide +that (a) while the students are allowed to use any language they want; +(b) with a single exception, the best work consistently results from +those working in GAWK. (footnote: The exception was a PASCAL +programmer who is now an NSF graduate fellow getting a Ph.D. in +mathematics at Harvard.) Programmers in C, C++, and LISP haven't even +been close (we have not seen work in PROLOG or JAVA). + +Why GAWK? + +There are some quick answers that have to do with the pragmatics of +undergraduate programming. Then there are more instructive answers that +might be valuable to those who debate programming paradigms or to those +who study the history of AI languages. And there are some deep +philosophical answers that expose the nature of reasoning and symbolic +AI. I think the answers, especially the last ones, can be even more +surprising than the observed effectiveness of GAWK for AI. + +First it must be confessed that PERL programmers can cobble together AI +projects well, too. Most of GAWK's attractiveness is reproduced in +PERL, and the success of PERL forebodes some of the success of GAWK. +Both are powerful string-processing languages that allow the programmer +to exploit many of the features of a UNIX environment. Both provide +powerful constructions for manipulating a wide variety of data in +reasonably efficient ways. Both are interpreted, which can reduce +development time. Both have short learning curves. The GAWK manual can +be consumed in a single lab session and the language can be mastered by +the next morning by the average student. GAWK's automatic +initialization, implicit coercion, I/O support and lack of pointers +forgive many of the mistakes that young programmers are likely to make. +Those who have seen C but not mastered it are happy to see that GAWK +retains some of the same sensibilities while adding what must be +regarded as spoonsful of syntactic sugar. Some will argue that +PERL has superior functionality, but for quick AI applications, the +additional functionality is rarely missed. In fact, PERL's terse syntax +is not friendly when regular expressions begin to proliferate and +strings contain fragments of HTML, WWW addresses, or shell commands. +PERL provides new ways of doing things, but not necessarily ways of +doing new things. + +In the end, despite minor difference, both PERL and GAWK minimize +programmer time. Neither really provides the programmer the setting in +which to worry about minimizing run-time. + +There are further simple answers. Probably the best is the fact that +increasingly, undergraduate AI programming is involving the Web. Oren +Etzioni (University of Washington, Seattle) has for a while been arguing +that the "softbot" is replacing the mechanical engineers' robot as the +most glamorous AI testbed. If the artifact whose behavior needs to be +controlled in an intelligent way is the software agent, then a language +that is well-suited to controlling the software environment is the +appropriate language. That would imply a scripting language. If the +robot is KAREL, then the right language is "turn left; turn right." If +the robot is Netscape, then the right language is something that can +generate "netscape -remote 'openURL(http://cs.wustl.edu/~loui)'" with +elan. + +Of course, there are deeper answers. Jon Bentley found two pearls in +GAWK: its regular expressions and its associative arrays. GAWK asks +the programmer to use the file system for data organization and the +operating system for debugging tools and subroutine libraries. There is +no issue of user-interface. This forces the programmer to return to the +question of what the program does, not how it looks. There is no time +spent programming a binsort when the data can be shipped to /bin/sort +in no time. (footnote: I am reminded of my IBM colleague Ben Grosof's +advice for Palo Alto: Don't worry about whether it's highway 101 or 280. +Don't worry if you have to head south for an entrance to go north. Just +get on the highway as quickly as possible.) + +There are some similarities between GAWK and LISP that are illuminating. +Both provided a powerful uniform data structure (the associative array +implemented as a hash table for GAWK and the S-expression, or list of +lists, for LISP). Both were well-supported in their environments (GAWK +being a child of UNIX, and LISP being the heart of lisp machines). Both +have trivial syntax and find their power in the programmer's willingness +to use the simple blocks to build a complex approach. + +Deeper still, is the nature of AI programming. AI is about +functionality and exploratory programming. It is about bottom-up design +and the building of ambitions as greater behaviors can be demonstrated. +Woe be to the top-down AI programmer who finds that the bottom-level +refinements, "this subroutine parses the sentence," cannot actually be +implemented. Woe be to the programmer who perfects the data structures +for that heapsort when the whole approach to the high-level problem +needs to be rethought, and the code is sent to the junkheap the next day. + +AI programming requires high-level thinking. There have always been a few +gifted programmers who can write high-level programs in assembly language. +Most however need the ambient abstraction to have a higher floor. + +Now for the surprising philosophical answers. First, AI has discovered +that brute-force combinatorics, as an approach to generating intelligent +behavior, does not often provide the solution. Chess, neural nets, and +genetic programming show the limits of brute computation. The +alternative is clever program organization. (footnote: One might add +that the former are the AI approaches that work, but that is easily +dismissed: those are the AI approaches that work in general, precisely +because cleverness is problem-specific.) So AI programmers always want +to maximize the content of their program, not optimize the efficiency +of an approach. They want minds, not insects. Instead of enumerating +large search spaces, they define ways of reducing search, ways of +bringing different knowledge to the task. A language that maximizes +what the programmer can attempt rather than one that provides tremendous +control over how to attempt it, will be the AI choice in the end. + +Second, inference is merely the expansion of notation. No matter whether +the logic that underlies an AI program is fuzzy, probabilistic, deontic, +defeasible, or deductive, the logic merely defines how strings can be +transformed into other strings. A language that provides the best +support for string processing in the end provides the best support for +logic, for the exploration of various logics, and for most forms of +symbolic processing that AI might choose to call "reasoning" instead of +"logic." The implication is that PROLOG, which saves the AI programmer +from having to write a unifier, saves perhaps two dozen lines of GAWK +code at the expense of strongly biasing the logic and representational +expressiveness of any approach. + +I view these last two points as news not only to the programming language +community, but also to much of the AI community that has not reflected on +the past decade's lessons. + +In the puny language, GAWK, which Aho, Weinberger, and Kernighan thought +not much more important than grep or sed, I find lessons in AI's trends, +AI's history, and the foundations of AI. What I have found not only +surprising but also hopeful, is that when I have approached the AI +people who still enjoy programming, some of them are not the least bit +surprised. + + +R. Loui (loui@ai.wustl.edu) is Associate Professor of Computer Science, +at Washington University in St. Louis. He has published in AI Journal, +Computational Intelligence, ACM SIGART, AI Magazine, AI and Law, the ACM +Computing Surveys Symposium on AI, Cognitive Science, Minds and +Machines, Journal of Philosophy, and is on this year's program +committees for AAAI (National AI conference) and KR (Knowledge +Representation and Reasoning). diff --git a/doc/cardfonts b/doc/cardfonts new file mode 100644 index 00000000..66367eef --- /dev/null +++ b/doc/cardfonts @@ -0,0 +1,37 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" cardfonts --- this file sets the fonts to use for the reference card +.\" +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of +.\" this reference card provided the copyright notice and this permission +.\" notice are preserved on all copies. +.\" +.\" Permission is granted to process this file through troff and print the +.\" results, provided the printed document carries copying permission +.\" notice identical to this one except for the removal of this paragraph +.\" (this paragraph not being relevant to the printed reference card). +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" reference card under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" reference card into another language, under the above conditions for +.\" modified versions, except that this permission notice may be stated in +.\" a translation approved by the Foundation. +.\" +.ig +Strings for inline font change. +FR - font roman +FI - font italic +FC - font courier +.. +.ds FR \fR +.ds FI \fI +.ds FC \f(CB +.ds RN Times Roman +.ds IN Times Italic +.ds CN Courier Bold +.ds AM \fIThe GNU Awk User's Guide\fP diff --git a/doc/colors b/doc/colors new file mode 100644 index 00000000..e600f64c --- /dev/null +++ b/doc/colors @@ -0,0 +1,42 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" This file sets the colors to use. +.\" +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of +.\" this reference card provided the copyright notice and this permission +.\" notice are preserved on all copies. +.\" +.\" Permission is granted to process this file through troff and print the +.\" results, provided the printed document carries copying permission +.\" notice identical to this one except for the removal of this paragraph +.\" (this paragraph not being relevant to the printed reference card). +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" reference card under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" reference card into another language, under the above conditions for +.\" modified versions, except that this permission notice may be stated in +.\" a translation approved by the Foundation. +.\" +.ig +Strings for inline color change. +CR - color red +CG - color green +CL - color light blue +CB - color blue +CD - color dark, i.e. black +CX - color boX, i.e. for the surrounding boxes (red for now) +.. +.ds CR \X'ps: exec .768 0 .047 setrgbcolor' +.ds CG \X'ps: exec 0 .819 .259 setrgbcolor' +.\" this is deepskyblue3, pretty good +...ds CL \X'ps: exec 0 .604 .804 setrgbcolor' +.\" this is deepskyblue2, even better, use this for now +.ds CL \X'ps: exec 0 .698 .933 setrgbcolor' +.ds CB \X'ps: exec 0 .219 .941 setrgbcolor' +.ds CD \X'ps: exec 0 0 0 setrgbcolor' +.ds CX \*(CG @@ -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 28 1995" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Dec 09 1996" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -63,12 +63,7 @@ options are supplied via arguments to the .B \-W option. Multiple .B \-W -options may be supplied, or multiple arguments may be supplied together -if they are separated by commas, or enclosed in quotes and separated -by white space. -Case is ignored in arguments to the -.B \-W -option. +options may be supplied Each .B \-W option has a corresponding long option, as detailed below. @@ -125,10 +120,10 @@ Multiple options may be used. .TP .PD 0 -.BI \-mf= NNN +.BI \-mf " NNN" .TP .PD -.BI \-mr= NNN +.BI \-mr " NNN" Set various memory limits to the value .IR NNN . The @@ -182,7 +177,7 @@ below, for more information. .PD .B \-\^\-copyright Print the short version of the GNU copyright information message on -the error output. +the standard output, and exits successfully. .TP .PD 0 .B "\-W help" @@ -196,7 +191,7 @@ the error output. .PD .B \-\^\-usage Print a relatively short summary of the available options on -the error output. +the standard output. (Per the .IR "GNU Coding Standards" , these options cause an immediate, successful exit.) @@ -245,6 +240,11 @@ mode, with the following additional restrictions: escape sequences are not recognized. .TP \(bu +Only space and tab act as field separators when +.B FS +is set to a single space, newline does not. +.TP +\(bu The synonym .B func for the keyword @@ -306,14 +306,6 @@ and options) with source code entered on the command line. It is intended primarily for medium to large AWK programs used in shell scripts. -.sp .5 -The -.B "\-W source=" -form of this option uses the rest of the command line argument for -.IR program-text ; -no other options to -.B \-W -will be recognized in the same argument. .TP .PD 0 .B "\-W version" @@ -322,7 +314,7 @@ will be recognized in the same argument. .B \-\^\-version Print version information for this particular copy of .I gawk -on the error output. +on the standard output. This is useful mainly for knowing if the current copy of .I gawk on your system @@ -504,7 +496,10 @@ is expected to be a full regular expression. In the special case that .B FS is a single space, fields are separated -by runs of spaces and/or tabs. +by runs of spaces and/or tabs and/or newlines. +(But see the discussion of +.BR \-\-posix , +below). Note that the value of .B IGNORECASE (see below) will also affect how fields are split when @@ -561,6 +556,12 @@ cause the value of to be recomputed, with the fields being separated by the value of .BR OFS . References to negative numbered fields cause a fatal error. +Decrementing +.B NF +causes the values of fields past the new value to be lost, and the value of +.B $0 +to be recomputed, with the fields being separated by the value of +.BR OFS . .SS Built-in Variables .PP .IR Gawk 's @@ -1017,8 +1018,7 @@ character list, matches any of the characters .TP .BI [^ abc... ] negated character list, matches any character except -.I abc... -and newline. +.IR abc... . .TP .IB r1 | r2 alternation: matches either @@ -1203,16 +1203,23 @@ or .BR h . .TP Equivalence Classes -An equivalence class is a list of equivalent characters enclosed in +An equivalence class is a locale-specific name for a list of +characters that are equivalent. The name is enclosed in .B [= and .BR =] . -Thus, -.B [[=ee\`=]] -is regexp that matches either +For example, the name .B e +might be used to represent all of +``e,'' ``e\`,'' and ``e\`.'' +In this case, +.B [[=e]] +is a regexp +that matches any of + .BR e , + .BR e\' , or -.B e\` . + .BR e\` . .PP These features are very valuable in non-English speaking locales. The library functions that @@ -1415,7 +1422,7 @@ set Set .I var from next input record; set -.BR NF , +.BR NR , .BR FNR . .TP .BI getline " var" " <" file @@ -1800,7 +1807,9 @@ returns the arctangent of in radians. .TP .BI cos( expr ) -returns the cosine in radians. +returns the cosine of +.IR expr , +which is in radians. .TP .BI exp( expr ) the exponential function. @@ -1815,7 +1824,9 @@ the natural logarithm function. returns a random number between 0 and 1. .TP .BI sin( expr ) -returns the sine in radians. +returns the sine of +.IR expr , +which is in radians. .TP .BI sqrt( expr ) the square root function. @@ -2387,10 +2398,19 @@ argument to the option is ``t'', then .B FS will be set to the tab character. +Note that typing +.B "gawk \-F\et \&..." +simply causes the shell to quote the ``t,'', and does not pass +``\et'' to the +.B \-F +option. Since this is a rather ugly special case, it is not the default behavior. This behavior also does not occur if .B \-\^\-posix has been specified. +To really get a tab character as the field separator, it is best to use +quotes: +.BR "gawk \-F'\et' \&..." . .ig .PP If @@ -2512,13 +2532,10 @@ Syntactically invalid single character programs tend to overflow the parse stack, generating a rather unhelpful message. Such programs are surprisingly difficult to diagnose in the completely general case, and the effort to do so really is not worth it. -.PP -The word ``GNU'' is incorrectly capitalized in at least one file -in the source code. .SH VERSION INFORMATION This man page documents .IR gawk , -version 3.0. +version 3.0.1. .SH AUTHORS The original version of \*(UX .I awk @@ -2580,3 +2597,25 @@ addresses given above. 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. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. diff --git a/doc/gawk.texi b/doc/gawk.texi index 6227ac32..75bf11f0 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -1,18 +1,17 @@ \input texinfo @c -*-texinfo-*- @c %**start of header (This is for running Texinfo on a region.) @setfilename gawk.info -@settitle AWK Language Programming +@settitle The GNU Awk User's Guide @c %**end of header (This is for running Texinfo on a region.) -@ignore +@c inside ifinfo for older versions of texinfo.tex @ifinfo -@format -START-INFO-DIR-ENTRY +@c I hope this is the right category +@dircategory Programming Languages +@direntry * Gawk: (gawk.info). A Text Scanning and Processing Language. -END-INFO-DIR-ENTRY -@end format +@end direntry @end ifinfo -@end ignore @c @set xref-automatic-section-title @c @set DRAFT @@ -20,10 +19,12 @@ END-INFO-DIR-ENTRY @c The following information should be updated here only! @c This sets the edition of the document, the version of gawk it @c applies to, and when the document was updated. -@set TITLE AWK Language Programming -@set EDITION 1.0 +@set TITLE The GNU Awk User's Guide +@set SUBTITLE Effective AWK Programming +@set EDITION 1.0.1 @set VERSION 3.0 -@set UPDATE-MONTH January 1996 +@set PATCHLEVEL 1 +@set UPDATE-MONTH December 1996 @iftex @set DOCUMENT book @end iftex @@ -33,9 +34,9 @@ END-INFO-DIR-ENTRY @ignore Some comments on the layout for TeX. -1. Use the texinfo.tex from the gawk distribution. It contains fixes that +1. Use at least texinfo.tex 2.159. It contains fixes that are needed to get the footings for draft mode to not appear. -2. I have done A LOT of work to make this look good. There `@page' commands +2. I have done A LOT of work to make this look good. There are `@page' commands and use of `@group ... @end group' in a number of places. If you muck with anything, it's your responsibility not to break the layout. @end ignore @@ -63,7 +64,7 @@ Some comments on the layout for TeX. @smallbook @iftex -@cropmarks +@c @cropmarks @end iftex @ifinfo @@ -71,9 +72,9 @@ This file documents @code{awk}, a program that you can use to select particular records in a file and perform operations upon them. This is Edition @value{EDITION} of @cite{@value{TITLE}}, -for the @value{VERSION} version of the GNU implementation of AWK. +for the @value{VERSION}.@value{PATCHLEVEL} version of the GNU implementation of AWK. -Copyright (C) 1989, 1991 - 1996 Free Software Foundation, Inc. +Copyright (C) 1989, 1991, 92, 93, 96 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -101,7 +102,7 @@ by the Foundation. @titlepage @title @value{TITLE} -@subtitle A User's Guide for GNU AWK +@subtitle @value{SUBTITLE} @subtitle Edition @value{EDITION} @subtitle @value{UPDATE-MONTH} @author Arnold D. Robbins @@ -135,11 +136,11 @@ Corporation. @* Registered Trademark of Paramount Pictures Corporation. @* @c sorry, i couldn't resist @sp 3 -Copyright @copyright{} 1989, 1991 - 1996 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1991, 92, 93, 96 Free Software Foundation, Inc. @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}}, @* -for the @value{VERSION} (or later) version of the GNU implementation of AWK. +for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU implementation of AWK. @sp 2 Published by the Free Software Foundation @* @@ -180,6 +181,8 @@ Cover art by Etienne Suvasa. @center @i{To Chana, for the joy you bring us.} @sp @center @i{To Rivka, for the exponential increase.} +@sp +@center @i{To Nachum, for the added dimension.} @page @w{ } @page @@ -188,8 +191,8 @@ Cover art by Etienne Suvasa. @iftex @headings off -@evenheading @thispage@ @ @ @b{@thistitle} @| @| -@oddheading @| @| @b{@thischapter}@ @ @ @thispage +@evenheading @thispage@ @ @ @strong{@thistitle} @| @| +@oddheading @| @| @strong{@thischapter}@ @ @ @thispage @ifset DRAFT @evenfooting @today{} @| @emph{DRAFT!} @| Please Do Not Redistribute @oddfooting Please Do Not Redistribute @| @emph{DRAFT!} @| @today{} @@ -206,7 +209,7 @@ This file documents @code{awk}, a program that you can use to select particular records in a file and perform operations upon them. This is Edition @value{EDITION} of @cite{@value{TITLE}}, @* -for the @value{VERSION} version of the GNU implementation @* +for the @value{VERSION}.@value{PATCHLEVEL} version of the GNU implementation @* of AWK. @end ifinfo @@ -420,6 +423,8 @@ of AWK. function. * Assert Function:: A function for assertions in @code{awk} programs. +* Round Function:: A function for rounding if @code{sprintf} does + not do it correctly. * Ordinal Functions:: Functions for using characters as numbers and vice versa. * Join Function:: A function to join an array into a string. @@ -457,7 +462,7 @@ of AWK. * SVR4:: Minor changes between System V Releases 3.1 and 4. * POSIX:: New features from the POSIX standard. -* BTL:: New features from the AT&T Bell Laboratories +* BTL:: New features from the Bell Laboratories version of @code{awk}. * POSIX/GNU:: The extensions in @code{gawk} not in POSIX @code{awk}. @@ -521,6 +526,8 @@ of AWK. @center To Chana, for the joy you bring us. @sp 1 @center To Rivka, for the exponential increase. +@sp 1 +@center To Nachum, for the added dimension. @end ifinfo @node Preface, What Is Awk, Top, Top @@ -534,7 +541,7 @@ how you can use it effectively. You should already be familiar with basic system commands, such as @code{cat} and @code{ls},@footnote{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} and basic shell +be familiar with the ideas of I/O redirection and pipes.} and basic shell facilities, such as Input/Output (I/O) redirection and pipes. Implementations of the @code{awk} language are available for many different @@ -587,6 +594,7 @@ performance improvements, standards compliance, and occasionally, new features. @unnumberedsec The GNU Project and This Book @cindex Free Software Foundation +@cindex Stallman, Richard The Free Software Foundation (FSF) is a non-profit organization dedicated to the production and distribution of freely distributable software. It was founded by Richard M.@: Stallman, the author of the original @@ -677,6 +685,7 @@ problem reports electronically, or write to me in care of the FSF. @node Acknowledgements, , Manual History, Preface @unnumberedsec Acknowledgements +@cindex Stallman, Richard I would like to acknowledge Richard M.@: Stallman, for his vision of a better world, and for his courage in founding the FSF and starting the GNU project. @@ -1196,9 +1205,6 @@ reliable since there are no other files to misplace. @ref{One-liners, , Useful One Line Programs}, presents several short, self-contained programs. -@iftex -@page -@end iftex As an interesting side point, the command @example @@ -1343,7 +1349,7 @@ BEGIN @{ print "Don't Panic!" @} @noindent After making this file executable (with the @code{chmod} utility), you can simply type @samp{advice} -at the shell, and the system will arrange to run @code{awk} @footnote{The +at the shell, and the system will arrange to run @code{awk}@footnote{The line beginning with @samp{#!} 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 @@ -1353,8 +1359,10 @@ argument list will either be options to @code{awk}, or data files, or both.} as if you had typed @samp{awk -f advice}. @example +@group $ advice @print{} Don't Panic! +@end group @end example @noindent @@ -1695,6 +1703,28 @@ begin on the same line as the pattern. To have the pattern and action on separate lines, you @emph{must} use backslash continuation---there is no other way. +@cindex backslash continuation and comments +@cindex comments and backslash continuation +Note that backslash continuation and comments do not mix. As soon +as @code{awk} sees the @samp{#} that starts a comment, it ignores +@emph{everything} on the rest of the line. For example: + +@example +@group +$ gawk 'BEGIN @{ print "dont panic" # a friendly \ +> BEGIN rule +> @}' +@error{} gawk: cmd. line:2: BEGIN rule +@error{} gawk: cmd. line:2: ^ parse error +@end group +@end example + +@noindent +Here, it looks like the backslash would continue the comment onto the +next line. However, the backslash-newline combination is never even +noticed, since it is ``hidden'' inside the comment. Thus, the +@samp{BEGIN} is noted as a syntax error. + @cindex multiple statements on one line When @code{awk} statements within one rule are short, you might want to put more than one of them on a line. You do this by separating the statements @@ -1840,10 +1870,10 @@ This program prints a sorted list of the login names of all users. @item awk 'END @{ print NR @}' data This program counts lines in a file. -@item awk 'NR % 2' data +@item awk 'NR % 2 == 0' data This program prints the even numbered lines in the data file. If you were to use the expression @samp{NR % 2 == 1} instead, -it would print the odd number lines. +it would print the odd numbered lines. @end table @node Regexp, Reading Files, One-liners, Top @@ -2001,9 +2031,6 @@ Here is a table of all the escape sequences used in @code{awk}, and what they represent. Unless noted otherwise, all of these escape sequences apply to both string constants and regexp constants. -@iftex -@page -@end iftex @c @cartouche @table @code @item \\ @@ -2151,9 +2178,6 @@ the very first step in processing regexps. Here is a table of metacharacters. All characters that are not escape sequences and that are not listed in the table stand for themselves. -@iftex -@page -@end iftex @table @code @item \ This is used to suppress the special meaning of a character when @@ -2166,6 +2190,8 @@ matching. For example: @noindent matches the character @samp{$}. +@c NEEDED +@page @cindex anchors in regexps @cindex regexp, anchors @item ^ @@ -2345,14 +2371,7 @@ These apply to non-ASCII character sets, which can have single symbols (called @dfn{collating elements}) that are represented with more than one character, as well as several characters that are equivalent for @dfn{collating}, or sorting, purposes. (E.g., in French, a plain ``e'' -and a grave-accented -@iftex -``@`e'' -@end iftex -@ifinfo -``e'' -@end ifinfo -are equivalent.) +and a grave-accented ``@`e'' are equivalent.) @table @asis @cindex collating symbols @@ -2364,15 +2383,12 @@ then @code{[[.ch.]]} is a regexp that matches this collating element, while @cindex equivalence classes @item Equivalence Classes -An @dfn{equivalence class} is a list of equivalent characters enclosed in +An @dfn{equivalence class} is a locale-specific name for a list of +characters that are equivalent. The name is enclosed in @samp{[=} and @samp{=]}. -@iftex -Thus, @code{[[=e@`e=]]} is regexp that matches either @samp{e} or @samp{@`e}. -@end iftex -@ifinfo -Because Info files use plain ASCII characters, it is not possible to present -a realistic equivalence class example here. -@end ifinfo +For example, the name @samp{e} might be used to represent all of +``e,'' ``@`e,'' and ``@'e.'' In this case, @code{[[=e]]} is a regexp +that matches any of @samp{e}, @samp{@'e}, or @samp{@`e}. @end table These features are very valuable in non-English speaking locales. @@ -2387,7 +2403,7 @@ they do not recognize collating symbols or equivalence classes. @item [^ @dots{}] This is a @dfn{complemented character list}. The first character after the @samp{[} @emph{must} be a @samp{^}. It matches any characters -@emph{except} those in the square brackets, or newline. For example: +@emph{except} those in the square brackets. For example: @example [^0-9] @@ -3111,8 +3127,10 @@ When @code{awk} reads an input record, the record is automatically separated or @dfn{parsed} by the interpreter into chunks called @dfn{fields}. By default, fields are separated by whitespace, like words in a line. -Whitespace in @code{awk} means any string of one or more spaces and/or -tabs; other characters such as newline, formfeed, and so on, that are +Whitespace in @code{awk} means any string of one or more spaces, +tabs or newlines;@footnote{In POSIX @code{awk}, newlines are not +considered whitespace for separating fields.} other characters such as +formfeed, and so on, that are considered whitespace by other languages are @emph{not} considered whitespace by @code{awk}. @@ -3346,8 +3364,8 @@ else should print @samp{everything is normal}, because @code{NF+1} is certain to be out of range. (@xref{If Statement, ,The @code{if}-@code{else} Statement}, for more information about @code{awk}'s @code{if-else} statements. -@xref{Typing and Comparison, ,Variable Typing and Comparison Expressions}, for more information -about the @samp{!=} operator.) +@xref{Typing and Comparison, ,Variable Typing and Comparison Expressions}, +for more information about the @samp{!=} operator.) It is important to note that making an assignment to an existing field will change the @@ -3381,6 +3399,17 @@ The intervening field, @code{$5} is created with an empty value (indicated by the second pair of adjacent colons), and @code{NF} is updated with the value six. +Finally, decrementing @code{NF} will lose the values of the fields +after the new value of @code{NF}, and @code{$0} will be recomputed. +Here is an example: + +@example +$ echo a b c d e f | ../gawk '@{ print "NF =", NF; +> NF = 3; print $0 @}' +@print{} NF = 6 +@print{} a b c +@end example + @node Field Separators, Constant Size, Changing Fields, Reading Files @section Specifying How Fields are Separated @@ -3481,7 +3510,7 @@ As you know, normally, Normally, @end ifinfo fields are separated by whitespace sequences -(spaces and tabs), not by single spaces: two spaces in a row do not +(spaces, tabs and newlines), not by single spaces: two spaces in a row do not delimit an empty field. The default value of the field separator @code{FS} is a string containing a single space, @w{@code{" "}}. If this value were interpreted in the usual way, each space character would separate @@ -3531,12 +3560,13 @@ bracket). This regular expression matches a single space and nothing else (@pxref{Regexp, ,Regular Expressions}). There is an important difference between the two cases of @samp{FS = @w{" "}} -(a single space) and @samp{FS = @w{"[ \t]+"}} (left bracket, space, backslash, -``t'', right bracket, which is a regular expression -matching one or more spaces or tabs). For both values of @code{FS}, fields -are separated by runs of spaces and/or tabs. However, when the value of -@code{FS} is @w{@code{" "}}, @code{awk} will first strip leading and trailing -whitespace from the record, and then decide where the fields are. +(a single space) and @samp{FS = @w{"[ \t\n]+"}} (left bracket, space, +backslash, ``t'', backslash, ``n'', right bracket, which is a regular +expression matching one or more spaces, tabs, or newlines). For both +values of @code{FS}, fields are separated by runs of spaces, tabs +and/or newlines. However, when the value of @code{FS} is @w{@code{" +"}}, @code{awk} will first strip leading and trailing whitespace from +the record, and then decide where the fields are. For example, the following pipeline prints @samp{b}: @@ -4078,11 +4108,11 @@ can be used to read input under your explicit control. * Plain Getline:: Using @code{getline} with no arguments. * Getline/Variable:: Using @code{getline} into a variable. * Getline/File:: Using @code{getline} from a file. -* Getline/Variable/File:: Using @code{getline} into a variable from a - file. +* Getline/Variable/File:: Using @code{getline} into a variable from a + file. * Getline/Pipe:: Using @code{getline} from a pipe. -* Getline/Variable/Pipe:: Using @code{getline} into a variable from a - pipe. +* Getline/Variable/Pipe:: Using @code{getline} into a variable from a + pipe. * Getline Summary:: Summary Of @code{getline} Variants. @end menu @@ -4258,6 +4288,14 @@ Since the main input stream is not used, the values of @code{NR} and the normal manner, so the values of @code{$0} and other fields are changed. So is the value of @code{NF}. +@c Thanks to Paul Eggert for initial wording here +According to POSIX, @samp{getline < @var{expression}} is ambiguous if +@var{expression} contains unparenthesized operators other than +@samp{$}; for example, @samp{getline < dir "/" file} is ambiguous +because the concatenation operator is not parenthesized, and you should +write it as @samp{getline < (dir "/" file)} if you want your program +to be portable to other @code{awk} implementations. + @node Getline/Variable/File, Getline/Pipe, Getline/File, Getline @subsection Using @code{getline} Into a Variable from a File @@ -4270,6 +4308,16 @@ In this version of @code{getline}, none of the built-in variables are changed, and the record is not split into fields. The only variable changed is @var{var}. +@ifinfo +@c Thanks to Paul Eggert for initial wording here +According to POSIX, @samp{getline @var{var} < @var{expression}} is ambiguous if +@var{expression} contains unparenthesized operators other than +@samp{$}; for example, @samp{getline < dir "/" file} is ambiguous +because the concatenation operator is not parenthesized, and you should +write it as @samp{getline < (dir "/" file)} if you want your program +to be portable to other @code{awk} implementations. +@end ifinfo + For example, the following program copies all the input files to the output, except for records that say @w{@samp{@@include @var{filename}}}. Such a record is replaced by the contents of the file @@ -4341,6 +4389,8 @@ each one. @c Exercise!! @c This example is unrealistic, since you could just use system +@c NEEDED +@page Given the input: @example @@ -4377,6 +4427,14 @@ This variation of @code{getline} splits the record into fields, sets the value of @code{NF} and recomputes the value of @code{$0}. The values of @code{NR} and @code{FNR} are not changed. +@c Thanks to Paul Eggert for initial wording here +According to POSIX, @samp{@var{expression} | getline} is ambiguous if +@var{expression} contains unparenthesized operators other than +@samp{$}; for example, @samp{"echo " "date" | getline} is ambiguous +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. + @node Getline/Variable/Pipe, Getline Summary, Getline/Pipe, Getline @subsection Using @code{getline} Into a Variable from a Pipe @@ -4400,6 +4458,16 @@ awk 'BEGIN @{ In this version of @code{getline}, none of the built-in variables are changed, and the record is not split into fields. +@ifinfo +@c Thanks to Paul Eggert for initial wording here +According to POSIX, @samp{@var{expression} | getline @var{var}} is ambiguous if +@var{expression} contains unparenthesized operators other than +@samp{$}; for example, @samp{"echo " "date" | getline @var{var}} is ambiguous +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. +@end ifinfo + @node Getline Summary, , Getline/Variable/Pipe, Getline @subsection Summary of @code{getline} Variants @@ -4417,12 +4485,22 @@ program may have open to just one! In @code{gawk}, there is no such limit. You can open as many pipelines as the underlying operating system will permit. +@vindex FILENAME +@cindex dark corner +@cindex @code{getline}, setting @code{FILENAME} +@cindex @code{FILENAME}, being set by @code{getline} +An interesting side-effect occurs if you use @code{getline} (without a +redirection) inside a @code{BEGIN} rule. Since an unredirected @code{getline} +reads from the command line data files, the first @code{getline} command +causes @code{awk} to set the value of @code{FILENAME}. Normally, +@code{FILENAME} does not have a value inside @code{BEGIN} rules, since you +have not yet started to process the command line data files (d.c.). +(@xref{BEGIN/END, , The @code{BEGIN} and @code{END} Special Patterns}, +also @pxref{Auto-set, , Built-in Variables that Convey Information}.) + The following table summarizes the six variants of @code{getline}, listing which built-in variables are set by each one. -@iftex -@page -@end iftex @c @cartouche @table @code @item getline @@ -4809,9 +4887,6 @@ This prints a number as an ASCII character. Thus, @samp{printf "%c", 65} outputs the letter @samp{A}. The output for a string value is the first character of the string. -@iftex -@page -@end iftex @item d @itemx i These are equivalent. They both print a decimal integer. @@ -5706,6 +5781,7 @@ as arguments to user defined functions For example: @example +@group function mysub(pat, repl, str, global) @{ if (global) @@ -5714,13 +5790,16 @@ function mysub(pat, repl, str, global) sub(pat, repl, str) return str @} +@end group +@group @{ @dots{} text = "hi! hi yourself!" mysub(/hi/, "howdy", text, 1) @dots{} @} +@end group @end example In this example, the programmer wishes to pass a regexp constant to the @@ -5967,10 +6046,6 @@ $ awk '@{ sum = $2 + $3 + $4 ; avg = sum / 3 This table lists the arithmetic operators in @code{awk}, in order from highest precedence to lowest: -@c sigh. this seems necessary -@iftex -@page -@end iftex @c @cartouche @table @code @item - @var{x} @@ -6366,6 +6441,7 @@ string, @code{""}) is false. The following program will print @samp{A strange truth value} three times: @example +@group BEGIN @{ if (3.1415927) print "A strange truth value" @@ -6374,6 +6450,7 @@ BEGIN @{ if (j = 57) print "A strange truth value" @} +@end group @end example @cindex dark corner @@ -6975,6 +7052,8 @@ while @samp{$} has higher precedence. Here is a table of @code{awk}'s operators, in order from highest precedence to lowest: +@c NEEDED +@page @c use @code in the items, looks better in TeX w/o all the quotes @table @code @item (@dots{}) @@ -7678,9 +7757,11 @@ The @code{do} loop executes the @var{body} once, and then repeats @var{body} as long as @var{condition} is true. It looks like this: @example +@group do @var{body} while (@var{condition}) +@end group @end example Even if @var{condition} is false at the start, @var{body} is executed at @@ -8048,6 +8129,12 @@ If the @code{next} statement causes the end of the input to be reached, then the code in any @code{END} rules will be executed. @xref{BEGIN/END, ,The @code{BEGIN} and @code{END} Special Patterns}. +@cindex @code{next}, inside a user-defined function +@strong{Caution:} Some @code{awk} implementations generate a run-time +error if you use the @code{next} statement inside a user-defined function +(@pxref{User-defined, , User-defined Functions}). +@code{gawk} does not have this problem. + @node Nextfile Statement, Exit Statement, Next Statement, Statements @section The @code{nextfile} Statement @cindex @code{nextfile} statement @@ -8221,8 +8308,9 @@ character in the record becomes a separate field. The default value is @w{@code{" "}}, a string consisting of a single space. As a special exception, this value means that any -sequence of spaces and tabs is a single separator. It also causes -spaces and tabs at the beginning and end of a record to be ignored. +sequence of spaces, tabs, and/or newlines is a single separator.@footnote{In +POSIX @code{awk}, newline does not count as whitespace.} It also causes +spaces, tabs, and newlines at the beginning and end of a record to be ignored. You can set the value of @code{FS} on the command line using the @samp{-F} option: @@ -9080,6 +9168,7 @@ A reasonable attempt at a program to do so (with some test data) might look like this: @example +@group $ echo 'line 1 > line 2 > line 3' | awk '@{ l[lines] = $0; ++lines @} @@ -9089,6 +9178,7 @@ $ echo 'line 1 > @}' @print{} line 3 @print{} line 2 +@end group @end example Unfortunately, the very first line of input data did not come out in the @@ -9646,7 +9736,7 @@ returns the string @w{@code{"pi = 3.14 (approx.)"}}. null string when using closures like *. E.g., $ echo abc | awk '{ gsub(/m*/, "X"); print }' - @print{} XaXbXc + @print{} XaXbXcX Although this makes a certain amount of sense, it can be very suprising. @@ -9721,6 +9811,8 @@ an @samp{&}: awk '@{ sub(/\|/, "\\&"); print @}' @end example +@cindex @code{sub}, third argument of +@cindex @code{gsub}, third argument of @strong{Note:} As mentioned above, the third argument to @code{sub} must be a variable, field or array reference. Some versions of @code{awk} allow the third argument to @@ -9735,7 +9827,10 @@ sub(/USA/, "United States", "the USA and Canada") @end example @noindent -This is considered erroneous in @code{gawk}. +For historical compatibility, @code{gawk} will accept erroneous code, +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. @item gsub(@var{regexp}, @var{replacement} @r{[}, @var{target}@r{]}) @findex gsub @@ -9834,6 +9929,23 @@ suffix is also returned if @var{length} is greater than the number of characters remaining in the string, counting from character number @var{start}. +@strong{Note:} The string returned by @code{substr} @emph{cannot} be +assigned to. Thus, it is a mistake to attempt to change a portion of +a string, like this: + +@example +string = "abcdef" +# try to get "abCDEf", won't work +substr(string, 3, 3) = "CDE" +@end example + +@noindent +or to use @code{substr} as the third agument of @code{sub} or @code{gsub}: + +@example +gsub(/xyz/, "pdq", substr($0, 5, 20)) # WRONG +@end example + @cindex case conversion @cindex conversion of case @item tolower(@var{string}) @@ -10117,7 +10229,7 @@ version of @code{awk}; it is not part of the POSIX standard, and will not be available if @samp{--posix} has been specified on the command line (@pxref{Options, ,Command Line Options}). -@code{gawk} extends the @code{fflush} function in two ways. This first +@code{gawk} extends the @code{fflush} function in two ways. The first is to allow no argument at all. In this case, the buffer for the standard output is flushed. The second way is to allow the null string (@w{@code{""}}) as the argument. In this case, the buffers for @@ -10157,6 +10269,53 @@ Some operating systems cannot implement the @code{system} function. @end table @c fakenode --- for prepinfo +@subheading Interactive vs. Non-Interactive Buffering +@cindex buffering, interactive vs. non-interactive +@cindex buffering, non-interactive vs. interactive +@cindex interactive buffering vs. non-interactive +@cindex non-interactive buffering vs. interactive + +As a side point, buffering issues can be even more confusing depending +upon whether or not your program is @dfn{interactive}, i.e., communicating +with a user sitting at a keyboard.@footnote{A program is interactive +if the standard output is connected +to a terminal device.} + +Interactive programs generally @dfn{line buffer} their output; they +write out every line. Non-interactive programs wait until they have +a full buffer, which may be many lines of output. + +@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for +@c motivating me to write this section. +Here is an example of the difference. + +@example +$ awk '@{ print $1 + $2 @}' +1 1 +@print{} 2 +2 3 +@print{} 5 +@kbd{Control-d} +@end example + +@noindent +Each line of output is printed immediately. Compare that behavior +with this example. + +@example +$ awk '@{ print $1 + $2 @}' | cat +1 1 +2 3 +@kbd{Control-d} +@print{} 2 +@print{} 5 +@end example + +@noindent +Here, no output is printed until after the @kbd{Control-D} is typed, since +it is all buffered, and sent down the pipe to @code{cat} in one shot. + +@c fakenode --- for prepinfo @subheading Controlling Output Buffering with @code{system} @cindex flushing buffers @cindex buffers, flushing @@ -10311,9 +10470,9 @@ The locale's equivalent of the AM/PM designations associated with a 12-hour clock. @item %S -The second as a decimal number (00--61).@footnote{Occasionally there are -minutes in a year with one or two leap seconds, which is why the -seconds can go up to 61.} +The second as a decimal number (00--60).@footnote{Occasionally there are +minutes in a year with a leap second, which is why the +seconds can go up to 60.} @item %U The week number of the year (the first Sunday as the first day of week one) @@ -10649,9 +10808,11 @@ This program prints, in our special format, all the third fields that contain a positive number in our input. Therefore, when given: @example +@group 1.2 3.4 5.6 7.8 9.10 11.12 -13.14 15.16 17.18 19.20 21.22 23.24 +@end group @end example @noindent @@ -10860,6 +11021,12 @@ If @samp{--lint} has been specified (@pxref{Options, ,Command Line Options}), @code{gawk} will report about calls to undefined functions. +Some @code{awk} implementations generate a run-time +error if you use the @code{next} statement +(@pxref{Next Statement, , The @code{next} Statement}) +inside a user-defined function. +@code{gawk} does not have this problem. + @node Return Statement, , Function Caveats, User-defined @section The @code{return} Statement @cindex @code{return} statement @@ -11046,8 +11213,8 @@ The @samp{-v} option can only set one variable, but you can use it more than once, setting another variable each time, like this: @samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}. -@item -mf=@var{NNN} -@itemx -mr=@var{NNN} +@item -mf @var{NNN} +@itemx -mr @var{NNN} Set various memory limits to the value @var{NNN}. The @samp{f} flag sets the maximum number of fields, and the @samp{r} flag sets the maximum record size. These two flags and the @samp{-m} option are from the @@ -11058,9 +11225,7 @@ for compatibility, but otherwise ignored by @item -W @var{gawk-opt} @cindex @code{-W} option Following the POSIX standard, options that are implementation -specific are supplied as arguments to the @samp{-W} option. With @code{gawk}, -these arguments may be separated by commas, or quoted and separated by -whitespace. Case is ignored when processing these options. These options +specific are supplied as arguments to the @samp{-W} option. These options also have corresponding GNU style long options. See below. @@ -11099,7 +11264,7 @@ which summarizes the extensions. Also see @itemx --copyright @cindex @code{--copyleft} option @cindex @code{--copyright} option -Print the short version of the General Public License. +Print the short version of the General Public License, and then exit. This option may disappear in a future version of @code{gawk}. @item -W help @@ -11142,6 +11307,10 @@ restrictions: (@pxref{Escape Sequences}). @item +Newlines do not act as whitespace to separate fields when @code{FS} is +equal to a single space. + +@item The synonym @code{func} for the keyword @code{function} is not recognized (@pxref{Definition Syntax, ,Function Definition Syntax}). @@ -11396,7 +11565,8 @@ they will @emph{not} be in the next release). @c update this section for each release! -For version @value{VERSION} of @code{gawk}, there are no command line options +For version @value{VERSION}.@value{PATCHLEVEL} of @code{gawk}, there are no +command line options or other deprecated features from the previous version of @code{gawk}. @iftex This section @@ -11496,10 +11666,6 @@ Syntactically invalid single character programs tend to overflow the parse stack, generating a rather unhelpful message. Such programs are surprisingly difficult to diagnose in the completely general case, and the effort to do so really is not worth it. - -@item -The word ``GNU'' is incorrectly capitalized in at least one -file in the source code. @end itemize @node Library Functions, Sample Programs, Invoking Gawk, Top @@ -11532,6 +11698,8 @@ or assign the copyright in it to the Free Software Foundation. function. * Assert Function:: A function for assertions in @code{awk} programs. +* Round Function:: A function for rounding if @code{sprintf} does + not do it correctly. * Ordinal Functions:: Functions for using characters as numbers and vice versa. * Join Function:: A function to join an array into a string. @@ -11698,7 +11866,7 @@ next one, saving a lot of time. This is particularly important in they spend most of their time doing input and output, instead of performing computations). -@node Assert Function, Ordinal Functions, Nextfile Function, Library Functions +@node Assert Function, Round Function, Nextfile Function, Library Functions @section Assertions @cindex assertions @@ -11804,19 +11972,63 @@ will attempt to read the input data files, or standard input (@pxref{Using BEGIN/END, , Startup and Cleanup Actions}), most likely causing the program to hang, waiting for input. -@cindex backslash continuation -Just a note on programming style. You may have noticed that the @code{END} -rule uses backslash continuation, with the open brace on a line by -itself. This is so that it more closely resembles the way functions -are written. Many of the examples -@iftex -in this chapter and the next one -@end iftex -use this style. You can decide for yourself if you like writing -your @code{BEGIN} and @code{END} rules this way, -or not. +@node Round Function, Ordinal Functions, Assert Function, Library Functions +@section Rounding Numbers + +@cindex rounding +The way @code{printf} and @code{sprintf} +(@pxref{Printf, , Using @code{printf} Statements for Fancier Printing}) +do rounding will often depend +upon the system's C @code{sprintf} subroutine. +On many machines, +@code{sprintf} rounding is ``unbiased,'' which means it doesn't always +round a trailing @samp{.5} up, contrary to naive expectations. In unbiased +rounding, @samp{.5} rounds to even, rather than always up, so 1.5 rounds to +2 but 4.5 rounds to 4. +The result is that if you are using a format that does +rounding (e.g., @code{"%.0f"}) you should check what your system does. +The following function does traditional rounding; +it might be useful if your awk's @code{printf} does unbiased rounding. + +@findex round +@example +@c file eg/lib/round.awk +# round --- do normal rounding +# +# Arnold Robbins, arnold@@gnu.ai.mit.edu, August, 1996 +# Public Domain + +function round(x, ival, aval, fraction) +@{ + ival = int(x) # integer part, int() truncates + + # see if fractional part + if (ival == x) # no fraction + return x + + if (x < 0) @{ + aval = -x # absolute value + ival = int(aval) + fraction = aval - ival + if (fraction >= .5) + return int(x) - 1 # -2.5 --> -3 + else + return int(x) # -2.3 --> -2 + @} else @{ + fraction = x - ival + if (fraction >= .5) + return ival + 1 + else + return ival + @} +@} + +# test harness +@{ print $0, round($0) @} +@c endfile +@end example -@node Ordinal Functions, Join Function, Assert Function, Library Functions +@node Ordinal Functions, Join Function, Round Function, Library Functions @section Translating Between Characters and Numbers @cindex numeric character values @@ -11835,7 +12047,7 @@ reason to build them into the @code{awk} interpreter. @findex ord @findex chr @example -@c @group +@group @c file eg/lib/ord.awk # ord.awk --- do ord and chr # @@ -11851,7 +12063,7 @@ reason to build them into the @code{awk} interpreter. BEGIN @{ _ord_init() @} @c endfile -@c @end group +@end group @c @group @c file eg/lib/ord.awk @@ -12202,7 +12414,7 @@ function mktime(str, res1, res2, a, b, i, j, t, diff) a[3] < 1 || a[3] > 31 || a[4] < 0 || a[4] > 23 || a[5] < 0 || a[5] > 59 || - a[6] < 0 || a[6] > 61 ) + a[6] < 0 || a[6] > 60 ) return -1 @end group @@ -12649,11 +12861,13 @@ The discussion walks through the code a bit at a time. # Initial version: March, 1991 # Revised: May, 1993 +@group # External variables: # Optind -- index of ARGV for first non-option argument # Optarg -- string value of argument to current option # Opterr -- if non-zero, print our own diagnostic # Optopt -- current option letter +@end group # Returns # -1 at end of options @@ -12987,6 +13201,7 @@ $ pwcat @print{} bin:*:3:3::/bin: @print{} arnold:xyzzy:2076:10:Arnold Robbins:/home/arnold:/bin/sh @print{} miriam:yxaay:112:10:Miriam Robbins:/home/miriam:/bin/sh +@print{} andy:abcca2:113:10:Andy Jacobs:/home/andy:/bin/sh @dots{} @c @end group @end example @@ -13009,6 +13224,7 @@ BEGIN @{ @} @end group +@group function _pw_init( oldfs, oldrs, olddol0, pwcat) @{ if (_pw_inited) @@ -13032,7 +13248,7 @@ function _pw_init( oldfs, oldrs, olddol0, pwcat) $0 = olddol0 @} @c endfile -@c @end group +@end group @end example The @code{BEGIN} rule sets a private variable to the directory where @@ -13245,9 +13461,6 @@ return those group-id numbers in @code{$5} through @code{$NF}. @pxref{Special Files, ,Special File Names in @code{gawk}}.) @end table -@iftex -@page -@end iftex Here is what running @code{grcat} might produce: @example @@ -13713,6 +13926,7 @@ BEGIN \ if (c == "f") @{ by_fields = 1 fieldlist = Optarg +@group @} else if (c == "c") @{ by_chars = 1 fieldlist = Optarg @@ -13732,6 +13946,7 @@ BEGIN \ else usage() @} +@end group for (i = 1; i < Optind; i++) ARGV[i] = "" @@ -13742,7 +13957,7 @@ BEGIN \ Special care is taken when the field delimiter is a space. Using @code{@w{" "}} (a single space) for the value of @code{FS} is incorrect---@code{awk} would -separate fields with runs of spaces and/or tabs, and we want them to be +separate fields with runs of spaces, tabs and/or newlines, and we want them to be separated with individual spaces. Also, note that after @code{getopt} is through, we have to clear out all the elements of @code{ARGV} from one to @code{Optind}, so that @code{awk} will not try to process the command line @@ -13845,7 +14060,7 @@ function set_charlist( field, i, j, f, g, t, if (index(f[i], "-") != 0) @{ # range m = split(f[i], g, "-") if (m != 2 || g[1] >= g[2]) @{ - printf(bad character list: %s\n", + printf("bad character list: %s\n", f[i]) > "/dev/stderr" exit 1 @} @@ -13941,6 +14156,8 @@ Normally, @code{egrep} prints the lines that matched. If multiple file names are provided on the command line, each output line is preceded by the name of the file and a colon. +@c NEEDED +@page The options are: @table @code @@ -14072,14 +14289,14 @@ does is initialize a variable @code{fcount} to zero. @code{fcount} tracks how many lines in the current file matched the pattern. @example -@c @group +@group @c file eg/prog/egrep.awk function beginfile(junk) @{ fcount = 0 @} @c endfile -@c @end group +@end group @end example The @code{endfile} function is called after each file has been processed. @@ -14155,8 +14372,10 @@ necessary. fcount += matches # 1 or 0 +@group if (! matches) next +@end group if (no_print && ! count_only) nextfile @@ -14212,6 +14431,18 @@ function usage( e) The variable @code{e} is used so that the function fits nicely on the printed page. +@cindex backslash continuation +Just a note on programming style. You may have noticed that the @code{END} +rule uses backslash continuation, with the open brace on a line by +itself. This is so that it more closely resembles the way functions +are written. Many of the examples +@iftex +in this chapter +@end iftex +use this style. You can decide for yourself if you like writing +your @code{BEGIN} and @code{END} rules this way, +or not. + @node Id Program, Split Program, Egrep Program, Clones @subsection Printing Out User Information @@ -14597,9 +14828,9 @@ Count lines. This option overrides @samp{-d} and @samp{-u}. Both repeated and non-repeated lines are counted. @item -@var{n} -Skip @var{n} fields before comparing lines. The definition of fields is the -same as @code{awk}'s default: non-whitespace characters separated by runs of -spaces and/or tabs. +Skip @var{n} fields before comparing lines. The definition of fields +is similar to @code{awk}'s default: non-whitespace characters separated +by runs of spaces and/or tabs. @item +@var{n} Skip @var{n} characters before comparing lines. Any fields specified with @@ -14650,18 +14881,22 @@ standard output, @file{/dev/stdout}. # Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain # May 1993 +@group function usage( e) @{ e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]" print e > "/dev/stderr" exit 1 @} +@end group +@group # -c count lines. overrides -d and -u # -d only repeated lines # -u only non-repeated lines # -n skip n fields # +n skip n characters, skip fields first +@end group BEGIN \ @{ @@ -14699,13 +14934,14 @@ BEGIN \ if (repeated_only == 0 && non_repeated_only == 0) repeated_only = non_repeated_only = 1 +@group if (ARGC - Optind == 2) @{ outputfile = ARGV[ARGC - 1] ARGV[ARGC - 1] = "" @} @} @c endfile -@c @end group +@end group @end example The following function, @code{are_equal}, compares the current line, @@ -14906,7 +15142,7 @@ BEGIN @{ if (! do_lines && ! do_words && ! do_chars) do_lines = do_words = do_chars = 1 - print_total = (ARC - i > 2) + print_total = (ARGC - i > 2) @} @c endfile @c @end group @@ -15029,6 +15265,7 @@ that punctuation does not affect the comparison either. This sometimes leads to reports of duplicated words that really are different, but this is unusual. +@c FIXME: add check for $i != "" @findex dupword.awk @example @group @@ -15495,9 +15732,6 @@ as the same word. This is undesirable since, in normal text, words are capitalized if they begin sentences, and a frequency analyzer should not be sensitive to capitalization. -@iftex -@page -@end iftex @item The output does not come out in any useful order. You're more likely to be interested in which words occur most frequently, or having an alphabetized @@ -15782,9 +16016,9 @@ line. That line is then printed to the output file. @example @c @group @c file eg/prog/extract.awk +@group /^@@c(omment)?[ \t]+file/ \ @{ -@group if (NF != 3) @{ e = (FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" @@ -15899,11 +16133,13 @@ are provided, the standard input is used. # Arnold Robbins, arnold@@gnu.ai.mit.edu, Public Domain # August 1995 +@group function usage() @{ print "usage: awksed pat repl [files...]" > "/dev/stderr" exit 1 @} +@end group BEGIN @{ # validate arguments @@ -16096,9 +16332,6 @@ argument (e.g., @samp{--file=}). @itemx -Wsource= The source text is echoed into @file{/tmp/ig.s.$$}. -@iftex -@page -@end iftex @item --version @itemx --version @itemx -Wversion @@ -16160,8 +16393,10 @@ do -f) echo @@include "$2" >> /tmp/ig.s.$$ shift;; +@group -f*) f=`echo "$1" | sed 's/-f//'` echo @@include "$f" >> /tmp/ig.s.$$ ;; +@end group -?file=*) # -Wfile or --file f=`echo "$1" | sed 's/-.file=//'` @@ -16270,7 +16505,7 @@ splitting the path on @samp{:}, null elements are replaced with @code{"."}, which represents the current directory. @example -@c @group +@group @c file eg/prog/igawk.sh BEGIN @{ path = ENVIRON["AWKPATH"] @@ -16280,7 +16515,7 @@ BEGIN @{ pathlist[i] = "." @} @c endfile -@c @end group +@end group @end example The stack is initialized with @code{ARGV[1]}, which will be @file{/tmp/ig.s.$$}. @@ -16443,7 +16678,7 @@ of the @value{DOCUMENT} where you can find more information. * SVR4:: Minor changes between System V Releases 3.1 and 4. * POSIX:: New features from the POSIX standard. -* BTL:: New features from the AT&T Bell Laboratories +* BTL:: New features from the Bell Laboratories version of @code{awk}. * POSIX/GNU:: The extensions in @code{gawk} not in POSIX @code{awk}. @@ -16617,6 +16852,10 @@ standard: (@pxref{Escape Sequences}). @item +Newlines do not act as whitespace to separate fields when @code{FS} is +equal to a single space. + +@item The synonym @code{func} for the keyword @code{function} is not recognized (@pxref{Definition Syntax, ,Function Definition Syntax}). @@ -16636,7 +16875,7 @@ The @code{fflush} built-in function is not supported @end itemize @node BTL, POSIX/GNU, POSIX, Language History -@section Extensions in the AT&T Bell Laboratories @code{awk} +@section Extensions in the Bell Laboratories @code{awk} @cindex Kernighan, Brian Brian Kernighan, one of the original designers of Unix @code{awk}, @@ -16647,7 +16886,7 @@ not in POSIX @code{awk}. @itemize @bullet @item -The @samp{-mf=@var{NNN}} and @samp{-mr=@var{NNN}} command line options +The @samp{-mf @var{NNN}} and @samp{-mr @var{NNN}} command line options to set the maximum number of fields, and the maximum record size, respectively (@pxref{Options, ,Command Line Options}). @@ -16868,8 +17107,8 @@ predefined variable). Read the @code{awk} program source from the file @var{program-file}, instead of from the first command line argument. -@item -mf=@var{NNN} -@itemx -mr=@var{NNN} +@item -mf @var{NNN} +@itemx -mr @var{NNN} The @samp{f} flag sets the maximum number of fields, and the @samp{r} flag sets the maximum record size. These options are ignored by @code{gawk}, since @code{gawk} @@ -16892,14 +17131,15 @@ off. @itemx -W copyright @itemx --copyleft @itemx --copyright -Print the short version of the General Public License on the error -output. This option may disappear in a future version of @code{gawk}. +Print the short version of the General Public License on the standard +output, and exit. This option may disappear in a future version of @code{gawk}. @item -W help @itemx -W usage @itemx --help @itemx --usage -Print a relatively short summary of the available options on the error output. +Print a relatively short summary of the available options on the standard +output, and exit. @item -W lint @itemx --lint @@ -17019,7 +17259,8 @@ As each input line is read, @code{gawk} splits the line into separator. If @code{FS} is a single character, fields are separated by that character. Otherwise, @code{FS} is expected to be a full regular expression. In the special case that @code{FS} is a single space, -fields are separated by runs of spaces and/or tabs. +fields are separated by runs of spaces, tabs and/or newlines.@footnote{In +POSIX @code{awk}, newline does not separate fields.} If @code{FS} is the null string (@code{""}), then each individual character in the record becomes a separate field. Note that the value @@ -17045,6 +17286,9 @@ the null string. However, assigning to a non-existent field (e.g., intervening fields with the null string as their value, and causes the value of @code{$0} to be recomputed, with the fields being separated by the value of @code{OFS}. +Decrementing @code{NF} causes the values of fields past the new value to +be lost, and the value of @code{$0} to be recomputed, with the fields being +separated by the value of @code{OFS}. @xref{Reading Files, ,Reading Input Files}. @node Built-in Summary, Arrays Summary, Fields Summary, Variables/Fields @@ -17361,12 +17605,13 @@ are @code{alnum}, @code{alpha}, @code{blank}, @code{cntrl}, matches the multi-character collating symbol @var{symbol}. @code{gawk} does not currently support collating symbols. -@item [[=@var{chars}=]] -matches any of the equivalent characters in @var{chars}. +@item [[=@var{classname}=]] +matches any of the equivalent characters in the current locale named by the +equivalence class @var{classname}. @code{gawk} does not currently support equivalence classes. @item [^@var{abc}@dots{}] -matches any character except @var{abc}@dots{} and newline (negated +matches any character except @var{abc}@dots{} (negated character list). @item @var{r1}|@var{r2} @@ -17586,7 +17831,7 @@ Set @code{$0} from next input record; set @code{NF}, @code{NR}, @code{FNR}. Set @code{$0} from next record of @var{file}; set @code{NF}. @item getline @var{var} -Set @var{var} from next input record; set @code{NF}, @code{FNR}. +Set @var{var} from next input record; set @code{NR}, @code{FNR}. @item getline @var{var} <@var{file} Set @var{var} from next record of @var{file}. @@ -17832,7 +18077,7 @@ The built-in arithmetic functions are: the arctangent of @var{y/x} in radians. @item cos(@var{expr}) -the cosine in radians. +the cosine of @var{expr}, which is in radians. @item exp(@var{expr}) the exponential function (@code{e ^ @var{expr}}). @@ -17847,7 +18092,7 @@ the natural logarithm of @code{expr}. a random number between zero and one. @item sin(@var{expr}) -the sine in radians. +the sine of @var{expr}, which is in radians. @item sqrt(@var{expr}) the square root function. @@ -17858,9 +18103,6 @@ is provided, the time of day is used. The return value is the previous seed for the random number generator. @end table -@iftex -@page -@end iftex @code{awk} has the following built-in string functions: @table @code @@ -17873,6 +18115,7 @@ original @var{target} is not modified. Within @var{subst}, @samp{\@var{n}}, where @var{n} is a digit from one to nine, can be used to indicate the text that matched the @var{n}'th parenthesized subexpression. +This function is @code{gawk}-specific. @item gsub(@var{regex}, @var{subst} @r{[}, @var{target}@r{]}) for each substring matching the regular expression @var{regex} in the string @@ -17946,6 +18189,7 @@ output. This is more portable, but less obvious, than calling @code{fflush}. The following two functions are available for getting the current time of day, and for formatting time stamps. +They are specific to @code{gawk}. @table @code @item systime() @@ -18247,9 +18491,8 @@ You should use a site that is geographically close to you. @itemx ftp.kpc.com:/pub/mirror/gnu @end table -@iftex +@c NEEDED @page -@end iftex @item USA (continued): @table @code @itemx ftp.uu.net:/systems/gnu @@ -18269,17 +18512,17 @@ You should use a site that is geographically close to you. GNU Zip program, @code{gzip}. Once you have the distribution (for example, -@file{gawk-@value{VERSION}.0.tar.gz}), first use @code{gzip} to expand the +@file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}), first use @code{gzip} to expand the file, and then use @code{tar} to extract it. You can use the following pipeline to produce the @code{gawk} distribution: @example # Under System V, add 'o' to the tar flags -gzip -d -c gawk-@value{VERSION}.0.tar.gz | tar -xvpf - +gzip -d -c gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz | tar -xvpf - @end example @noindent -This will create a directory named @file{gawk-@value{VERSION}.0} in the current +This will create a directory named @file{gawk-@value{VERSION}.@value{PATCHLEVEL}} in the current directory. The distribution file name is of the form @@ -18312,9 +18555,6 @@ operating systems. These files are the actual @code{gawk} source code. @end table -@iftex -@page -@end iftex @table @file @item README @itemx README_d/README.* @@ -18357,6 +18597,25 @@ incorrect, and how @code{gawk} handles the problem. @item PROBLEMS A file describing known problems with the current release. +@cindex artificial intelligence, using @code{gawk} +@cindex AI programming, using @code{gawk} +@item doc/awkforai.txt +A short article describing why @code{gawk} is a good language for +AI (Artificial Intelligence) programming. + +@item doc/README.card +@itemx doc/ad.block +@itemx doc/awkcard.in +@itemx doc/cardfonts +@itemx doc/colors +@itemx doc/macros +@itemx doc/no.colors +@itemx doc/setter.outline +The @code{troff} source for a five-color @code{awk} reference card. +A modern version of @code{troff}, such as GNU Troff (@code{groff}) is +needed to produce the color version. See the file @file{README.card} +for instructions if you have an older @code{troff}. + @item doc/gawk.1 The @code{troff} source for a manual page describing @code{gawk}. This is distributed for the convenience of Unix users. @@ -18445,7 +18704,7 @@ to configure @code{gawk} for your system yourself. @cindex installation, unix After you have extracted the @code{gawk} distribution, @code{cd} -to @file{gawk-@value{VERSION}.0}. Like most GNU software, +to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. Like most GNU software, @code{gawk} is configured automatically for your Unix system by running the @code{configure} program. This program is a Bourne shell script that was generated automatically using @@ -18699,33 +18958,29 @@ translation, and not a multi-translation @code{RMS} searchlist. @appendixsubsec Building and Using @code{gawk} on VMS POSIX Ignore the instructions above, although @file{vms/gawk.hlp} should still -be made available in a help library. Make sure that the @code{configure} -script is executable; use @samp{chmod +x} -on it if necessary. Then execute the following commands: +be made available in a help library. The source tree should be unpacked +into a container file subsystem rather than into the ordinary VMS file +system. Make sure that the two scripts, @file{configure} and +@file{vms/posix-cc.sh}, are executable; use @samp{chmod +x} on them if +necessary. Then execute the following two commands: @example @group -$ POSIX psx> CC=vms/posix-cc.sh configure -psx> CC=c89 make gawk +psx> make CC=c89 gawk @end group @end example @noindent -The first command will construct files @file{config.h} and @file{Makefile} -out of templates. The second command will compile and link @code{gawk}. -@ignore -Due to a @code{make} bug in VMS POSIX V1.0 and V1.1, -the file @file{awktab.c} must be given as an explicit target or it will -not be built and the final link step will fail. -@end ignore -Ignore the warning -@code{"Could not find lib m in lib list"}; it is harmless, caused by the -explicit use of @samp{-lm} as a linker option which is not needed -under VMS POSIX. Under V1.1 (but not V1.0) a problem with the @code{yacc} -skeleton @file{/etc/yyparse.c} will cause a compiler warning for -@file{awktab.c}, followed by a linker warning about compilation warnings -in the resulting object module. These warnings can be ignored. +The first command will construct files @file{config.h} and @file{Makefile} out +of templates, using a script to make the C compiler fit @code{configure}'s +expectations. The second command will compile and link @code{gawk} using +the C compiler directly; ignore any warnings from @code{make} about being +unable to redefine @code{CC}. @code{configure} will take a very long +time to execute, but at least it provides incremental feedback as it +runs. + +This has been tested with VAX/VMS V6.2, VMS POSIX V2.0, and DEC C V5.2. Once built, @code{gawk} will work like any other shell utility. Unlike the normal VMS port of @code{gawk}, no special command line manipulation is @@ -18774,7 +19029,8 @@ Microsoft C can be used to build 16-bit versions for MS-DOS and OS/2. The file @file{README_d/README.pc} in the @code{gawk} distribution contains additional notes, and @file{pc/Makefile} contains important notes on compilation options. -To build @code{gawk}, copy the files in the @file{pc} directory to the +To build @code{gawk}, copy the files in the @file{pc} directory (@emph{except} +for @file{ChangeLog}) to the directory with the rest of the @code{gawk} sources. The @file{Makefile} contains a configuration section with comments, and may need to be edited in order to work with your @code{make} utility. @@ -18926,12 +19182,15 @@ A more complete distribution for the Amiga is available on the FreshFish CD-ROM from: @quotation -Amiga Library Services @* -610 North Alma School Road, Suite 18 @* -Chandler, AZ 85224 USA @* -Phone: +1-602-491-0048 @* +CRONUS @* +1840 E. Warner Road #105-265 @* +Tempe, AZ 85284 USA @* +US Toll Free: (800) 804-0833 @* +Phone: +1-602-491-0442 @* FAX: +1-602-491-0048 @* -E-mail: @code{orders@@amigalib.com} +Email: @code{info@@ninemoons.com} @* +WWW: @code{http://www.ninemoons.com} @* +Anonymous @code{ftp} site: @code{ftp.ninemoons.com} @* @end quotation Once you have the distribution, you can configure @code{gawk} simply by @@ -18997,7 +19256,7 @@ mail at the Internet address above. If you find bugs in one of the non-Unix ports of @code{gawk}, please send an electronic mail message to the person who maintains that port. They are listed below, and also in the @file{README} file in the @code{gawk} -distribution. Information in the @code{README} file should be considered +distribution. Information in the @file{README} file should be considered authoritative if it conflicts with this @value{DOCUMENT}. The people maintaining the non-Unix ports of @code{gawk} are: @@ -19023,7 +19282,7 @@ Pat Rankin, @samp{rankin@@eql.caltech.edu}. Michal Jaegermann, @samp{michal@@gortel.phys.ualberta.ca}. @item Amiga -Fred Fish, @samp{fnf@@amigalib.com}. +Fred Fish, @samp{fnf@@ninemoons.com}. @end table If your bug is also reproducible under Unix, please send copies of your @@ -19033,6 +19292,20 @@ addresses listed above. @node Other Versions, , Bugs, Installation @appendixsec Other Freely Available @code{awk} Implementations +@cindex Brennan, Michael +@display +@ignore +From: emory!amc.com!brennan (Michael Brennan) +Subject: C++ comments in awk programs +To: arnold@gnu.ai.mit.edu (Arnold Robbins) +Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) + +@end ignore +@i{It's kind of fun to put comments like this in your awk code.} + @code{// Do C++ comments work? answer: yes! of course} +Michael Brennan +@end display + There are two other freely available @code{awk} implementations. This section briefly describes where to get them. @@ -19063,9 +19336,9 @@ called @code{mawk}. It is available under the GPL just as @code{gawk} is. You can get it via anonymous @code{ftp} to the host -@code{@w{oxy.edu}}. Change directory to @file{/public}. Use ``binary'' -or ``image'' mode, and retrieve @file{mawk1.2.1.tar.gz} (or the latest -version that is there). +@code{@w{ftp.whidbey.net}}. Change directory to @file{/pub/brennan}. +Use ``binary'' or ``image'' mode, and retrieve @file{mawk1.3.3.tar.gz} +(or the latest version that is there). @code{gunzip} may be used to decompress this file. Installation is similar to @code{gawk}'s @@ -19215,6 +19488,11 @@ Provide one-line descriptive comments for each function. @item Do not use @samp{#elif}. Many older Unix C compilers cannot handle it. + +@item +Do not use the @code{alloca} function for allocating memory off the stack. +Its use causes more portability trouble than the minor benefit of not having +to free the storage. Instead, use @code{malloc} and @code{free}. @end itemize If I have to reformat your code to follow the coding style used in @@ -19359,10 +19637,6 @@ operating systems that is already there. In the code that you supply, and that you maintain, feel free to use a coding style and brace layout that suits your taste. -@c why should this be needed? sigh -@iftex -@page -@end iftex @node Future Extensions, Improvements, Additions, Notes @appendixsec Probable Future Extensions @@ -19486,10 +19760,6 @@ The @code{dfa} pattern matcher from GNU @code{grep} has some problems. Either a new version or a fixed one will deal with some important regexp matching issues. -@item Use of @code{mmap} -On systems that support the @code{mmap} system call, its use would provide -much faster file input, and considerably simplified input buffer management. - @item Use of GNU @code{malloc} The GNU version of @code{malloc} could potentially speed up @code{gawk}, since it relies heavily on the use of dynamic memory allocation. @@ -19967,8 +20237,8 @@ versions of Unix, as well as several work-alike systems whose source code is freely available (such as Linux, NetBSD, and FreeBSD). @item Whitespace -A sequence of space or tab characters occurring inside an input record or a -string. +A sequence of space, tab, or newline characters occurring inside an input +record or a string. @end table @node Copying, Index, Glossary, Top @@ -20410,8 +20680,7 @@ Consistency issues: Use alphanumeric, not alpha-numeric Use --foo, not -Wfoo when describing long options Use findex for all programs and functions in the example chapters - Use "Bell Labs" or "AT&T Bell Laboratories", but not - "AT&T Bell Labs". + Use "Bell Laboratories", but not "Bell Labs". Use "behavior" instead of "behaviour". Use "zeros" instead of "zeroes". Use "Input/Output", not "input/output". Also "I/O", not "i/o". diff --git a/doc/macros b/doc/macros new file mode 100644 index 00000000..bdfc5c8c --- /dev/null +++ b/doc/macros @@ -0,0 +1,211 @@ +.\" SSC Reference card macros +.\" +.\" Copyright (C) 1996, Specialized System Consultants Inc. (SSC) +.\" +.\" These macros are free software; you can redistribute them and/or modify +.\" them under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" These macros are 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 program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +.\" +.\" Generic SSC "card" macros +.\" based on lots of other macros +.\" Last update: 4-25-91 ph +.\" attempting to get margins in the boxes Aug 3 09:43:48 PDT 1994 +.ll 3i \" length of text line +.lt 3.2i \" length of title line +.de BT \" bottom of page trap +.sp |8.2i \" go to where we put footer +.ie \\n(CL=1 \{\ +. nr CL 2 +.tl ''\\*(CD\\n+(PN'' \" footer is just page number +. po 4i \" go to second column +.TP \" print header if any +\} +.el \{\ +. nr CL 1 +.tl ''\\*(CD\\n+(PN'' \" footer is just page number +. po .5i \" go to first column +. bp \" force a new page (which will force header) +. TP +\} +.. +.de TP \" top of page +.\" .sp |.2i +.sp |0 +.\" put page header stuff here +.\" for example: .tl ''WOW!'' +.\".sp +.. +.\" .wh 8.1i BT \" set bottom of column trap +.nf \" don't fill lines +.nh \" no hyphenation +.nr CL 1 \" start with column = 1 +.po .5i \" offset for first column +.vs 9 \" line spacing +.ps 8 \" point size +.de ST \" set tabs to normal places +.ta .2i .78i 1.2i 1.7i \" set tabs +.. +.ig + From: bryang@chinet.chi.il.us (Bryan Glennon) + Box macro. Do a .mk z where the box is to start, and a .eb + where it is to end. Optional argument is a title to be centered + within the top box line. + + Usage: + + .mk z + Text, etc to be boxed... + .eb "Optional title goes here" + + ~or~ + + .mk z + Text, etc to be boxed... + .eb + + + Some explanation: + The macro name is eb <.de eb>. First thing we do is to go up on line + <.sp -1> and turn off fill mode <.nf>. Now it gets interesting: the + .ie is the if/else construct. We check the number of arguments provided + to the macro <\\n(.$> and if it is greater than 0 (meaning we have a title), + we do the rest of the .ie line, as follows: + + \h'-.5n' - move left one-half of an n + \L'|\\nzu-1' - draw a vertical line <\L> to the + absolute position (|) given by \\nzu-1, + which is the position set with the .mk + command into register z <\\nz> in base + units <u> minus 1. + \l'(\\n(.lu+1n-\w'\\$1'u/2u)\(ul' - Draw a horizontal line <\l> with length + equal to the current line length + <\\n(.l> in base units <u> plus the + space required for an 'n' <1n>, minus + the width <\w> of the title string + <\\$1> in base units <u> divided by 2 + <in base units <u>>. Draw the line + using the underline character, <\(ul>. + \v'.3m'\|\\$1\|\v'-.3m' - Move down the page 3/10 of an m, + <\v'.3m'>, output a 1/6 of an m space + <\|>, output the title <\\$1>, another + 1/6 of an m space <\|>, and then move + up the page 3/10 of an m <\v'-.3m'>. + \l'...\(ul' - Draw the second part of the line, just + like the corresponding left half done + before. + \L'-|\\nzu+1' - Draw a verticle line <\L> going down + the absolute distance <-|> from where + the macro was given to where the start + point was marked <\\nz> in base units + <u> plus one line <+1> + \l'|0u-.5n\(ul' - Draw a horizontal line to the absolute + position (|0) when the macro was + invoked, minus half an n <-.5n> using + the underline character <\(ul>. + + The .el beings the else part, which is identical to the above, except + the string dosen't get printed. This makes the printing of the top + line much easier: just draw a line <\l> with width equal to the + current line plus the witdh of an n <\\n(.l+1n> using the underline + character <.\(ul>. +.. +.de ES \" start "text in a box" +.mk z +.in +.5n +.ll -.5n +.sp 1.3 +.. +.de EB \" end "text in a box" -- optional box title as argument +.sp -.6 +.nf +.in -.5n +.ll +.5n +.ie \\n(.$\ +\L'|\\nzu'\ +\l'(\\n(.lu-\w'\\$1'u)/2u-.33m\(ul'\ +\v'.3m'\|\\$1\|\v'-.3m'\ +\l'(\\n(.lu-\w'\\$1'u)/2u\(ul'\ +\L'-|\\nzu'\ +\l'|0u\(ul' +.el \h'-.5n'\L'|\\nzu-1'\l'\\n(.lu+1n\(ul'\L'-|\\nzu+1'\l'|0u-.5n\(ul' +.in 0 +.. +.de SL \" draw single line (works in non-fill mode only) +.sp -.8 +.ti 0 +\l'\\n(.lu\(ul' +.. +.de Hl \" draw horizontal line +.br +.ti 0 +\l'\\n(.lu-\\n(.iu' +.br +.. +.de DL \" draw double line (works in non-fill mode only) +.sp -.8 +.ti 0 +\l'\\n(.lu\(ul' +.sp -.8 +.ti 0 +\l'\\n(.lu\(ul' +.. +.ST +.nr PN 0 1 \" sets starting page number and auto-increment +.\" must define page header (if any) before here +.TP +.ds 3) \|\v'3p'\s+5\z\(sq\s0\v'-3p'\h'1.25p'\v'-.5p'3\v'.5p'\h'2p' +.\" old one .ds 2) \h'-1.5p'\v'1p'\s+4\z\(ci\s0\v'-1p'\h'3.25p'2 +.ds 2) \|\v'-2.4p'\D'c.095id'\h'-5.15p'\v'2.4p'2\h'1.9p' +.ds dC \v'1p'\s+5\(bu\s0\v'-1p'\" for development commands +.ds tC \s+2\(dm\s0\" (for DWB) should be a triangle +.ds tP \s+2\(dm\s0\" (for other text processing) should be a triangle +.\" various trademark symbols +.ds Tm \v'-0.5m'\s8TM\s0\v'0.5m' +.ds Ts \v'-0.5m'\s4TM\s0\v'0.5m' +.ig ++ +.\" mount Serifa fonts +.fp 5 SR +.fp 6 SB +.fp 4 Si +.++ +.\" other assorted junk +.lg 0 +.\" Fl requires extended version of troff +.de Fl \" draw fat horizontal line +.br +.ti 0 +.ruw 1.5p +\l'\\n(.lu-\\n(.iu' +.br +.ruw +.. +.de Bx \" box for keys in text +\\$3\&\|\&\c +\s-3\(br\|\fH\v'.18n'\\$1\v'-.18n\fP\|\(br\l'|0\(rn'\l'|0\(ul'\&\s0\|\\$2 +.. +.de Fn \" function name - left justified, gray background +.\" bold with gray for function name +.ns +.br +\ +.ns +.br +\!! gsave ( ) stringwidth neg 0 rmoveto +\!! /Serifa-Bold findfont 8 scalefont setfont +\!! (\\$1) dup stringwidth pop 6 gsave dup 0 exch rlineto neg exch 0 rlineto +\!! 0 exch rlineto closepath .9 setgray fill grestore show +\!! grestore +.nf +.rs +.. +.rs diff --git a/doc/no.colors b/doc/no.colors new file mode 100644 index 00000000..4e0d0c62 --- /dev/null +++ b/doc/no.colors @@ -0,0 +1,31 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" This file is for troff which does not know what to do +.\" with a literal Poscript and cannot use macros from 'colors'. +.\" +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of +.\" this reference card provided the copyright notice and this permission +.\" notice are preserved on all copies. +.\" +.\" Permission is granted to process this file through troff and print the +.\" results, provided the printed document carries copying permission +.\" notice identical to this one except for the removal of this paragraph +.\" (this paragraph not being relevant to the printed reference card). +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" reference card under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" reference card into another language, under the above conditions for +.\" modified versions, except that this permission notice may be stated in +.\" a translation approved by the Foundation. +.\" +.ds CR +.ds CG +.ds CL +.ds CB +.ds CD +.ds CX diff --git a/doc/setter.outline b/doc/setter.outline new file mode 100644 index 00000000..67ade73a --- /dev/null +++ b/doc/setter.outline @@ -0,0 +1,77 @@ +%!PS-Adobe-3.0 +% SSC Reference card typesetter outline / cut marks +% +% Copyright (C) 1996, Specialized System Consultants Inc. (SSC) +% +% This 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 of the License, or +% (at your option) any later version. +% +% This 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 program; if not, write to the Free Software +% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA +% +%! page cut marks and stuff for Pocket References - 10-26-88 - ph +%! modified to move the cut marks onto the page +%! center a string +/inch {72 mul} def +/cshow % stk: string + % center string in space (space us variable) + { + dup stringwidth pop % get length of string + space exch sub 2 div % compute initial space needed + 0 rmoveto % move over + show + } def + +/flashme +{ /space 612 def + 0 0 0 setrgbcolor % always print this stuff + + /Helvetica findfont 12 scalefont setfont + gsave +% for groff (I hope) + -6 -6 translate + 0.2 setlinewidth + + 0.25 inch 10.5 inch moveto + 0.5 inch 10.5 inch lineto + .75 inch 10.75 inch moveto + .75 inch 11 inch lineto + stroke + + 0.25 inch 2 inch moveto + 0.5 inch 2 inch lineto + .75 inch 1.75 inch moveto + .75 inch 1.50 inch lineto + stroke + 4.25 inch 11 inch moveto + 4.25 inch 10.75 inch lineto + stroke + + 4.25 inch 1.75 inch moveto + 4.25 inch 1.5 inch lineto + stroke + + 7.75 inch 1.5 inch moveto + 7.75 inch 1.75 inch lineto + 8 inch 2 inch moveto + 8.25 inch 2 inch lineto + stroke + + 7.75 inch 11 inch moveto + 7.75 inch 10.75 inch lineto + 8 inch 10.5 inch moveto + 8.25 inch 10.5 inch lineto + stroke + grestore + } def + +% actually do something + diff --git a/doc/texinfo.tex b/doc/texinfo.tex index ea80e1d0..f9254e77 100644 --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -1,6 +1,8 @@ -%% TeX macros to handle texinfo files +%% 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, 1994 Free Software Foundation, Inc. +% 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 @@ -34,7 +36,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 2.159 $ +\deftexinfoversion$Revision: 2.193 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -45,20 +47,20 @@ % Save some parts of plain tex whose names we will redefine. -\let\ptextilde=\~ -\let\ptexlbrace=\{ -\let\ptexrbrace=\} -\let\ptexdots=\dots -\let\ptexdot=\. -\let\ptexstar=\* -\let\ptexend=\end -\let\ptexbullet=\bullet \let\ptexb=\b +\let\ptexbullet=\bullet \let\ptexc=\c +\let\ptexcomma=\, +\let\ptexdot=\. +\let\ptexdots=\dots +\let\ptexend=\end +\let\ptexequiv = \equiv \let\ptexi=\i +\let\ptexlbrace=\{ +\let\ptexrbrace=\} +\let\ptexstar=\* \let\ptext=\t -\let\ptexl=\l -\let\ptexL=\L +\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,6 +75,7 @@ } \let\~ = \tie % And make it available as @~. + \message{Basics,} \chardef\other=12 @@ -102,10 +105,9 @@ \hyphenation{eshell} % Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset \bindingoffset=0pt -\newdimen \normaloffset \normaloffset=\hoffset +\newdimen \bindingoffset +\newdimen \normaloffset \newdimen\pagewidth \newdimen\pageheight -\pagewidth=\hsize \pageheight=\vsize % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, @@ -126,7 +128,7 @@ \newdimen\cornerlong \newdimen\cornerthick \newdimen \topandbottommargin \newdimen \outerhsize \newdimen \outervsize -\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks +\cornerlong=1pc\cornerthick=.3pt % These set size of cropmarks \outerhsize=7in %\outervsize=9.5in % Alternative @smallbook page size is 9.25in @@ -135,16 +137,42 @@ % %---------------------End change----------------------- +% Main output routine. +\chardef\PAGE = 255 +\output = {\onepageout{\pagecontents\PAGE}} + +\newbox\headlinebox \newbox\footlinebox + % \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions itself, but you have to call it yourself. -\chardef\PAGE=255 \output={\onepageout{\pagecontents\PAGE}} -\def\onepageout#1{\hoffset=\normaloffset -\ifodd\pageno \advance\hoffset by \bindingoffset -\else \advance\hoffset by -\bindingoffset\fi -{\escapechar=`\\\relax % makes sure backslash is used in output files. -\shipout\vbox{{\let\hsize=\pagewidth \makeheadline} \pagebody{#1}% -{\let\hsize=\pagewidth \makefootline}}}% -\advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi} +% does insertions, but you have to call it yourself. +\def\onepageout#1{% + \hoffset=\normaloffset + \ifodd\pageno \advance\hoffset by \bindingoffset + \else \advance\hoffset by -\bindingoffset\fi + % + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% + \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% + % + {% + % Have to do this stuff outside the \shipout because we want it to + % take effect in \write's, yet the group defined by the \vbox ends + % before the \shipout runs. + % + \escapechar = `\\ % use backslash in output files. + \indexdummies % don't expand commands in the output. + \normalturnoffactive % \ in index entries must not stay \, e.g., if + % the page break happens to be in the middle of an example. + \shipout\vbox{% + \unvbox\headlinebox + \pagebody{#1}% + \unvbox\footlinebox + }% + }% + \advancepageno + \ifnum\outputpenalty>-20000 \else\dosupereject\fi +} %%%% For @cropmarks command %%%% @@ -156,8 +184,8 @@ % \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 + \shipout + \vbox to \outervsize{\hsize=\outerhsize \vbox{\line{\ewtop\hfill\ewtop}} \nointerlineskip \line{\vbox{\moveleft\cornerthick\nstop} @@ -165,19 +193,19 @@ \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 + \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} % @@ -365,11 +393,43 @@ %\def\'{{'}} % Used to generate quoted braces. - \def\mylbrace {{\tt \char '173}} \def\myrbrace {{\tt \char '175}} \let\{=\mylbrace \let\}=\myrbrace +\begingroup + % Definitions to produce actual \{ & \} command in an index. + \catcode`\{ = 12 \catcode`\} = 12 + \catcode`\[ = 1 \catcode`\] = 2 + \catcode`\@ = 0 \catcode`\\ = 12 + @gdef@lbracecmd[\{]% + @gdef@rbracecmd[\}]% +@endgroup + +% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent +% Others are defined by plain TeX: @` @' @" @^ @~ @= @v @H. +\let\, = \c +\let\dotaccent = \. +\def\ringaccent#1{{\accent23 #1}} +\let\tieaccent = \t +\let\ubaraccent = \b +\let\udotaccent = \d + +% Other special characters: @questiondown @exclamdown +% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss. +\def\questiondown{?`} +\def\exclamdown{!`} + +% Dotless i and dotless j, used for accents. +\def\imacro{i} +\def\jmacro{j} +\def\dotless#1{% + \def\temp{#1}% + \ifx\temp\imacro \ptexi + \else\ifx\temp\jmacro \j + \else \errmessage{@dotless can be used only with i or j}% + \fi\fi +} % @: forces normal size whitespace following. \def\:{\spacefactor=1000 } @@ -548,14 +608,22 @@ where each line of input produces a line of output.} %\hbox{{\rm#1}}\hfil\break}} % @include file insert text of that file as input. - -\def\include{\parsearg\includezzz} -%Use \input\thisfile to avoid blank after \input, which may be an active -%char (in which case the blank would become the \input argument). -%The grouping keeps the value of \thisfile correct even when @include -%is nested. -\def\includezzz #1{\begingroup -\def\thisfile{#1}\input\thisfile +% Allow normal characters that we make active in the argument (a file name). +\def\include{\begingroup + \catcode`\\=12 + \catcode`~=12 + \catcode`^=12 + \catcode`_=12 + \catcode`|=12 + \catcode`<=12 + \catcode`>=12 + \catcode`+=12 + \parsearg\includezzz} +% Restore active chars for included file. +\def\includezzz#1{\endgroup\begingroup + % Read the included file in a group so nested @include's work. + \def\thisfile{#1}% + \input\thisfile \endgroup} \def\thisfile{} @@ -570,7 +638,7 @@ where each line of input produces a line of output.} % @sp n outputs n lines of vertical space \def\sp{\parsearg\spxxx} -\def\spxxx #1{\par \vskip #1\baselineskip} +\def\spxxx #1{\vskip #1\baselineskip} % @comment ...line which is ignored... % @c is the same as @comment @@ -583,6 +651,9 @@ where each line of input produces a line of output.} \let\c=\comment +% @paragraphindent is defined for the Info formatting commands only. +\let\paragraphindent=\comment + % Prevent errors for section commands. % Used in @ignore and in failing conditionals. \def\ignoresections{% @@ -617,6 +688,7 @@ where each line of input produces a line of output.} % incorrectly. % \def\ignoremorecommands{% + \let\defcodeindex = \relax \let\defcv = \relax \let\deffn = \relax \let\deffnx = \relax @@ -657,7 +729,6 @@ where each line of input produces a line of output.} \let\set = \relax \let\clear = \relax \let\item = \relax - \let\message = \relax } % Ignore @ignore ... @end ignore. @@ -672,10 +743,15 @@ where each line of input produces a line of output.} \def\menu{\doignore{menu}} \def\direntry{\doignore{direntry}} +% Also ignore @macro ... @end macro. The user must run texi2dvi, +% which runs makeinfo to do macro expansion. Ignore @unmacro, too. +\def\macro{\doignore{macro}} +\let\unmacro = \comment + + % @dircategory CATEGORY -- specify a category of the dir file % which this file should belong to. Ignore this in TeX. - -\def\dircategory{\comment} +\let\dircategory = \comment % Ignore text until a line `@end #1'. % @@ -708,11 +784,12 @@ where each line of input produces a line of output.} \immediate\write16{If you are running another version of TeX, relax.} \immediate\write16{If you are running Unix TeX 3.0, kill this TeX process.} \immediate\write16{ Then upgrade your TeX installation if you can.} + \immediate\write16{ (See ftp://ftp.gnu.ai.mit.edu/pub/gnu/TeX.README.)} \immediate\write16{If you are stuck with version 3.0, run the} \immediate\write16{ script ``tex3patch'' from the Texinfo distribution} \immediate\write16{ to use a workaround.} \immediate\write16{} - \warnedobstrue + \global\warnedobstrue \fi } @@ -788,15 +865,19 @@ where each line of input produces a line of output.} % Since we want to separate VAR from REST-OF-LINE (which might be % empty), we can't just use \parsearg; we have to insert a space of our % own to delimit the rest of the line, and then take it out again if we -% didn't need it. +% didn't need it. Make sure the catcode of space is correct to avoid +% losing inside @example, for instance. % -\def\set{\parsearg\setxxx} +\def\set{\begingroup\catcode` =10 + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \parsearg\setxxx} \def\setxxx#1{\setyyy#1 \endsetyyy} \def\setyyy#1 #2\endsetyyy{% \def\temp{#2}% \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted. \fi + \endgroup } % Can't use \xdef to pre-expand #2 and save some time, since \temp or % \next or other control sequences that we've defined might get us into @@ -810,10 +891,16 @@ where each line of input produces a line of output.} % @value{foo} gets the text saved in variable foo. % -\def\value#1{\expandafter - \ifx\csname SET#1\endcsname\relax - {\{No value for ``#1''\}} - \else \csname SET#1\endcsname \fi} +\def\value{\begingroup + \catcode`\-=12 \catcode`\_=12 % Allow - and _ in VAR. + \valuexxx} +\def\valuexxx#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + {\{No value for ``#1''\}}% + \else + \csname SET#1\endcsname + \fi +\endgroup} % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. @@ -913,6 +1000,7 @@ where each line of input produces a line of output.} \expandafter\expandafter\expandafter\appendixsetref{\lastnode}\fi \global\let\lastnode=\relax} +% @refill is a no-op. \let\refill=\relax % @setfilename is done at the beginning of every texinfo file. @@ -927,11 +1015,24 @@ where each line of input produces a line of output.} \comment % Ignore the actual filename. } +% @bye. \outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} -\def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, - node \samp{\ignorespaces#1{}}} +% \def\macro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\macroxxx} +% \def\macroxxx#1#2 \end macro{% +% \expandafter\gdef\macrotemp#1{#2}% +% \endgroup} + +%\def\linemacro#1{\begingroup\ignoresections\catcode`\#=6\def\macrotemp{#1}\parsearg\linemacroxxx} +%\def\linemacroxxx#1#2 \end linemacro{% +%\let\parsearg=\relax +%\edef\macrotempx{\csname M\butfirst\expandafter\string\macrotemp\endcsname}% +%\expandafter\xdef\macrotemp{\parsearg\macrotempx}% +%\expandafter\gdef\macrotempx#1{#2}% +%\endgroup} + +%\def\butfirst#1{} + \message{fonts,} @@ -943,12 +1044,16 @@ where each line of input produces a line of output.} \def\sf{\fam=\sffam \tensf} \let\li = \sf % Sometimes we call it \li, not \sf. +% We don't need math for this one. +\def\ttsl{\tenttsl} + %% Try out Computer Modern fonts at \magstephalf \let\mainmagstep=\magstephalf % Set the font macro #1 to the font named #2, adding on the % specified font prefix (normally `cm'). -\def\setfont#1#2{\font#1=\fontprefix#2} +% #3 is the font's design size, #4 is a scale factor +\def\setfont#1#2#3#4{\font#1=\fontprefix#2#3 scaled #4} % Use cm as the default font prefix. % To specify the font prefix, you must define \fontprefix @@ -956,96 +1061,119 @@ where each line of input produces a line of output.} \ifx\fontprefix\undefined \def\fontprefix{cm} \fi +% Support font families that don't use the same naming scheme as CM. +\def\rmshape{r} +\def\rmbshape{bx} %where the normal face is bold +\def\bfshape{b} +\def\bxshape{bx} +\def\ttshape{tt} +\def\ttbshape{tt} +\def\ttslshape{sltt} +\def\itshape{ti} +\def\itbshape{bxti} +\def\slshape{sl} +\def\slbshape{bxsl} +\def\sfshape{ss} +\def\sfbshape{ss} +\def\scshape{csc} +\def\scbshape{csc} \ifx\bigger\relax \let\mainmagstep=\magstep1 -\setfont\textrm{r12} -\setfont\texttt{tt12} +\setfont\textrm\rmshape{12}{1000} +\setfont\texttt\ttshape{12}{1000} \else -\setfont\textrm{r10 scaled \mainmagstep} -\setfont\texttt{tt10 scaled \mainmagstep} +\setfont\textrm\rmshape{10}{\mainmagstep} +\setfont\texttt\ttshape{10}{\mainmagstep} \fi % Instead of cmb10, you many want to use cmbx10. % cmbx10 is a prettier font on its own, but cmb10 % looks better when embedded in a line with cmr10. -\setfont\textbf{b10 scaled \mainmagstep} -\setfont\textit{ti10 scaled \mainmagstep} -\setfont\textsl{sl10 scaled \mainmagstep} -\setfont\textsf{ss10 scaled \mainmagstep} -\setfont\textsc{csc10 scaled \mainmagstep} +\setfont\textbf\bfshape{10}{\mainmagstep} +\setfont\textit\itshape{10}{\mainmagstep} +\setfont\textsl\slshape{10}{\mainmagstep} +\setfont\textsf\sfshape{10}{\mainmagstep} +\setfont\textsc\scshape{10}{\mainmagstep} +\setfont\textttsl\ttslshape{10}{\mainmagstep} \font\texti=cmmi10 scaled \mainmagstep \font\textsy=cmsy10 scaled \mainmagstep % A few fonts for @defun, etc. -\setfont\defbf{bx10 scaled \magstep1} %was 1314 -\setfont\deftt{tt10 scaled \magstep1} +\setfont\defbf\bxshape{10}{\magstep1} %was 1314 +\setfont\deftt\ttshape{10}{\magstep1} \def\df{\let\tentt=\deftt \let\tenbf = \defbf \bf} -% Fonts for indices and small examples. +% Fonts for indices and small examples (9pt). % We actually use the slanted font rather than the italic, % because texinfo normally uses the slanted fonts for that. % Do not make many font distinctions in general in the index, since they % aren't very useful. -\setfont\ninett{tt9} -\setfont\indrm{r9} -\setfont\indit{sl9} +\setfont\ninett\ttshape{9}{1000} +\setfont\indrm\rmshape{9}{1000} +\setfont\indit\slshape{9}{1000} \let\indsl=\indit \let\indtt=\ninett +\let\indttsl=\ninett \let\indsf=\indrm \let\indbf=\indrm -\setfont\indsc{csc10 at 9pt} +\setfont\indsc\scshape{10}{900} \font\indi=cmmi9 \font\indsy=cmsy9 -% Fonts for headings -\setfont\chaprm{bx12 scaled \magstep2} -\setfont\chapit{ti12 scaled \magstep2} -\setfont\chapsl{sl12 scaled \magstep2} -\setfont\chaptt{tt12 scaled \magstep2} -\setfont\chapsf{ss12 scaled \magstep2} +% 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} \let\chapbf=\chaprm -\setfont\chapsc{csc10 scaled\magstep3} +\setfont\chapsc\scbshape{10}{\magstep3} \font\chapi=cmmi12 scaled \magstep2 \font\chapsy=cmsy10 scaled \magstep3 -\setfont\secrm{bx12 scaled \magstep1} -\setfont\secit{ti12 scaled \magstep1} -\setfont\secsl{sl12 scaled \magstep1} -\setfont\sectt{tt12 scaled \magstep1} -\setfont\secsf{ss12 scaled \magstep1} -\setfont\secbf{bx12 scaled \magstep1} -\setfont\secsc{csc10 scaled\magstep2} +% Section fonts (14.4pt). +\setfont\secrm\rmbshape{12}{\magstep1} +\setfont\secit\itbshape{10}{\magstep2} +\setfont\secsl\slbshape{10}{\magstep2} +\setfont\sectt\ttbshape{12}{\magstep1} +\setfont\secttsl\ttslshape{10}{\magstep2} +\setfont\secsf\sfbshape{12}{\magstep1} +\let\secbf\secrm +\setfont\secsc\scbshape{10}{\magstep2} \font\seci=cmmi12 scaled \magstep1 \font\secsy=cmsy10 scaled \magstep2 -% \setfont\ssecrm{bx10 scaled \magstep1} % This size an font looked bad. -% \setfont\ssecit{cmti10 scaled \magstep1} % The letters were too crowded. -% \setfont\ssecsl{sl10 scaled \magstep1} -% \setfont\ssectt{tt10 scaled \magstep1} -% \setfont\ssecsf{ss10 scaled \magstep1} +% \setfont\ssecrm\bxshape{10}{\magstep1} % This size an font looked bad. +% \setfont\ssecit\itshape{10}{\magstep1} % The letters were too crowded. +% \setfont\ssecsl\slshape{10}{\magstep1} +% \setfont\ssectt\ttshape{10}{\magstep1} +% \setfont\ssecsf\sfshape{10}{\magstep1} -%\setfont\ssecrm{b10 scaled 1315} % Note the use of cmb rather than cmbx. -%\setfont\ssecit{ti10 scaled 1315} % Also, the size is a little larger than -%\setfont\ssecsl{sl10 scaled 1315} % being scaled magstep1. -%\setfont\ssectt{tt10 scaled 1315} -%\setfont\ssecsf{ss10 scaled 1315} +%\setfont\ssecrm\bfshape{10}{1315} % Note the use of cmb rather than cmbx. +%\setfont\ssecit\itshape{10}{1315} % Also, the size is a little larger than +%\setfont\ssecsl\slshape{10}{1315} % being scaled magstep1. +%\setfont\ssectt\ttshape{10}{1315} +%\setfont\ssecsf\sfshape{10}{1315} %\let\ssecbf=\ssecrm -\setfont\ssecrm{bx12 scaled \magstephalf} -\setfont\ssecit{ti12 scaled \magstephalf} -\setfont\ssecsl{sl12 scaled \magstephalf} -\setfont\ssectt{tt12 scaled \magstephalf} -\setfont\ssecsf{ss12 scaled \magstephalf} -\setfont\ssecbf{bx12 scaled \magstephalf} -\setfont\ssecsc{csc10 scaled \magstep1} +% Subsection fonts (13.15pt). +\setfont\ssecrm\rmbshape{12}{\magstephalf} +\setfont\ssecit\itbshape{10}{1315} +\setfont\ssecsl\slbshape{10}{1315} +\setfont\ssectt\ttbshape{12}{\magstephalf} +\setfont\ssecttsl\ttslshape{10}{\magstep1} +\setfont\ssecsf\sfbshape{12}{\magstephalf} +\let\ssecbf\ssecrm +\setfont\ssecsc\scbshape{10}{\magstep1} \font\sseci=cmmi12 scaled \magstephalf \font\ssecsy=cmsy10 scaled \magstep1 % The smallcaps and symbol fonts should actually be scaled \magstep1.5, % but that is not a standard magnification. % Fonts for title page: -\setfont\titlerm{bx12 scaled \magstep3} +\setfont\titlerm\rmbshape{12}{\magstep3} \let\authorrm = \secrm % In order for the font changes to affect most math symbols and letters, @@ -1064,34 +1192,35 @@ where each line of input produces a line of output.} % The font-changing commands redefine the meanings of \tenSTYLE, instead % of just \STYLE. We do this so that font changes will continue to work % in math mode, where it is the current \fam that is relevant in most -% cases, not the current. Plain TeX does, for example, -% \def\bf{\fam=\bffam \tenbf} By redefining \tenbf, we obviate the need -% to redefine \bf itself. +% cases, not the current font. Plain TeX does \def\bf{\fam=\bffam +% \tenbf}, for example. By redefining \tenbf, we obviate the need to +% redefine \bf itself. \def\textfonts{% \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy + \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy \let\tenttsl=\textttsl \resetmathfonts} \def\chapfonts{% \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy - \resetmathfonts} + \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy \let\tenttsl=\chapttsl + \resetmathfonts \setleading{19pt}} \def\secfonts{% \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy - \resetmathfonts} + \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy \let\tenttsl=\secttsl + \resetmathfonts \setleading{16pt}} \def\subsecfonts{% \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy - \resetmathfonts} + \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy \let\tenttsl=\ssecttsl + \resetmathfonts \setleading{15pt}} +\let\subsubsecfonts = \subsecfonts % Maybe make sssec fonts scaled magstephalf? \def\indexfonts{% \let\tenrm=\indrm \let\tenit=\indit \let\tensl=\indsl \let\tenbf=\indbf \let\tentt=\indtt \let\smallcaps=\indsc - \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy - \resetmathfonts} + \let\tensf=\indsf \let\teni=\indi \let\tensy=\indsy \let\tenttsl=\indttsl + \resetmathfonts \setleading{12pt}} % Set up the default fonts, so we can use them for creating boxes. % @@ -1101,9 +1230,9 @@ where each line of input produces a line of output.} \newcount\fontdepth \fontdepth=0 % Fonts for short table of contents. -\setfont\shortcontrm{r12} -\setfont\shortcontbf{bx12} -\setfont\shortcontsl{sl12} +\setfont\shortcontrm\rmshape{12}{1000} +\setfont\shortcontbf\bxshape{12}{1000} +\setfont\shortcontsl\slshape{12}{1000} %% Add scribe-like font environments, plus @l for inline lisp (usually sans %% serif) and @ii for TeX italic @@ -1135,10 +1264,21 @@ where each line of input produces a line of output.} } \let\ttfont=\t \def\samp #1{`\tclose{#1}'\null} -\def\key #1{{\tt \nohyphenation \uppercase{#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{% + \vbox{\hrule\kern-0.4pt + \hbox{\raise0.4pt\hbox{\vphantom{$\langle$}}#1}}% + \kern-0.4pt\hrule}% + \kern-.06em\raise0.4pt\hbox{$\rangle$}}}} +% 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. @@ -1170,21 +1310,26 @@ where each line of input produces a line of output.} % Unfortunately, TeX uses one parameter (\hyphenchar) to control % both hyphenation at - and hyphenation within words. % We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate an a dash. +% and arrange explicitly to hyphenate at a dash. % -- rms. { \catcode`\-=\active \catcode`\_=\active +\catcode`\|=\active \global\def\code{\begingroup \catcode`\-=\active \let-\codedash \catcode`\_=\active \let_\codeunder \codex} % The following is used by \doprintindex to insure that long function names % wrap around. It is necessary for - and _ to be active before the index is % read from the file, as \entry parses the arguments long before \code is % ever called. -- mycroft -\global\def\indexbreaks{\catcode`\-=\active \let-\realdash \catcode`\_=\active \let_\realunder} +% _ is always active; and it shouldn't be \let = to an _ that is a +% subscript character anyway. Then, @cindex @samp{_} (for example) +% fails. --karl +\global\def\indexbreaks{% + \catcode`\-=\active \let-\realdash +} } \def\realdash{-} -\def\realunder{_} \def\codedash{-\discretionary{}{}{}} \def\codeunder{\normalunderscore\discretionary{}{}{}} \def\codex #1{\tclose{#1}\endgroup} @@ -1193,12 +1338,19 @@ where each line of input produces a line of output.} % @kbd is like @code, except that if the argument is just one @key command, % then @kbd has no effect. - +% \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{\look}\fi -\else\tclose{\look}\fi} +\else{\tclose{\ttsl\look}}\fi +\else{\tclose{\ttsl\look}}\fi} + +% 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 % argument is to make the input look right: @dmn{pt} instead of @@ -1208,12 +1360,19 @@ where each line of input produces a line of output.} \def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} -\def\l#1{{\li #1}\null} % +% @l was never documented to mean ``switch to the Lisp font'', +% and it is not used as such in any manual I can find. We need it for +% Polish suppressed-l. --karl, 22sep96. +%\def\l#1{{\li #1}\null} -\def\r#1{{\rm #1}} % roman font +\def\r#1{{\rm #1}} % roman font % Use of \lowercase was suggested. -\def\sc#1{{\smallcaps#1}} % smallcaps font -\def\ii#1{{\it #1}} % italic font +\def\sc#1{{\smallcaps#1}} % smallcaps font +\def\ii#1{{\it #1}} % italic font + +% @pounds{} is a sterling sign. +\def\pounds{{\it\$}} + \message{page headings,} @@ -1228,7 +1387,7 @@ where each line of input produces a line of output.} \def\shorttitlepage{\parsearg\shorttitlepagezzz} \def\shorttitlepagezzz #1{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} + \endgroup\page\hbox{}\page} \def\titlepage{\begingroup \parindent=0pt \textfonts \let\subtitlerm=\tenrm @@ -1245,9 +1404,9 @@ 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}} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% + % print a rule at the page bottom also. + \finishedtitlepagefalse + \vskip4pt \hrule height 4pt width \hsize \vskip4pt}% % No rule at page bottom unless we print one at the top with @title. \finishedtitlepagetrue % @@ -1265,7 +1424,7 @@ where each line of input produces a line of output.} \let\oldpage = \page \def\page{% \iffinishedtitlepage\else - \finishtitlepage + \finishtitlepage \fi \oldpage \let\page = \oldpage @@ -1353,14 +1512,15 @@ where each line of input produces a line of output.} % }% unbind the catcode of @. -% @headings double turns headings on for double-sided printing. -% @headings single turns headings on for single-sided printing. -% @headings off turns them off. -% @headings on same as @headings double, retained for compatibility. -% @headings after turns on double-sided headings after this page. -% @headings doubleafter turns on double-sided headings after this page. +% @headings double turns headings on for double-sided printing. +% @headings single turns headings on for single-sided printing. +% @headings off turns them off. +% @headings on same as @headings double, retained for compatibility. +% @headings after turns on double-sided headings after this page. +% @headings doubleafter turns on double-sided headings after this page. % @headings singleafter turns on single-sided headings after this page. -% By default, they are off. +% By default, they are off at the start of a document, +% and turned `on' after @end titlepage. \def\headings #1 {\csname HEADINGS#1\endcsname} @@ -1374,22 +1534,24 @@ where each line of input produces a line of output.} % title on inside top of left hand pages, and page numbers on outside top % edge of all pages. \def\HEADINGSdouble{ -%\pagealignmacro \global\pageno=1 \global\evenfootline={\hfil} \global\oddfootline={\hfil} \global\evenheadline={\line{\folio\hfil\thistitle}} \global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage } +\let\contentsalignmacro = \chappager + % For single-sided printing, chapter title goes across top left of page, % page number on top right. \def\HEADINGSsingle{ -%\pagealignmacro \global\pageno=1 \global\evenfootline={\hfil} \global\oddfootline={\hfil} \global\evenheadline={\line{\thischapter\hfil\folio}} \global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager } \def\HEADINGSon{\HEADINGSdouble} @@ -1400,6 +1562,7 @@ where each line of input produces a line of output.} \global\oddfootline={\hfil} \global\evenheadline={\line{\folio\hfil\thistitle}} \global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chapoddpage } \def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} @@ -1408,6 +1571,7 @@ where each line of input produces a line of output.} \global\oddfootline={\hfil} \global\evenheadline={\line{\thischapter\hfil\folio}} \global\oddheadline={\line{\thischapter\hfil\folio}} +\global\let\contentsalignmacro = \chappager } % Subroutines used in generating headings @@ -1431,6 +1595,7 @@ July\or August\or September\or October\or November\or December\fi \def\settitle{\parsearg\settitlezzz} \def\settitlezzz #1{\gdef\thistitle{#1}} + \message{tables,} % @tabs -- simple alignment @@ -1463,7 +1628,7 @@ July\or August\or September\or October\or November\or December\fi \newif\ifitemxneedsnegativevskip -\def\itemxpar{\par\ifitemxneedsnegativevskip\vskip-\parskip\nobreak\fi} +\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} \def\internalBitem{\smallbreak \parsearg\itemzzz} \def\internalBitemx{\itemxpar \parsearg\itemzzz} @@ -1734,7 +1899,7 @@ July\or August\or September\or October\or November\or December\fi \flushcr} % @multitable macros -% Amy Hendrickson, 8/18/94 +% Amy Hendrickson, 8/18/94, 3/6/96 % % @multitable ... @end multitable will make as many columns as desired. % Contents of each column will wrap at width given in preamble. Width @@ -1746,25 +1911,35 @@ 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: -% @multitable @percentofhsize .2 .3 .5 +% @multitable @columnfractions .25 .3 .45 % @item ... % -% Numbers following @percentofhsize are the percent of the total +% Numbers following @columnfractions are the percent of the total % current hsize to be used for each column. You may use as many % columns as desired. + % Or use a template: % @multitable {Column 1 template} {Column 2 template} {Column 3 template} % @item ... % using the widest term desired in each column. - +% +% For those who want to use more than one line's worth of words in +% the preamble, break the line within one argument and it +% will parse correctly, i.e., +% +% @multitable {Column 1 template} {Column 2 template} {Column 3 +% template} +% Not: +% @multitable {Column 1 template} {Column 2 template} +% {Column 3 template} % 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. -% @item, @tab, @multicolumn or @endmulticolumn do not need to be on their +% @item, @tab, @multitable or @end multitable do not need to be on their % own lines, but it will not hurt if they are. % Sample multitable: @@ -1785,68 +1960,83 @@ July\or August\or September\or October\or November\or December\fi % @end multitable % Default dimensions may be reset by user. -% @intableparskip will set vertical space between paragraphs in table. -% @intableparindent will set paragraph indent in table. -% @spacebetweencols will set horizontal space to be left between columns. -% @spacebetweenlines will set vertical space to be left between lines. +% @multitableparskip is vertical space between paragraphs in table. +% @multitableparindent is paragraph indent in table. +% @multitablecolmargin is horizontal space to be left between columns. +% @multitablelinespace is space to leave between table items, baseline +% to baseline. +% 0pt means it depends on current normal line spacing. %%%% % Dimensions -\newdimen\intableparskip -\newdimen\intableparindent -\newdimen\spacebetweencols -\newdimen\spacebetweenlines -\intableparskip=0pt -\intableparindent=6pt -\spacebetweencols=12pt -\spacebetweenlines=12pt +\newskip\multitableparskip +\newskip\multitableparindent +\newdimen\multitablecolspace +\newskip\multitablelinespace +\multitableparskip=0pt +\multitableparindent=6pt +\multitablecolspace=12pt +\multitablelinespace=0pt %%%% % Macros used to set up halign preamble: \let\endsetuptable\relax \def\xendsetuptable{\endsetuptable} -\let\percentofhsize\relax -\def\xpercentofhsize{\percentofhsize} +\let\columnfractions\relax +\def\xcolumnfractions{\columnfractions} \newif\ifsetpercent +%% 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} + \newcount\colcount \def\setuptable#1{\def\firstarg{#1}% \ifx\firstarg\xendsetuptable\let\go\relax% \else - \ifx\firstarg\xpercentofhsize\global\setpercenttrue% + \ifx\firstarg\xcolumnfractions\global\setpercenttrue% \else \ifsetpercent - \if#1.\else% - \global\advance\colcount by1 % - \expandafter\xdef\csname col\the\colcount\endcsname{.#1\hsize}% - \fi + \let\go\pickupwholefraction % In this case arg of setuptable + % is the decimal point before the + % number given in percent of hsize. + % We don't need this so we don't use it. \else \global\advance\colcount by1 - \setbox0=\hbox{#1}% + \setbox0=\hbox{#1 }% Add a normal word space as a separator; + % typically that is always in the input, anyway. \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% \fi% \fi% - \let\go\setuptable% +\ifx\go\pickupwholefraction\else\let\go\setuptable\fi% \fi\go} + %%%% % multitable syntax -\def\tab{&} +\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#1\item{\bgroup +\def\multitable{\parsearg\dotable} + +\def\dotable#1{\bgroup \let\item\cr \tolerance=9500 \hbadness=9500 -\parskip=\intableparskip -\parindent=\intableparindent +\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 : -\def\one{#1}\expandafter\setuptable\one\endsetuptable +\setuptable#1 \endsetuptable % Need to reset this to 0 after \setuptable. \global\colcount=0\relax% % @@ -1855,11 +2045,11 @@ July\or August\or September\or October\or November\or December\fi % \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% -\vtop{\hsize=\expandafter\csname col\the\colcount\endcsname +\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 \spacebetweencols to all columns after + % we will add a \leftskip of \multitablecolspace to all columns after % the first one. - % If a template has been used, we will add \spacebetweencols + % 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 @@ -1871,20 +2061,58 @@ July\or August\or September\or October\or November\or December\fi \ifsetpercent \else % If user has <not> set preamble in terms of percent of \hsize - % we will advance \hsize by \spacebetweencols - \advance\hsize by \spacebetweencols + % we will advance \hsize by \multitablecolspace + \advance\hsize by \multitablecolspace \fi - % In either case we will make \leftskip=\spacebetweencols: -\leftskip=\spacebetweencols + % In either case we will make \leftskip=\multitablecolspace: +\leftskip=\multitablecolspace \fi -\noindent##}\cr% + % 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{\nointerlineskip\vskip\spacebetweenlines -\filbreak%% keeps underfull box messages off when table breaks over pages. -\global\colcount=0\relax}}} +\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}} +} + +\def\setmultitablespacing{% test to see if user has set \multitablelinespace. +% If so, do nothing. If not, give it an appropriate dimension based on +% current baselineskip. +\ifdim\multitablelinespace=0pt +%% strut to put in table in case some entry doesn't have descenders, +%% 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. +%% If so, set to same dimension as multitablelinespace. +\else +\gdef\multistrut{\vrule height\multitablelinespace depth\dp0 +width0pt\relax} \fi +\ifdim\multitableparskip>\multitablelinespace +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi% +\ifdim\multitableparskip=0pt +\global\multitableparskip=\multitablelinespace +\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller + %% than skip between lines in the table. +\fi} + \message{indexing,} % Index generation facilities @@ -1898,14 +2126,14 @@ July\or August\or September\or October\or November\or December\fi % It automatically defines \fooindex such that % \fooindex ...rest of line... puts an entry in the index foo. % It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. +% the file that accumulates this index. The file's extension is foo. % The name of an index should be no more than 2 characters long % for the sake of vms. \def\newindex #1{ \expandafter\newwrite \csname#1indfile\endcsname% Define number for output file -\openout \csname#1indfile\endcsname \jobname.#1 % Open the file -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex \noexpand\doindex {#1}} } @@ -1917,8 +2145,8 @@ July\or August\or September\or October\or November\or December\fi \def\newcodeindex #1{ \expandafter\newwrite \csname#1indfile\endcsname% Define number for output file -\openout \csname#1indfile\endcsname \jobname.#1 % Open the file -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\openout \csname#1indfile\endcsname \jobname.#1 % Open the file +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex \noexpand\docodeindex {#1}} } @@ -1929,7 +2157,7 @@ July\or August\or September\or October\or November\or December\fi \def\synindex #1 #2 {% \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname \expandafter\let\csname#1indfile\endcsname=\synindexfoo -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex \noexpand\doindex {#2}}% } @@ -1938,7 +2166,7 @@ July\or August\or September\or October\or November\or December\fi \def\syncodeindex #1 #2 {% \expandafter\let\expandafter\synindexfoo\expandafter=\csname#2indfile\endcsname \expandafter\let\csname#1indfile\endcsname=\synindexfoo -\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex +\expandafter\xdef\csname#1index\endcsname{% % Define \xxxindex \noexpand\docodeindex {#2}}% } @@ -1986,24 +2214,31 @@ July\or August\or September\or October\or November\or December\fi \def\L{\realbackslash L}% \def\ss{\realbackslash ss}% % Take care of texinfo commands likely to appear in an index entry. +% (Must be a way to avoid doing expansion at all, and thus not have to +% laboriously list every single command here.) +\def\@{@}% will be @@ when we switch to @ as escape char. +%\let\{ = \lbracecmd +%\let\} = \rbracecmd \def\_{{\realbackslash _}}% \def\w{\realbackslash w }% \def\bf{\realbackslash bf }% -\def\rm{\realbackslash rm }% +%\def\rm{\realbackslash rm }% \def\sl{\realbackslash sl }% \def\sf{\realbackslash sf}% \def\tt{\realbackslash tt}% \def\gtr{\realbackslash gtr}% \def\less{\realbackslash less}% \def\hat{\realbackslash hat}% -\def\char{\realbackslash char}% +%\def\char{\realbackslash char}% \def\TeX{\realbackslash TeX}% \def\dots{\realbackslash dots }% \def\copyright{\realbackslash copyright }% \def\tclose##1{\realbackslash tclose {##1}}% \def\code##1{\realbackslash code {##1}}% +\def\dotless##1{\realbackslash dotless {##1}}% \def\samp##1{\realbackslash samp {##1}}% -\def\t##1{\realbackslash r {##1}}% +\def\,##1{\realbackslash ,{##1}}% +\def\t##1{\realbackslash t {##1}}% \def\r##1{\realbackslash r {##1}}% \def\i##1{\realbackslash i {##1}}% \def\b##1{\realbackslash b {##1}}% @@ -2031,6 +2266,7 @@ July\or August\or September\or October\or November\or December\fi \def\indexnofonts{% % Just ignore accents. +\let\,=\indexdummyfont \let\"=\indexdummyfont \let\`=\indexdummyfont \let\'=\indexdummyfont @@ -2043,6 +2279,7 @@ July\or August\or September\or October\or November\or December\fi \let\u=\indexdummyfont \let\v=\indexdummyfont \let\H=\indexdummyfont +\let\dotless=\indexdummyfont % Take care of the plain tex special European modified letters. \def\oe{oe}% \def\ae{ae}% @@ -2076,6 +2313,7 @@ July\or August\or September\or October\or November\or December\fi \let\var=\indexdummyfont \let\TeX=\indexdummytex \let\dots=\indexdummydots +\def\@{@}% } % To define \realbackslash, we must make \ not be an escape. @@ -2091,29 +2329,37 @@ July\or August\or September\or October\or November\or December\fi % workhorse for all \fooindexes % #1 is name of index, #2 is stuff to put there \def\doind #1#2{% -% Put the index entry in the margin if desired. -\ifx\SETmarginindex\relax\else% -\insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% -\fi% -{\count10=\lastpenalty % -{\indexdummies % Must do this here, since \bf, etc expand at this stage -\escapechar=`\\% -{\let\folio=0% Expand all macros now EXCEPT \folio -\def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now -% so it will be output as is; and it will print as backslash in the indx. -% -% Now process the index-string once, with all font commands turned off, -% to get the string to sort the index by. -{\indexnofonts -\xdef\temp1{#2}% -}% -% Now produce the complete index entry. We process the index-string again, -% this time with font commands expanded, to get what to print in the index. -\edef\temp{% -\write \csname#1indfile\endcsname{% -\realbackslash entry {\temp1}{\folio}{#2}}}% -\temp }% -}\penalty\count10}} + % Put the index entry in the margin if desired. + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt #2}}% + \fi + {% + \count255=\lastpenalty + {% + \indexdummies % Must do this here, since \bf, etc expand at this stage + \escapechar=`\\ + {% + \let\folio=0% We will expand all macros now EXCEPT \folio. + \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now + % so it will be output as is; and it will print as backslash. + % + % First process the index-string with all font commands turned off + % to get the string to sort by. + {\indexnofonts \xdef\indexsorttmp{#2}}% + % + % Now produce the complete index entry, with both the sort key and the + % original text, including any font commands. + \toks0 = {#2}% + \edef\temp{% + \write\csname#1indfile\endcsname{% + \realbackslash entry{\indexsorttmp}{\folio}{\the\toks0}}% + }% + \temp + }% + }% + \penalty\count255 + }% +} \def\dosubind #1#2#3{% {\count10=\lastpenalty % @@ -2174,26 +2420,19 @@ July\or August\or September\or October\or November\or December\fi \def\printindex{\parsearg\doprintindex} -\def\doprintindex#1{% - \tex - \dobreak \chapheadingskip {10000} - \catcode`\%=\other\catcode`\&=\other\catcode`\#=\other - \catcode`\$=\other - \catcode`\~=\other - \indexbreaks +\def\doprintindex#1{\begingroup + \dobreak \chapheadingskip{10000}% % - % The following don't help, since the chars were translated - % when the raw index was written, and their fonts were discarded - % due to \indexnofonts. - %\catcode`\"=\active - %\catcode`\^=\active - %\catcode`\_=\active - %\catcode`\|=\active - %\catcode`\<=\active - %\catcode`\>=\active - % % - \def\indexbackslash{\rawbackslashxx} - \indexfonts\rm \tolerance=9500 \advance\baselineskip -1pt + \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. @@ -2204,7 +2443,7 @@ July\or August\or September\or October\or November\or December\fi % index. The easiest way to prevent this problem is to make sure % there is some text. (Index is nonexistent) - \else + \else % % If the index file exists but is empty, then \openin leaves \ifeof % false. We have to make TeX try to read something from the file, so @@ -2218,8 +2457,7 @@ July\or August\or September\or October\or November\or December\fi \fi \closein 1 \enddoublecolumns - \Etex -} +\endgroup} % These macros are used by the sorted index file itself. % Change them to control the appearance of the index. @@ -2310,15 +2548,15 @@ July\or August\or September\or October\or November\or December\fi \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill #2\par }} -%% Define two-column mode, which is used in indexes. -%% Adapted from the TeXbook, page 416. -\catcode `\@=11 +% Define two-column mode, which we use to typeset indexes. +% Adapted from the TeXbook, page 416, which is to say, +% the manmac.tex format used to print the TeXbook itself. +\catcode`\@=11 \newbox\partialpage - \newdimen\doublecolumnhsize -\def\begindoublecolumns{\begingroup +\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns % Grab any single-column material above us. \output = {\global\setbox\partialpage =\vbox{\unvbox255\kern -\topskip \kern \baselineskip}}% @@ -2351,51 +2589,51 @@ July\or August\or September\or October\or November\or December\fi % Double the \vsize as well. (We don't need a separate register here, % since nobody clobbers \vsize.) \vsize = 2\vsize - \doublecolumnpagegoal } - -\def\enddoublecolumns{\eject \endgroup \pagegoal=\vsize \unvbox\partialpage} - -\def\doublecolumnsplit{\splittopskip=\topskip \splitmaxdepth=\maxdepth - \global\dimen@=\pageheight \global\advance\dimen@ by-\ht\partialpage - \global\setbox1=\vsplit255 to\dimen@ \global\setbox0=\vbox{\unvbox1} - \global\setbox3=\vsplit255 to\dimen@ \global\setbox2=\vbox{\unvbox3} - \ifdim\ht0>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi - \ifdim\ht2>\dimen@ \setbox255=\vbox{\unvbox0\unvbox2} \global\setbox255=\copy5 \fi +\def\doublecolumnout{% + \splittopskip=\topskip \splitmaxdepth=\maxdepth + % Get the available space for the double columns -- the normal + % (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. + \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ + \onepageout\pagesofar + \unvbox255 \penalty\outputpenalty } -\def\doublecolumnpagegoal{% - \dimen@=\vsize \advance\dimen@ by-2\ht\partialpage \global\pagegoal=\dimen@ +\def\pagesofar{% + % 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\pagesofar{\unvbox\partialpage % - \hsize=\doublecolumnhsize % have to restore this since output routine - \wd0=\hsize \wd2=\hsize \hbox to\pagewidth{\box0\hfil\box2}} -\def\doublecolumnout{% - \setbox5=\copy255 - {\vbadness=10000 \doublecolumnsplit} - \ifvbox255 - \setbox0=\vtop to\dimen@{\unvbox0} - \setbox2=\vtop to\dimen@{\unvbox2} - \onepageout\pagesofar \unvbox255 \penalty\outputpenalty - \else - \setbox0=\vbox{\unvbox5} - \ifvbox0 - \dimen@=\ht0 \advance\dimen@ by\topskip \advance\dimen@ by-\baselineskip - \divide\dimen@ by2 \splittopskip=\topskip \splitmaxdepth=\maxdepth - {\vbadness=10000 - \loop \global\setbox5=\copy0 - \setbox1=\vsplit5 to\dimen@ - \setbox3=\vsplit5 to\dimen@ - \ifvbox5 \global\advance\dimen@ by1pt \repeat - \setbox0=\vbox to\dimen@{\unvbox1} - \setbox2=\vbox to\dimen@{\unvbox3} - \global\setbox\partialpage=\vbox{\pagesofar} - \doublecolumnpagegoal - } - \fi - \fi +\def\enddoublecolumns{% + \output={\balancecolumns}\eject % split what we have + \endgroup + % Back to normal single-column typesetting, but take account of the + % fact that we just accumulated some stuff on the output page. + \pagegoal=\vsize +} +\def\balancecolumns{% + % Called on the last page 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 + \global\setbox1=\vsplit3 to\dimen@ + \ifdim\ht3>\dimen@ \global\advance\dimen@ by1pt \repeat}% + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + \pagesofar } - \catcode `\@=\other + + \message{sectioning,} % Define chapters, sections, etc. @@ -2567,6 +2805,10 @@ July\or August\or September\or October\or November\or December\fi \global\let\subsubsection = \appendixsubsubsec }} +% @centerchap is like @unnumbered, but the heading is centered. +\outer\def\centerchap{\parsearg\centerchapyyy} +\def\centerchapyyy #1{{\let\unnumbchapmacro=\centerchapmacro \unnumberedyyy{#1}}} + \outer\def\top{\parsearg\unnumberedyyy} \outer\def\unnumbered{\parsearg\unnumberedyyy} \def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz @@ -2669,7 +2911,7 @@ July\or August\or September\or October\or November\or December\fi \outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} \def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz \def\unnumberedsubseczzz #1{\seccheck{unnumberedsubsec}% -\plainsecheading {#1}\gdef\thissection{#1}% +\plainsubsecheading {#1}\gdef\thissection{#1}% {\chapternofonts% \edef\temp{{\realbackslash unnumbsubsecentry{#1}{\noexpand\folio}}}% \escapechar=`\\% @@ -2714,7 +2956,7 @@ July\or August\or September\or October\or November\or December\fi \outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} \def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz \def\unnumberedsubsubseczzz #1{\seccheck{unnumberedsubsubsec}% -\plainsecheading {#1}\gdef\thissection{#1}% +\plainsubsubsecheading {#1}\gdef\thissection{#1}% {\chapternofonts% \edef\temp{{\realbackslash unnumbsubsubsecentry{#1}{\noexpand\folio}}}% \escapechar=`\\% @@ -2752,10 +2994,10 @@ July\or August\or September\or October\or November\or December\fi % NOTE on use of \vbox for chapter headings, section headings, and % such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. +% 1) We use \vbox rather than the earlier \line to permit +% overlong headings to fold. +% 2) \hyphenpenalty is set to 10000 because hyphenation in a +% heading is obnoxious; this forbids it. % 3) Likewise, headings look best if no \parindent is used, and % if justification is not attempted. Hence \raggedright. @@ -2773,11 +3015,10 @@ July\or August\or September\or October\or November\or December\fi \parindent=0pt\raggedright \rm #1\hfill}}\bigskip \par\penalty 200} -\def\heading{\parsearg\secheadingi} - -\def\subheading{\parsearg\subsecheadingi} - -\def\subsubheading{\parsearg\subsubsecheadingi} +% @heading, @subheading, @subsubheading. +\def\heading{\parsearg\plainsecheading} +\def\subheading{\parsearg\plainsubsecheading} +\def\subsubheading{\parsearg\plainsubsubsecheading} % These macros generate a chapter, section, etc. heading only % (including whitespace, linebreaking, etc. around it), @@ -2791,7 +3032,7 @@ July\or August\or September\or October\or November\or December\fi %%% Define plain chapter starts, and page on/off switching for it % Parameter controlling skip before chapter headings (if needed) -\newskip \chapheadingskip \chapheadingskip = 30pt plus 8pt minus 4pt +\newskip\chapheadingskip \def\chapbreak{\dobreak \chapheadingskip {-4000}} \def\chappager{\par\vfill\supereject} @@ -2800,15 +3041,18 @@ July\or August\or September\or October\or November\or December\fi \def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} \def\CHAPPAGoff{ +\global\let\contentsalignmacro = \chappager \global\let\pchapsepmacro=\chapbreak \global\let\pagealignmacro=\chappager} \def\CHAPPAGon{ +\global\let\contentsalignmacro = \chappager \global\let\pchapsepmacro=\chappager \global\let\pagealignmacro=\chappager \global\def\HEADINGSon{\HEADINGSsingle}} \def\CHAPPAGodd{ +\global\let\contentsalignmacro = \chapoddpage \global\let\pchapsepmacro=\chapoddpage \global\let\pagealignmacro=\chapoddpage \global\def\HEADINGSon{\HEADINGSdouble}} @@ -2817,25 +3061,39 @@ July\or August\or September\or October\or November\or December\fi \def\CHAPFplain{ \global\let\chapmacro=\chfplain -\global\let\unnumbchapmacro=\unnchfplain} +\global\let\unnumbchapmacro=\unnchfplain +\global\let\centerchapmacro=\centerchfplain} -\def\chfplain #1#2{% +% Plain chapter opening. +% #1 is the text, #2 the chapter number or empty if unnumbered. +\def\chfplain#1#2{% \pchapsepmacro {% - \chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #2\enspace #1}% + \chapfonts \rm + \def\chapnum{#2}% + \setbox0 = \hbox{#2\ifx\chapnum\empty\else\enspace\fi}% + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 \centerparametersmaybe + \unhbox0 #1\par}% }% - \bigskip - \penalty5000 + \nobreak\bigskip % no page break after a chapter title + \nobreak } -\def\unnchfplain #1{% -\pchapsepmacro % -{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 10000 % -} +% Plain opening for unnumbered. +\def\unnchfplain#1{\chfplain{#1}{}} + +% @centerchap -- centered and unnumbered. +\let\centerparametersmaybe = \relax +\def\centerchfplain#1{{% + \def\centerparametersmaybe{% + \advance\rightskip by 3\rightskip + \leftskip = \rightskip + \parfillskip = 0pt + }% + \chfplain{#1}{}% +}} + \CHAPFplain % The default \def\unnchfopen #1{% @@ -2849,73 +3107,81 @@ July\or August\or September\or October\or November\or December\fi \par\penalty 5000 % } +\def\centerchfopen #1{% +\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt + \hfill {\rm #1}\hfill}}\bigskip \par\penalty 10000 % +} + \def\CHAPFopen{ \global\let\chapmacro=\chfopen -\global\let\unnumbchapmacro=\unnchfopen} +\global\let\unnumbchapmacro=\unnchfopen +\global\let\centerchapmacro=\centerchfopen} + -% Parameter controlling skip before section headings. +% Section titles. +\newskip\secheadingskip +\def\secheadingbreak{\dobreak \secheadingskip {-1000}} +\def\secheading#1#2#3{\sectionheading{sec}{#2.#3}{#1}} +\def\plainsecheading#1{\sectionheading{sec}{}{#1}} -\newskip \subsecheadingskip \subsecheadingskip = 17pt plus 8pt minus 4pt +% Subsection titles. +\newskip \subsecheadingskip \def\subsecheadingbreak{\dobreak \subsecheadingskip {-500}} +\def\subsecheading#1#2#3#4{\sectionheading{subsec}{#2.#3.#4}{#1}} +\def\plainsubsecheading#1{\sectionheading{subsec}{}{#1}} -\newskip \secheadingskip \secheadingskip = 21pt plus 8pt minus 4pt -\def\secheadingbreak{\dobreak \secheadingskip {-1000}} +% Subsubsection titles. +\let\subsubsecheadingskip = \subsecheadingskip +\let\subsubsecheadingbreak = \subsecheadingbreak +\def\subsubsecheading#1#2#3#4#5{\sectionheading{subsubsec}{#2.#3.#4.#5}{#1}} +\def\plainsubsubsecheading#1{\sectionheading{subsubsec}{}{#1}} -% @paragraphindent is defined for the Info formatting commands only. -\let\paragraphindent=\comment -% Section fonts are the base font at magstep2, which produces -% a size a bit more than 14 points in the default situation. - -\def\secheading #1#2#3{\secheadingi {#2.#3\enspace #1}} -\def\plainsecheading #1{\secheadingi {#1}} -\def\secheadingi #1{{\advance \secheadingskip by \parskip % -\secheadingbreak}% -{\secfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% -\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } - - -% Subsection fonts are the base font at magstep1, -% which produces a size of 12 points. - -\def\subsecheading #1#2#3#4{\subsecheadingi {#2.#3.#4\enspace #1}} -\def\subsecheadingi #1{{\advance \subsecheadingskip by \parskip % -\subsecheadingbreak}% -{\subsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% -\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000 } - -\def\subsubsecfonts{\subsecfonts} % Maybe this should change: - % Perhaps make sssec fonts scaled - % magstep half -\def\subsubsecheading #1#2#3#4#5{\subsubsecheadingi {#2.#3.#4.#5\enspace #1}} -\def\subsubsecheadingi #1{{\advance \subsecheadingskip by \parskip % -\subsecheadingbreak}% -{\subsubsecfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% -\ifdim \parskip<10pt \kern 10pt\kern -\parskip\fi \penalty 10000} +% 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{% + {% + \expandafter\advance\csname #1headingskip\endcsname by \parskip + \csname #1headingbreak\endcsname + }% + {% + % Switch to the right set of fonts. + \csname #1fonts\endcsname \rm + % + % Only insert the separating space if we have a section number. + \def\secnum{#2}% + \setbox0 = \hbox{#2\ifx\secnum\empty\else\enspace\fi}% + % + \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright + \hangindent = \wd0 % zero if no section number + \unhbox0 #3}% + }% + \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak +} \message{toc printing,} - % Finish up the main text and prepare to read what we've written % to \contentsfile. \newskip\contentsrightmargin \contentsrightmargin=1in \def\startcontents#1{% - \pagealignmacro + % If @setchapternewpage on, and @headings double, the contents should + % start on an odd page, unlike chapters. Thus, we maintain + % \contentsalignmacro in parallel with \pagealignmacro. + % From: Torbjorn Granlund <tege@matematik.su.se> + \contentsalignmacro \immediate\closeout \contentsfile \ifnum \pageno>0 - \pageno = -1 % Request roman numbered pages. + \pageno = -1 % Request roman numbered pages. \fi % Don't need to put `Contents' or `Short Contents' in the headline. % It is abundantly clear what they are. \unnumbchapmacro{#1}\def\thischapter{}% - \begingroup % Set up to handle contents files properly. + \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 \raggedbottom % Worry more about breakpoints than the bottom. @@ -2941,6 +3207,7 @@ July\or August\or September\or October\or November\or December\fi \secfonts \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl \rm + \hyphenpenalty = 10000 \advance\baselineskip by 1pt % Open it up a little. \def\secentry ##1##2##3##4{} \def\unnumbsecentry ##1##2{} @@ -2984,7 +3251,7 @@ July\or August\or September\or October\or November\or December\fi % This space should be plenty, since a single number is .5em, and the % widest letter (M) is 1em, at least in the Computer Modern fonts. % (This space doesn't include the extra space that gets added after - % the label; that gets put in in \shortchapentry above.) + % the label; that gets put in by \shortchapentry above.) \advance\dimen0 by 1.1em \hbox to \dimen0{#1\hfil}% } @@ -3005,22 +3272,21 @@ July\or August\or September\or October\or November\or December\fi \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} \def\unnumbsubsubsecentry#1#2{\dosubsubsecentry{#1}{#2}} - % This parameter controls the indentation of the various levels. \newdimen\tocindent \tocindent = 3pc % Now for the actual typesetting. In all these, #1 is the text and #2 is the % page number. % -% If the toc has to be broken over pages, we would want to be at chapters +% If the toc has to be broken over pages, we want it to be at chapters % if at all possible; hence the \penalty. \def\dochapentry#1#2{% - \penalty-300 \vskip\baselineskip + \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip \begingroup \chapentryfonts \tocentry{#1}{\dopageno{#2}}% \endgroup - \nobreak\vskip .25\baselineskip + \nobreak\vskip .25\baselineskip plus.1\baselineskip } \def\dosecentry#1#2{\begingroup @@ -3045,7 +3311,7 @@ July\or August\or September\or October\or November\or December\fi % % \turnoffactive is for the sake of @" used for umlauts. \def\tocentry#1#2{\begingroup - \hyphenpenalty = 10000 + \vskip 0pt plus1pt % allow a little stretch for the sake of nice page breaks \entry{\turnoffactive #1}{\turnoffactive #2}% \endgroup} @@ -3070,8 +3336,6 @@ July\or August\or September\or October\or November\or December\fi \newbox\pushcharbox \newbox\bullbox \newbox\equivbox \newbox\errorbox -\let\ptexequiv = \equiv - %{\tentt %\global\setbox\dblarrowbox = \hbox to 1em{\hfil$\Rightarrow$\hfil} %\global\setbox\longdblarrowbox = \hbox to 1em{\hfil$\mapsto$\hfil} @@ -3082,12 +3346,11 @@ July\or August\or September\or October\or November\or December\fi % depth .1ex\hfil} %} +% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. \def\point{$\star$} - \def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} \def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} \def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} - \def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} % Adapted from the TeXbook's \boxit. @@ -3119,7 +3382,7 @@ July\or August\or September\or October\or November\or December\fi \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie \catcode `\%=14 -\catcode 43=12 +\catcode 43=12 % plus \catcode`\"=12 \catcode`\==12 \catcode`\|=12 @@ -3127,16 +3390,18 @@ July\or August\or September\or October\or November\or December\fi \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 \let\l=\ptexl -\let\L=\ptexL +\let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext % \let\Etex=\endgroup} @@ -3195,50 +3460,50 @@ July\or August\or September\or October\or November\or December\fi \def\cbl{{\circle\char'012\hskip -6pt}} \def\cbr{{\hskip 6pt\circle\char'011}} \def\carttop{\hbox to \cartouter{\hskip\lskip - \ctl\leaders\hrule height\circthick\hfil\ctr - \hskip\rskip}} + \ctl\leaders\hrule height\circthick\hfil\ctr + \hskip\rskip}} \def\cartbot{\hbox to \cartouter{\hskip\lskip - \cbl\leaders\hrule height\circthick\hfil\cbr - \hskip\rskip}} + \cbl\leaders\hrule height\circthick\hfil\cbr + \hskip\rskip}} % \newskip\lskip\newskip\rskip \long\def\cartouche{% \begingroup - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt %we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18pt % allow for 3pt kerns on either -% side, and for 6pt waste from -% each corner char - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing=\comment - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \hsize=\cartinner - \kern3pt - \begingroup - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip + \lskip=\leftskip \rskip=\rightskip + \leftskip=0pt\rightskip=0pt %we want these *outside*. + \cartinner=\hsize \advance\cartinner by-\lskip + \advance\cartinner by-\rskip + \cartouter=\hsize + \advance\cartouter by 18pt % allow for 3pt kerns on either +% side, and for 6pt waste from +% each corner char + \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip + % Flag to tell @lisp, etc., not to narrow margin. + \let\nonarrowing=\comment + \vbox\bgroup + \baselineskip=0pt\parskip=0pt\lineskip=0pt + \carttop + \hbox\bgroup + \hskip\lskip + \vrule\kern3pt + \vbox\bgroup + \hsize=\cartinner + \kern3pt + \begingroup + \baselineskip=\normbskip + \lineskip=\normlskip + \parskip=\normpskip + \vskip -\parskip \def\Ecartouche{% - \endgroup - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup + \endgroup + \kern3pt + \egroup + \kern3pt\vrule + \hskip\rskip + \egroup + \cartbot + \egroup \endgroup }} @@ -3301,8 +3566,7 @@ July\or August\or September\or October\or November\or December\fi \let\Esmalllisp = \nonfillfinish \let\Esmallexample = \nonfillfinish % - % Smaller interline space and fonts for small examples. - \setleading{10pt}% + % Smaller fonts for small examples. \indexfonts \tt \rawbackslash % make \ output the \ character from the current font (tt) \gobble @@ -3542,17 +3806,16 @@ July\or August\or September\or October\or November\or December\fi } % Fine, but then we have to eventually remove the \empty *and* the -% braces (if any). That's what this does, putting the result in \tptemp. +% braces (if any). That's what this does. % -\def\removeemptybraces\empty#1\relax{\def\tptemp{#1}}% +\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{% - \removeemptybraces#2\relax - #1{\tptemp}{#3}% + #1{\removeemptybraces#2\relax}{#3}% }% \def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % @@ -3786,19 +4049,21 @@ July\or August\or September\or October\or November\or December\fi \def\deftypevar{\defvarparsebody\Edeftypevar\deftypevarx\deftypevarheader} -% #1 is the data type. #2 is the name. +% #1 is the data type. #2 is the name, perhaps followed by text that +% is actually part of the data type, which should not be put into the index. \def\deftypevarheader #1#2{% -\doind {vr}{\code{#2}}% Make entry in variables index +\dovarind#2 \relax% Make entry in variables index \begingroup\defname {\defheaderxcond#1\relax$$$#2}{Variable}% \interlinepenalty=10000 \endgraf\penalty 10000\vskip -\parskip\penalty 10000 \endgroup} +\def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} % @deftypevr {Global Flag} int enable \def\deftypevr{\defvrparsebody\Edeftypevr\deftypevrx\deftypevrheader} -\def\deftypevrheader #1#2#3{\doind {vr}{\code{#3}}% +\def\deftypevrheader #1#2#3{\dovarind#3 \relax% \begingroup\defname {\defheaderxcond#2\relax$$$#3}{#1} \interlinepenalty=10000 \endgraf\penalty 10000\vskip -\parskip\penalty 10000 @@ -3830,6 +4095,7 @@ July\or August\or September\or October\or November\or December\fi \def\deftpx #1 {\errmessage{@deftpx in invalid context}} + \message{cross reference,} % Define cross-reference macros \newwrite \auxfile @@ -3837,6 +4103,11 @@ July\or August\or September\or October\or November\or December\fi \newif\ifhavexrefs % True if xref values are known. \newif\ifwarnedxrefs % True if we warned once that they aren't known. +% @inforef is simple. +\def\inforef #1{\inforefzzz #1,,,,**} +\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, + node \samp{\ignorespaces#1{}}} + % \setref{foo} defines a cross-reference point named foo. \def\setref#1{% @@ -3915,7 +4186,7 @@ July\or August\or September\or October\or November\or December\fi % Use \turnoffactive so that punctuation chars such as underscore % work in node names. -\def\dosetq #1#2{{\let\folio=0 \turnoffactive \auxhat% +\def\dosetq #1#2{{\let\folio=0 \turnoffactive \edef\next{\write\auxfile{\internalsetq {#1}{#2}}}% \next}} @@ -3984,84 +4255,101 @@ July\or August\or September\or October\or November\or December\fi #2% Output the suffix in any case. } -% Read the last existing aux file, if any. No error if none exists. - % 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#2{{% + \catcode`\'=\other + \expandafter\gdef\csname X#1\endcsname{#2}% +}} -\def\readauxfile{% -\begingroup -\catcode `\^^@=\other -\catcode `\=\other -\catcode `\=\other -\catcode `\^^C=\other -\catcode `\^^D=\other -\catcode `\^^E=\other -\catcode `\^^F=\other -\catcode `\^^G=\other -\catcode `\^^H=\other -\catcode `\ =\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 -\catcode 26=\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 -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode `\$=\other -\catcode `\#=\other -\catcode `\&=\other -% `\+ does not work, so use 43. -\catcode 43=\other -% Make the characters 128-255 be printing characters -{% - \count 1=128 - \def\loop{% - \catcode\count 1=\other - \advance\count 1 by 1 - \ifnum \count 1<256 \loop \fi +% Read the last existing aux file, if any. No error if none exists. +\def\readauxfile{\begingroup + \catcode`\^^@=\other + \catcode`\=\other + \catcode`\=\other + \catcode`\^^C=\other + \catcode`\^^D=\other + \catcode`\^^E=\other + \catcode`\^^F=\other + \catcode`\^^G=\other + \catcode`\^^H=\other + \catcode`\ =\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`\^^[=\other + \catcode`\^^\=\other + \catcode`\^^]=\other + \catcode`\^^^=\other + \catcode`\^^_=\other + \catcode`\@=\other + \catcode`\^=\other + % It was suggested to define this as 7, which would allow ^^e4 etc. + % in xref tags, i.e., node names. But since ^^e4 notation isn't + % supported in the main text, it doesn't seem desirable. Furthermore, + % that is not enough: for node names that actually contain a ^ + % character, we would end up writing a line like this: 'xrdef {'hat + % 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 + \catcode`\"=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\$=\other + \catcode`\#=\other + \catcode`\&=\other + % `\+ does not work, so use 43. + \catcode43=\other + % Make the characters 128-255 be printing characters + {% + \count 1=128 + \def\loop{% + \catcode\count 1=\other + \advance\count 1 by 1 + \ifnum \count 1<256 \loop \fi + }% }% -}% -% the aux file uses ' as the escape. -% Turn off \ as an escape so we do not lose on -% entries which were dumped with control sequences in their names. -% For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ -% Reference to such entries still does not work the way one would wish, -% but at least they do not bomb out when the aux file is read in. -\catcode `\{=1 \catcode `\}=2 -\catcode `\%=\other -\catcode `\'=0 -\catcode`\^=7 % to make ^^e4 etc usable in xref tags -\catcode `\\=\other -\openin 1 \jobname.aux -\ifeof 1 \else \closein 1 \input \jobname.aux \global\havexrefstrue -\global\warnedobstrue -\fi -% Open the new aux file. Tex will close it automatically at exit. -\openout \auxfile=\jobname.aux + % The aux file uses ' as the escape (for now). + % Turn off \ as an escape so we do not lose on + % entries which were dumped with control sequences in their names. + % For example, 'xrdef {$\leq $-fun}{page ...} made by @defun ^^ + % Reference to such entries still does not work the way one would wish, + % but at least they do not bomb out when the aux file is read in. + \catcode`\{=1 + \catcode`\}=2 + \catcode`\%=\other + \catcode`\'=0 + \catcode`\\=\other + % + \openin 1 \jobname.aux + \ifeof 1 \else + \closein 1 + \input \jobname.aux + \global\havexrefstrue + \global\warnedobstrue + \fi + % Open the new aux file. TeX will close it automatically at exit. + \openout\auxfile=\jobname.aux \endgroup} @@ -4072,7 +4360,8 @@ July\or August\or September\or October\or November\or December\fi % The trailing space in the following definition for supereject is % vital for proper filling; pages come out unaligned when you do a % pagealignmacro call if that space before the closing brace is -% removed. +% removed. (Generally, numeric constants should always be followed by a +% space to prevent strange expansion errors.) \def\supereject{\par\penalty -20000\footnoteno =0 } % @footnotestyle is meaningful for info output only.. @@ -4100,8 +4389,12 @@ July\or August\or September\or October\or November\or December\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. % -\long\gdef\footnotezzz#1{\insert\footins{% +\long\gdef\footnotezzz{\insert\footins\bgroup % We want to typeset this text as a normal paragraph, even if the % footnote reference occurs in (for example) a display environment. % So reset some parameters. @@ -4123,8 +4416,13 @@ July\or August\or September\or October\or November\or December\fi % expands into a box, it must come within the paragraph, lest it % provide a place where TeX can split the footnote. \footstrut - #1\strut}% + \futurelet\next\fo@t } +\def\fo@t{\ifcat\bgroup\noexpand\next \let\next\f@@t + \else\let\next\f@t\fi \next} +\def\f@@t{\bgroup\aftergroup\@foot\let\next} +\def\f@t#1{#1\@foot} +\def\@foot{\strut\egroup} }%end \catcode `\@=11 @@ -4197,13 +4495,18 @@ July\or August\or September\or October\or November\or December\fi % Set some numeric style parameters, for 8.5 x 11 format. -%\hsize = 6.5in +\hsize = 6in +\hoffset = .25in \newdimen\defaultparindent \defaultparindent = 15pt \parindent = \defaultparindent -\parskip 18pt plus 1pt -\setleading{15pt} +\parskip 3pt plus 2pt minus 1pt +\setleading{13.2pt} \advance\topskip by 1.2cm +\chapheadingskip = 15pt plus 4pt minus 2pt +\secheadingskip = 12pt plus 3pt minus 2pt +\subsecheadingskip = 9pt plus 2pt minus 2pt + % Prevent underfull vbox error messages. \vbadness=10000 @@ -4226,30 +4529,28 @@ July\or August\or September\or October\or November\or December\fi % Use @smallbook to reset parameters for 7x9.5 format (or else 7x9.25) \def\smallbook{ - -% These values for secheadingskip and subsecheadingskip are -% experiments. RJC 7 Aug 1992 -\global\secheadingskip = 17pt plus 6pt minus 3pt -\global\subsecheadingskip = 14pt plus 6pt minus 3pt - -\global\lispnarrowing = 0.3in -\setleading{12pt} -\advance\topskip by -1cm -\global\parskip 3pt plus 1pt -\global\hsize = 5in -\global\vsize=7.5in -\global\tolerance=700 -\global\hfuzz=1pt -\global\contentsrightmargin=0pt -\global\deftypemargin=0pt -\global\defbodyindent=.5cm - -\global\pagewidth=\hsize -\global\pageheight=\vsize - -\global\let\smalllisp=\smalllispx -\global\let\smallexample=\smalllispx -\global\def\Esmallexample{\Esmalllisp} + \global\chapheadingskip = 15pt plus 4pt minus 2pt + \global\secheadingskip = 12pt plus 3pt minus 2pt + \global\subsecheadingskip = 9pt plus 2pt minus 2pt + % + \global\lispnarrowing = 0.3in + \setleading{12pt} + \advance\topskip by -1cm + \global\parskip 2pt plus 1pt + \global\hsize = 5in + \global\vsize=7.5in + \global\tolerance=700 + \global\hfuzz=1pt + \global\contentsrightmargin=0pt + \global\deftypemargin=0pt + \global\defbodyindent=.5cm + % + \global\pagewidth=\hsize + \global\pageheight=\vsize + % + \global\let\smalllisp=\smalllispx + \global\let\smallexample=\smalllispx + \global\def\Esmallexample{\Esmalllisp} } % Use @afourpaper to print on European A4 paper. @@ -4272,12 +4573,19 @@ July\or August\or September\or October\or November\or December\fi \global\pageheight=\vsize } +\bindingoffset=0pt +\normaloffset=\hoffset +\pagewidth=\hsize +\pageheight=\vsize + % Allow control of the text dimensions. Parameters in order: textheight; -% textwidth; \voffset; \hoffset (!); binding offset. All require a dimension; +% textwidth; voffset; hoffset; binding offset; topskip. +% All require a dimension; % header is additional; added length extends the bottom of the page. -\def\changepagesizes#1#2#3#4#5{ +\def\changepagesizes#1#2#3#4#5#6{ \global\vsize= #1 + \global\topskip= #6 \advance\vsize by \topskip \global\voffset= #3 \global\hsize= #2 @@ -4290,13 +4598,20 @@ July\or August\or September\or October\or November\or December\fi \global\normaloffset= #4 \global\bindingoffset= #5} -% This layout is compatible with Latex on A4 paper. - -\def\afourlatex{\changepagesizes{22cm}{15cm}{7mm}{4.6mm}{5mm}} +% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin +% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +\def\afourlatex + {\global\tolerance=700 + \global\hfuzz=1pt + \setleading{12pt} + \global\parskip 15pt plus 1pt + \advance\baselineskip by 1.6pt + \changepagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm} + } % Use @afourwide to print on European A4 paper in wide format. \def\afourwide{\afourpaper -\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}} +\changepagesizes{9.5in}{6.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}} % Define macros to output various characters with catcode for normal text. \catcode`\"=\other @@ -4339,7 +4654,6 @@ July\or August\or September\or October\or November\or December\fi \def~{{\tt \char '176}} \chardef\hat=`\^ \catcode`\^=\active -\def\auxhat{\def^{'hat}} \def^{{\tt \hat}} \catcode`\_=\active |