diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 87 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/Makefile.in | 268 | ||||
| -rw-r--r-- | doc/ad.block | 6 | ||||
| -rw-r--r-- | doc/awkcard.in | 154 | ||||
| -rw-r--r-- | doc/gawk.1 | 49 | ||||
| -rw-r--r-- | doc/gawk.info | 1722 | ||||
| -rw-r--r-- | doc/gawk.texi | 1087 | ||||
| -rw-r--r-- | doc/gawkinet.info | 375 | ||||
| -rw-r--r-- | doc/gawkinet.texi | 302 | ||||
| -rw-r--r-- | doc/pgawk.1 | 1 | ||||
| -rw-r--r-- | doc/texinfo.tex | 2230 |
12 files changed, 3884 insertions, 2399 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 6223634f..ef9a8860 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,90 @@ +Wed Mar 19 14:10:31 2003 Arnold D. Robbins <arnold@skeeve.com> + + This time for sure. + -- Bullwinkle + + * Release 3.1.2: Release tar file made. + +Tue Mar 11 11:22:36 2003 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (man_MANS): Add pgawk.1. + * pgawk.1: New file, does `.so gawk.1' so that `man pgawk' will work. + Thanks to Nelson Beebe for pointing the need for this. + +Sun Feb 9 09:45:06 2003 Arnold D. Robbins <arnold@skeeve.com> + + * gawk.texi, gawkinet.texi: Per Karl Berry, change dircategory + to follow current standards. In gawkinet.texi, remove + bracketing ifinfo. + +Thu Feb 6 12:06:22 2003 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Updated to version 2003-02-03.16 from Texinfo 4.5. + +Tue Feb 4 15:21:46 2003 Arnold D. Robbins <arnold@skeeve.com> + + * awkcard.in: Redid the page-breaking. + +Tue Feb 4 14:28:06 2003 Arnold D. Robbins <arnold@skeeve.com> + + All relevant files: Copyright year updated to 2003. + +Sun Jan 26 11:13:01 2003 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Updated to version 2003-01-24.17 from prep. + * gawk.texi: Documented asorti(), new elements in match() 3rd arg, + misc cleanups. Updated to FDL 1.2. + * awkcard.in, gawk.1: Ditto for asorti(), match(). + * gawkinet.texi: Updated to FDL 1.2. + +Thu Jan 16 18:34:54 2003 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Updated to version 2003-01-12.11 from prep. + +Sun Nov 24 17:55:23 2002 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Updated to version 2002-11-05.11 from Texinfo 4.3. + +Sun Nov 17 21:34:35 2002 Arnold D. Robbins <arnold@skeeve.com> + + * texinfo.tex: Updated to version 2002-10-13.14 from automake 1.7.1. + +Fri Nov 1 11:25:00 2002 Arnold D. Robbins <arnold@skeeve.com> + + From Kaveh Ghazi: + + * gawk.texi (grcat.c): Include stdlib.h. + (main): Fix format specifier warnings. + * gawk.texi (pwcat.c): Include config.h/stdlib.h. + (main): Fix format specifier warnings. + +Tue Jun 11 23:08:04 2002 Arnold D. Robbins <arnold@skeeve.com> + + * gawk.texi: Fix grcat code ifdef for HAVE_GETGRENT. + +2002-05-09 Paul Eggert <eggert@twinsun.com> + + [ ADR: Some minor post-patch editing was required. ] + + * gawk.texi (igawk): Do not put temporary files in /tmp, as that + has some security problems. This fixes a problem originally + reported by Jarno Huuskonen via solar@openwall.com. + + Fix the following problems with igawk while we're at it. + + * Report missing operands of options; this fixes e.g. an + infinite loop with "igawk -W". + + * Check for --source and -Wsource only, not -.source (which matches + errors). Similarly for other multichar options. + + * Do not use 'echo', as that mishandles backslashes. + +Mon May 13 01:25:40 2002 Arnold D. Robbins <arnold@skeeve.com> + + * gawkinet.texi: Change `ifinfo' to `ifnottex' around + the Top node. Thanks to Eli Zaretskii. + Wed May 1 16:41:32 2002 Arnold D. Robbins <arnold@skeeve.com> * Release 3.1.1: Release tar file made. diff --git a/doc/Makefile.am b/doc/Makefile.am index 93092a15..c1665e6b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,7 +25,7 @@ info_TEXINFOS = gawk.texi gawkinet.texi -man_MANS = gawk.1 igawk.1 +man_MANS = gawk.1 igawk.1 pgawk.1 EXTRA_DIST = ChangeLog README.card ad.block setter.outline \ awkcard.in awkforai.txt texinfo.tex cardfonts \ diff --git a/doc/Makefile.in b/doc/Makefile.in index 8c38c91c..91b1a887 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,6 +1,7 @@ -# Makefile.in generated automatically by automake 1.5 from Makefile.am. +# Makefile.in generated by automake 1.7.3 from Makefile.am. +# @configure_input@ -# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 +# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 # Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -36,96 +37,138 @@ # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA # -SHELL = @SHELL@ - srcdir = @srcdir@ top_srcdir = @top_srcdir@ VPATH = @srcdir@ -prefix = @prefix@ -exec_prefix = @exec_prefix@ - -bindir = @bindir@ -sbindir = @sbindir@ -libexecdir = @libexecdir@ -datadir = @datadir@ -sysconfdir = @sysconfdir@ -sharedstatedir = @sharedstatedir@ -localstatedir = @localstatedir@ -libdir = @libdir@ -infodir = @infodir@ -mandir = @mandir@ -includedir = @includedir@ -oldincludedir = /usr/include pkgdatadir = $(datadir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ top_builddir = .. -ACLOCAL = @ACLOCAL@ -AUTOCONF = @AUTOCONF@ -AUTOMAKE = @AUTOMAKE@ -AUTOHEADER = @AUTOHEADER@ - +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd INSTALL = @INSTALL@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c INSTALL_HEADER = $(INSTALL_DATA) -transform = @program_transform_name@ +transform = $(program_transform_name) NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = : NORMAL_UNINSTALL = : PRE_UNINSTALL = : POST_UNINSTALL = : -host_alias = @host_alias@ host_triplet = @host@ +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +AMDEP_FALSE = @AMDEP_FALSE@ +AMDEP_TRUE = @AMDEP_TRUE@ AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ AWK = @AWK@ BUILD_INCLUDED_LIBINTL = @BUILD_INCLUDED_LIBINTL@ CATOBJEXT = @CATOBJEXT@ CC = @CC@ +CCDEPMODE = @CCDEPMODE@ CFLAGS = @CFLAGS@ CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ DATADIRNAME = @DATADIRNAME@ +DEFS = @DEFS@ DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ EXEEXT = @EXEEXT@ GENCAT = @GENCAT@ GLIBC21 = @GLIBC21@ GMSGFMT = @GMSGFMT@ -HAVE_LIB = @HAVE_LIB@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ INSTOBJEXT = @INSTOBJEXT@ INTLBISON = @INTLBISON@ INTLLIBS = @INTLLIBS@ INTLOBJS = @INTLOBJS@ INTL_LIBTOOL_SUFFIX_PREFIX = @INTL_LIBTOOL_SUFFIX_PREFIX@ -LIB = @LIB@ +LDFLAGS = @LDFLAGS@ LIBICONV = @LIBICONV@ LIBINTL = @LIBINTL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ LN_S = @LN_S@ -LTLIB = @LTLIB@ LTLIBICONV = @LTLIBICONV@ LTLIBINTL = @LTLIBINTL@ +LTLIBOBJS = @LTLIBOBJS@ + +MAKEINFO = @MAKEINFO@ --no-split MKINSTALLDIRS = @MKINSTALLDIRS@ +MSGFMT = @MSGFMT@ +MSGMERGE = @MSGMERGE@ OBJEXT = @OBJEXT@ PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ RANLIB = @RANLIB@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ +STRIP = @STRIP@ U = @U@ USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@ USE_NLS = @USE_NLS@ VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ YACC = @YACC@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_RANLIB = @ac_ct_RANLIB@ +ac_ct_STRIP = @ac_ct_STRIP@ +am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ +am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ am__include = @am__include@ +am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +datadir = @datadir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +includedir = @includedir@ +infodir = @infodir@ install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +oldincludedir = @oldincludedir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ info_TEXINFOS = gawk.texi gawkinet.texi -man_MANS = gawk.1 igawk.1 +man_MANS = gawk.1 igawk.1 pgawk.1 EXTRA_DIST = ChangeLog README.card ad.block setter.outline \ awkcard.in awkforai.txt texinfo.tex cardfonts \ @@ -134,8 +177,6 @@ EXTRA_DIST = ChangeLog README.card ad.block setter.outline \ statist.jpg statist.eps -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/" @@ -152,8 +193,11 @@ mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/config.h CONFIG_CLEAN_FILES = DIST_SOURCES = +am__TEXINFO_TEX_DIR = $(srcdir) INFO_DEPS = gawk.info gawkinet.info DVIS = gawk.dvi gawkinet.dvi +PDFS = gawk.pdf gawkinet.pdf +PSS = gawk.ps gawkinet.ps TEXINFOS = gawk.texi gawkinet.texi NROFF = nroff @@ -162,85 +206,87 @@ DIST_COMMON = ChangeLog Makefile.am Makefile.in texinfo.tex all: all-am .SUFFIXES: -.SUFFIXES: .dvi .info .ps .texi +.SUFFIXES: .dvi .info .pdf .ps .texi $(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) cd $(top_srcdir) && \ $(AUTOMAKE) --gnu doc/Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status - cd $(top_builddir) && \ - CONFIG_HEADERS= CONFIG_LINKS= \ - CONFIG_FILES=$(subdir)/$@ $(SHELL) ./config.status - -gawk.info: gawk.texi -gawk.dvi: gawk.texi - -gawkinet.info: gawkinet.texi -gawkinet.dvi: gawkinet.texi + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe) .texi.info: - @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] - cd $(srcdir) \ - && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \ - `echo $< | sed 's,.*/,,'` + @rm -f $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9] + $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ `test -f '$<' || echo '$(srcdir)/'`$< .texi.dvi: - TEXINPUTS=$(srcdir):$$TEXINPUTS \ + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) $< + $(TEXI2DVI) `test -f '$<' || echo '$(srcdir)/'`$< -.texi: - @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] - cd $(srcdir) \ - && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \ - `echo $< | sed 's,.*/,,'` +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) `test -f '$<' || echo '$(srcdir)/'`$< +gawk.info: gawk.texi +gawk.dvi: gawk.texi +gawk.pdf: gawk.texi +gawkinet.info: gawkinet.texi +gawkinet.dvi: gawkinet.texi +gawkinet.pdf: gawkinet.texi TEXI2DVI = texi2dvi + +TEXI2PDF = $(TEXI2DVI) --pdf --batch DVIPS = dvips .dvi.ps: - $(DVIPS) $< -o $@ + $(DVIPS) -o $@ $< uninstall-info-am: $(PRE_UNINSTALL) @if (install-info --version && \ - install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \ + install-info --version | grep -i -v debian) >/dev/null 2>&1; then \ list='$(INFO_DEPS)'; \ for file in $$list; do \ - echo " install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file"; \ - install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file; \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$relfile"; \ + install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$relfile; \ done; \ else :; fi @$(NORMAL_UNINSTALL) @list='$(INFO_DEPS)'; \ for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ (if cd $(DESTDIR)$(infodir); then \ - echo " rm -f $$file $$file-[0-9] $$file-[0-9][0-9])"; \ - rm -f $$file $$file-[0-9] $$file-[0-9][0-9]; \ + echo " rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9])"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ else :; fi); \ done dist-info: $(INFO_DEPS) list='$(INFO_DEPS)'; \ for base in $$list; do \ - d=$(srcdir); \ - for file in `CDPATH=: && cd $$d && eval echo $$base*`; do \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + for file in $$d/$$base*; do \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f $(distdir)/$$relfile || \ + cp -p $$file $(distdir)/$$relfile; \ done; \ done mostlyclean-aminfo: - -rm -f gawk.aux gawk.cp gawk.cps gawk.dvi gawk.fn gawk.ky gawk.log gawk.pg \ - gawk.ps gawk.toc gawk.tp gawk.vr gawkinet.aux gawkinet.cp \ - gawkinet.cps gawkinet.dvi gawkinet.fn gawkinet.ky \ - gawkinet.log gawkinet.pg gawkinet.ps gawkinet.toc gawkinet.tp \ - gawkinet.vr + -rm -f gawk.aux gawk.cp gawk.cps gawk.fn gawk.ky gawk.kys gawk.log gawk.pg \ + gawk.pgs gawk.tmp gawk.toc gawk.tp gawk.tps gawk.vr gawk.dvi \ + gawk.pdf gawk.ps gawkinet.aux gawkinet.cp gawkinet.cps \ + gawkinet.fn gawkinet.ky gawkinet.kys gawkinet.log gawkinet.pg \ + gawkinet.pgs gawkinet.tmp gawkinet.toc gawkinet.tp \ + gawkinet.tps gawkinet.vr gawkinet.dvi gawkinet.pdf \ + gawkinet.ps maintainer-clean-aminfo: - cd $(srcdir) && \ - for i in $(INFO_DEPS); do \ - rm -f $$i; \ - if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ - rm -f $$i-[0-9]*; \ - fi; \ + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ done man1dir = $(mandir)/man1 @@ -258,6 +304,10 @@ install-man1: $(man1_MANS) $(man_MANS) if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ else file=$$i; fi; \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ inst=`echo $$inst | sed -e 's/^.*\///'`; \ inst=`echo $$inst | sed '$(transform)'`.$$ext; \ @@ -275,6 +325,10 @@ uninstall-man1: done; \ for i in $$list; do \ ext=`echo $$i | sed -e 's/^.*\\.//'`; \ + case "$$ext" in \ + 1*) ;; \ + *) ext='1' ;; \ + esac; \ inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ inst=`echo $$inst | sed -e 's/^.*\///'`; \ inst=`echo $$inst | sed '$(transform)'`.$$ext; \ @@ -284,6 +338,8 @@ uninstall-man1: tags: TAGS TAGS: +ctags: CTAGS +CTAGS: DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) @@ -291,15 +347,26 @@ top_distdir = .. distdir = $(top_distdir)/$(PACKAGE)-$(VERSION) distdir: $(DISTFILES) - @for file in $(DISTFILES); do \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \ + list='$(DISTFILES)'; for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + $(top_srcdir)/*) file=`echo "$$file" | sed "s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \ + esac; \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \ if test "$$dir" != "$$file" && test "$$dir" != "."; then \ - $(mkinstalldirs) "$(distdir)/$$dir"; \ + dir="/$$dir"; \ + $(mkinstalldirs) "$(distdir)$$dir"; \ + else \ + dir=''; \ fi; \ if test -d $$d/$$file; then \ - cp -pR $$d/$$file $(distdir) \ - || exit 1; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ else \ test -f $(distdir)/$$file \ || cp -p $$d/$$file $(distdir)/$$file \ @@ -307,7 +374,7 @@ distdir: $(DISTFILES) fi; \ done $(MAKE) $(AM_MAKEFLAGS) \ - top_distdir="${top_distdir}" distdir="$(distdir)" \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ dist-info check-am: all-am check: check-am @@ -327,6 +394,7 @@ install-am: all-am installcheck: installcheck-am install-strip: $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + INSTALL_STRIP_FLAG=-s \ `test -z '$(STRIP)' || \ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install mostlyclean-generic: @@ -334,7 +402,7 @@ mostlyclean-generic: clean-generic: distclean-generic: - -rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]* + -rm -f Makefile $(CONFIG_CLEAN_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @@ -366,21 +434,25 @@ install-info-am: $(INFO_DEPS) $(mkinstalldirs) $(DESTDIR)$(infodir) @list='$(INFO_DEPS)'; \ for file in $$list; do \ - d=$(srcdir); \ - for ifile in `CDPATH=: && cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ - if test -f $$d/$$ifile; then \ - echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \ - $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile"; \ + $(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile; \ else : ; fi; \ done; \ done @$(POST_INSTALL) @if (install-info --version && \ - install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \ + install-info --version | grep -i -v debian) >/dev/null 2>&1; then \ list='$(INFO_DEPS)'; \ for file in $$list; do \ - echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ - install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$relfile";\ + install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$relfile || :;\ done; \ else : ; fi install-man: install-man1 @@ -396,6 +468,14 @@ mostlyclean: mostlyclean-am mostlyclean-am: mostlyclean-aminfo mostlyclean-generic +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + uninstall-am: uninstall-info-am uninstall-man uninstall-man: uninstall-man1 @@ -407,8 +487,8 @@ uninstall-man: uninstall-man1 install-man1 install-strip installcheck installcheck-am \ installdirs maintainer-clean maintainer-clean-aminfo \ maintainer-clean-generic mostlyclean mostlyclean-aminfo \ - mostlyclean-generic uninstall uninstall-am uninstall-info-am \ - uninstall-man uninstall-man1 + mostlyclean-generic pdf pdf-am ps ps-am uninstall uninstall-am \ + uninstall-info-am uninstall-man uninstall-man1 # Uncomment the following definition of AWKCARD if your troff can produce diff --git a/doc/ad.block b/doc/ad.block index ee99a5a9..f50062e5 100644 --- a/doc/ad.block +++ b/doc/ad.block @@ -1,7 +1,7 @@ .\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" This file is the Ad block (included in cover) .\" -.\" Copyright (C) 1996, 1998, 2000, 2001 Free Software Foundation, Inc. +.\" Copyright (C) 1996, 1998, 2000, 2001, 2003 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of .\" this reference card provided the copyright notice and this permission @@ -40,8 +40,8 @@ URL: http://www.gnu.org .ce 5 .ft HB \*(CGSource Distributions on CD-ROM -Deluxe Distributions -Emacs, Gawk, Make and GDB Manuals +.\" Deluxe Distributions +Emacs, Make and GDB Manuals Emacs and GDB References\*(CX .EB "\f(HBOTHER FSF PRODUCTS:\*(FR" .ps diff --git a/doc/awkcard.in b/doc/awkcard.in index be6a7caa..9694cc55 100644 --- a/doc/awkcard.in +++ b/doc/awkcard.in @@ -1,6 +1,6 @@ .\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org .\" -.\" Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +.\" Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. .\" .\" Permission is granted to make and distribute verbatim copies of .\" this reference card provided the copyright notice and this permission @@ -24,6 +24,7 @@ .\" Strings to save typing .ds AK \*(FCawk\*(FR .ds GK \*(FCgawk\*(FR +.ds PK \*(FCpgawk\*(FR .ds NK Bell Labs \*(FCawk\*(FR .ds MK \*(FCmawk\*(FR .\" @@ -63,7 +64,7 @@ Escape Sequences 8 Expressions 11 Fields 6 FTP/HTTP Information 18 -Historical Features (\*(GK) 16 +Historical Features (\*(GK) 10 Input Control 12 Internationalization (\*(GK) 18 Lines And Statements 5 @@ -75,6 +76,7 @@ POSIX Character Classes (\*(GK) 6 Printf Formats 13 Records 6 Regular Expressions 5 +Signals (\*(PK) 4 Special Filenames 14 String Functions 15 Time Functions (\*(GK) 16 @@ -97,7 +99,7 @@ Brian Kernighan and Michael Brennan who reviewed it. \*(CD .SL .nf -\*(FRCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002 +\*(FRCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. .nf .BT @@ -286,12 +288,16 @@ T} .T& ls l lw(2.2i). -\*(FC\-\^\-lint\*(FR[\*(FC=fatal\*(FR] +\*(FC\-\^\-lint\*(FR[\*(FC=\*(FIvalue\*(FR] %T{ warn about constructs that are dubious or non-portable to other \*(AKs. With an optional argument of \*(FCfatal\*(FR, lint warnings become fatal errors. +With an optional argument of +\*(FCinvalid\*(FR, +only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) T} .T& l lw(2.2i). @@ -323,9 +329,9 @@ l lw(2.2i). %T{ send profiling data to \*(FIprof_file\*(FR (default: \*(FCawkprof.out\*(FR). -With \*(FIgawk\*(FR, +With \*(GK, the profile is just a ``pretty printed'' version of the program. -With \*(FIpgawk\*(FR, +With \*(PK, the profile contains execution counts in the left margin of each statement in the program. T} @@ -357,13 +363,7 @@ 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. -.sp .5 -\*(FIpgawk\fP accepts two signals. -\*(FCSIGUSR1\fP causes it to dump a profile and function call stack to the -profile file. It then continues to run. -\*(FCSIGHUP\fP -causes it to dump the profile and function call stack and then exit.\*(CB +programs via the \*(FC#!\*(FR executable interpreter mechanism.\*(CB .EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0" .BT @@ -411,7 +411,16 @@ The options may be abbreviated using just the first letter, e.g., \*(FC\-Wv\*(FR and so on.\*(CB .EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(MK\f(HB)\*(FR\s0" - +.sp .7 +.\" --- Signals (pgawk) +.ES +.fi +\*(CD\*(PK accepts two signals. +\*(FCSIGUSR1\fP dumps a profile and function call stack to the +profile file. It then continues to run. +\*(FCSIGHUP\fP is similar, but exits.\*(CB +.EB "\s+2\f(HBSIGNALS (\*(PK\f(HB)\*(FR\s0" +.sp .7 .\" --- Awk Program Execution .ES .fi @@ -857,7 +866,13 @@ T} \*(CB\*(FCIGNORECASE\fP T{ if non-zero, all regular expression and string operations ignore case. -Array subscripting and \*(FCasort()\*(FR are \*(FInot\*(FR affected. +Array subscripting +is \*(FInot\*(FR affected. +However, the +\*(FCasort()\*(FR +and +\*(FCasorti()\*(FR +function are affected. T} \*(CB\*(FCLINT\fP T{ provides dynamic control of the \*(FC\-\^\-lint\fP @@ -873,12 +888,7 @@ T} number of fields in the current input record. T} \*(FCNR\fP T{ -total number of input records seen so far. -T} -\*(FCOFMT\fP T{ -output format for numbers, \*(FC"%.6g"\*(FR, by default. -\*(CROld versions of \*(AK used this for number -to string conversion.\*(CX +total number of input records seen so far.\*(CX T} .TE .EB "\s+2\f(HBVARIABLES\*(FR\s0" @@ -890,7 +900,12 @@ T} .TS expand; l lw(2i). -\*(CD\*(FCOFS\fP T{ +\*(CD\*(FCOFMT\fP T{ +output format for numbers, \*(FC"%.6g"\*(FR, by default. +\*(CROld versions of \*(AK used this for number +to string conversion.\*(CD +T} +\*(FCOFS\fP T{ output field separator, a space by default. T} \*(FCORS\fP T{ @@ -980,9 +995,27 @@ Uninitialized variables have the numeric value 0 and the string value .BT +.\" --- Historical Features +.ES +.fi +\*(CD1. 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 +issues a warning about its use if \*(FC\-\^\-lint\fP +is specified on the command line. +.sp .5 +2. The \*(FCcontinue\fP +and \*(FCbreak\fP statements may be used 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 supports this usage if \*(FC\-\^\-traditional\fP +is specified.\*(CB +.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0" + .ES \*(CX -.sp 61 +.sp 47 .EB "\s+2\f(HBNOTES\*(FR\s0" .BT @@ -1479,6 +1512,12 @@ and returns the number of elements. If destination \*(FId\*(FR is supplied, \*(FIs\*(FR is copied to \*(FId\*(FR, \*(FId\*(FR is sorted, and \*(FIs\*(FR is unchanged.\*(CD .ti -.2i +\*(CB\*(FCasorti(\*(FIs\*(FC \*(FR[\*(FC, \*(FId\*(FR]\*(FC)\*(FR +.br +like \*(FCasort()\*(FR, but sorting is done on the indices, not +the values. The original values are thrown array, so provide a +second array to preserve the first.\*(CD +.ti -.2i \*(CB\*(FCgensub(\*(FIr\*(FC, \*(FIs\*(FC, \*(FIh \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR .br search the target string @@ -1527,7 +1566,13 @@ and \*(FCRLENGTH\*(FR. \*(CBIf \*(FIa\*(FR is supplied, the text matching all of \*(FIr\*(FR is placed in \*(FIa\*(FC[0]\*(FR. If there were parenthesized subexpressions, the matching texts are placed -in \*(FIa\*(FC[1]\*(FR, \*(FIa\*(FC[2]\*(FR, and so on.\*(CD +in \*(FIa\*(FC[1]\*(FR, \*(FIa\*(FC[2]\*(FR, and so on. +Subscripts +\*(FCa[\*(FIn\^\*(FC, "start"]\*(FR, +and +\*(FCa[\*(FIn\^\*(FC, "length"]\*(FR +provide the starting index in the string and length +respectively, of each matching substring.\*(CD .ti -.2i \*(FCsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr\*(FR]\*(FC)\*(FR .br @@ -1556,9 +1601,18 @@ or \*(FC0X\*(FR, \*(FCstrtonum()\*(FR assumes that \*(FCsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR .br just like -\*(FCgsub()\*(FR, but only the first matching substring is replaced. +\*(FCgsub()\*(FR, but only the first matching substring is replaced.\*(CX +.in -.2i +.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0" + +.BT + +.\" --- Builtin String Functions +.ES +.fi +.in +.2i .ti -.2i -\*(FCsubstr(\*(FIs\*(FC, \*(FIi \*(FR[\*(FC, \*(FIn\*(FR]\*(FC)\*(FR +\*(CD\*(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. @@ -1569,18 +1623,9 @@ If \*(FIn\fP is omitted, the rest of \*(FIs\fP is used. 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.\*(CX -.in -.2i -.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0" - -.BT - -.\" --- Builtin String Functions -.ES -.fi -.in +.2i +left unchanged. .ti -.2i -\*(CD\*(FCtoupper(\*(FIstr\*(FC)\*(FR +\*(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 @@ -1684,24 +1729,6 @@ then \*(GK behaves exactly as if the \*(FC\-\^\-posix\fP option had been given.\*(CB .EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0" -.\" --- Historical Features -.ES -.fi -\*(CD1. 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 -issues a warning about its use if \*(FC\-\^\-lint\fP -is specified on the command line. -.sp .5 -2. The \*(FCcontinue\fP -and \*(FCbreak\fP statements may be used 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 supports this usage if \*(FC\-\^\-traditional\fP -is specified.\*(CB -.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0" - .BT .\" --- User-defined Functions @@ -1833,15 +1860,16 @@ one of the known locale categories. You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR to use the current domain. .ti -.2i -\*(FCdcngettext(\*(FIstring1 \*(FR, \*(FIstring2 \*(FR, \*(FInumber \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR +\*(FCdcngettext(\*(FIstring1\*(FC, \*(FIstring2\*(FC, \*(FInumber\*(FR [\*(FC, \*(FIdom \*(FR[\*(FC, \*(FIcat\*(FR]]\*(FC)\*(FR .br returns the plural form used for \*(FInumber\*(FR of the translation of \*(FIstring1\*(FR and \*(FIstring2\*(FR in text domain -\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR. -The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR. -The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR. +\*(FIdom\*(FR for locale category \*(FIcat\*(FR. +The default value for \*(FIdom\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR. +\*(FC"LC_MESSAGES"\*(FR +is the default value for \*(FIcat\*(FR. .sp .5 -If you supply a value for \*(FIcategory\*(FR, it must be a string equal to +If you supply a value for \*(FIcat\*(FR, it must be a string equal to one of the known locale categories. You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR to use the current domain.\*(CB @@ -1853,7 +1881,7 @@ to use the current domain.\*(CB .ES .nf \*(CDHost: \*(FCftp.gnu.org\*(FR -File: \*(FC/gnu/gawk/gawk-3.1.1.tar.gz\fP +File: \*(FC/gnu/gawk/gawk-3.1.2.tar.gz\fP .in +.2i .fi GNU \*(AK (\*(GK). There may be a later version. @@ -1864,7 +1892,7 @@ GNU \*(AK (\*(GK). There may be a later version. .in +.2i .fi \*(NK. This version requires an ANSI C compiler; -GCC (the GNU C compiler) works well. +GCC (the GNU Compiler Collection) works well. .in -.2i .nf .sp .5 @@ -1880,7 +1908,7 @@ Michael Brennan's \*(MK. There may be a newer version.\*(CX .\" --- Copying Permissions .ES .fi -\*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +\*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 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 @@ -14,7 +14,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Apr 16 2002" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "February 3 2003" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -265,10 +265,10 @@ the standard output. these options cause an immediate, successful exit.) .TP .PD 0 -.BR "\-W lint" [ =fatal ] +.BR "\-W lint" [ =\fIvalue\fR ] .TP .PD -.BR \-\^\-lint [ =fatal ] +.BR \-\^\-lint [ =\fIvalue\fR ] Provide warnings about constructs that are dubious or non-portable to other \*(AK implementations. With an optional argument of @@ -276,6 +276,10 @@ With an optional argument of lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner \*(AK programs. +With an optional argument of +.BR invalid , +only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) .TP .PD 0 .B "\-W lint\-old" @@ -812,9 +816,12 @@ operations. .B NOTE: Array subscripting is .I not -affected, nor is the +affected. +However, the .B asort() -function. +and +.B asorti() +functions are affected. .sp .5 Thus, if .B IGNORECASE @@ -2236,6 +2243,20 @@ is sorted, leaving the indexes of the source array .I s unchanged. +.TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n" +\fBasorti(\fIs \fR[\fB, \fId\fR]\fB)\fR +Returns the number of elements in the source +array +.IR s . +The behavior is the same as that of +.BR asort() , +except that the array +.I indices +are used for sorting, not the array values. +When done, the array is indexed numerically, and +the values are those of the original indices. +The original values are lost; thus provide +a second array if you wish to preserve the original. .TP \fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR Search the target string @@ -2367,6 +2388,12 @@ of .I s matched by the entire regular expression .IR r . +Subscripts +\fBa[\fIn\^\fB, "start"]\fR, +and +\fBa[\fIn\^\fB, "length"]\fR +provide the starting index in the string and length +respectively, of each matching substring. .TP \fBsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR]\fB)\fR Splits the string @@ -2459,7 +2486,7 @@ formatting them. .PP .TP "\w'\fBsystime()\fR'u+1n" \fBmktime(\fIdatespec\fB)\fR -Rurns +Turns .I datespec into a time stamp of the same form as returned by .BR systime() . @@ -2782,6 +2809,12 @@ Concatenate and line number (a variation on a theme): .ft B { print NR, $0 } .ft R +Run an external command for particular lines of data: + +.ft B + tail -f access_log | + awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }' +.ft R .fi .SH INTERNATIONALIZATION .PP @@ -3117,9 +3150,11 @@ to abandon processing of the current input file. The .BR and() , .BR asort() , +.BR asorti() , .BR bindtextdomain() , .BR compl() , .BR dcgettext() , +.BR dcngettext() , .BR gensub() , .BR lshift() , .BR mktime() , @@ -3321,7 +3356,7 @@ provided valuable assistance during testing and debugging. We thank him. .SH COPYING PERMISSIONS Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998, 1999, 2001, 2002 Free Software Foundation, Inc. +1997, 1998, 1999, 2001, 2002, 2003 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission diff --git a/doc/gawk.info b/doc/gawk.info index 316b56c5..3c290463 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1,24 +1,24 @@ -This is gawk.info, produced by makeinfo version 4.2 from gawk.texi. +This is gawk.info, produced by makeinfo version 4.5 from gawk.texi. -INFO-DIR-SECTION GNU Packages +INFO-DIR-SECTION Text creation and manipulation START-INFO-DIR-ENTRY -* Gawk: (gawk). A text scanning and processing language. +* Gawk: (gawk). A text scanning and processing language. END-INFO-DIR-ENTRY INFO-DIR-SECTION Individual utilities START-INFO-DIR-ENTRY -* awk: (gawk)Invoking gawk. Text scanning and processing. +* awk: (gawk)Invoking gawk. Text scanning and processing. END-INFO-DIR-ENTRY Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, -2001, 2002 Free Software Foundation, Inc. +2001, 2002, 2003 Free Software Foundation, Inc. This is Edition 3 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 3.1.1 (or later) version of the GNU +Guide for GNU Awk', for the 3.1.2 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -41,15 +41,15 @@ General Introduction particular records in a file and perform operations upon them. Copyright (C) 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, -2001, 2002 Free Software Foundation, Inc. +2001, 2002, 2003 Free Software Foundation, Inc. This is Edition 3 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 3.1.1 (or later) version of the GNU +Guide for GNU Awk', for the 3.1.2 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -149,6 +149,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. * Records:: Controlling how data is split into records. * Fields:: An introduction to fields. * Nonconstant Fields:: Nonconstant Field Numbers. @@ -1258,7 +1259,11 @@ if you had typed `awk -f advice': $ advice -| Don't Panic! -Self-contained `awk' scripts are useful when you want to write a +(We assume you have the current directory in your shell's search path +variable (typically `$PATH'). If not, you may need to type `./advice' +at the shell.) + + Self-contained `awk' scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in `awk'. @@ -1734,7 +1739,7 @@ variables are automatically initialized to zero.) After the last line of output from `ls' has been processed, the `END' rule executes and prints the value of `sum'. In this example, -the value of `sum' is 140963. +the value of `sum' is 80600. These more advanced `awk' techniques are covered in later sections (*note Actions: Action Overview.). Before you can move on to more @@ -1956,6 +1961,7 @@ you specify more complicated classes of strings. * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. File: gawk.info, Node: Regexp Usage, Next: Escape Sequences, Prev: Regexp, Up: Regexp @@ -2248,7 +2254,8 @@ sequences and that are not listed in the table stand for themselves: arithmetic. They can be used to concatenate regular expressions containing the alternation operator, `|'. For example, `@(samp|code)\{[^}]+\}' matches both `@code{foo}' and `@samp{bar}'. - (These are Texinfo formatting control sequences.) + (These are Texinfo formatting control sequences. The `+' is + explained further on in this list.) `*' This symbol means that the preceding regular expression should be @@ -2513,7 +2520,9 @@ No options `--re-interval' Allow interval expressions in regexps, even if `--traditional' has - been provided. + been provided. (`--posix' automatically enables interval + expressions, so `--re-interval' is redundant when `--posix' is is + used.) File: gawk.info, Node: Case-sensitivity, Next: Leftmost Longest, Prev: GNU Regexp Operators, Up: Regexp @@ -2624,7 +2633,7 @@ Records: Records., and also *note Specifying How Fields Are Separated: Field Separators.). -File: gawk.info, Node: Computed Regexps, Prev: Leftmost Longest, Up: Regexp +File: gawk.info, Node: Computed Regexps, Next: Locales, Prev: Leftmost Longest, Up: Regexp Using Dynamic Regexps ===================== @@ -2703,6 +2712,40 @@ to be used inside a character list for a dynamic regexp: often in practice, but it's worth noting for future reference. +File: gawk.info, Node: Locales, Prev: Computed Regexps, Up: Regexp + +Where You Are Makes A Difference +================================ + + Modern systems support the notion of "locales": a way to tell the +system about the local character set and language. The current locale +setting can affect the way regexp matching works, often in surprising +ways. In particular, many locales do case-insensitive matching, even +when you may have specified characters of only one particular case. + + The following example uses the `sub' function, which does text +replacement (*note String-Manipulation Functions: String Functions.). +Here, the intent is to remove trailing uppercase characters: + + $ echo something1234abc | gawk '{ sub("[A-Z]*$", ""); print }' + -| something1234 + +This output is unexpected, since the `abc' at the end of +`something1234abc' should not normally match `[A-Z]*'. This result is +due to the locale setting (and thus you may not see it on your system). +There are two fixes. The first is to use the POSIX character class +`[[:upper:]]', instead of `[A-Z]'. The second is to change the locale +setting in the environment, before running `gawk', by using the shell +statements: + + LANG=C LC_ALL=C + export LANG LC_ALL + + The setting `C' forces `gawk' to behave in the traditional Unix +manner, where case distinctions do matter. You may wish to put these +statements into your shell startup file, e.g., `$HOME/.profile'. + + File: gawk.info, Node: Reading Files, Next: Printing, Prev: Regexp, Up: Top Reading Input Files @@ -2889,6 +2932,14 @@ value of `RT' is a newline, and the `print' statement supplies its own terminating newline. *Note A Simple Stream Editor: Simple Sed, for a more useful example of `RS' as a regexp and `RT'. + If you set `RS' to a regular expression that allows optional +trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to +implementation constraints, that `gawk' may match the leading part of +the regular expression, but not the trailing part, particularly if the +input text that could match the trailing part is fairly long. `gawk' +attempts to avoid this problem, but currently, there's no guarantee +that this will never happen. + The use of `RS' as a regular expression and the `RT' variable are `gawk' extensions; they are not available in compatibility mode (*note Command-Line Options: Options.). In compatibility mode, only the first @@ -3058,9 +3109,9 @@ input file.) Consider the following example and its output: $ awk '{ nboxes = $3 ; $3 = $3 - 10 > print nboxes, $3 }' inventory-shipped - -| 13 3 - -| 15 5 - -| 15 5 + -| 25 15 + -| 32 22 + -| 24 14 ... The program first saves the original value of field three in the @@ -3071,7 +3122,7 @@ Ops.) Then it prints the original and new values for field three. (Someone in the warehouse made a consistent mistake while inventorying the red boxes.) - For this to work, the text in field `$2' must make sense as a + For this to work, the text in field `$3' must make sense as a number; the string of characters must be converted to a number for the computer to do arithmetic on it. The number resulting from the subtraction is converted back to a string of characters that then @@ -3112,11 +3163,11 @@ the appropriate number of field separators between it and the previously existing fields. This recomputation affects and is affected by `NF' (the number of -fields; *note Examining Fields: Fields.). It is also affected by a -feature that has not been discussed yet: the "output field separator", -`OFS', used to separate the fields (*note Output Separators::). For -example, the value of `NF' is set to the number of the highest field -you create. +fields; *note Examining Fields: Fields.). For example, the value of +`NF' is set to the number of the highest field you create. The exact +format of `$0' is also affected by a feature that has not been +discussed yet: the "output field separator", `OFS', used to separate +the fields (*note Output Separators::). Note, however, that merely _referencing_ an out-of-range field does _not_ change the value of either `$0' or `NF'. Referencing an @@ -3166,6 +3217,22 @@ value of `NF' and recomputes `$0'. (d.c.) Here is an example: *Caution:* Some versions of `awk' don't rebuild `$0' when `NF' is decremented. Caveat emptor. + Finally, there are times when it is convenient to force `awk' to +rebuild the entire record, using the current value of the fields and +`OFS'. To do this, use the seemingly innocuous assignment: + + $1 = $1 # force record to be reconstituted + print $0 # or whatever else with $0 + +This forces `awk' rebuild the record. It does help to add a comment, +as we've shown here. + + There is a flip side to the relationship between `$0' and the +fields. Any assignment to `$0' causes the record to be reparsed into +fields using the _current_ value of `FS'. This also applies to any +built-in function that updates `$0', such as `sub' and `gsub' (*note +String-Manipulation Functions: String Functions.). + File: gawk.info, Node: Field Separators, Next: Constant Size, Prev: Changing Fields, Up: Reading Files @@ -3426,6 +3493,15 @@ File: gawk.info, Node: Field Splitting Summary, Prev: Command Line Field Separ Field-Splitting Summary ----------------------- + It is important to remember that when you assign a string constant +as the value of `FS', it undergoes normal `awk' string processing. For +example, with Unix `awk' and `gawk', the assignment `FS = "\.."' +assigns the character string `".."' to `FS' (the backslash is +stripped). This creates a regexp meaning "fields are separated by +occurrences of any two characters." If instead you want fields to be +separated by a literal period followed by any single character, use `FS += "\\.."'. + The following table summarizes how fields are split, based on the value of `FS' (`==' means "is equal to"): @@ -3476,6 +3552,24 @@ like: root:nSijPlPhZZwgE:0:0:Root:/: +Advanced Notes: `FS' and `IGNORECASE' +------------------------------------- + + The `IGNORECASE' variable (*note Built-in Variables That Control +`awk': User-modified.) affects field splitting _only_ when the value +of `FS' is a regexp. It has no effect when `FS' is a single character, +even if that character is a letter. Thus, in the following code: + + FS = "c" + IGNORECASE = 1 + $0 = "aCa" + print $1 + +The output is `aCa'. If you really want to split fields on an +alphabetic character while ignoring case, use a regexp that will do it +for you. E.g., `FS = "[c]"'. In this case, `IGNORECASE' will take +effect. + ---------- Footnotes ---------- (1) The `sed' utility is a "stream editor." Its behavior is also @@ -3632,8 +3726,9 @@ second case, this special processing is not done. (d.c.) separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default as the result of a special feature. When `RS' is set to the empty -string, the newline character _always_ acts as a field separator. This -is in addition to whatever field separations result from `FS'. +string, _and_ `FS' is a set to a single character, the newline +character _always_ acts as a field separator. This is in addition to +whatever field separations result from `FS'.(1) The original motivation for this special exception was probably to provide useful behavior in the default case (i.e., `FS' is equal to @@ -3641,14 +3736,18 @@ provide useful behavior in the default case (i.e., `FS' is equal to newline character to separate fields, because there is no way to prevent it. However, you can work around this by using the `split' function to break up the record manually (*note String Manipulation -Functions: String Functions.). +Functions: String Functions.). If you have a single character field +separator, you can work around the special feature in a different way, +by making `FS' into a regexp for that single character. For example, +if the field separator is a percent character, instead of `FS = "%"', +use `FS = "[%]"'. Another way to separate fields is to put each field on a separate line: to do this, just set the variable `FS' to the string `"\n"'. -(This simple regular expression matches a single newline.) A practical -example of a data file organized this way might be a mailing list, -where each entry is separated by blank lines. Consider a mailing list -in a file named `addresses', which looks like this: +(This single character seperator matches a single newline.) A +practical example of a data file organized this way might be a mailing +list, where each entry is separated by blank lines. Consider a mailing +list in a file named `addresses', which looks like this: Jane Doe 123 Main Street @@ -3716,6 +3815,12 @@ equal to.") In all cases, `gawk' sets `RT' to the input text that matched the value specified by `RS'. + ---------- Footnotes ---------- + + (1) When `FS' is the null string (`""') or a regexp, this special +feature of `RS' does not apply. It does apply to the default field +separator of a single space: `FS = " "'. + File: gawk.info, Node: Getline, Prev: Multiple Line, Up: Reading Files @@ -4097,6 +4202,13 @@ bear in mind: BEGIN/END, also *note Built-in Variables That Convey Information: Auto-set..) + * Using `FILENAME' with `getline' (`getline < FILENAME') is likely + to be a source for confusion. `awk' opens a separate input stream + from the current input file. However, by not using a variable, + `$0' and `NR' are still updated. If you're doing this, it's + probably by accident, and you should reconsider what it is you're + trying to accomplish. + File: gawk.info, Node: Getline Summary, Prev: Getline Notes, Up: Getline @@ -5158,6 +5270,11 @@ not closed and released until `close' is called or `awk' exits. `close' will silently do nothing if given an argument that does not represent a file, pipe or coprocess that was opened with a redirection. + Note also that `close(FILENAME)' has no "magic" effects on the +implicit loop that reads through the files named on the command line. +It is, more likely, a close of a file that was never opened, so `awk' +silently does nothing. + When using the `|&' operator to communicate with a coprocess, it is occasionally useful to be able to close one end of the two-way pipe without closing the other. This is done by supplying a second argument @@ -5187,10 +5304,10 @@ cases, `gawk' sets the built-in variable `ERRNO' to a string describing the problem. In `gawk', when closing a pipe or coprocess, the return value is the -exit status of the command. Otherwise, it is the return value from the -system's `close' or `fclose' C functions when closing input or output -files, respectively. This value is zero if the close succeeds, or -1 if -it fails. +exit status of the command.(2) Otherwise, it is the return value from +the system's `close' or `fclose' C functions when closing input or +output files, respectively. This value is zero if the close succeeds, +or -1 if it fails. The return value for closing a pipeline is particularly useful. It allows you to get the output from a command as well as its exit status. @@ -5215,6 +5332,10 @@ return value from `close' is that of the library's `pclose' function. is called a "zombie," and cleaning up after it is referred to as "reaping." + (2) This is a full 16-bit value as returned by the `wait' system +call. See the system manual pages for information on how to decode this +value. + File: gawk.info, Node: Expressions, Next: Patterns and Actions, Prev: Printing, Up: Top @@ -6808,7 +6929,7 @@ program attempts to combine a range pattern with another, simpler test: interprets this as `/1/, (/2/ || /Yes/)'. This cannot be changed or worked around; range patterns do not combine with other patterns: - $ echo yes | gawk '(/1/,/2/) || /Yes/' + $ echo Yes | gawk '(/1/,/2/) || /Yes/' error--> gawk: cmd. line:1: (/1/,/2/) || /Yes/ error--> gawk: cmd. line:1: ^ parse error error--> gawk: cmd. line:2: (/1/,/2/) || /Yes/ @@ -7677,8 +7798,10 @@ specific to `gawk' are marked with a pound sign (`#'). `gsub', `index', `match', `split', and `sub' functions, record termination with `RS', and field splitting with `FS', all ignore case when doing their particular regexp operations. However, the - value of `IGNORECASE' does _not_ affect array subscripting. *Note - Case Sensitivity in Matching: Case-sensitivity. + value of `IGNORECASE' does _not_ affect array subscripting and it + does not affect field splitting when using a single-character + field separator. *Note Case Sensitivity in Matching: + Case-sensitivity. If `gawk' is in compatibility mode (*note Command-Line Options: Options.), then `IGNORECASE' has no special meaning. Thus, string @@ -7688,7 +7811,9 @@ specific to `gawk' are marked with a pound sign (`#'). When this variable is true (nonzero or non-null), `gawk' behaves as if the `--lint' command-line option is in effect. (*note Command-Line Options: Options.). With a value of `"fatal"', lint - warnings become fatal errors. Any other true value prints + warnings become fatal errors. With a value of `"invalid"', only + warnings about things that are actually invalid are issued. (This + is not fully implemented yet.) Any other true value prints nonfatal warnings. Assigning a false value to `LINT' turns off the lint warnings. @@ -7766,7 +7891,7 @@ Built-in Variables That Convey Information The following is an alphabetical list of variables that `awk' sets automatically on certain occasions in order to provide information to your program. The variables that are specific to `gawk' are marked -with an asterisk (`*'). +with a pound sign (`#'). `ARGC, ARGV' The command-line arguments available to `awk' programs are stored @@ -7862,6 +7987,12 @@ with an asterisk (`*'). each time a new record is read, when a new field is created or when `$0' changes (*note Examining Fields: Fields.). + Unlike most of the variables described in this node, assigning a + value to `NF' has the potential to affect `awk''s internal + workings. In particular, assignments to `NF' can be used to + create or remove fields from the current record: *Note Changing + the Contents of a Field: Changing Fields. + `NR' The number of input records `awk' has processed since the beginning of the program's execution (*note How Input Is Split @@ -8676,9 +8807,9 @@ Sorting Array Values and Indices with `gawk' loop is essentially arbitrary. In most `awk' implementations, sorting an array requires writing a `sort' function. While this can be educational for exploring different sorting algorithms, usually that's -not the point of the program. `gawk' provides the built-in `asort' -function (*note String Manipulation Functions: String Functions.) that -sorts an array. For example: +not the point of the program. `gawk' provides the built-in `asort' and +`asorti' functions (*note String Manipulation Functions: String +Functions.) for sorting arrays. For example: POPULATE THE ARRAY data n = asort(data) @@ -8706,9 +8837,23 @@ and then sorts `dest', destroying its indices. However, the `source' array is not affected. Often, what's needed is to sort on the values of the _indices_ -instead of the values of the elements. To do this, use a helper array -to hold the sorted index values, and then access the original array's -elements. It works in the following way: +instead of the values of the elements. To do that, starting with +`gawk' 3.1.2, use the `asorti' function. The interface is identical to +that of `asort', except that the index values are used for sorting, and +become the values of the result array: + + { source[$0] = some_func($0) } + + END { + n = asorti(source, dest) + for (i = 1; i <= n; i++) + DO SOMETHING WITH dest[i] + } + + If your version of `gawk' is 3.1.0 or 3.1.1, you don't have +`asorti'. Instead, use a helper array to hold the sorted index values, +and then access the original array's elements. It works in the +following way: POPULATE THE ARRAY data # copy indices @@ -8733,8 +8878,10 @@ is only one copy of the original array elements' data, even though both arrays use the values. Similarly, when copying the indices from `data' to `ind', there is only one copy of the actual index strings. - As with array subscripts, the value of `IGNORECASE' does not affect -array sorting. + We said previously that comparisons are done using `gawk''s "usual +comparison rules." Because `IGNORECASE' affects string comparisons, +the value of `IGNORECASE' also affects sorting for both `asort' and +`asorti'. Caveat Emptor. File: gawk.info, Node: Functions, Next: Internationalization, Prev: Arrays, Up: Top @@ -8830,8 +8977,8 @@ Numeric Functions ----------------- The following list describes all of the built-in functions that work -with numbers. Optional parameters are enclosed in square brackets ([ -]): +with numbers. Optional parameters are enclosed in square +brackets ([ ]): `int(X)' This returns the nearest integer to X, located between X and zero @@ -8943,9 +9090,9 @@ String-Manipulation Functions ----------------------------- The functions in this minor node look at or change the text of one -or more strings. Optional parameters are enclosed in square brackets -([ ]). Those functions that are specific to `gawk' are marked with a -pound sign (`#'): +or more strings. Optional parameters are enclosed in square +brackets ([ ]). Those functions that are specific to `gawk' are marked +with a pound sign (`#'): * Menu: @@ -8956,12 +9103,13 @@ pound sign (`#'): `asort(SOURCE [, DEST]) #' `asort' is a `gawk'-specific extension, returning the number of elements in the array SOURCE. The contents of SOURCE are sorted - using `gawk''s normal rules for comparing values, and the indices - of the sorted values of SOURCE are replaced with sequential - integers starting with one. If the optional array DEST is - specified, then SOURCE is duplicated into DEST. DEST is then - sorted, leaving the indices of SOURCE unchanged. For example, if - the contents of `a' are as follows: + using `gawk''s normal rules for comparing values (in particular, + `IGNORECASE' affects the sorting) and the indices of the sorted + values of SOURCE are replaced with sequential integers starting + with one. If the optional array DEST is specified, then SOURCE is + duplicated into DEST. DEST is then sorted, leaving the indices of + SOURCE unchanged. For example, if the contents of `a' are as + follows: a["last"] = "de" a["first"] = "sac" @@ -8982,6 +9130,20 @@ pound sign (`#'): `gawk' extension; it is not available in compatibility mode (*note Command-Line Options: Options.). +`asorti(SOURCE [, DEST]) #' + `asorti' is a `gawk'-specific extension, returning the number of + elements in the array SOURCE. It works similarly to `asort', + however, the _indices_ are sorted, instead of the values. As + array indices are always strings, the comparison performed is + always a string comparison. (Here too, `IGNORECASE' affects the + sorting.) + + The `asorti' function is described in more detail in *Note Sorting + Array Values and Indices with `gawk': Array Sorting. It was added + in `gawk' 3.1.2. `asorti' is a `gawk' extension; it is not + available in compatibility mode (*note Command-Line Options: + Options.). + `index(IN, FIND)' This searches the string IN for the first occurrence of the string FIND, and returns the position in characters where that occurrence @@ -9017,6 +9179,12 @@ pound sign (`#'): (one, if it starts at the beginning of STRING). If no match is found, it returns zero. + The REGEXP argument may be either a regexp constant (`/.../') or a + string constant ("..."). In the latter case, the string is + treated as a regexp to be matched. *Note Using Dynamic Regexps: + Computed Regexps, for a discussion of the difference between the + two forms, and the implications for writing your program correctly. + The order of the first two arguments is backwards from most other string functions that work with regular expressions, such as `sub' and `gsub'. It might help to remember that for `match', the order @@ -9069,6 +9237,20 @@ pound sign (`#'): > print arr[1], arr[2] }' -| foooo barrrrr + In addition, beginning with `gawk' 3.1.2, multidimensional + subscripts are available providing the start index and length of + each matched subexpression: + + $ echo foooobazbarrrrr | + > gawk '{ match($0, /(fo+).+(bar*)/, arr) + > print arr[1], arr[2] + > print arr[1, "start"], arr[1, "length"] + > print arr[2, "start"], arr[2, "length"] + > }' + -| foooo barrrrr + -| 1 5 + -| 9 7 + The ARRAY argument to `match' is a `gawk' extension. In compatibility mode (*note Command-Line Options: Options.), using a third argument is a fatal error. @@ -9104,14 +9286,27 @@ pound sign (`#'): character in the string is split into its own array element. (This is a `gawk'-specific extension.) + Note, however, that `RS' has no effect on the way `split' works. + Even though `RS = ""' causes newline to also be an input field + separator, this does not affect how `split' splits strings. + Modern implementations of `awk', including `gawk', allow the third argument to be a regexp constant (`/abc/') as well as a string. - (d.c.) The POSIX standard allows this as well. + (d.c.) The POSIX standard allows this as well. *Note Using + Dynamic Regexps: Computed Regexps, for a discussion of the + difference between using a string constant or a regexp constant, + and the implications for writing your program correctly. Before splitting the string, `split' deletes any previously - existing elements in the array ARRAY. If STRING does not match - FIELDSEP at all, ARRAY has one element only. The value of that - element is the original STRING. + existing elements in the array ARRAY. + + If STRING is null, the array has no elements. (So this is a + portable way to delete an entire array with one statement. *Note + The `delete' Statement: Delete.) + + If STRING does not match FIELDSEP at all (but is not null), ARRAY + has one element only. The value of that element is the original + STRING. `sprintf(FORMAT, EXPRESSION1, ...)' This returns (without printing) the string that `printf' would @@ -9146,11 +9341,17 @@ pound sign (`#'): entire string is changed by replacing the matched text with REPLACEMENT. The modified string becomes the new value of TARGET. + The REGEXP argument may be either a regexp constant (`/.../') or a + string constant ("..."). In the latter case, the string is + treated as a regexp to be matched. *Note Using Dynamic Regexps: + Computed Regexps, for a discussion of the difference between the + two forms, and the implications for writing your program correctly. + This function is peculiar because TARGET is not simply used to compute a value, and not just any expression will do--it must be a variable, field, or array element so that `sub' can store a modified value there. If this argument is omitted, then the - default is to use and alter `$0'. For example: + default is to use and alter `$0'.(2) For example: str = "water, water, everywhere" sub(/at/, "ith", str) @@ -9280,7 +9481,7 @@ pound sign (`#'): `substr(STRING, START [, LENGTH])' This returns a LENGTH-character-long substring of STRING, starting at character number START. The first character of a string is - character number one.(2) For example, `substr("washington", 5, 3)' + character number one.(3) For example, `substr("washington", 5, 3)' returns `"ing"'. If LENGTH is not present, this function returns the whole suffix of @@ -9289,10 +9490,12 @@ pound sign (`#'): also returned if LENGTH is greater than the number of characters remaining in the string, counting from character START. - If START is less than one or greater than the number of characters - in the string, `substr' returns the null string. Similarly, if - LENGTH is present but less than or equal to zero, the null string - is returned. + If START is less than one, `substr' treats it as if it was one. + (POSIX doesn't specify what to do in this case: Unix `awk' acts + this way, and therefore `gawk' does too.) If START is greater + than the number of characters in the string, `substr' returns the + null string. Similarly, if LENGTH is present but less than or + equal to zero, the null string is returned. The string returned by `substr' _cannot_ be assigned. Thus, it is a mistake to attempt to change a portion of a string, as shown in @@ -9335,7 +9538,12 @@ pound sign (`#'): recommended. *Note Allowing Nondecimal Input Data: Nondecimal Data, for more information. - (2) This is different from C and C++, in which the first character + (2) Note that this means that the record will first be regenerated +using the value of `OFS' if any fields have been changed, and that the +fields will be updated after the substituion, even if the operation is +a "no-op" such as `sub(/^/, "")'. + + (3) This is different from C and C++, in which the first character is number zero. @@ -10868,7 +11076,7 @@ translations for `guide'. ---------- Footnotes ---------- - (1) Starting with `gettext' version 0.11.1, the `xgettext' utility + (1) Starting with `gettext' version 0.11.5, the `xgettext' utility that comes with GNU `gettext' can handle `.awk' files. @@ -11112,8 +11320,8 @@ File: gawk.info, Node: Gawk I18N, Prev: I18N Example, Up: Internationalizatio As of version 3.1, `gawk' itself has been internationalized using the GNU `gettext' package. (GNU `gettext' is described in complete detail in *Note Top::.) As of this writing, the latest version of GNU -`gettext' is version 0.11.1 -(ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.1.tar.gz). +`gettext' is version 0.11.5 +(ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.5.tar.gz). If a translation of `gawk''s messages exists, then `gawk' produces usage messages, warnings, and fatal errors in the local language. @@ -11225,7 +11433,7 @@ processing and then read the result. This can always be done with temporary files: # write the data for processing - tempfile = ("/tmp/mydata." PROCINFO["pid"]) + tempfile = ("mydata." PROCINFO["pid"]) while (NOT DONE WITH DATA) print DATA | ("subprogram > " tempfile) close("subprogram > " tempfile) @@ -11236,7 +11444,10 @@ temporary files: close(tempfile) system("rm " tempfile) -This works, but not elegantly. +This works, but not elegantly. Among other things, it requires that +the program be run in a directory that cannot be shared among users; +for example, `/tmp' will not do, as another user might happen to be +using a temporary file with the same name. Starting with version 3.1 of `gawk', it is possible to open a _two-way_ pipe to another process. The second process is termed a @@ -11265,8 +11476,6 @@ or pipeline of programs, that can be started by the shell. standard error goes. It is not possible to read the child's standard error separately. - </itemizedlist> - * I/O buffering may be a problem. `gawk' automatically flushes all output down the pipe to the child process. However, if the coprocess does not flush its output, `gawk' may hang when doing a @@ -11314,6 +11523,22 @@ terminates the coprocess and exits. As a side note, the assignment `LC_ALL=C' in the `sort' command ensures traditional Unix (ASCII) sorting from `sort'. + Beginning with `gawk' 3.1.2, you may use Pseudo-ttys (ptys) for +two-way communication instead of pipes, if your system supports them. +This is done on a per-command basis, by setting a special element in +the `PROCINFO' array (*note Built-in Variables That Convey Information: +Auto-set.), like so: + + command = "sort -nr" # command, saved in variable for convenience + PROCINFO[command, "pty"] = 1 # update PROCINFO + print ... |& command # start two-way pipe + ... + +Using ptys avoids the buffer deadlock issues described earlier, at some +loss in performance. If your system does not have ptys, or if all the +system's ptys are in use, `gawk' automatically falls back to using +regular pipes. + ---------- Footnotes ---------- (1) This is very different from the same operator in the C shell, @@ -11810,6 +12035,9 @@ The following list describes `gawk'-specific options: executes. With an optional argument of `fatal', lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner `awk' programs. + With an optional argument of `invalid', only warnings about things + that are actually invalid are issued. (This is not fully + implemented yet.) `-W lint-old' `--lint-old' @@ -13330,12 +13558,12 @@ that "cats" the password database: struct passwd *p; while ((p = getpwent()) != NULL) - printf("%s:%s:%d:%d:%s:%s:%s\n", - p->pw_name, p->pw_passwd, p->pw_uid, - p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); + printf("%s:%s:%ld:%ld:%s:%s:%s\n", + p->pw_name, p->pw_passwd, (long) p->pw_uid, + (long) p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); endpwent(); - exit(0); + return 0; } If you don't understand C, don't worry about it. The output from @@ -13541,8 +13769,8 @@ have a small C program that generates the group database as its output. int i; while ((g = getgrent()) != NULL) { - printf("%s:%s:%d:", g->gr_name, g->gr_passwd, - g->gr_gid); + printf("%s:%s:%ld:", g->gr_name, g->gr_passwd, + (long) g->gr_gid); for (i = 0; g->gr_mem[i] != NULL; i++) { printf("%s", g->gr_mem[i]); if (g->gr_mem[i+1] != NULL) @@ -13551,7 +13779,7 @@ have a small C program that generates the group database as its output. putchar('\n'); } endgrent(); - exit(0); + return 0; } Each line in the group database represents one group. The fields are @@ -15853,36 +16081,41 @@ should accept all of `gawk''s command-line arguments, including the ability to have multiple source files specified via `-f', and the ability to mix command-line and library source files. - The program is written using the POSIX Shell (`sh') command language. -It works as follows: + The program is written using the POSIX Shell (`sh') command +language.(1) It works as follows: 1. Loop through the arguments, saving anything that doesn't represent `awk' source code for later, when the expanded program is run. 2. For any arguments that do represent `awk' text, put the arguments - into a temporary file that will be expanded. There are two cases: + into a shell variable that will be expanded. There are two cases: a. Literal text, provided with `--source' or `--source='. This - text is just echoed directly. The `echo' program - automatically supplies a trailing newline. + text is just appended directly. b. Source file names, provided with `-f'. We use a neat trick - and echo `@include FILENAME' into the temporary file. Since - the file-inclusion program works the way `gawk' does, this - gets the text of the file included into the program at the - correct point. + and append `@include FILENAME' to the shell variable's + contents. Since the file-inclusion program works the way + `gawk' does, this gets the text of the file included into the + program at the correct point. - 3. Run an `awk' program (naturally) over the temporary file to expand - `@include' statements. The expanded program is placed in a second - temporary file. + 3. Run an `awk' program (naturally) over the shell variable's + contents to expand `@include' statements. The expanded program is + placed in a second shell variable. 4. Run the expanded program with `gawk' and any other original command-line arguments that the user supplied (such as the data file names). + This program uses shell variables extensively; for storing command +line arguments, the text of the `awk' program that will expand the +user's program, for the user's original program, and for the expanded +program. Doing so removes some potential problems that might arise +were we to use temporary files instead, at the cost of making the +script somewhat more complicated. + The initial part of the program turns on shell tracing if the first -argument is `debug'. Otherwise, a shell `trap' statement arranges to -clean up any temporary files on program exit or upon an interrupt. +argument is `debug'. The next part loops through all the command-line arguments. There are several cases of interest: @@ -15902,12 +16135,16 @@ are several cases of interest: These are saved and passed on to `gawk'. `-f, --file, --file=, -Wfile=' - The file name is saved to the temporary file `/tmp/ig.s.$$' with an - `@include' statement. The `sed' utility is used to remove the - leading option part of the argument (e.g., `--file='). + The file name is appended to the shell variable `program' with an + `@include' statement. The `expr' utility is used to remove the + leading option part of the argument (e.g., `--file='). (Typical + `sh' usage would be to use the `echo' and `sed' utilities to do + this work. Unfortunately, some versions of `echo' evaluate escape + sequences in their arguments, possibly mangling the program text. + Using `expr' avoids this problem.) `--source, --source=, -Wsource=' - The source text is echoed into `/tmp/ig.s.$$'. + The source text is appended to `program'. `--version, -Wversion' `igawk' prints its version number, runs `gawk --version' to get @@ -15917,14 +16154,11 @@ are several cases of interest: arguments are supplied, then the first nonoption argument should be the `awk' program. If there are no command-line arguments left, `igawk' prints an error message and exits. Otherwise, the first argument is -echoed into `/tmp/ig.s.$$'. In any case, after the arguments have been -processed, `/tmp/ig.s.$$' contains the complete text of the original -`awk' program. +appended to `program'. In any case, after the arguments have been +processed, `program' contains the complete text of the original `awk' +program. - The `$$' in `sh' represents the current process ID number. It is -often used in shell programs to generate unique temporary file names. -This allows multiple users to run `igawk' without worrying that the -temporary file names will clash. The program is as follows: + The program is as follows: #! /bin/sh # igawk --- like gawk but do @include processing @@ -15932,49 +16166,56 @@ temporary file names will clash. The program is as follows: then set -x shift - else - # cleanup on exit, hangup, interrupt, quit, termination - trap 'rm -f /tmp/ig.[se].$$' 0 1 2 3 15 fi + # A literal newline, so that program text is formmatted correctly + n=' + ' + + # Initialize variables to empty + program= + opts= + while [ $# -ne 0 ] # loop over arguments do case $1 in --) shift; break;; -W) shift - set -- -W"$@" + # The ${x?'message here'} construct prints a + # diagnostic if $x is the null string + set -- -W"${@?'missing operand'}" continue;; - -[vF]) opts="$opts $1 '$2'" + -[vF]) opts="$opts $1 '${2?'missing operand'}'" shift;; -[vF]*) opts="$opts '$1'" ;; - -f) echo @include "$2" >> /tmp/ig.s.$$ + -f) program="$program$n@include ${2?'missing operand'}" shift;; - -f*) f=`echo "$1" | sed 's/-f//'` - echo @include "$f" >> /tmp/ig.s.$$ ;; + -f*) f=`expr "$1" : '-f\(.*\)'` + program="$program$n@include $f";; - -?file=*) # -Wfile or --file - f=`echo "$1" | sed 's/-.file=//'` - echo @include "$f" >> /tmp/ig.s.$$ ;; + -[W-]file=*) + f=`expr "$1" : '-.file=\(.*\)'` + program="$program$n@include $f";; - -?file) # get arg, $2 - echo @include "$2" >> /tmp/ig.s.$$ + -[W-]file) + program="$program$n@include ${2?'missing operand'}" shift;; - -?source=*) # -Wsource or --source - t=`echo "$1" | sed 's/-.source=//'` - echo "$t" >> /tmp/ig.s.$$ ;; + -[W-]source=*) + t=`expr "$1" : '-.source=\(.*\)'` + program="$program$n$t";; - -?source) # get arg, $2 - echo "$2" >> /tmp/ig.s.$$ + -[W-]source) + program="$program$n${2?'missing operand'}" shift;; - -?version) - echo igawk: version 1.0 1>&2 + -[W-]version) + echo igawk: version 2.0 1>&2 gawk --version exit 0 ;; @@ -15985,29 +16226,25 @@ temporary file names will clash. The program is as follows: shift done - if [ ! -s /tmp/ig.s.$$ ] + if [ -z "$program" ] then - if [ -z "$1" ] - then - echo igawk: no program! 1>&2 - exit 1 - else - echo "$1" > /tmp/ig.s.$$ - shift - fi + program=${1?'missing program'} + shift fi - # at this point, /tmp/ig.s.$$ has the program - - The `awk' program to process `@include' directives reads through the -program, one line at a time, using `getline' (*note Explicit Input with -`getline': Getline.). The input file names and `@include' statements -are managed using a stack. As each `@include' is encountered, the -current file name is "pushed" onto the stack and the file named in the -`@include' directive becomes the current file name. As each file is -finished, the stack is "popped," and the previous input file becomes -the current input file again. The process is started by making the -original file the first one on the stack. + # At this point, `program' has the program. + + The `awk' program to process `@include' directives is stored in the +shell variable `expand_prog'. Doing this keeps the shell script +readable. The `awk' program reads through the user's program, one line +at a time, using `getline' (*note Explicit Input with `getline': +Getline.). The input file names and `@include' statements are managed +using a stack. As each `@include' is encountered, the current file +name is "pushed" onto the stack and the file named in the `@include' +directive becomes the current file name. As each file is finished, the +stack is "popped," and the previous input file becomes the current +input file again. The process is started by making the original file +the first one on the stack. The `pathto' function does the work of finding the full path to a file. It simulates `gawk''s behavior when searching the `AWKPATH' @@ -16016,11 +16253,10 @@ Variable.). If a file name has a `/' in it, no path search is done. Otherwise, the file name is concatenated with the name of each directory in the path, and an attempt is made to open the generated file name. The only way to test if a file can be read in `awk' is to go -ahead and try to read it with `getline'; this is what `pathto' does.(1) +ahead and try to read it with `getline'; this is what `pathto' does.(2) If the file can be read, it is closed and the file name is returned: - gawk -- ' - # process @include directives + expand_prog=' function pathto(file, i, t, junk) { @@ -16051,12 +16287,12 @@ represents the current directory: pathlist[i] = "." } - The stack is initialized with `ARGV[1]', which will be -`/tmp/ig.s.$$'. The main loop comes next. Input lines are read in -succession. Lines that do not start with `@include' are printed -verbatim. If the line does start with `@include', the file name is in -`$2'. `pathto' is called to generate the full path. If it cannot, -then we print an error message and continue. + The stack is initialized with `ARGV[1]', which will be `/dev/stdin'. +The main loop comes next. Input lines are read in succession. Lines +that do not start with `@include' are printed verbatim. If the line +does start with `@include', the file name is in `$2'. `pathto' is +called to generate the full path. If it cannot, then we print an error +message and continue. The next thing to check is if the file is included already. The `processed' array is indexed by the full file name of each included @@ -16093,19 +16329,48 @@ zero, the program is done: } close(input[stackptr]) } - }' /tmp/ig.s.$$ > /tmp/ig.e.$$ + }' # close quote ends `expand_prog' variable + + processed_program=`gawk -- "$expand_prog" /dev/stdin <<EOF + $program + EOF + ` + + The shell construct `COMMAND << MARKER' is called a "here document". +Everything in the shell script up to the MARKER is fed to COMMAND as +input. The shell processes the contents of the here document for +variable and command substitution (and possibly other things as well, +depending upon the shell). + + The shell construct ``...`' is called "command substitution". The +output of the command between the two backquotes (grave accents) is +substituted into the command line. It is saved as a single string, +even if the results contain whitespace. + + The expanded program is saved in the variable `processed_program'. +It's done in these steps: + + 1. Run `gawk' with the `@include'-processing program (the value of + the `expand_prog' shell variable) on standard input. + + 2. Standard input is the contents of the user's program, from the + shell variable `program'. Its contents are fed to `gawk' via a + here document. + + 3. The results of this processing are saved in the shell variable + `processed_program' by using command substitution. The last step is to call `gawk' with the expanded program, along with the original options and command-line arguments that the user -supplied. `gawk''s exit status is passed back on to `igawk''s calling -program: +supplied. - eval gawk -f /tmp/ig.e.$$ $opts -- "$@" - - exit $? + eval gawk $opts -- '"$processed_program"' '"$@"' - This version of `igawk' represents my third attempt at this program. -There are three key simplifications that make the program work better: + The `eval' command is a shell construct that reruns the shell's +parsing process. This keeps things properly quoted. + + This version of `igawk' represents my fourth attempt at this program. +There are four key simplifications that make the program work better: * Using `@include' even for the files named with `-f' makes building the initial collected `awk' program much simpler; all the @@ -16119,6 +16384,12 @@ There are three key simplifications that make the program work better: place. It is not necessary to call out to a separate loop for processing nested `@include' statements. + * Instead of saving the expanded program in a temporary file, + putting it in a shell variable avoids some potential security + problems. This has the disadvantage that the script relies upon + more features of the `sh' language, making it harder to follow for + those who aren't familiar with `sh'. + Also, this program illustrates that it is often worthwhile to combine `sh' and `awk' programming together. You can usually accomplish quite a lot, without having to resort to low-level programming in C or C++, @@ -16152,7 +16423,11 @@ for the desired library functions. ---------- Footnotes ---------- - (1) On some very old versions of `awk', the test `getline junk < t' + (1) Fully explaining the `sh' language is beyond the scope of this +book. We provide some minimal explanations, but see a good shell +programming book if you wish to understand things in more depth. + + (2) On some very old versions of `awk', the test `getline junk < t' can loop forever if the file exists but is empty. Caveat emptor. @@ -16547,10 +16822,10 @@ options (*note Command-Line Options: Options.). * Positional specifiers in `printf' formats for making translations easier (*note Rearranging `printf' Arguments: Printf Ordering.). - * The `asort' function for sorting arrays (*note Sorting Array - Values and Indices with `gawk': Array Sorting.). + * The `asort' and `asorti' functions for sorting arrays (*note + Sorting Array Values and Indices with `gawk': Array Sorting.). - * The `bindtextdomain' and `dcgettext' functions for + * The `bindtextdomain', `dcgettext' and `dcngettext' functions for internationalization (*note Internationalizing `awk' Programs: Programmer i18n.). @@ -16603,6 +16878,10 @@ options (*note Command-Line Options: Options.). * The source code now uses new-style function definitions, with `ansi2knr' to convert the code on systems with old compilers. + * The `--disable-lint' configuration option to disable lint checking + at compile time (*note Additional Configuration Options: + Additional Configuration Options.). + File: gawk.info, Node: Contributors, Prev: POSIX/GNU, Up: Language History @@ -16774,20 +17053,20 @@ Extracting the Distribution `gawk' is distributed as a `tar' file compressed with the GNU Zip program, `gzip'. - Once you have the distribution (for example, `gawk-3.1.1.tar.gz'), + Once you have the distribution (for example, `gawk-3.1.2.tar.gz'), use `gzip' to expand the file and then use `tar' to extract it. You can use the following pipeline to produce the `gawk' distribution: # Under System V, add 'o' to the tar options - gzip -d -c gawk-3.1.1.tar.gz | tar -xvpf - + gzip -d -c gawk-3.1.2.tar.gz | tar -xvpf - -This creates a directory named `gawk-3.1.1' in the current directory. +This creates a directory named `gawk-3.1.2' in the current directory. The distribution file name is of the form `gawk-V.R.P.tar.gz'. The V represents the major version of `gawk', the R represents the current release of version V, and the P represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch -level is 1, but when retrieving distributions, you should get the +level is 2, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note, however, that patch levels greater than or equal to 80 denote "beta" or nonproduction software; you might not want to retrieve such a version @@ -16981,7 +17260,7 @@ Compiling `gawk' for Unix ------------------------- After you have extracted the `gawk' distribution, `cd' to -`gawk-3.1.1'. Like most GNU software, `gawk' is configured +`gawk-3.1.2'. Like most GNU software, `gawk' is configured automatically for your Unix system by running the `configure' program. This program is a Bourne shell script that is generated automatically using GNU `autoconf'. (The `autoconf' software is described fully @@ -17038,6 +17317,22 @@ command line when compiling `gawk' from scratch, including: (or later) of the GNU C library. All known modern GNU/Linux systems use Glibc 2. Use this option on any other system. +`--disable-lint' + This option disables all lint checking within `gawk'. The + `--lint' and `--lint-old' options (*note Command-Line Options: + Options.) are accepted, but silently do nothing. Similarly, + setting the `LINT' variable (*note Built-in Variables That Control + `awk': User-modified.) has no effect on the running `awk' program. + + When used with GCC's automatic dead-code-elimination, this option + cuts almost 200K bytes off the size of the `gawk' executable on + GNU/Linux x86 systems. Results on other systems and with other + compilers are likely to vary. Using this option may bring you + some slight performance improvement. + + Using this option will cause some of the tests in the test suite + to fail. This option may be removed at a later date. + `--disable-nls' Disable all message-translation facilities. This is usually not desirable, but it may bring you some slight performance @@ -17247,15 +17542,19 @@ Compiling `gawk' for PC Operating Systems development tools from DJ Delorie (DJGPP; MS-DOS only) or Eberhard Mattes (EMX; MS-DOS, Win32 and OS/2). Microsoft Visual C/C++ can be used to build a Win32 version, and Microsoft C/C++ can be used to build -16-bit versions for MS-DOS and OS/2. The file `README_d/README.pc' in -the `gawk' distribution contains additional notes, and `pc/Makefile' -contains important information on compilation options. - - To build `gawk' for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX) -see below), copy the files in the `pc' directory (_except_ for -`ChangeLog') to the directory with the rest of the `gawk' sources. The -`Makefile' contains a configuration section with comments and may need -to be edited in order to work with your `make' utility. +16-bit versions for MS-DOS and OS/2. (As of `gawk' 3.1.2, the MSC +version doesn't work. However, the maintainer is working on fixing it.) +The file `README_d/README.pc' in the `gawk' distribution contains +additional notes, and `pc/Makefile' contains important information on +compilation options. + + To build `gawk' for MS-DOS, Win32, and OS/2 (16 bit only; for 32 bit +(EMX) you can use the `configure' script and skip the following +paragraphs; for details see below), copy the files in the `pc' +directory (_except_ for `ChangeLog') to the directory with the rest of +the `gawk' sources. The `Makefile' contains a configuration section +with comments and may need to be edited in order to work with your +`make' utility. The `Makefile' contains a number of targets for building various MS-DOS, Win32, and OS/2 versions. A list of targets is printed if the @@ -17273,63 +17572,73 @@ the file `pc/Makefile.tst' over the file `test/Makefile' as a replacement. Details can be found in `README_d/README.pc' and in the file `pc/Makefile.tst'. - To build `gawk' for OS/2 (32 bit, EMX), there are three -possibilities: - - 1. Using the `configure' script included in the official `gawk' - distribution. `configure' need not be recreated but a number of - restrictions exist when using this choice: - - * An external `gettext' library cannot be used. I.e. the - `configure' option `--without-included-gettext' does not - work. Unfortunately, the internal `gettext' library is - seriuosly broken for OS/2. Therefore you have to use - `--disable-nls'. - - * Executables must be linked statically (`a.out' format only). - `make install' does not work. - - These restrictions are due to restrictions in Autoconf 2.13 - and cannot be avoided. They will vanish as soon as `gawk' - moves on to Autoconf 2.5x. Now enter the following commands - at your `sh' prompt: - - $ CC="gcc"; export CC - $ CFLAGS="-O2"; export CFLAGS - $ AWK="awk"; export AWK - $ LD="ld"; export LD - $ LDFLAGS="-Zexe"; export LDFLAGS - $ RANLIB="ranlib"; export RANLIB - $ ac_cv_header_sys_socket_h="yes" - $ export ac_cv_header_sys_socket_h - $ ./configure --prefix=c:/usr --disable-nls - $ make - - 2. Using a special version of Autoconf 2.13 for OS/2 to recreate - `configure'. Not tested. In principle this should work but the - same restrictions apply as in 1, but the environment variables - `CC', `AWK', `LDFLAGS' and `RANLIB' are not necessary. - - 3. Using Autoconf 2.5x to recreate `configure' (2.52f or higher - recommended). Some patches must be applied to `Makefile.am' and - `test/Makefile.am' and `po/Makefile.in.in'. Currently not - supported. - - *Note:* Even if the compiled `gawk.exe' executable contains a DOS -header (`a.out' format), it does _not_ work under DOS. To compile an -executable that runs under DOS, `CPPFLAGS' must be set to -`"-DPIPES_SIMULATED"'. But then some nonstandard extensions of `gawk' -(e.g., `|&') do not work! + The 32 bit EMX version of `gawk' works "out of the box" under OS/2. +In principle, it is possible to compile `gawk' the following way: + + $ ./configure + $ make + + This is not recommended, though. To get an OMF executable you should +use the following commands at your `sh' prompt: + + $ CPPFLAGS="-D__ST_MT_ERRNO__" + $ export CPPFLAGS + $ CFLAGS="-O2 -Zomf -Zmt" + $ export CFLAGS + $ LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack 0x8000" + $ export LDFLAGS + $ RANLIB="echo" + $ export RANLIB + $ ./configure --prefix=c:/usr --without-included-gettext + $ make AR=emxomfar + + These are just suggestions. You may use any other set of +(self-consistent) environment variables and compiler flags. + + To get an FHS-compliant file hierarchy it is recommended to use the +additional `configure' options `--infodir=c:/usr/share/info', +`--mandir=c:/usr/share/man' and `--libexecdir=c:/usr/lib'. + + The internal `gettext' library tends to be problematic. It is +therefore recommended to use either an external one +(`--without-included-gettext') or to disable NLS entirely +(`--disable-nls'). + + If you use GCC 2.95 or newer it is recommended to use also: + + $ LIBS="-lgcc" + $ export LIBS + + You can also get an `a.out' executable if you prefer: + + $ CPPFLAGS="-D__ST_MT_ERRNO__" + $ export CPPFLAGS + $ CFLAGS="-O2 -Zmt" + $ export CFLAGS + $ LDFLAGS="-s -Zstack 0x8000" + $ LIBS="-lgcc" + $ unset RANLIB + $ ./configure --prefix=c:/usr --without-included-gettext + $ make + + *Note:* Even if the compiled `gawk.exe' (`a.out') executable +contains a DOS header, it does _not_ work under DOS. To compile an +executable that runs under DOS, `"-DPIPES_SIMULATED"' must be added to +`CPPFLAGS'. But then some nonstandard extensions of `gawk' (e.g., +`|&') do not work! After compilation the internal tests can be performed. Enter `make check CMP="diff -a"' at your command prompt. All tests but the `pid' -test are expected to work properly. The `pid' test might or might not -work, no idea why. +test are expected to work properly. The `pid' test fails because child +processes are not started by `fork()'. + + `make install' works as expected. *Note:* Most OS/2 ports of GNU `make' are not able to handle the Makefiles of this package. If you encounter any problems with `make' -try GNU `make' 3.79.1. You should find the latest version on -`ftp://ftp.unixos2.org'. +try GNU Make 3.79.1 or later versions. You should find the latest +version on `http://www.unixos2.org/sw/pub/binary/make/' or on +`ftp://hobbes.nmsu.edu/pub/os2/'. File: gawk.info, Node: PC Using, Next: Cygwin, Prev: PC Compiling, Up: PC Installation @@ -17443,8 +17752,8 @@ simulation of Unix, using the GNU tools, such as `bash', the GNU Compiler Collection (GCC), GNU Make, and other GNU tools. Compilation and installation for Cygwin is the same as for a Unix system: - tar -xvpzf gawk-3.1.1.tar.gz - cd gawk-3.1.1 + tar -xvpzf gawk-3.1.2.tar.gz + cd gawk-3.1.2 ./configure make @@ -17864,7 +18173,7 @@ MS-Windows Juan Grigera, <juan@biophnet.unlp.edu.ar>. OS/2 The Unix for OS/2 team, <gawk-maintainer@unixos2.org>. Tandem Stephen Davies, <scldad@sdc.com.au>. -VMS Pat Rankin, <rankin@eql.caltech.edu>. +VMS Pat Rankin, <rankin@pactechdata.com>. If your bug is also reproducible under Unix, please send a copy of your report to the <bug-gawk@gnu.org> email list as well. @@ -17959,7 +18268,17 @@ Unix `awk' under the LGPL. To get `awka', go to `http://awka.sourceforge.net'. You can reach - Andrew Sumner at <andrew_sumner@bigfoot.com>. + Andrew Sumner at <andrew@zbcom.net>. + +`pawk' + Nelson H.F. Beebe at the University of Utah has modified the Bell + Labs `awk' to provide timing and profiling information. It is + different from `pgawk' (*note Profiling Your `awk' Programs: + Profiling.), in that it uses CPU-based profiling, not line-count + profiling. You may find it at either + `ftp://ftp.math.utah.edu/pub/pawk/pawk-20020210.tar.gz' or + `http://www.math.utah.edu/pub/pawk/pawk-20020210.tar.gz'. + ---------- Footnotes ---------- @@ -18056,8 +18375,10 @@ make it possible for me to include your changes: haven't read it, please do so, preferably _before_ starting to modify `gawk'. (The `GNU Coding Standards' are available from the GNU Project's `ftp' site, at - `ftp://ftp.gnu.org/gnu/GNUInfo/standards.text'. Texinfo, Info, - and DVI versions are also available.) + `ftp://ftp.gnu.org/gnu/GNUinfo/standards.text'. An HTML version, + suitable for reading with a WWW browser, is available at + `http://www.gnu.org/prep/standards_toc.html'. Texinfo, Info, and + DVI versions are also available.) 4. Use the `gawk' coding style. The C code for `gawk' follows the instructions in the `GNU Coding Standards', with minor exceptions. @@ -18878,11 +19199,6 @@ Integrating the DBUG library Following is a list of probable improvements that will make `gawk' perform better: -An improved version of `dfa' - The `dfa' pattern matcher from GNU `grep' has some problems. - Either a new version or a fixed one will deal with some important - regexp matching issues. - Compilation of `awk' programs `gawk' uses a Bison (YACC-like) parser to convert the script given it into a syntax tree; the syntax tree is then executed by a @@ -19213,7 +19529,7 @@ noted and can affect comparisons. ---------- Footnotes ---------- - (1) `http://www.validgh.com/goldberg/paper.ps'. + (1) `http://www.validlab.com/goldberg/paper.ps'. (2) Pathological cases can require up to 752 digits (!), but we doubt that you need to worry about this. @@ -20193,24 +20509,22 @@ File: gawk.info, Node: GNU Free Documentation License, Next: Index, Prev: Cop GNU Free Documentation License ****************************** - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Version 1.2, November 2002 + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. - 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. @@ -20226,60 +20540,71 @@ GNU Free Documentation License We recommend this License principally for works whose purpose is instruction or reference. - 1. APPLICABILITY AND DEFINITIONS - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you". + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. - A "Secondary Section" is a named appendix or a front-matter - section of the Document that deals exclusively with the - relationship of the publishers or authors of the Document to the - Document's overall subject (or to related matters) and contains - nothing that could fall directly within that overall subject. - (For example, if the Document is in part a textbook of - mathematics, a Secondary Section may not explain any mathematics.) - The relationship could be a matter of historical connection with - the subject or with related matters, or of legal, commercial, - philosophical, ethical or political position regarding them. + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this - License. + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed - to thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque". + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and - standard-conforming simple HTML designed for human modification. - Opaque formats include PostScript, PDF, proprietary formats that - can be read and edited only by proprietary word processors, SGML - or XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML produced by some word - processors for output purposes only. + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the @@ -20288,6 +20613,22 @@ GNU Free Documentation License Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either @@ -20306,10 +20647,11 @@ GNU Free Documentation License 3. COPYING IN QUANTITY - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the @@ -20327,11 +20669,10 @@ GNU Free Documentation License If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. If you use the + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated @@ -20365,7 +20706,8 @@ GNU Free Documentation License entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal - authors, if it has less than five). + authors, if it has fewer than five), unless they release you + from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. @@ -20386,10 +20728,10 @@ GNU Free Documentation License H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and - add to it an item stating at least the title, year, new + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on - the Title Page. If there is no section entitled "History" in + the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in @@ -20404,9 +20746,9 @@ GNU Free Documentation License Document itself, or if the original publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all - the substance and tone of each of the contributor + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, @@ -20414,11 +20756,14 @@ GNU Free Documentation License or the equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements". Such a section + M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no @@ -20428,11 +20773,11 @@ GNU Free Documentation License Version's license notice. These titles must be distinct from any other section titles. - You may add a section entitled "Endorsements", provided it contains + You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition - of a standard. + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end @@ -20456,7 +20801,8 @@ GNU Free Documentation License modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your - combined work in its license notice. + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -20468,11 +20814,11 @@ GNU Free Documentation License the list of Invariant Sections in the license notice of the combined work. - In the combination, you must combine any sections entitled + In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications". You - must delete all sections entitled "Endorsements." + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS @@ -20493,20 +20839,20 @@ GNU Free Documentation License A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of - a storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they are not themselves - derivative works of the Document. + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. 8. TRANSLATION @@ -20516,10 +20862,18 @@ GNU Free Documentation License permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. + translation of this License, and all the license notices in the + Document, and any Warrany Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. 9. TERMINATION @@ -20549,7 +20903,6 @@ GNU Free Documentation License you may choose any version ever published (not as a draft) by the Free Software Foundation. - ADDENDUM: How to use this License for your documents ==================================================== @@ -20557,19 +20910,24 @@ ADDENDUM: How to use this License for your documents the License in the document and put the following copyright and license notices just after the title page: - Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. -If you have no Invariant Sections, write "with no Invariant -Sections" instead of saying which ones are invariant. If you have no -Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover -Texts being LIST"; likewise for Back-Cover Texts. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of @@ -20652,6 +21010,7 @@ Index * --compat option: Options. * --copyleft option: Options. * --copyright option: Options. +* --disable-lint configuration option: Additional Configuration Options. * --disable-nls configuration option: Additional Configuration Options. * --dump-variables option <1>: Library Names. * --dump-variables option: Options. @@ -20868,6 +21227,7 @@ Index * asort function (gawk) <1>: String Functions. * asort function (gawk): Array Sorting. * asort function (gawk), arrays, sorting: Array Sorting. +* asorti function (gawk): String Functions. * assert function (C library): Assert Function. * assert user-defined function: Assert Function. * assertions: Assert Function. @@ -20982,6 +21342,7 @@ Index * backslash (\), regexp constants: Computed Regexps. * BBS-list file: Sample Data Files. * Beebe, Nelson: Acknowledgments. +* Beebe, Nelson H.F.: Other Versions. * BEGIN pattern <1>: BEGIN/END. * BEGIN pattern <2>: Field Separators. * BEGIN pattern: Records. @@ -21133,6 +21494,7 @@ Index * compound statements, control statements and: Statements. * concatenating: Concatenation. * conditional expressions: Conditional Exp. +* configuration option, --disable-lint: Additional Configuration Options. * configuration option, --disable-nls: Additional Configuration Options. * configuration option, --enable-portals: Additional Configuration Options. * configuration option, --with-included-gettext <1>: Additional Configuration Options. @@ -22027,6 +22389,7 @@ Index * patterns, ranges in: Ranges. * patterns, regexp constants as: Expression Patterns. * patterns, types of: Pattern Overview. +* pawk profiling Bell Labs awk: Other Versions. * PC operating systems, gawk on: PC Using. * PC operating systems, gawk on, installing: PC Installation. * percent sign (%), % operator: Precedence. @@ -22308,8 +22671,7 @@ Index * searching, files for regular expressions: Egrep Program. * searching, for words: Dupword Program. * sed utility <1>: Glossary. -* sed utility <2>: Igawk Program. -* sed utility <3>: Simple Sed. +* sed utility <2>: Simple Sed. * sed utility: Field Splitting Summary. * semicolon (;): Statements/Lines. * semicolon (;), AWKPATH variable and: PC Using. @@ -22393,8 +22755,7 @@ Index * statements, multiple: Statements/Lines. * stlen internal variable: Internals. * stptr internal variable: Internals. -* stream editors <1>: Igawk Program. -* stream editors <2>: Simple Sed. +* stream editors <1>: Simple Sed. * stream editors: Field Splitting Summary. * strftime function (gawk): Time Functions. * string constants: Scalar Constants. @@ -22622,339 +22983,344 @@ Index Tag Table: -Node: Top353 -Node: Foreword26454 -Node: Preface30778 -Ref: Preface-Footnote-133660 -Node: History33892 -Node: Names36151 -Ref: Names-Footnote-137660 -Node: This Manual37732 -Ref: This Manual-Footnote-142925 -Node: Conventions43025 -Node: Manual History44902 -Ref: Manual History-Footnote-148588 -Ref: Manual History-Footnote-248629 -Node: How To Contribute48703 -Node: Acknowledgments49301 -Node: Getting Started53106 -Node: Running gawk55499 -Node: One-shot56704 -Node: Read Terminal57961 -Ref: Read Terminal-Footnote-159610 -Node: Long59781 -Node: Executable Scripts61182 -Ref: Executable Scripts-Footnote-162918 -Ref: Executable Scripts-Footnote-263069 -Node: Comments63520 -Node: Quoting65912 -Node: Sample Data Files69890 -Node: Very Simple72968 -Node: Two Rules77588 -Node: More Complex79787 -Ref: More Complex-Footnote-182710 -Ref: More Complex-Footnote-283186 -Node: Statements/Lines83269 -Ref: Statements/Lines-Footnote-187628 -Node: Other Features87937 -Node: When88802 -Node: Regexp90791 -Node: Regexp Usage92181 -Node: Escape Sequences94272 -Node: Regexp Operators100184 -Ref: Regexp Operators-Footnote-1107325 -Ref: Regexp Operators-Footnote-2107472 -Node: Character Lists107570 -Node: GNU Regexp Operators112039 -Node: Case-sensitivity115534 -Ref: Case-sensitivity-Footnote-1118659 -Node: Leftmost Longest118894 -Node: Computed Regexps120208 -Node: Reading Files123599 -Node: Records125385 -Ref: Records-Footnote-1133263 -Node: Fields133300 -Ref: Fields-Footnote-1136355 -Node: Nonconstant Fields136441 -Node: Changing Fields138693 -Node: Field Separators143403 -Node: Regexp Field Splitting146947 -Node: Single Character Fields149448 -Node: Command Line Field Separator150511 -Node: Field Splitting Summary153962 -Ref: Field Splitting Summary-Footnote-1156065 -Node: Constant Size156166 -Node: Multiple Line160740 -Node: Getline166171 -Node: Plain Getline168234 -Node: Getline/Variable170284 -Node: Getline/File171416 -Node: Getline/Variable/File172841 -Node: Getline/Pipe174464 -Node: Getline/Variable/Pipe176671 -Node: Getline/Coprocess177887 -Node: Getline/Variable/Coprocess179161 -Node: Getline Notes179909 -Node: Getline Summary181258 -Node: Printing181965 -Node: Print183679 -Node: Print Examples185060 -Node: Output Separators187957 -Node: OFMT189773 -Node: Printf191175 -Node: Basic Printf192089 -Node: Control Letters193673 -Node: Format Modifiers196260 -Node: Printf Examples201312 -Node: Redirection204082 -Node: Special Files210806 -Node: Special FD211435 -Node: Special Process214474 -Node: Special Network216760 -Node: Special Caveats217675 -Ref: Special Caveats-Footnote-1218885 -Node: Close Files And Pipes219268 -Ref: Close Files And Pipes-Footnote-1226450 -Node: Expressions226598 -Node: Constants228786 -Node: Scalar Constants229482 -Ref: Scalar Constants-Footnote-1230346 -Node: Nondecimal-numbers230528 -Node: Regexp Constants233704 -Node: Using Constant Regexps234168 -Node: Variables237328 -Node: Using Variables237979 -Node: Assignment Options239520 -Node: Conversion241460 -Ref: Conversion-Footnote-1244691 -Node: Arithmetic Ops244800 -Node: Concatenation247297 -Node: Assignment Ops249992 -Node: Increment Ops256308 -Node: Truth Values259796 -Node: Typing and Comparison260841 -Ref: Typing and Comparison-Footnote-1267395 -Node: Boolean Ops267540 -Node: Conditional Exp271648 -Node: Function Calls273444 -Node: Precedence276417 -Node: Patterns and Actions279861 -Node: Pattern Overview280914 -Node: Regexp Patterns282527 -Node: Expression Patterns283086 -Node: Ranges286692 -Node: BEGIN/END289793 -Node: Using BEGIN/END290533 -Ref: Using BEGIN/END-Footnote-1293318 -Node: I/O And BEGIN/END293432 -Node: Empty295771 -Node: Using Shell Variables296070 -Node: Action Overview298430 -Node: Statements300996 -Node: If Statement302702 -Node: While Statement304211 -Node: Do Statement306234 -Node: For Statement307374 -Node: Break Statement310562 -Node: Continue Statement312666 -Node: Next Statement314605 -Node: Nextfile Statement316994 -Node: Exit Statement319748 -Node: Built-in Variables321857 -Node: User-modified322947 -Ref: User-modified-Footnote-1330533 -Node: Auto-set330595 -Ref: Auto-set-Footnote-1338618 -Node: ARGC and ARGV338823 -Node: Arrays342685 -Node: Array Intro344615 -Node: Reference to Elements348885 -Node: Assigning Elements350770 -Node: Array Example351232 -Node: Scanning an Array352955 -Node: Delete355279 -Ref: Delete-Footnote-1357729 -Node: Numeric Array Subscripts357786 -Node: Uninitialized Subscripts360065 -Node: Multi-dimensional361687 -Node: Multi-scanning364734 -Node: Array Sorting366406 -Node: Functions369220 -Node: Built-in369954 -Node: Calling Built-in370937 -Node: Numeric Functions372912 -Ref: Numeric Functions-Footnote-1376652 -Ref: Numeric Functions-Footnote-2376978 -Node: String Functions377247 -Ref: String Functions-Footnote-1393843 -Ref: String Functions-Footnote-2394002 -Node: Gory Details394089 -Ref: Gory Details-Footnote-1400676 -Ref: Gory Details-Footnote-2400727 -Node: I/O Functions400934 -Ref: I/O Functions-Footnote-1407611 -Node: Time Functions407702 -Ref: Time Functions-Footnote-1418476 -Ref: Time Functions-Footnote-2418544 -Ref: Time Functions-Footnote-3418702 -Ref: Time Functions-Footnote-4418813 -Ref: Time Functions-Footnote-5418938 -Ref: Time Functions-Footnote-6419197 -Node: Bitwise Functions419459 -Ref: Bitwise Functions-Footnote-1424157 -Node: I18N Functions424341 -Node: User-defined426085 -Node: Definition Syntax426861 -Node: Function Example431253 -Node: Function Caveats433894 -Node: Return Statement437794 -Node: Dynamic Typing440452 -Node: Internationalization441190 -Node: I18N and L10N442608 -Node: Explaining gettext443317 -Ref: Explaining gettext-Footnote-1448253 -Ref: Explaining gettext-Footnote-2448492 -Node: Programmer i18n448661 -Node: Translator i18n453007 -Node: String Extraction453792 -Ref: String Extraction-Footnote-1454794 -Node: Printf Ordering454920 -Ref: Printf Ordering-Footnote-1457711 -Node: I18N Portability457775 -Ref: I18N Portability-Footnote-1460213 -Node: I18N Example460276 -Ref: I18N Example-Footnote-1462913 -Node: Gawk I18N462985 -Node: Advanced Features463807 -Node: Nondecimal Data465239 -Node: Two-way I/O466846 -Ref: Two-way I/O-Footnote-1471508 -Node: TCP/IP Networking471585 -Node: Portal Files474048 -Node: Profiling474711 -Node: Invoking Gawk482337 -Node: Command Line483514 -Node: Options484314 -Ref: Options-Footnote-1496204 -Node: Other Arguments496229 -Node: AWKPATH Variable498981 -Ref: AWKPATH Variable-Footnote-1501764 -Node: Obsolete502024 -Node: Undocumented503105 -Node: Known Bugs503357 -Node: Library Functions503976 -Ref: Library Functions-Footnote-1507160 -Node: Library Names507331 -Ref: Library Names-Footnote-1510940 -Ref: Library Names-Footnote-2511159 -Node: General Functions511245 -Node: Nextfile Function512181 -Node: Assert Function516646 -Node: Round Function519977 -Node: Cliff Random Function521536 -Ref: Cliff Random Function-Footnote-1522519 -Node: Ordinal Functions522590 -Ref: Ordinal Functions-Footnote-1525664 -Node: Join Function525880 -Ref: Join Function-Footnote-1527684 -Node: Gettimeofday Function527884 -Node: Data File Management531662 -Node: Filetrans Function532223 -Node: Rewind Function535774 -Node: File Checking537398 -Node: Ignoring Assigns538444 -Node: Getopt Function540028 -Ref: Getopt Function-Footnote-1551177 -Node: Passwd Functions551378 -Ref: Passwd Functions-Footnote-1560100 -Node: Group Functions560188 -Node: Sample Programs568287 -Node: Running Examples569017 -Node: Clones569788 -Node: Cut Program570913 -Node: Egrep Program580778 -Ref: Egrep Program-Footnote-1588643 -Node: Id Program588753 -Node: Split Program592438 -Node: Tee Program595947 -Node: Uniq Program598618 -Node: Wc Program606128 -Ref: Wc Program-Footnote-1610442 -Node: Miscellaneous Programs610664 -Node: Dupword Program611653 -Node: Alarm Program613704 -Node: Translate Program618328 -Ref: Translate Program-Footnote-1622644 -Ref: Translate Program-Footnote-2622881 -Node: Labels Program623015 -Ref: Labels Program-Footnote-1626372 -Node: Word Sorting626456 -Node: History Sorting630759 -Node: Extract Program632628 -Node: Simple Sed640210 -Node: Igawk Program643407 -Ref: Igawk Program-Footnote-1656434 -Node: Language History656572 -Node: V7/SVR3.1657939 -Node: SVR4660534 -Node: POSIX662181 -Node: BTL663969 -Node: POSIX/GNU665786 -Node: Contributors674410 -Node: Installation677662 -Node: Gawk Distribution678641 -Node: Getting679141 -Node: Extracting680387 -Node: Distribution contents681766 -Node: Unix Installation687363 -Node: Quick Installation687949 -Node: Additional Configuration Options689696 -Node: Configuration Philosophy690791 -Node: Non-Unix Installation693174 -Node: Amiga Installation693756 -Node: BeOS Installation694901 -Node: PC Installation696073 -Node: PC Binary Installation697206 -Node: PC Compiling699060 -Node: PC Using703514 -Node: Cygwin708232 -Ref: Cygwin-Footnote-1709245 -Node: VMS Installation709277 -Node: VMS Compilation709796 -Node: VMS Installation Details711385 -Node: VMS Running713002 -Node: VMS POSIX714586 -Node: Unsupported715850 -Node: Atari Installation716248 -Node: Atari Compiling717569 -Node: Atari Using719498 -Node: Tandem Installation722362 -Node: Bugs724168 -Node: Other Versions727453 -Ref: Other Versions-Footnote-1731039 -Node: Notes731081 -Node: Compatibility Mode731754 -Node: Additions732596 -Node: Adding Code733368 -Node: New Ports739410 -Node: Dynamic Extensions743513 -Node: Internals744529 -Node: Sample Library750865 -Node: Internal File Description751515 -Node: Internal File Ops755267 -Ref: Internal File Ops-Footnote-1760683 -Node: Using Internal File Ops760831 -Node: Future Extensions762852 -Node: Basic Concepts767195 -Node: Basic High Level767933 -Ref: Basic High Level-Footnote-1772094 -Node: Basic Data Typing772288 -Node: Floating Point Issues776778 -Ref: Floating Point Issues-Footnote-1780701 -Ref: Floating Point Issues-Footnote-2780753 -Node: Glossary780862 -Node: Copying805171 -Node: GNU Free Documentation License824368 -Node: Index844250 +Node: Top1322 +Node: Foreword26566 +Node: Preface30890 +Ref: Preface-Footnote-133772 +Node: History34004 +Node: Names36263 +Ref: Names-Footnote-137772 +Node: This Manual37844 +Ref: This Manual-Footnote-143037 +Node: Conventions43137 +Node: Manual History45014 +Ref: Manual History-Footnote-148700 +Ref: Manual History-Footnote-248741 +Node: How To Contribute48815 +Node: Acknowledgments49413 +Node: Getting Started53218 +Node: Running gawk55611 +Node: One-shot56816 +Node: Read Terminal58073 +Ref: Read Terminal-Footnote-159722 +Node: Long59893 +Node: Executable Scripts61294 +Ref: Executable Scripts-Footnote-163190 +Ref: Executable Scripts-Footnote-263341 +Node: Comments63792 +Node: Quoting66184 +Node: Sample Data Files70162 +Node: Very Simple73240 +Node: Two Rules77860 +Node: More Complex80059 +Ref: More Complex-Footnote-182981 +Ref: More Complex-Footnote-283457 +Node: Statements/Lines83540 +Ref: Statements/Lines-Footnote-187899 +Node: Other Features88208 +Node: When89073 +Node: Regexp91062 +Node: Regexp Usage92515 +Node: Escape Sequences94606 +Node: Regexp Operators100518 +Ref: Regexp Operators-Footnote-1107710 +Ref: Regexp Operators-Footnote-2107857 +Node: Character Lists107955 +Node: GNU Regexp Operators112424 +Node: Case-sensitivity116045 +Ref: Case-sensitivity-Footnote-1119170 +Node: Leftmost Longest119405 +Node: Computed Regexps120719 +Node: Locales124126 +Node: Reading Files125575 +Node: Records127361 +Ref: Records-Footnote-1135677 +Node: Fields135714 +Ref: Fields-Footnote-1138769 +Node: Nonconstant Fields138855 +Node: Changing Fields141107 +Node: Field Separators146549 +Node: Regexp Field Splitting150093 +Node: Single Character Fields152594 +Node: Command Line Field Separator153657 +Node: Field Splitting Summary157108 +Ref: Field Splitting Summary-Footnote-1160331 +Node: Constant Size160432 +Node: Multiple Line165006 +Ref: Multiple Line-Footnote-1170787 +Node: Getline170966 +Node: Plain Getline173029 +Node: Getline/Variable175079 +Node: Getline/File176211 +Node: Getline/Variable/File177636 +Node: Getline/Pipe179259 +Node: Getline/Variable/Pipe181466 +Node: Getline/Coprocess182682 +Node: Getline/Variable/Coprocess183956 +Node: Getline Notes184704 +Node: Getline Summary186429 +Node: Printing187136 +Node: Print188850 +Node: Print Examples190231 +Node: Output Separators193128 +Node: OFMT194944 +Node: Printf196346 +Node: Basic Printf197260 +Node: Control Letters198844 +Node: Format Modifiers201431 +Node: Printf Examples206483 +Node: Redirection209253 +Node: Special Files215977 +Node: Special FD216606 +Node: Special Process219645 +Node: Special Network221931 +Node: Special Caveats222846 +Ref: Special Caveats-Footnote-1224056 +Node: Close Files And Pipes224439 +Ref: Close Files And Pipes-Footnote-1231853 +Ref: Close Files And Pipes-Footnote-2232001 +Node: Expressions232149 +Node: Constants234337 +Node: Scalar Constants235033 +Ref: Scalar Constants-Footnote-1235897 +Node: Nondecimal-numbers236079 +Node: Regexp Constants239255 +Node: Using Constant Regexps239719 +Node: Variables242879 +Node: Using Variables243530 +Node: Assignment Options245071 +Node: Conversion247011 +Ref: Conversion-Footnote-1250242 +Node: Arithmetic Ops250351 +Node: Concatenation252848 +Node: Assignment Ops255543 +Node: Increment Ops261859 +Node: Truth Values265347 +Node: Typing and Comparison266392 +Ref: Typing and Comparison-Footnote-1272946 +Node: Boolean Ops273091 +Node: Conditional Exp277199 +Node: Function Calls278995 +Node: Precedence281968 +Node: Patterns and Actions285412 +Node: Pattern Overview286465 +Node: Regexp Patterns288078 +Node: Expression Patterns288637 +Node: Ranges292243 +Node: BEGIN/END295344 +Node: Using BEGIN/END296084 +Ref: Using BEGIN/END-Footnote-1298869 +Node: I/O And BEGIN/END298983 +Node: Empty301322 +Node: Using Shell Variables301621 +Node: Action Overview303981 +Node: Statements306547 +Node: If Statement308253 +Node: While Statement309762 +Node: Do Statement311785 +Node: For Statement312925 +Node: Break Statement316113 +Node: Continue Statement318217 +Node: Next Statement320156 +Node: Nextfile Statement322545 +Node: Exit Statement325299 +Node: Built-in Variables327408 +Node: User-modified328498 +Ref: User-modified-Footnote-1336321 +Node: Auto-set336383 +Ref: Auto-set-Footnote-1344724 +Node: ARGC and ARGV344929 +Node: Arrays348791 +Node: Array Intro350721 +Node: Reference to Elements354991 +Node: Assigning Elements356876 +Node: Array Example357338 +Node: Scanning an Array359061 +Node: Delete361385 +Ref: Delete-Footnote-1363835 +Node: Numeric Array Subscripts363892 +Node: Uninitialized Subscripts366171 +Node: Multi-dimensional367793 +Node: Multi-scanning370840 +Node: Array Sorting372512 +Node: Functions375934 +Node: Built-in376668 +Node: Calling Built-in377651 +Node: Numeric Functions379626 +Ref: Numeric Functions-Footnote-1383366 +Ref: Numeric Functions-Footnote-2383692 +Node: String Functions383961 +Ref: String Functions-Footnote-1403266 +Ref: String Functions-Footnote-2403425 +Ref: String Functions-Footnote-3403672 +Node: Gory Details403759 +Ref: Gory Details-Footnote-1410346 +Ref: Gory Details-Footnote-2410397 +Node: I/O Functions410604 +Ref: I/O Functions-Footnote-1417281 +Node: Time Functions417372 +Ref: Time Functions-Footnote-1428146 +Ref: Time Functions-Footnote-2428214 +Ref: Time Functions-Footnote-3428372 +Ref: Time Functions-Footnote-4428483 +Ref: Time Functions-Footnote-5428608 +Ref: Time Functions-Footnote-6428867 +Node: Bitwise Functions429129 +Ref: Bitwise Functions-Footnote-1433827 +Node: I18N Functions434011 +Node: User-defined435755 +Node: Definition Syntax436531 +Node: Function Example440923 +Node: Function Caveats443564 +Node: Return Statement447464 +Node: Dynamic Typing450122 +Node: Internationalization450860 +Node: I18N and L10N452278 +Node: Explaining gettext452987 +Ref: Explaining gettext-Footnote-1457923 +Ref: Explaining gettext-Footnote-2458162 +Node: Programmer i18n458331 +Node: Translator i18n462677 +Node: String Extraction463462 +Ref: String Extraction-Footnote-1464464 +Node: Printf Ordering464590 +Ref: Printf Ordering-Footnote-1467381 +Node: I18N Portability467445 +Ref: I18N Portability-Footnote-1469883 +Node: I18N Example469946 +Ref: I18N Example-Footnote-1472583 +Node: Gawk I18N472655 +Node: Advanced Features473477 +Node: Nondecimal Data474909 +Node: Two-way I/O476516 +Ref: Two-way I/O-Footnote-1482093 +Node: TCP/IP Networking482170 +Node: Portal Files484633 +Node: Profiling485296 +Node: Invoking Gawk492922 +Node: Command Line494099 +Node: Options494899 +Ref: Options-Footnote-1506946 +Node: Other Arguments506971 +Node: AWKPATH Variable509723 +Ref: AWKPATH Variable-Footnote-1512506 +Node: Obsolete512766 +Node: Undocumented513847 +Node: Known Bugs514099 +Node: Library Functions514718 +Ref: Library Functions-Footnote-1517902 +Node: Library Names518073 +Ref: Library Names-Footnote-1521682 +Ref: Library Names-Footnote-2521901 +Node: General Functions521987 +Node: Nextfile Function522923 +Node: Assert Function527388 +Node: Round Function530719 +Node: Cliff Random Function532278 +Ref: Cliff Random Function-Footnote-1533261 +Node: Ordinal Functions533332 +Ref: Ordinal Functions-Footnote-1536406 +Node: Join Function536622 +Ref: Join Function-Footnote-1538426 +Node: Gettimeofday Function538626 +Node: Data File Management542404 +Node: Filetrans Function542965 +Node: Rewind Function546516 +Node: File Checking548140 +Node: Ignoring Assigns549186 +Node: Getopt Function550770 +Ref: Getopt Function-Footnote-1561919 +Node: Passwd Functions562120 +Ref: Passwd Functions-Footnote-1570859 +Node: Group Functions570947 +Node: Sample Programs579048 +Node: Running Examples579778 +Node: Clones580549 +Node: Cut Program581674 +Node: Egrep Program591539 +Ref: Egrep Program-Footnote-1599404 +Node: Id Program599514 +Node: Split Program603199 +Node: Tee Program606708 +Node: Uniq Program609379 +Node: Wc Program616889 +Ref: Wc Program-Footnote-1621203 +Node: Miscellaneous Programs621425 +Node: Dupword Program622414 +Node: Alarm Program624465 +Node: Translate Program629089 +Ref: Translate Program-Footnote-1633405 +Ref: Translate Program-Footnote-2633642 +Node: Labels Program633776 +Ref: Labels Program-Footnote-1637133 +Node: Word Sorting637217 +Node: History Sorting641520 +Node: Extract Program643389 +Node: Simple Sed650971 +Node: Igawk Program654168 +Ref: Igawk Program-Footnote-1669060 +Ref: Igawk Program-Footnote-2669261 +Node: Language History669399 +Node: V7/SVR3.1670766 +Node: SVR4673361 +Node: POSIX675008 +Node: BTL676796 +Node: POSIX/GNU678613 +Node: Contributors687441 +Node: Installation690693 +Node: Gawk Distribution691672 +Node: Getting692172 +Node: Extracting693418 +Node: Distribution contents694797 +Node: Unix Installation700394 +Node: Quick Installation700980 +Node: Additional Configuration Options702727 +Node: Configuration Philosophy704634 +Node: Non-Unix Installation707017 +Node: Amiga Installation707599 +Node: BeOS Installation708744 +Node: PC Installation709916 +Node: PC Binary Installation711049 +Node: PC Compiling712903 +Node: PC Using717416 +Node: Cygwin722134 +Ref: Cygwin-Footnote-1723147 +Node: VMS Installation723179 +Node: VMS Compilation723698 +Node: VMS Installation Details725287 +Node: VMS Running726904 +Node: VMS POSIX728488 +Node: Unsupported729752 +Node: Atari Installation730150 +Node: Atari Compiling731471 +Node: Atari Using733400 +Node: Tandem Installation736264 +Node: Bugs738070 +Node: Other Versions741355 +Ref: Other Versions-Footnote-1745386 +Node: Notes745428 +Node: Compatibility Mode746101 +Node: Additions746943 +Node: Adding Code747715 +Node: New Ports753888 +Node: Dynamic Extensions757991 +Node: Internals759007 +Node: Sample Library765343 +Node: Internal File Description765993 +Node: Internal File Ops769745 +Ref: Internal File Ops-Footnote-1775161 +Node: Using Internal File Ops775309 +Node: Future Extensions777330 +Node: Basic Concepts781477 +Node: Basic High Level782215 +Ref: Basic High Level-Footnote-1786376 +Node: Basic Data Typing786570 +Node: Floating Point Issues791060 +Ref: Floating Point Issues-Footnote-1794983 +Ref: Floating Point Issues-Footnote-2795036 +Node: Glossary795145 +Node: Copying819454 +Node: GNU Free Documentation License838651 +Node: Index861054 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index e5f50413..108b3320 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -4,13 +4,13 @@ @settitle The GNU Awk User's Guide @c %**end of header (This is for running Texinfo on a region.) -@dircategory GNU Packages +@dircategory Text creation and manipulation @direntry -* Gawk: (gawk). A text scanning and processing language. +* Gawk: (gawk). A text scanning and processing language. @end direntry @dircategory Individual utilities @direntry -* awk: (gawk)Invoking gawk. Text scanning and processing. +* awk: (gawk)Invoking gawk. Text scanning and processing. @end direntry @c @set xref-automatic-section-title @@ -20,9 +20,9 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH April, 2002 +@set UPDATE-MONTH February, 2003 @set VERSION 3.1 -@set PATCHLEVEL 1 +@set PATCHLEVEL 2 @set FSF @@ -54,6 +54,14 @@ @set SUBSECTION subsection @set DARKCORNER (d.c.) @end ifhtml +@ifxml +@set DOCUMENT book +@set CHAPTER chapter +@set APPENDIX appendix +@set SECTION section +@set SUBSECTION subsection +@set DARKCORNER (d.c.) +@end ifxml @c some special symbols @iftex @@ -87,6 +95,10 @@ Some comments on the layout for TeX. @syncodeindex fn cp @syncodeindex vr cp @end iftex +@ifxml +@syncodeindex fn cp +@syncodeindex vr cp +@end ifxml @c If "finalout" is commented out, the printed output will show @c black boxes that mark lines that are too long. Thus, it is @@ -98,7 +110,7 @@ Some comments on the layout for TeX. @end iftex @copying -Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1991, 1992, 1993, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @sp 2 This is Edition @value{EDITION} of @cite{@value{TITLE}: @value{SUBTITLE}}, @@ -106,7 +118,7 @@ for the @value{VERSION}.@value{PATCHLEVEL} (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'', the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -219,6 +231,7 @@ Cover art by Etienne Suvasa. @end iftex @ifnottex +@ifnotxml @node Top, Foreword, (dir), (dir) @top General Introduction @c Preface node should come right after the Top @@ -230,6 +243,7 @@ particular records in a file and perform operations upon them. @insertcopying +@end ifnotxml @end ifnottex @menu @@ -319,6 +333,7 @@ particular records in a file and perform operations upon them. * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. * Records:: Controlling how data is split into records. * Fields:: An introduction to fields. * Nonconstant Fields:: Nonconstant Field Numbers. @@ -1099,13 +1114,13 @@ This @value{DOCUMENT} is written using Texinfo, the GNU documentation formatting language. A single Texinfo source file is used to produce both the printed and online versions of the documentation. -@iftex +@ifnotinfo Because of this, the typographical conventions are slightly different than in other books you may have read. -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo This @value{SECTION} briefly documents the typographical conventions used in Texinfo. -@end ifnottex +@end ifinfo Examples you would type at the command-line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. @@ -1121,7 +1136,7 @@ $ echo hello on stderr 1>&2 @error{} hello on stderr @end example -@iftex +@ifnotinfo In the text, command names appear in @code{this font}, while code segments appear in the same font and quoted, @samp{like this}. Some things are emphasized @emph{like this}, and if a point needs to be made @@ -1129,7 +1144,7 @@ strongly, it is done @strong{like this}. The first occurrence of a new term is usually its @dfn{definition} and appears in the same font as the previous occurrence of ``definition'' in this sentence. @value{FN}s are indicated like this: @file{/path/to/ourfile}. -@end iftex +@end ifnotinfo Characters that you type at the keyboard look @kbd{like this}. In particular, there are special characters called ``control characters.'' These are @@ -1844,6 +1859,10 @@ $ advice @end example @noindent +(We assume you have the current directory in your shell's search +path variable (typically @code{$PATH}). If not, you may need +to type @samp{./advice} at the shell.) + Self-contained @command{awk} scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in @command{awk}. @@ -2453,7 +2472,7 @@ are automatically initialized to zero.) After the last line of output from @command{ls} has been processed, the @code{END} rule executes and prints the value of @code{sum}. -In this example, the value of @code{sum} is 140963. +In this example, the value of @code{sum} is 80600. These more advanced @command{awk} techniques are covered in later sections (@pxref{Action Overview, ,Actions}). Before you can move on to more @@ -2699,6 +2718,7 @@ regular expressions work, we will present more complicated instances. * Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* Locales:: How the locale affects things. @end menu @node Regexp Usage, Escape Sequences, Regexp, Regexp @@ -3124,7 +3144,8 @@ arithmetic. They can be used to concatenate regular expressions containing the alternation operator, @samp{|}. For example, @samp{@@(samp|code)\@{[^@}]+\@}} matches both @samp{@@code@{foo@}} and @samp{@@samp@{bar@}}. -(These are Texinfo formatting control sequences.) +(These are Texinfo formatting control sequences. The @samp{+} is +explained further on in this list.) @cindex @code{*} (asterisk), @code{*} operator, as regexp operator @cindex asterisk (@code{*}), @code{*} operator, as regexp operator @@ -3556,7 +3577,9 @@ treated literally, even if they represent regexp metacharacters. @item @code{--re-interval} Allow interval expressions in regexps, even if @option{--traditional} -has been provided. +has been provided. (@option{--posix} automatically enables +interval expressions, so @option{--re-interval} is redundant +when @option{--posix} is is used.) @end table @c ENDOFRANGE gregexp @c ENDOFRANGE regexpg @@ -3698,7 +3721,7 @@ Understanding this principle is also important for regexp-based record and field splitting (@pxref{Records, ,How Input Is Split into Records}, and also @pxref{Field Separators, ,Specifying How Fields Are Separated}). -@node Computed Regexps, , Leftmost Longest, Regexp +@node Computed Regexps, Locales, Leftmost Longest, Regexp @section Using Dynamic Regexps @c STARTOFRANGE dregexp @@ -3814,6 +3837,46 @@ occur often in practice, but it's worth noting for future reference. @c ENDOFRANGE regexpd @c ENDOFRANGE regexp +@node Locales, , Computed Regexps, Regexp +@section Where You Are Makes A Difference + +Modern systems support the notion of @dfn{locales}: a way to tell +the system about the local character set and language. The current +locale setting can affect the way regexp matching works, often +in surprising ways. In particular, many locales do case-insensitive +matching, even when you may have specified characters of only +one particular case. + +The following example uses the @code{sub} function, which +does text replacement +(@pxref{String Functions, , String-Manipulation Functions}). +Here, the intent is to remove trailing uppercase characters: + +@example +$ echo something1234abc | gawk '@{ sub("[A-Z]*$", ""); print @}' +@print{} something1234 +@end example + +@noindent +This output is unexpected, since the @samp{abc} at the end of @samp{something1234abc} +should not normally match @samp{[A-Z]*}. This result is due to the +locale setting (and thus you may not see it on your system). +There are two fixes. The first is to use the POSIX character +class @samp{[[:upper:]]}, instead of @samp{[A-Z]}. +The second is to change the locale setting in the environment, +before running @command{gawk}, +by using the shell statements: + +@example +LANG=C LC_ALL=C +export LANG LC_ALL +@end example + +The setting @samp{C} forces @command{gawk} to behave in the traditional +Unix manner, where case distinctions do matter. +You may wish to put these statements into your shell startup file, +e.g., @file{$HOME/.profile}. + @node Reading Files, Printing, Regexp, Top @chapter Reading Input Files @@ -4057,6 +4120,14 @@ supplies its own terminating newline. @xref{Simple Sed, ,A Simple Stream Editor}, for a more useful example of @code{RS} as a regexp and @code{RT}. +If you set @code{RS} to a regular expression that allows optional +trailing text, such as @samp{RS = "abc(XYZ)?"} it is possible, due +to implementation constraints, that @command{gawk} may match the leading +part of the regular expression, but not the trailing part, particularly +if the input text that could match the trailing part is fairly long. +@command{gawk} attempts to avoid this problem, but currently, there's +no guarantee that this will never happen. + @cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables The use of @code{RS} as a regular expression and the @code{RT} variable are @command{gawk} extensions; they are not available in @@ -4258,6 +4329,7 @@ evaluating @code{NF} and using its value as a field number. @node Changing Fields, Field Separators, Nonconstant Fields, Reading Files @section Changing the Contents of a Field +@c STARTOFRANGE ficon @cindex fields, changing contents of The contents of a field, as seen by @command{awk}, can be changed within an @command{awk} program; this changes what @command{awk} perceives as the @@ -4268,9 +4340,9 @@ Consider the following example and its output: @example $ awk '@{ nboxes = $3 ; $3 = $3 - 10 > print nboxes, $3 @}' inventory-shipped -@print{} 13 3 -@print{} 15 5 -@print{} 15 5 +@print{} 25 15 +@print{} 32 22 +@print{} 24 14 @dots{} @end example @@ -4284,7 +4356,7 @@ Then it prints the original and new values for field three. (Someone in the warehouse made a consistent mistake while inventorying the red boxes.) -For this to work, the text in field @code{$2} must make sense +For this to work, the text in field @code{$3} must make sense as a number; the string of characters must be converted to a number for the computer to do arithmetic on it. The number resulting from the subtraction is converted back to a string of characters that @@ -4337,11 +4409,11 @@ existing fields. @cindex field separators, See Also @code{OFS} This recomputation affects and is affected by @code{NF} (the number of fields; @pxref{Fields, ,Examining Fields}). -It is also affected by a feature that has not been discussed yet: -the @dfn{output field separator}, @code{OFS}, -used to separate the fields (@pxref{Output Separators}). For example, the value of @code{NF} is set to the number of the highest field you create. +The exact format of @code{$0} is also affected by a feature that has not been discussed yet: +the @dfn{output field separator}, @code{OFS}, +used to separate the fields (@pxref{Output Separators}). Note, however, that merely @emph{referencing} an out-of-range field does @emph{not} change the value of either @code{$0} or @code{NF}. @@ -4410,6 +4482,27 @@ $ echo a b c d e f | awk '@{ print "NF =", NF; @cindex portability, @code{NF} variable, decrementing @strong{Caution:} Some versions of @command{awk} don't rebuild @code{$0} when @code{NF} is decremented. Caveat emptor. + +Finally, there are times when it is convenient to force +@command{awk} to rebuild the entire record, using the current +value of the fields and @code{OFS}. To do this, use the +seemingly innocuous assignment: + +@example +$1 = $1 # force record to be reconstituted +print $0 # or whatever else with $0 +@end example + +@noindent +This forces @command{awk} rebuild the record. It does help +to add a comment, as we've shown here. + +There is a flip side to the relationship between @code{$0} and +the fields. Any assignment to @code{$0} causes the record to be +reparsed into fields using the @emph{current} value of @code{FS}. +This also applies to any built-in function that updates @code{$0}, +such as @code{sub} and @code{gsub} +(@pxref{String Functions, ,String-Manipulation Functions}). @c ENDOFRANGE ficon @node Field Separators, Constant Size, Changing Fields, Reading Files @@ -4759,10 +4852,17 @@ awk -F: '$2 == ""' /etc/passwd @node Field Splitting Summary, , Command Line Field Separator, Field Separators @subsection Field-Splitting Summary -The following -table -summarizes how fields are split, based on the -value of @code{FS} (@samp{==} means ``is equal to''): +It is important to remember that when you assign a string constant +as the value of @code{FS}, it undergoes normal @command{awk} string +processing. For example, with Unix @command{awk} and @command{gawk}, +the assignment @samp{FS = "\.."} assigns the character string @code{".."} +to @code{FS} (the backslash is stripped). This creates a regexp meaning +``fields are separated by occurrences of any two characters.'' +If instead you want fields to be separated by a literal period followed +by any single character, use @samp{FS = "\\.."}. + +The following table summarizes how fields are split, based on the value +of @code{FS} (@samp{==} means ``is equal to''): @table @code @item FS == " " @@ -4830,6 +4930,29 @@ prints something like: @example root:nSijPlPhZZwgE:0:0:Root:/: @end example + +@c fakenode --- for prepinfo +@subheading Advanced Notes: @code{FS} and @code{IGNORECASE} + +The @code{IGNORECASE} variable +(@pxref{User-modified, ,Built-in Variables That Control @command{awk}}) +affects field splitting @emph{only} when the value of @code{FS} is a regexp. +It has no effect when @code{FS} is a single character, even if +that character is a letter. Thus, in the following code: + +@example +FS = "c" +IGNORECASE = 1 +$0 = "aCa" +print $1 +@end example + +@noindent +The output is @samp{aCa}. If you really want to split fields on an +alphabetic character while ignoring case, use a regexp that will +do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE} +will take effect. + @c ENDOFRANGE fisepr @c ENDOFRANGE fisepg @@ -5029,8 +5152,13 @@ Now that the input is separated into records, the second step is to separate the fields in the record. One way to do this is to divide each of the lines into fields in the normal manner. This happens by default as the result of a special feature. When @code{RS} is set to the empty -string, the newline character @emph{always} acts as a field separator. -This is in addition to whatever field separations result from @code{FS}. +string, @emph{and} @code{FS} is a set to a single character, +the newline character @emph{always} acts as a field separator. +This is in addition to whatever field separations result from +@code{FS}.@footnote{When @code{FS} is the null string (@code{""}) +or a regexp, this special feature of @code{RS} does not apply. +It does apply to the default field separator of a single space: +@samp{FS = " "}.} The original motivation for this special exception was probably to provide useful behavior in the default case (i.e., @code{FS} is equal @@ -5039,11 +5167,16 @@ want the newline character to separate fields, because there is no way to prevent it. However, you can work around this by using the @code{split} function to break up the record manually (@pxref{String Functions, ,String Manipulation Functions}). +If you have a single character field separator, you can work around +the special feature in a different way, by making @code{FS} into a +regexp for that single character. For example, if the field +separator is a percent character, instead of +@samp{FS = "%"}, use @samp{FS = "[%]"}. Another way to separate fields is to put each field on a separate line: to do this, just set the -variable @code{FS} to the string @code{"\n"}. (This simple regular -expression matches a single newline.) +variable @code{FS} to the string @code{"\n"}. (This single +character seperator matches a single newline.) A practical example of a @value{DF} organized this way might be a mailing list, where each entry is separated by blank lines. Consider a mailing list in a file named @file{addresses}, which looks like this: @@ -5600,6 +5733,16 @@ have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} (@xref{BEGIN/END, , The @code{BEGIN} and @code{END} Special Patterns}, also @pxref{Auto-set, ,Built-in Variables That Convey Information}.) + +@item +Using @code{FILENAME} with @code{getline} +(@samp{getline < FILENAME}) +is likely to be a source for +confusion. @command{awk} opens a separate input stream from the +current input file. However, by not using a variable, @code{$0} +and @code{NR} are still updated. If you're doing this, it's +probably by accident, and you should reconsider what it is you're +trying to accomplish. @end itemize @node Getline Summary, , Getline Notes, Getline @@ -6978,6 +7121,12 @@ is not closed and released until @code{close} is called or does not represent a file, pipe or coprocess that was opened with a redirection. +Note also that @samp{close(FILENAME)} has no +``magic'' effects on the implicit loop that reads through the +files named on the command line. It is, more likely, a close +of a file that was never opened, so @command{awk} silently +does nothing. + @c comma is part of tertiary @cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes, closing When using the @samp{|&} operator to communicate with a coprocess, @@ -7024,7 +7173,10 @@ In these cases, @command{gawk} sets the built-in variable In @command{gawk}, when closing a pipe or coprocess, -the return value is the exit status of the command. +the return value is the exit status of the command.@footnote{ +This is a full 16-bit value as returned by the @code{wait} +system call. See the system manual pages for information on +how to decode this value.} Otherwise, it is the return value from the system's @code{close} or @code{fclose} C functions when closing input or output files, respectively. @@ -7034,6 +7186,8 @@ it fails. The return value for closing a pipeline is particularly useful. It allows you to get the output from a command as well as its exit status. +@c 8/21/2002, FIXME: Maybe the code and this doc should be adjusted to +@c create values indicating death-by-signal? Sigh. @cindex pipes, closing @c comma does NOT start tertiary @@ -8916,8 +9070,6 @@ whereas @samp{$} has higher precedence. This table presents @command{awk}'s operators, in order of highest to lowest precedence: -@page - @c use @code in the items, looks better in TeX w/o all the quotes @table @code @item (@dots{}) @@ -9340,7 +9492,7 @@ This cannot be changed or worked around; range patterns do not combine with other patterns: @example -$ echo yes | gawk '(/1/,/2/) || /Yes/' +$ echo Yes | gawk '(/1/,/2/) || /Yes/' @error{} gawk: cmd. line:1: (/1/,/2/) || /Yes/ @error{} gawk: cmd. line:1: ^ parse error @error{} gawk: cmd. line:2: (/1/,/2/) || /Yes/ @@ -10325,7 +10477,7 @@ describing their areas of activity. The following is an alphabetical list of variables that you can change to control how @command{awk} does certain things. The variables that are -specific to @command{gawk} are marked with a pound sign (@samp{#}). +specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}).} @table @code @cindex @code{BINMODE} variable @@ -10430,7 +10582,9 @@ matching with @samp{~} and @samp{!~}, as well as the @code{gensub}, @code{gsub}, @code{index}, @code{match}, @code{split}, and @code{sub} functions, record termination with @code{RS}, and field splitting with @code{FS}, all ignore case when doing their particular regexp operations. -However, the value of @code{IGNORECASE} does @emph{not} affect array subscripting. +However, the value of @code{IGNORECASE} does @emph{not} affect array subscripting +and it does not affect field splitting when using a single-character +field separator. @xref{Case-sensitivity, ,Case Sensitivity in Matching}. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -10447,6 +10601,8 @@ When this variable is true (nonzero or non-null), @command{gawk} behaves as if the @option{--lint} command-line option is in effect. (@pxref{Options, ,Command-Line Options}). With a value of @code{"fatal"}, lint warnings become fatal errors. +With a value of @code{"invalid"}, only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) Any other true value prints nonfatal warnings. Assigning a false value to @code{LINT} turns off the lint warnings. @@ -10551,7 +10707,7 @@ it is not special. The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. The variables that are specific to -@command{gawk} are marked with an asterisk (@samp{*}). +@command{gawk} are marked with a pound sign@w{ (@samp{#}).} @table @code @cindex @code{ARGC}/@code{ARGV} variables @@ -10682,6 +10838,18 @@ The number of fields in the current input record. @code{NF} is set each time a new record is read, when a new field is created or when @code{$0} changes (@pxref{Fields, ,Examining Fields}). +Unlike most of the variables described in this +@ifnotinfo +section, +@end ifnotinfo +@ifinfo +node, +@end ifinfo +assigning a value to @code{NF} has the potential to affect +@command{awk}'s internal workings. In particular, assignments +to @code{NF} can be used to create or remove fields from the +current record: @xref{Changing Fields, ,Changing the Contents of a Field}. + @cindex @code{NR} variable @item NR The number of input records @command{awk} has processed since @@ -11031,6 +11199,14 @@ conceptually, if the element values are 8, @code{"foo"}, 0 1 2 3 @r{Index} @end example @end ifinfo +@ifxml +@example ++---------+---------+--------+---------+ +| 8 | "foo" | "" | 30 | @r{Value} ++---------+---------+--------+---------+ + 0 1 2 3 @r{Index} +@end example +@end ifxml @noindent Only the values are stored; the indices are implicit from the order of @@ -11712,9 +11888,10 @@ In most @command{awk} implementations, sorting an array requires writing a @code{sort} function. While this can be educational for exploring different sorting algorithms, usually that's not the point of the program. -@command{gawk} provides the built-in @code{asort} function +@command{gawk} provides the built-in @code{asort} +and @code{asorti} functions (@pxref{String Functions, ,String Manipulation Functions}) -that sorts an array. For example: +for sorting arrays. For example: @example @var{populate the array} data @@ -11749,7 +11926,24 @@ In this case, @command{gawk} copies the @code{source} array into the However, the @code{source} array is not affected. Often, what's needed is to sort on the values of the @emph{indices} -instead of the values of the elements. To do this, use a helper array +instead of the values of the elements. +To do that, starting with @command{gawk} 3.1.2, use the +@code{asorti} function. The interface is identical to that of +@code{asort}, except that the index values are used for sorting, and +become the values of the result array: + +@example +@{ source[$0] = some_func($0) @} + +END @{ + n = asorti(source, dest) + for (i = 1; i <= n; i++) + @var{do something with} dest[i] +@} +@end example + +If your version of @command{gawk} is 3.1.0 or 3.1.1, you don't +have @code{asorti}. Instead, use a helper array to hold the sorted index values, and then access the original array's elements. It works in the following way: @@ -11779,10 +11973,14 @@ both arrays use the values. Similarly, when copying the indices from @code{data} to @code{ind}, there is only one copy of the actual index strings. +@c Document It And Call It A Feature. Sigh. @cindex arrays, sorting, @code{IGNORECASE} variable and @cindex @code{IGNORECASE} variable, array sorting and -As with array subscripts, the value of @code{IGNORECASE} -does not affect array sorting. +We said previously that comparisons are done using @command{gawk}'s +``usual comparison rules.'' Because @code{IGNORECASE} affects +string comparisons, the value of @code{IGNORECASE} also +affects sorting for both @code{asort} and @code{asorti}. +Caveat Emptor. @c ENDOFRANGE arrs @node Functions, Internationalization, Arrays, Top @@ -11894,7 +12092,7 @@ two arguments 11 and 10. The following list describes all of the built-in functions that work with numbers. -Optional parameters are enclosed in square brackets ([ ]): +Optional parameters are enclosed in square brackets@w{ ([ ]):} @table @code @item int(@var{x}) @@ -12021,9 +12219,9 @@ sequences of random numbers. The functions in this @value{SECTION} look at or change the text of one or more strings. -Optional parameters are enclosed in square brackets ([ ]). +Optional parameters are enclosed in square brackets@w{ ([ ]).} Those functions that are -specific to @command{gawk} are marked with a pound sign (@samp{#}): +specific to @command{gawk} are marked with a pound sign@w{ (@samp{#}):} @menu * Gory Details:: More than you want to know about @samp{\} and @@ -12037,7 +12235,9 @@ specific to @command{gawk} are marked with a pound sign (@samp{#}): @cindex @code{asort} function (@command{gawk}) @code{asort} is a @command{gawk}-specific extension, returning the number of elements in the array @var{source}. The contents of @var{source} are -sorted using @command{gawk}'s normal rules for comparing values, and the indices +sorted using @command{gawk}'s normal rules for comparing values +(in particular, @code{IGNORECASE} affects the sorting) +and the indices of the sorted values of @var{source} are replaced with sequential integers starting with one. If the optional array @var{dest} is specified, then @var{source} is duplicated into @var{dest}. @var{dest} is then @@ -12071,6 +12271,21 @@ The @code{asort} function is described in more detail in @code{asort} is a @command{gawk} extension; it is not available in compatibility mode (@pxref{Options, ,Command-Line Options}). +@item asorti(@var{source} @r{[}, @var{dest}@r{]}) # +@cindex @code{asorti} function (@command{gawk}) +@code{asorti} is a @command{gawk}-specific extension, returning the number of +elements in the array @var{source}. +It works similarly to @code{asort}, however, the @emph{indices} +are sorted, instead of the values. As array indices are always strings, +the comparison performed is always a string comparison. (Here too, +@code{IGNORECASE} affects the sorting.) + +The @code{asorti} function is described in more detail in +@ref{Array Sorting, ,Sorting Array Values and Indices with @command{gawk}}. +It was added in @command{gawk} 3.1.2. +@code{asorti} is a @command{gawk} extension; it is not available +in compatibility mode (@pxref{Options, ,Command-Line Options}). + @item index(@var{in}, @var{find}) @cindex @code{index} function @cindex searching @@ -12118,6 +12333,13 @@ longest, leftmost substring matched by the regular expression, at which that substring begins (one, if it starts at the beginning of @var{string}). If no match is found, it returns zero. +The @var{regexp} argument may be either a regexp constant +(@samp{/@dots{}/}) or a string constant (@var{"@dots{}"}). +In the latter case, the string is treated as a regexp to be matched. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between the two forms, and the +implications for writing your program correctly. + The order of the first two arguments is backwards from most other string functions that work with regular expressions, such as @code{sub} and @code{gsub}. It might help to remember that @@ -12191,6 +12413,23 @@ $ echo foooobazbarrrrr | @print{} foooo barrrrr @end example +In addition, +beginning with @command{gawk} 3.1.2, +multidimensional subscripts are available providing +the start index and length of each matched subexpression: + +@example +$ echo foooobazbarrrrr | +> gawk '@{ match($0, /(fo+).+(bar*)/, arr) +> print arr[1], arr[2] +> print arr[1, "start"], arr[1, "length"] +> print arr[2, "start"], arr[2, "length"] +> @}' +@print{} foooo barrrrr +@print{} 1 5 +@print{} 9 7 +@end example + @cindex troubleshooting, @code{match} function The @var{array} argument to @code{match} is a @command{gawk} extension. In compatibility mode @@ -12237,17 +12476,30 @@ Also as with input field-splitting, if @var{fieldsep} is the null string, each individual character in the string is split into its own array element. (This is a @command{gawk}-specific extension.) +Note, however, that @code{RS} has no effect on the way @code{split} +works. Even though @samp{RS = ""} causes newline to also be an input +field separator, this does not affect how @code{split} splits strings. + @cindex dark corner, @code{split} function Modern implementations of @command{awk}, including @command{gawk}, allow the third argument to be a regexp constant (@code{/abc/}) as well as a string. @value{DARKCORNER} The POSIX standard allows this as well. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between using a string constant or a regexp constant, +and the implications for writing your program correctly. Before splitting the string, @code{split} deletes any previously existing elements in the array @var{array}. -If @var{string} does not match @var{fieldsep} at all, @var{array} has -one element only. The value of that element is the original @var{string}. + +If @var{string} is null, the array has no elements. (So this is a portable +way to delete an entire array with one statement. +@xref{Delete, ,The @code{delete} Statement}.) + +If @var{string} does not match @var{fieldsep} at all (but is not null), +@var{array} has one element only. The value of that element is the original +@var{string}. @item sprintf(@var{format}, @var{expression1}, @dots{}) @cindex @code{sprintf} function @@ -12297,11 +12549,22 @@ Then the entire string is changed by replacing the matched text with @var{replacement}. The modified string becomes the new value of @var{target}. +The @var{regexp} argument may be either a regexp constant +(@samp{/@dots{}/}) or a string constant (@var{"@dots{}"}). +In the latter case, the string is treated as a regexp to be matched. +@ref{Computed Regexps, ,Using Dynamic Regexps}, for a +discussion of the difference between the two forms, and the +implications for writing your program correctly. + This function is peculiar because @var{target} is not simply used to compute a value, and not just any expression will do---it must be a variable, field, or array element so that @code{sub} can store a modified value there. If this argument is omitted, then the -default is to use and alter @code{$0}. +default is to use and alter @code{$0}.@footnote{Note that this means +that the record will first be regenerated using the value of @code{OFS} if +any fields have been changed, and that the fields will be updated +after the substituion, even if the operation is a ``no-op'' such +as @samp{sub(/^/, "")}.} For example: @example @@ -12477,7 +12740,11 @@ suffix is also returned if @var{length} is greater than the number of characters remaining in the string, counting from character @var{start}. -If @var{start} is less than one or greater than the number of characters +If @var{start} is less than one, @code{substr} treats it as +if it was one. (POSIX doesn't specify what to do in this case: +Unix @command{awk} acts this way, and therefore @command{gawk} +does too.) +If @var{start} is greater than the number of characters in the string, @code{substr} returns the null string. Similarly, if @var{length} is present but less than or equal to zero, the null string is returned. @@ -13846,7 +14113,6 @@ this program, using our function to format the results, prints: 21.2 @end example -@page This function deletes all the elements in an array: @example @@ -14612,7 +14878,7 @@ to standard output in the format of a GNU @code{gettext} Portable Object file. Also included in the output are any constant strings that appear as the first argument to @code{dcgettext} or as the first and second argument to @code{dcngettext}.@footnote{Starting with @code{gettext} -version 0.11.1, the @command{xgettext} utility that comes with GNU +version 0.11.5, the @command{xgettext} utility that comes with GNU @code{gettext} can handle @file{.awk} files.} @xref{I18N Example, ,A Simple Internationalization Example}, for the full list of steps to go through to create and test @@ -14941,7 +15207,7 @@ complete detail in @cite{GNU gettext tools}.) @end ifnotinfo As of this writing, the latest version of GNU @code{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.1.tar.gz, @value{PVERSION} 0.11.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.11.5.tar.gz, @value{PVERSION} 0.11.5}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -15100,7 +15366,7 @@ done with temporary files: @example # write the data for processing -tempfile = ("/tmp/mydata." PROCINFO["pid"]) +tempfile = ("mydata." PROCINFO["pid"]) while (@var{not done with data}) print @var{data} | ("subprogram > " tempfile) close("subprogram > " tempfile) @@ -15113,7 +15379,10 @@ system("rm " tempfile) @end example @noindent -This works, but not elegantly. +This works, but not elegantly. Among other things, it requires that +the program be run in a directory that cannot be shared among users; +for example, @file{/tmp} will not do, as another user might happen +to be using a temporary file with the same name. @cindex coprocesses @cindex input/output, two-way @@ -15157,7 +15426,6 @@ standard error separately. @cindex deadlocks @cindex buffering, input/output @cindex @code{getline} command, deadlock and -</itemizedlist> @item I/O buffering may be a problem. @command{gawk} automatically flushes all output down the pipe to the child process. @@ -15215,6 +15483,26 @@ has been read, @command{gawk} terminates the coprocess and exits. As a side note, the assignment @samp{LC_ALL=C} in the @command{sort} command ensures traditional Unix (ASCII) sorting from @command{sort}. +Beginning with @command{gawk} 3.1.2, you may use Pseudo-ttys (ptys) for +two-way communication instead of pipes, if your system supports them. +This is done on a per-command basis, by setting a special element +in the @code{PROCINFO} array +(@pxref{Auto-set, ,Built-in Variables That Convey Information}), +like so: + +@example +command = "sort -nr" # command, saved in variable for convenience +PROCINFO[command, "pty"] = 1 # update PROCINFO +print @dots{} |& command # start two-way pipe +@dots{} +@end example + +@noindent +Using ptys avoids the buffer deadlock issues described earlier, at some +loss in performance. If your system does not have ptys, or if all the +system's ptys are in use, @command{gawk} automatically falls back to +using regular pipes. + @node TCP/IP Networking, Portal Files, Two-way I/O, Advanced Features @section Using @command{gawk} for Network Programming @cindex advanced features, @command{gawk}, network programming @@ -15894,6 +16182,8 @@ With an optional argument of @samp{fatal}, lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner @command{awk} programs. +With an optional argument of @samp{invalid}, only warnings about things that are +actually invalid are issued. (This is not fully implemented yet.) @item -W lint-old @itemx --lint-old @@ -17444,12 +17734,12 @@ This code relies on the @code{ARGIND} variable which is specific to @command{gawk}. If you are not using @command{gawk}, you can use ideas presented in -@iftex +@ifnotinfo the previous @value{SECTION} -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo @ref{Filetrans Function, ,Noting @value{DDF} Boundaries}, -@end ifnottex +@end ifinfo to either update @code{ARGIND} on your own or modify this code as appropriate. @@ -17990,12 +18280,26 @@ Following is @command{pwcat}, a C program that ``cats'' the password database: * Public Domain */ +#if HAVE_CONFIG_H +#include <config.h> +#endif + @c endfile @end ignore @c file eg/lib/pwcat.c #include <stdio.h> #include <pwd.h> +@c endfile +@ignore +@c file eg/lib/pwcat.c +#if defined (STDC_HEADERS) +#include <stdlib.h> +#endif + +@c endfile +@end ignore +@c file eg/lib/pwcat.c int main(argc, argv) int argc; @@ -18004,12 +18308,12 @@ char **argv; struct passwd *p; while ((p = getpwent()) != NULL) - printf("%s:%s:%d:%d:%s:%s:%s\n", - p->pw_name, p->pw_passwd, p->pw_uid, - p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); + printf("%s:%s:%ld:%ld:%s:%s:%s\n", + p->pw_name, p->pw_passwd, (long) p->pw_uid, + (long) p->pw_gid, p->pw_gecos, p->pw_dir, p->pw_shell); endpwent(); - exit(0); + return 0; @} @c endfile @end example @@ -18028,9 +18332,12 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. +(On some systems it's a C @code{long}, and not an @code{int}. Thus +we cast it to @code{long} for all cases.) @item Group-ID The user's numeric group ID number. +(Similar comments about @code{long} vs.@: @code{int} apply here.) @item Full name The user's full name, and perhaps other information associated with the @@ -18328,9 +18635,13 @@ is as follows: #if HAVE_CONFIG_H #include <config.h> #endif + +#if defined (STDC_HEADERS) +#include <stdlib.h> +#endif -#ifndef HAVE_GETPGRENT -int main() { exit(0); } +#ifndef HAVE_GETGRENT +int main() { return 0; } #else @c endfile @end ignore @@ -18347,8 +18658,8 @@ char **argv; int i; while ((g = getgrent()) != NULL) @{ - printf("%s:%s:%d:", g->gr_name, g->gr_passwd, - g->gr_gid); + printf("%s:%s:%ld:", g->gr_name, g->gr_passwd, + (long) g->gr_gid); for (i = 0; g->gr_mem[i] != NULL; i++) @{ printf("%s", g->gr_mem[i]); @group @@ -18359,13 +18670,13 @@ char **argv; putchar('\n'); @} endgrent(); - exit(0); + return 0; @} @c endfile @end example @ignore @c file eg/lib/grcat.c -#endif /* HAVE_GETPGRENT */ +#endif /* HAVE_GETGRENT */ @c endfile @end ignore @@ -18383,6 +18694,8 @@ usually empty or set to @samp{*}. @item Group ID Number The numeric group ID number. This number is unique within the file. +(On some systems it's a C @code{long}, and not an @code{int}. Thus +we cast it to @code{long} for all cases.) @item Group Member List A comma-separated list of usernames. These users are members of the group. @@ -21378,8 +21691,11 @@ means it should accept all of @command{gawk}'s command-line arguments, including the ability to have multiple source files specified via @option{-f}, and the ability to mix command-line and library source files. -The program is written using the POSIX Shell (@command{sh}) command language. -It works as follows: +The program is written using the POSIX Shell (@command{sh}) command +language.@footnote{Fully explaining the @command{sh} language is beyond +the scope of this book. We provide some minimal explanations, but see +a good shell programming book if you wish to understand things in more +depth.} It works as follows: @enumerate @item @@ -21388,38 +21704,38 @@ Loop through the arguments, saving anything that doesn't represent @item For any arguments that do represent @command{awk} text, put the arguments into -a temporary file that will be expanded. There are two cases: +a shell variable that will be expanded. There are two cases: @enumerate a @item Literal text, provided with @option{--source} or @option{--source=}. This -text is just echoed directly. The @command{echo} program automatically -supplies a trailing newline. +text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and echo -@samp{@@include @var{filename}} into the temporary file. Since the file-inclusion +Source @value{FN}s, provided with @option{-f}. We use a neat trick and append +@samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion program works the way @command{gawk} does, this gets the text of the file included into the program at the correct point. @end enumerate @item -Run an @command{awk} program (naturally) over the temporary file to expand +Run an @command{awk} program (naturally) over the shell variable's contents to expand @samp{@@include} statements. The expanded program is placed in a second -temporary file. +shell variable. @item Run the expanded program with @command{gawk} and any other original command-line arguments that the user supplied (such as the data @value{FN}s). @end enumerate -The initial part of the program turns on shell tracing if the first -argument is @samp{debug}. Otherwise, a shell @code{trap} statement -arranges to clean up any temporary files on program exit or upon an -interrupt. +This program uses shell variables extensively; for storing command line arguments, +the text of the @command{awk} program that will expand the user's program, for the +user's original program, and for the expanded program. Doing so removes some +potential problems that might arise were we to use temporary files instead, +at the cost of making the script somewhat more complicated. -@c 2e: For the temp file handling, go with Darrel's ig=${TMP:-/tmp}/igs.$$ -@c 2e: or something as similar as possible. +The initial part of the program turns on shell tracing if the first +argument is @samp{debug}. The next part loops through all the command-line arguments. There are several cases of interest: @@ -21440,13 +21756,17 @@ programming trick. Don't worry about it if you are not familiar with These are saved and passed on to @command{gawk}. @item -f@r{,} --file@r{,} --file=@r{,} -Wfile= -The @value{FN} is saved to the temporary file @file{/tmp/ig.s.$$} with an +The @value{FN} is appended to the shell variable @code{program} with an @samp{@@include} statement. -The @command{sed} utility is used to remove the leading option part of the +The @command{expr} utility is used to remove the leading option part of the argument (e.g., @samp{--file=}). +(Typical @command{sh} usage would be to use the @command{echo} and @command{sed} +utilities to do this work. Unfortunately, some versions of @command{echo} evaluate +escape sequences in their arguments, possibly mangling the program text. +Using @command{expr} avoids this problem.) @item --source@r{,} --source=@r{,} -Wsource= -The source text is echoed into @file{/tmp/ig.s.$$}. +The source text is appended to @code{program}. @item --version@r{,} -Wversion @command{igawk} prints its version number, runs @samp{gawk --version} @@ -21457,17 +21777,11 @@ If none of the @option{-f}, @option{--file}, @option{-Wfile}, @option{--source}, or @option{-Wsource} arguments are supplied, then the first nonoption argument should be the @command{awk} program. If there are no command-line arguments left, @command{igawk} prints an error message and exits. -Otherwise, the first argument is echoed into @file{/tmp/ig.s.$$}. +Otherwise, the first argument is appended to @code{program}. In any case, after the arguments have been processed, -@file{/tmp/ig.s.$$} contains the complete text of the original @command{awk} +@code{program} contains the complete text of the original @command{awk} program. -@cindex @command{sed} utility -@cindex stream editors -The @samp{$$} in @command{sh} represents the current process ID number. -It is often used in shell programs to generate unique temporary @value{FN}s. -This allows multiple users to run @command{igawk} without worrying -that the temporary @value{FN}s will clash. The program is as follows: @cindex @code{igawk.sh} program @@ -21489,49 +21803,56 @@ if [ "$1" = debug ] then set -x shift -else - # cleanup on exit, hangup, interrupt, quit, termination - trap 'rm -f /tmp/ig.[se].$$' 0 1 2 3 15 fi +# A literal newline, so that program text is formmatted correctly +n=' +' + +# Initialize variables to empty +program= +opts= + while [ $# -ne 0 ] # loop over arguments do case $1 in --) shift; break;; -W) shift - set -- -W"$@@" + # The $@{x?'message here'@} construct prints a + # diagnostic if $x is the null string + set -- -W"$@{@@?'missing operand'@}" continue;; - -[vF]) opts="$opts $1 '$2'" + -[vF]) opts="$opts $1 '$@{2?'missing operand'@}'" shift;; -[vF]*) opts="$opts '$1'" ;; - -f) echo @@include "$2" >> /tmp/ig.s.$$ + -f) program="$program$n@@include $@{2?'missing operand'@}" shift;; - -f*) f=`echo "$1" | sed 's/-f//'` - echo @@include "$f" >> /tmp/ig.s.$$ ;; + -f*) f=`expr "$1" : '-f\(.*\)'` + program="$program$n@@include $f";; - -?file=*) # -Wfile or --file - f=`echo "$1" | sed 's/-.file=//'` - echo @@include "$f" >> /tmp/ig.s.$$ ;; + -[W-]file=*) + f=`expr "$1" : '-.file=\(.*\)'` + program="$program$n@@include $f";; - -?file) # get arg, $2 - echo @@include "$2" >> /tmp/ig.s.$$ + -[W-]file) + program="$program$n@@include $@{2?'missing operand'@}" shift;; - -?source=*) # -Wsource or --source - t=`echo "$1" | sed 's/-.source=//'` - echo "$t" >> /tmp/ig.s.$$ ;; + -[W-]source=*) + t=`expr "$1" : '-.source=\(.*\)'` + program="$program$n$t";; - -?source) # get arg, $2 - echo "$2" >> /tmp/ig.s.$$ + -[W-]source) + program="$program$n$@{2?'missing operand'@}" shift;; - -?version) - echo igawk: version 1.0 1>&2 + -[W-]version) + echo igawk: version 2.0 1>&2 gawk --version exit 0 ;; @@ -21542,26 +21863,20 @@ do shift done -if [ ! -s /tmp/ig.s.$$ ] +if [ -z "$program" ] then -@group - if [ -z "$1" ] - then - echo igawk: no program! 1>&2 - exit 1 -@end group - else - echo "$1" > /tmp/ig.s.$$ - shift - fi + program=$@{1?'missing program'@} + shift fi -# at this point, /tmp/ig.s.$$ has the program +# At this point, `program' has the program. @c endfile @end example The @command{awk} program to process @samp{@@include} directives -reads through the program, one line at a time, using @code{getline} +is stored in the shell variable @code{expand_prog}. Doing this keeps +the shell script readable. The @command{awk} program +reads through the user's program, one line at a time, using @code{getline} (@pxref{Getline, ,Explicit Input with @code{getline}}). The input @value{FN}s and @samp{@@include} statements are managed using a stack. As each @samp{@@include} is encountered, the current @value{FN} is @@ -21595,8 +21910,7 @@ slower. @example @c file eg/prog/igawk.sh -gawk -- ' -# process @@include directives +expand_prog=' function pathto(file, i, t, junk) @{ @@ -21635,7 +21949,7 @@ BEGIN @{ @c endfile @end example -The stack is initialized with @code{ARGV[1]}, which will be @file{/tmp/ig.s.$$}. +The stack is initialized with @code{ARGV[1]}, which will be @file{/dev/stdin}. The main loop comes next. Input lines are read in succession. Lines that do not start with @samp{@@include} are printed verbatim. If the line does start with @samp{@@include}, the @value{FN} is in @code{$2}. @@ -21681,14 +21995,44 @@ the program is done: @} close(input[stackptr]) @} -@}' /tmp/ig.s.$$ > /tmp/ig.e.$$ +@}' # close quote ends `expand_prog' variable + +processed_program=`gawk -- "$expand_prog" /dev/stdin <<EOF +$program +EOF +` @c endfile @end example +The shell construct @samp{@var{command} << @var{marker}} is called a @dfn{here document}. +Everything in the shell script up to the @var{marker} is fed to @var{command} as input. +The shell processes the contents of the here document for variable and command substitution +(and possibly other things as well, depending upon the shell). + +The shell construct @samp{`@dots{}`} is called @dfn{command substitution}. +The output of the command between the two backquotes (grave accents) is substituted +into the command line. It is saved as a single string, even if the results +contain whitespace. + +The expanded program is saved in the variable @code{processed_program}. +It's done in these steps: + +@enumerate +@item +Run @command{gawk} with the @samp{@@include}-processing program (the +value of the @code{expand_prog} shell variable) on standard input. + +@item +Standard input is the contents of the user's program, from the shell variable @code{program}. +Its contents are fed to @command{gawk} via a here document. + +@item +The results of this processing are saved in the shell variable @code{processed_program} by using command substitution. +@end enumerate + The last step is to call @command{gawk} with the expanded program, along with the original -options and command-line arguments that the user supplied. @command{gawk}'s -exit status is passed back on to @command{igawk}'s calling program: +options and command-line arguments that the user supplied. @c this causes more problems than it solves, so leave it out. @ignore @@ -21707,14 +22051,15 @@ end of file indication. @example @c file eg/prog/igawk.sh -eval gawk -f /tmp/ig.e.$$ $opts -- "$@@" - -exit $? +eval gawk $opts -- '"$processed_program"' '"$@@"' @c endfile @end example -This version of @command{igawk} represents my third attempt at this program. -There are three key simplifications that make the program work better: +The @command{eval} command is a shell construct that reruns the shell's parsing +process. This keeps things properly quoted. + +This version of @command{igawk} represents my fourth attempt at this program. +There are four key simplifications that make the program work better: @itemize @bullet @item @@ -21734,6 +22079,13 @@ considerably. Using a @code{getline} loop in the @code{BEGIN} rule does it all in one place. It is not necessary to call out to a separate loop for processing nested @samp{@@include} statements. + +@item +Instead of saving the expanded program in a temporary file, putting it in a shell variable +avoids some potential security problems. +This has the disadvantage that the script relies upon more features +of the @command{sh} language, making it harder to follow for those who +aren't familiar with @command{sh}. @end itemize Also, this program illustrates that it is often worthwhile to combine @@ -22365,11 +22717,11 @@ making translations easier (@pxref{Printf Ordering, , Rearranging @code{printf} Arguments}). @item -The @code{asort} function for sorting arrays +The @code{asort} and @code{asorti} functions for sorting arrays (@pxref{Array Sorting, ,Sorting Array Values and Indices with @command{gawk}}). @item -The @code{bindtextdomain} and @code{dcgettext} functions +The @code{bindtextdomain}, @code{dcgettext} and @code{dcngettext} functions for internationalization (@pxref{Programmer i18n, ,Internationalizing @command{awk} Programs}). @@ -22449,6 +22801,11 @@ The Atari port became officially unsupported The source code now uses new-style function definitions, with @command{ansi2knr} to convert the code on systems with old compilers. +@item +The @option{--disable-lint} configuration option to disable lint checking +at compile time +(@pxref{Additional Configuration Options, , Additional Configuration Options}). + @end itemize @c XXX ADD MORE STUFF HERE @@ -23026,6 +23383,26 @@ This option should be used on systems that do @emph{not} use @value{PVERSION} 2 of the GNU C library. All known modern GNU/Linux systems use Glibc 2. Use this option on any other system. +@cindex @code{--disable-lint} configuration option +@cindex configuration option, @code{--disable-lint} +@item --disable-lint +This option disables all lint checking within @code{gawk}. The +@option{--lint} and @option{--lint-old} options +(@pxref{Options, , Command-Line Options}) +are accepted, but silently do nothing. +Similarly, setting the @code{LINT} variable +(@pxref{User-modified, , Built-in Variables That Control @command{awk}}) +has no effect on the running @command{awk} program. + +When used with GCC's automatic dead-code-elimination, this option +cuts almost 200K bytes off the size of the @command{gawk} +executable on GNU/Linux x86 systems. Results on other systems and +with other compilers are likely to vary. +Using this option may bring you some slight performance improvement. + +Using this option will cause some of the tests in the test suite +to fail. This option may be removed at a later date. + @cindex @code{--disable-nls} configuration option @cindex configuration option, @code{--disable-nls} @item --disable-nls @@ -23249,16 +23626,21 @@ or more detailed installation instructions. development tools from DJ Delorie (DJGPP; MS-DOS only) or Eberhard Mattes (EMX; MS-DOS, Win32 and OS/2). Microsoft Visual C/C++ can be used to build a Win32 version, and Microsoft C/C++ can be -used to build 16-bit versions for MS-DOS and OS/2. The file +used to build 16-bit versions for MS-DOS and OS/2. +@c FIXME: +(As of @command{gawk} 3.1.2, the MSC version doesn't work. However, +the maintainer is working on fixing it.) +The file @file{README_d/README.pc} in the @command{gawk} distribution contains additional notes, and @file{pc/Makefile} contains important information on compilation options. -To build @command{gawk} for MS-DOS, Win32, and OS/2 (16 bit; for 32 bit (EMX) -see below), copy the files in the @file{pc} directory (@emph{except} for -@file{ChangeLog}) to the directory with the rest of the @command{gawk} sources. -The @file{Makefile} contains a configuration section with comments and may need -to be edited in order to work with your @command{make} utility. +To build @command{gawk} for MS-DOS, Win32, and OS/2 (16 bit only; for 32 bit +(EMX) you can use the @command{configure} script and skip the following paragraphs; +for details see below), copy the files in the @file{pc} directory (@emph{except} +for @file{ChangeLog}) to the directory with the rest of the @command{gawk} +sources. The @file{Makefile} contains a configuration section with comments and +may need to be edited in order to work with your @command{make} utility. The @file{Makefile} contains a number of targets for building various MS-DOS, Win32, and OS/2 versions. A list of targets is printed if the @command{make} @@ -23276,69 +23658,79 @@ companion utilities or appropriate GNU utilities. However, some editing of replacement. Details can be found in @file{README_d/README.pc} and in the file @file{pc/Makefile.tst}. -To build @command{gawk} for OS/2 (32 bit, EMX), there are three possibilities: +The 32 bit EMX version of @command{gawk} works ``out of the box'' under OS/2. +In principle, it is possible to compile @command{gawk} the following way: -@enumerate 1 -@item -Using the @command{configure} script included in the official @command{gawk} distribution. -@command{configure} need not be recreated but a number of restrictions exist -when using this choice: +@example +$ ./configure +$ make +@end example -@itemize @bullet -@item -An external @code{gettext} library cannot be used. I.e. the @command{configure} option -@option{--without-included-gettext} does not work. Unfortunately, -the internal @code{gettext} library is seriuosly broken for OS/2. -Therefore you have to use @option{--disable-nls}. +This is not recommended, though. To get an OMF executable you should +use the following commands at your @command{sh} prompt: -@item -Executables must be linked statically (@code{a.out} format only). -@samp{make install} does not work. +@example +$ CPPFLAGS="-D__ST_MT_ERRNO__" +$ export CPPFLAGS +$ CFLAGS="-O2 -Zomf -Zmt" +$ export CFLAGS +$ LDFLAGS="-s -Zcrtdll -Zlinker /exepack:2 -Zlinker /pm:vio -Zstack 0x8000" +$ export LDFLAGS +$ RANLIB="echo" +$ export RANLIB +$ ./configure --prefix=c:/usr --without-included-gettext +$ make AR=emxomfar +@end example + +These are just suggestions. You may use any other set of (self-consistent) +environment variables and compiler flags. + +To get an FHS-compliant file hierarchy it is recommended to use the additional +@command{configure} options @option{--infodir=c:/usr/share/info}, @option{--mandir=c:/usr/share/man} +and @option{--libexecdir=c:/usr/lib}. + +The internal @code{gettext} library tends to be problematic. It is therefore recommended +to use either an external one (@option{--without-included-gettext}) or to disable +NLS entirely (@option{--disable-nls}). -These restrictions are due to restrictions in Autoconf 2.13 and cannot be -avoided. They will vanish as soon as @command{gawk} moves on to Autoconf 2.5x. -Now enter the following commands at your @command{sh} prompt: +If you use GCC 2.95 or newer it is recommended to use also: @example -$ CC="gcc"; export CC -$ CFLAGS="-O2"; export CFLAGS -$ AWK="awk"; export AWK -$ LD="ld"; export LD -$ LDFLAGS="-Zexe"; export LDFLAGS -$ RANLIB="ranlib"; export RANLIB -$ ac_cv_header_sys_socket_h="yes" -$ export ac_cv_header_sys_socket_h -$ ./configure --prefix=c:/usr --disable-nls -$ make +$ LIBS="-lgcc" +$ export LIBS @end example -@end itemize -@item -Using a special version of Autoconf 2.13 for OS/2 to recreate @command{configure}. -Not tested. In principle this should work but the same restrictions -apply as in 1, but the environment variables @env{CC}, @env{AWK}, -@env{LDFLAGS} and @env{RANLIB} are not necessary. +You can also get an @code{a.out} executable if you prefer: -@item -Using Autoconf 2.5x to recreate @command{configure} (2.52f or higher recommended). -Some patches must be applied to @file{Makefile.am} and @file{test/Makefile.am} -and @file{po/Makefile.in.in}. Currently not supported. -@end enumerate - -@strong{Note:} Even if the compiled @command{gawk.exe} executable contains a DOS header -(@code{a.out} format), it does @emph{not} work under DOS. To compile an executable -that runs under DOS, @env{CPPFLAGS} must be set to @code{"-DPIPES_SIMULATED"}. +@example +$ CPPFLAGS="-D__ST_MT_ERRNO__" +$ export CPPFLAGS +$ CFLAGS="-O2 -Zmt" +$ export CFLAGS +$ LDFLAGS="-s -Zstack 0x8000" +$ LIBS="-lgcc" +$ unset RANLIB +$ ./configure --prefix=c:/usr --without-included-gettext +$ make +@end example + +@strong{Note:} Even if the compiled @command{gawk.exe} (@code{a.out}) executable +contains a DOS header, it does @emph{not} work under DOS. To compile an executable +that runs under DOS, @code{"-DPIPES_SIMULATED"} must be added to @env{CPPFLAGS}. But then some nonstandard extensions of @command{gawk} (e.g., @samp{|&}) do not work! After compilation the internal tests can be performed. Enter @samp{make check CMP="diff -a"} at your command prompt. All tests but the @code{pid} test are expected to work properly. The @code{pid} -test might or might not work, no idea why. +test fails because child processes are not started by @code{fork()}. + +@samp{make install} works as expected. @strong{Note:} Most OS/2 ports of GNU @command{make} are not able to handle the Makefiles of this package. If you encounter any problems with @command{make} -try GNU @command{make} 3.79.1. You should find the latest version on -@uref{ftp://ftp.unixos2.org}. +try GNU Make 3.79.1 or later versions. You should find the latest +version on @uref{http://www.unixos2.org/sw/pub/binary/make/} or on +@uref{ftp://hobbes.nmsu.edu/pub/os2/}. @node PC Using, Cygwin, PC Compiling, PC Installation @@ -23508,6 +23900,7 @@ for any other environment for MS-DOS or MS-Windows. @appendixsubsec How to Compile and Install @command{gawk} on VMS @c based on material from Pat Rankin <rankin@eql.caltech.edu> +@c now rankin@pactechdata.com @cindex installation, vms This @value{SUBSECTION} describes how to compile and install @command{gawk} under VMS. @@ -23955,7 +24348,7 @@ Stephen Davies, @email{scldad@@sdc.com.au}. @cindex Rankin, Pat @item VMS -Pat Rankin, @email{rankin@@eql.caltech.edu}. +Pat Rankin, @email{rankin@@pactechdata.com}. @end table @end ignore @@ -23980,7 +24373,7 @@ Darrel Hankerson, @email{hankedr@@mail.auburn.edu}. @item Tandem @tab Stephen Davies, @email{scldad@@sdc.com.au}. @cindex Rankin, Pat -@item VMS @tab Pat Rankin, @email{rankin@@eql.caltech.edu}. +@item VMS @tab Pat Rankin, @email{rankin@@pactechdata.com}. @end multitable If your bug is also reproducible under Unix, please send a copy of your @@ -24117,12 +24510,22 @@ It also has a number of extensions. The @command{awk} translator is released under the GPL, and the library is under the LGPL. -@ignore -To get @command{awka}, go to its home page at -Go to @uref{http://awka.sourceforge.net}. -@end ignore To get @command{awka}, go to @uref{http://awka.sourceforge.net}. -You can reach Andrew Sumner at @email{andrew_sumner@@bigfoot.com}. +You can reach Andrew Sumner at @email{andrew@@zbcom.net}. + +@cindex Beebe, Nelson H.F. +@cindex @command{pawk} profiling Bell Labs @command{awk} +@item @command{pawk} +Nelson H.F.@: Beebe at the University of Utah has modified +the Bell Labs @command{awk} to provide timing and profiling information. +It is different from @command{pgawk} +(@pxref{Profiling, ,Profiling Your @command{awk} Programs}), +in that it uses CPU-based profiling, not line-count +profiling. You may find it at either +@uref{ftp://ftp.math.utah.edu/pub/pawk/pawk-20020210.tar.gz} +or +@uref{http://www.math.utah.edu/pub/pawk/pawk-20020210.tar.gz}. + @end table @c ENDOFRANGE gligawk @c ENDOFRANGE ingawk @@ -24234,7 +24637,10 @@ read it, please do so, preferably @emph{before} starting to modify @command{gawk the GNU Project's @command{ftp} site, at -@uref{ftp://ftp.gnu.org/gnu/GNUInfo/standards.text}. +@uref{ftp://ftp.gnu.org/gnu/GNUinfo/standards.text}. +An HTML version, suitable for reading with a WWW browser, is +available at +@uref{http://www.gnu.org/prep/standards_toc.html}. Texinfo, Info, and DVI versions are also available.) @cindex @command{gawk}, coding style in @@ -25275,11 +25681,6 @@ Following is a list of probable improvements that will make @command{gawk} perform better: @table @asis -@item An improved version of @code{dfa} -The @code{dfa} pattern matcher from GNU @command{grep} has some -problems. Either a new version or a fixed one will deal with some -important regexp matching issues. - @c NEXT ED: remove this item. awka and mawk do these respectively @item Compilation of @command{awk} programs @command{gawk} uses a Bison (YACC-like) @@ -25712,7 +26113,7 @@ There is a very nice paper on floating-point arithmetic by David Goldberg, ``What Every Computer Scientist Should Know About Floating-point Arithmetic,'' @cite{ACM Computing Surveys} @strong{23}, 1 (1991-03), -5-48.@footnote{@uref{http://www.validgh.com/goldberg/paper.ps}.} +5-48.@footnote{@uref{http://www.validlab.com/goldberg/paper.ps}.} This is worth reading if you are interested in the details, but it does require a background in computer science. @@ -25899,12 +26300,12 @@ Another name for an @command{awk} program. @item Bash The GNU version of the standard shell -@iftex +@ifnotinfo (the @b{B}ourne-@b{A}gain @b{SH}ell). -@end iftex -@ifnottex +@end ifnotinfo +@ifinfo (the Bourne-Again SHell). -@end ifnottex +@end ifinfo See also ``Bourne Shell.'' @item BBS @@ -26915,32 +27316,33 @@ consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. -@node GNU Free Documentation License, Index, Copying, Top +@node GNU Free Documentation License @unnumbered GNU Free Documentation License -@center Version 1.1, March 2000 + @cindex FDL (Free Documentation License) @cindex Free Documentation License (FDL) @cindex GNU Free Documentation License +@center Version 1.2, November 2002 @display -Copyright (C) 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end display -@sp 1 + @enumerate 0 @item PREAMBLE The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It @@ -26955,60 +27357,72 @@ it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. -@sp 1 @item APPLICABILITY AND DEFINITIONS -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and +general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material @@ -27016,7 +27430,22 @@ this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. -@sp 1 + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + @item VERBATIM COPYING @@ -27032,13 +27461,14 @@ number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. -@sp 1 + @item COPYING IN QUANTITY -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present @@ -27056,21 +27486,20 @@ pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. -@sp 1 + @item MODIFICATIONS @@ -27093,7 +27522,8 @@ if the original publisher of that version gives permission. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has less than five). +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. @item State on the Title page the name of the publisher of the @@ -27119,10 +27549,10 @@ and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. @item -Preserve the section entitled ``History'', and its title, and add to -it an item stating at least the title, year, new authors, and +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If -there is no section entitled ``History'' in the Document, create one +there is no section Entitled ``History'' in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @@ -27137,10 +27567,10 @@ least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @item -In any section entitled ``Acknowledgements'' or ``Dedications'', -preserve the section's title, and preserve in the section all the -substance and tone of each of the contributor acknowledgements -and/or dedications given therein. +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. @item Preserve all the Invariant Sections of the Document, @@ -27148,12 +27578,15 @@ unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item -Delete any section entitled ``Endorsements''. Such a section +Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. @item -Do not retitle any existing section as ``Endorsements'' -or to conflict in title with any Invariant Section. +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. @end enumerate If the Modified Version includes new front-matter sections or @@ -27163,9 +27596,9 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has +parties---for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. @@ -27182,7 +27615,7 @@ permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. -@sp 1 + @item COMBINING DOCUMENTS @@ -27191,7 +27624,7 @@ License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its -license notice. +license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -27202,12 +27635,12 @@ author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' -@sp 1 +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + @item COLLECTIONS OF DOCUMENTS @@ -27221,25 +27654,27 @@ You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. -@sp 1 + @item AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -@sp 1 +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + @item TRANSLATION @@ -27249,11 +27684,18 @@ Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. -@sp 1 +translation of this License, and all the license notices in the +Document, and any Warrany Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + @item TERMINATION @@ -27264,7 +27706,7 @@ automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. -@sp 1 + @item FUTURE REVISIONS OF THIS LICENSE @@ -27282,7 +27724,6 @@ of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. - @end enumerate @c fakenode --- for prepinfo @@ -27294,27 +27735,41 @@ license notices just after the title page: @smallexample @group - Copyright (C) @var{year} @var{your name}. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being @var{list their titles}, with the - Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end group @end smallexample -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + + @node Index, , GNU Free Documentation License, Top @unnumbered Index @printindex cp diff --git a/doc/gawkinet.info b/doc/gawkinet.info index 3c1f9722..5a010dbb 100644 --- a/doc/gawkinet.info +++ b/doc/gawkinet.info @@ -1,9 +1,9 @@ -This is gawkinet.info, produced by makeinfo version 4.2 from +This is gawkinet.info, produced by makeinfo version 4.5 from gawkinet.texi. -INFO-DIR-SECTION GNU Packages +INFO-DIR-SECTION Text creation and manipulation START-INFO-DIR-ENTRY -* Gawkinet: (gawkinet). TCP/IP Internetworking With `gawk'. +* Gawkinet: (gawkinet). TCP/IP Internetworking With `gawk'. END-INFO-DIR-ENTRY This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the @@ -14,7 +14,7 @@ This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -37,7 +37,7 @@ This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -67,7 +67,7 @@ This is Edition 1.1 of `TCP/IP Internetworking With `gawk'', for the Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -259,7 +259,7 @@ of the postal system are thus: The price the user pays for the lower overhead of datagram communications is exactly the lower reliability; it is often necessary for user-level protocols that use datagram communications to add their -own reliabilty features on top of the basic communications. +own reliability features on top of the basic communications. File: gawkinet.info, Node: The TCP/IP Protocols, Next: Making Connections, Prev: Datagram Communications, Up: Introduction @@ -267,7 +267,7 @@ File: gawkinet.info, Node: The TCP/IP Protocols, Next: Making Connections, Pr The Internet Protocols ====================== - The Internet Protocol Suite (usually referred as just TCP/IP)(1) + The Internet Protocol Suite (usually referred to as just TCP/IP)(1) consists of a number of different protocols at different levels or "layers." For our purposes, three protocols provide the fundamental communications mechanisms. All other defined protocols are referred to @@ -312,7 +312,7 @@ TCP All other user-level protocols use either TCP or UDP to do their basic communications. Examples are SMTP (Simple Mail Transfer -Protocol), FTP (File Transfer Protocol) and HTTP (HyperText Transfer +Protocol), FTP (File Transfer Protocol), and HTTP (HyperText Transfer Protocol). @@ -323,7 +323,7 @@ TCP and UDP Ports In the postal system, the address on an envelope indicates a physical location, such as a residence or office building. But there may be -more than one person at the location; thus you have to further quantify +more than one person at a location; thus you have to further quantify the recipient by putting a person or company name on the envelope. In the phone system, one phone number may represent an entire @@ -334,16 +334,16 @@ say, "May I please speak to ..." before talking to the person directly. IP networking provides the concept of addressing. An IP address represents a particular computer, but no more. In order to reach the mail service on a system, or the FTP or WWW service on a system, you -have to have some way to further specify which service you want. In -the Internet Protocol suite, this is done with "port numbers", which +must have some way to further specify which service you want. In the +Internet Protocol suite, this is done with "port numbers", which represent the services, much like an extension number used with a phone number. Port numbers are 16-bit integers. Unix and Unix-like systems reserve ports below 1024 for "well known" services, such as SMTP, FTP, -and HTTP. Numbers above 1024 may be used by any application, although -there is no promise made that a particular port number is always -available. +and HTTP. Numbers 1024 and above may be used by any application, +although there is no promise made that a particular port number is +always available. File: gawkinet.info, Node: Making Connections, Prev: The TCP/IP Protocols, Up: Introduction @@ -364,7 +364,7 @@ server or email server. It is the "host" (system) which is _connected to_ in a transaction. For this to work though, the server must be expecting connections. Much as there has to be someone at the office building to answer the phone(1), the server process (usually) has to be -started first and waiting for a connection. +started first and be waiting for a connection. The "client" is the system requesting the service. It is the system _initiating the connection_ in a transaction. (Just as when you pick @@ -381,7 +381,7 @@ pay this price in order to enjoy the benefits of a simple communication paradigm in `gawk'.) Furthermore, once the connection is established, communications are -"synchronous". I.e., each end waits on the other to finish +"synchronous".(2) I.e., each end waits on the other to finish transmitting, before replying. This is much like two people in a phone conversation. While both could talk simultaneously, doing so usually doesn't work too well. @@ -401,6 +401,10 @@ RAW X (1) In the days before voice mail systems! + (2) For the technically savvy, data reads block--if there's no +incoming data, the program is made to wait until there is, instead of +receiving a "there's no data" error return. + File: gawkinet.info, Node: Using Networking, Next: Some Applications and Techniques, Prev: Introduction, Up: Top @@ -875,7 +879,8 @@ browser to Microsoft Windows 95 at the last minute. They even back-ported their TCP/IP implementation to Microsoft Windows for Workgroups 3.11, but it was a rather rudimentary and half-hearted implementation. Nevertheless, the equivalent of `/etc/services' resides -under `c:\windows\services' on Microsoft Windows. +under `C:\WINNT\system32\drivers\etc\services' on Microsoft Windows +2000. File: gawkinet.info, Node: Interacting, Next: Setting Up, Prev: Troubleshooting, Up: Using Networking @@ -3712,29 +3717,29 @@ Book Review of `Introduction to Computational Biology' `Developing Bioinformatics Computer Skills' `http://www.oreilly.com/catalog/bioskills/' + File: gawkinet.info, Node: GNU Free Documentation License, Next: Index, Prev: Links, Up: Top GNU Free Documentation License ****************************** - Version 1.1, March 2000 - Copyright (C) 2000 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Version 1.2, November 2002 + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. - 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. @@ -3750,60 +3755,71 @@ GNU Free Documentation License We recommend this License principally for works whose purpose is instruction or reference. - 1. APPLICABILITY AND DEFINITIONS - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you". + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. - A "Secondary Section" is a named appendix or a front-matter - section of the Document that deals exclusively with the - relationship of the publishers or authors of the Document to the - Document's overall subject (or to related matters) and contains - nothing that could fall directly within that overall subject. - (For example, if the Document is in part a textbook of - mathematics, a Secondary Section may not explain any mathematics.) - The relationship could be a matter of historical connection with - the subject or with related matters, or of legal, commercial, - philosophical, ethical or political position regarding them. + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this - License. + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed - to thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque". + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and - standard-conforming simple HTML designed for human modification. - Opaque formats include PostScript, PDF, proprietary formats that - can be read and edited only by proprietary word processors, SGML - or XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML produced by some word - processors for output purposes only. + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the @@ -3812,6 +3828,22 @@ GNU Free Documentation License Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either @@ -3830,10 +3862,11 @@ GNU Free Documentation License 3. COPYING IN QUANTITY - If you publish printed copies of the Document numbering more than - 100, and the Document's license notice requires Cover Texts, you - must enclose the copies in covers that carry, clearly and legibly, - all these Cover Texts: Front-Cover Texts on the front cover, and + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the @@ -3851,11 +3884,10 @@ GNU Free Documentation License If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. If you use the + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated @@ -3889,7 +3921,8 @@ GNU Free Documentation License entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal - authors, if it has less than five). + authors, if it has fewer than five), unless they release you + from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. @@ -3910,10 +3943,10 @@ GNU Free Documentation License H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and - add to it an item stating at least the title, year, new + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on - the Title Page. If there is no section entitled "History" in + the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in @@ -3928,9 +3961,9 @@ GNU Free Documentation License Document itself, or if the original publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all - the substance and tone of each of the contributor + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, @@ -3938,11 +3971,14 @@ GNU Free Documentation License or the equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements". Such a section + M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no @@ -3952,11 +3988,11 @@ GNU Free Documentation License Version's license notice. These titles must be distinct from any other section titles. - You may add a section entitled "Endorsements", provided it contains + You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition - of a standard. + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end @@ -3980,7 +4016,8 @@ GNU Free Documentation License modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your - combined work in its license notice. + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -3992,11 +4029,11 @@ GNU Free Documentation License the list of Invariant Sections in the license notice of the combined work. - In the combination, you must combine any sections entitled + In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications". You - must delete all sections entitled "Endorsements." + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS @@ -4017,20 +4054,20 @@ GNU Free Documentation License A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of - a storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they are not themselves - derivative works of the Document. + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. 8. TRANSLATION @@ -4040,10 +4077,18 @@ GNU Free Documentation License permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. + translation of this License, and all the license notices in the + Document, and any Warrany Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. 9. TERMINATION @@ -4073,7 +4118,6 @@ GNU Free Documentation License you may choose any version ever published (not as a draft) by the Free Software Foundation. - ADDENDUM: How to use this License for your documents ==================================================== @@ -4081,19 +4125,24 @@ ADDENDUM: How to use this License for your documents the License in the document and put the following copyright and license notices just after the title page: - Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. -If you have no Invariant Sections, write "with no Invariant -Sections" instead of saying which ones are invariant. If you have no -Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover -Texts being LIST"; likewise for Back-Cover Texts. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of @@ -4137,12 +4186,14 @@ Index * ELIZA program: Simple Server. * email: Email. * FASTA/Pearson format: PROTBASE. +* FDL (Free Documentation License): GNU Free Documentation License. * filenames, for network access: Gawk Special Files. * files, /inet/ (gawk): Gawk Special Files. * files, /inet/raw (gawk): File /inet/raw. * files, /inet/tcp (gawk): File /inet/tcp. * files, /inet/udp (gawk): File /inet/udp. * finger utility: Setting Up. +* Free Documentation License (FDL): GNU Free Documentation License. * FTP (File Transfer Protocol): Basic Protocols. * gawk, networking: Using Networking. * gawk, networking, connections <1>: TCP Connecting. @@ -4156,6 +4207,7 @@ Index * GETURL program: GETURL. * GIF image format <1>: STATIST. * GIF image format: Web page. +* GNU Free Documentation License: GNU Free Documentation License. * GNU/Linux <1>: REMCONF. * GNU/Linux <2>: Interacting. * GNU/Linux: Troubleshooting. @@ -4279,56 +4331,57 @@ Index Tag Table: -Node: Top1132 -Node: Preface5684 -Node: Introduction7062 -Node: Stream Communications8086 -Node: Datagram Communications9254 -Node: The TCP/IP Protocols10879 -Ref: The TCP/IP Protocols-Footnote-111555 -Node: Basic Protocols11712 -Node: Ports13019 -Node: Making Connections14416 -Ref: Making Connections-Footnote-116987 -Node: Using Networking17034 -Node: Gawk Special Files19387 -Node: Special File Fields21386 -Node: Comparing Protocols26692 -Node: File /inet/tcp27272 -Node: File /inet/udp28285 -Node: File /inet/raw29393 -Ref: File /inet/raw-Footnote-132413 -Node: TCP Connecting32493 -Node: Troubleshooting34826 -Ref: Troubleshooting-Footnote-137877 -Node: Interacting38396 -Node: Setting Up41121 -Node: Email44610 -Node: Web page46931 -Ref: Web page-Footnote-149731 -Node: Primitive Service49928 -Node: Interacting Service52657 -Ref: Interacting Service-Footnote-161781 -Node: CGI Lib61813 -Node: Simple Server68795 -Ref: Simple Server-Footnote-176528 -Node: Caveats76629 -Node: Challenges77766 -Node: Some Applications and Techniques86425 -Node: PANIC88881 -Node: GETURL90594 -Node: REMCONF93212 -Node: URLCHK98683 -Node: WEBGRAB102513 -Node: STATIST106958 -Ref: STATIST-Footnote-1118659 -Node: MAZE119104 -Node: MOBAGWHO125284 -Ref: MOBAGWHO-Footnote-1139220 -Node: STOXPRED139275 -Node: PROTBASE153550 -Node: Links166641 -Node: GNU Free Documentation License170073 -Node: Index189956 +Node: Top2014 +Node: Preface5707 +Node: Introduction7085 +Node: Stream Communications8109 +Node: Datagram Communications9277 +Node: The TCP/IP Protocols10903 +Ref: The TCP/IP Protocols-Footnote-111582 +Node: Basic Protocols11739 +Node: Ports13047 +Node: Making Connections14443 +Ref: Making Connections-Footnote-117019 +Ref: Making Connections-Footnote-217066 +Node: Using Networking17247 +Node: Gawk Special Files19600 +Node: Special File Fields21599 +Node: Comparing Protocols26905 +Node: File /inet/tcp27485 +Node: File /inet/udp28498 +Node: File /inet/raw29606 +Ref: File /inet/raw-Footnote-132626 +Node: TCP Connecting32706 +Node: Troubleshooting35039 +Ref: Troubleshooting-Footnote-138090 +Node: Interacting38633 +Node: Setting Up41358 +Node: Email44847 +Node: Web page47168 +Ref: Web page-Footnote-149968 +Node: Primitive Service50165 +Node: Interacting Service52894 +Ref: Interacting Service-Footnote-162018 +Node: CGI Lib62050 +Node: Simple Server69032 +Ref: Simple Server-Footnote-176765 +Node: Caveats76866 +Node: Challenges78003 +Node: Some Applications and Techniques86662 +Node: PANIC89118 +Node: GETURL90831 +Node: REMCONF93449 +Node: URLCHK98920 +Node: WEBGRAB102750 +Node: STATIST107195 +Ref: STATIST-Footnote-1118896 +Node: MAZE119341 +Node: MOBAGWHO125521 +Ref: MOBAGWHO-Footnote-1139457 +Node: STOXPRED139512 +Node: PROTBASE153787 +Node: Links166878 +Node: GNU Free Documentation License170311 +Node: Index192716 End Tag Table diff --git a/doc/gawkinet.texi b/doc/gawkinet.texi index d51ce794..0573c8f5 100644 --- a/doc/gawkinet.texi +++ b/doc/gawkinet.texi @@ -5,13 +5,10 @@ @c %**end of header (This is for running Texinfo on a region.) @c FIXME: web vs. Web -@c inside ifinfo for older versions of texinfo.tex -@ifinfo -@dircategory GNU Packages +@dircategory Text creation and manipulation @direntry -* Gawkinet: (gawkinet). TCP/IP Internetworking With @command{gawk}. +* Gawkinet: (gawkinet). TCP/IP Internetworking With `gawk'. @end direntry -@end ifinfo @iftex @set DOCUMENT book @@ -78,7 +75,7 @@ implementation of AWK. Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. @sp 2 Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'', the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) @@ -142,7 +139,7 @@ ISBN 1-882114-93-0 @* @oddheading @| @| @strong{@thischapter}@ @ @ @thispage @end iftex -@ifinfo +@ifnottex @node Top, Preface, (dir), (dir) @top General Introduction @comment node-name, next, previous, up @@ -151,7 +148,7 @@ This file documents the networking features in GNU Awk (@command{gawk}) version 3.1 and later. @insertcopying -@end ifinfo +@end ifnottex @menu * Preface:: About this document. @@ -350,13 +347,13 @@ It is not necessary to set up the call first. The price the user pays for the lower overhead of datagram communications is exactly the lower reliability; it is often necessary for user-level -protocols that use datagram communications to add their own reliabilty +protocols that use datagram communications to add their own reliability features on top of the basic communications. @node The TCP/IP Protocols, Making Connections, Datagram Communications, Introduction @section The Internet Protocols -The Internet Protocol Suite (usually referred as just TCP/IP)@footnote{ +The Internet Protocol Suite (usually referred to as just TCP/IP)@footnote{ It should be noted that although the Internet seems to have conquered the world, there are other networking protocol suites in existence and in use.} consists of a number of different protocols at different levels or ``layers.'' @@ -395,7 +392,7 @@ when using @command{gawk} for network programming. All other user-level protocols use either TCP or UDP to do their basic communications. Examples are SMTP (Simple Mail Transfer Protocol), -FTP (File Transfer Protocol) and HTTP (HyperText Transfer Protocol). +FTP (File Transfer Protocol), and HTTP (HyperText Transfer Protocol). @cindex SMTP (Simple Mail Transfer Protocol) @cindex FTP (File Transfer Protocol) @cindex HTTP (Hypertext Transfer Protocol) @@ -405,7 +402,7 @@ FTP (File Transfer Protocol) and HTTP (HyperText Transfer Protocol). In the postal system, the address on an envelope indicates a physical location, such as a residence or office building. But there may be -more than one person at the location; thus you have to further quantify +more than one person at a location; thus you have to further quantify the recipient by putting a person or company name on the envelope. In the phone system, one phone number may represent an entire company, @@ -415,14 +412,14 @@ say, ``May I please speak to ...'' before talking to the person directly. IP networking provides the concept of addressing. An IP address represents a particular computer, but no more. In order to reach the mail service -on a system, or the FTP or WWW service on a system, you have to have some +on a system, or the FTP or WWW service on a system, you must have some way to further specify which service you want. In the Internet Protocol suite, this is done with @dfn{port numbers}, which represent the services, much like an extension number used with a phone number. Port numbers are 16-bit integers. Unix and Unix-like systems reserve ports below 1024 for ``well known'' services, such as SMTP, FTP, and HTTP. -Numbers above 1024 may be used by any application, although there is no +Numbers 1024 and above may be used by any application, although there is no promise made that a particular port number is always available. @node Making Connections, , The TCP/IP Protocols, Introduction @@ -445,7 +442,7 @@ is @emph{connected to} in a transaction. For this to work though, the server must be expecting connections. Much as there has to be someone at the office building to answer the phone@footnote{In the days before voice mail systems!}, the -server process (usually) has to be started first and waiting +server process (usually) has to be started first and be waiting for a connection. @cindex clients @@ -464,11 +461,13 @@ enjoy the benefits of a simple communication paradigm in @command{gawk}.) @cindex blocking @cindex synchronous communications -Furthermore, once the connection is established, communications -are @dfn{synchronous}. I.e., each end waits on the other to finish -transmitting, before replying. This is much like two people in a phone -conversation. While both could talk simultaneously, doing so usually -doesn't work too well. +Furthermore, once the connection is established, communications are +@dfn{synchronous}.@footnote{For the technically savvy, data reads +block---if there's no incoming data, the program is made to wait until +there is, instead of receiving a ``there's no data'' error return.} I.e., +each end waits on the other to finish transmitting, before replying. This +is much like two people in a phone conversation. While both could talk +simultaneously, doing so usually doesn't work too well. In the case of TCP, the synchronicity is enforced by the protocol when sending data. Data writes @dfn{block} until the data have been received on the @@ -1076,7 +1075,7 @@ their own browser to Microsoft Windows 95 at the last minute. They even back-por their TCP/IP implementation to Microsoft Windows for Workgroups 3.11, but it was a rather rudimentary and half-hearted implementation. Nevertheless, the equivalent of @file{/etc/services} resides under -@file{c:\windows\services} on Microsoft Windows.} +@file{C:\WINNT\system32\drivers\etc\services} on Microsoft Windows 2000.} The first column of the file gives the name of the service, and the second column gives a unique number and the protocol that one can use to connect to this service. @@ -4721,29 +4720,33 @@ They are presented in the order in which they appear. @end table -@node GNU Free Documentation License, Index, Links, Top +@node GNU Free Documentation License @unnumbered GNU Free Documentation License -@center Version 1.1, March 2000 + +@cindex FDL (Free Documentation License) +@cindex Free Documentation License (FDL) +@cindex GNU Free Documentation License +@center Version 1.2, November 2002 @display -Copyright (C) 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end display -@sp 1 + @enumerate 0 @item PREAMBLE The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It @@ -4758,60 +4761,72 @@ it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. -@sp 1 @item APPLICABILITY AND DEFINITIONS -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and +general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material @@ -4819,7 +4834,22 @@ this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. -@sp 1 + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + @item VERBATIM COPYING @@ -4835,13 +4865,14 @@ number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. -@sp 1 + @item COPYING IN QUANTITY -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present @@ -4859,21 +4890,20 @@ pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. -@sp 1 + @item MODIFICATIONS @@ -4896,7 +4926,8 @@ if the original publisher of that version gives permission. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has less than five). +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. @item State on the Title page the name of the publisher of the @@ -4922,10 +4953,10 @@ and required Cover Texts given in the Document's license notice. Include an unaltered copy of this License. @item -Preserve the section entitled ``History'', and its title, and add to -it an item stating at least the title, year, new authors, and +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If -there is no section entitled ``History'' in the Document, create one +there is no section Entitled ``History'' in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @@ -4940,10 +4971,10 @@ least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @item -In any section entitled ``Acknowledgements'' or ``Dedications'', -preserve the section's title, and preserve in the section all the -substance and tone of each of the contributor acknowledgements -and/or dedications given therein. +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. @item Preserve all the Invariant Sections of the Document, @@ -4951,12 +4982,15 @@ unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item -Delete any section entitled ``Endorsements''. Such a section +Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. @item -Do not retitle any existing section as ``Endorsements'' -or to conflict in title with any Invariant Section. +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. @end enumerate If the Modified Version includes new front-matter sections or @@ -4966,9 +5000,9 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has +parties---for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. @@ -4985,7 +5019,7 @@ permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. -@sp 1 + @item COMBINING DOCUMENTS @@ -4994,7 +5028,7 @@ License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its -license notice. +license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single @@ -5005,12 +5039,12 @@ author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' -@sp 1 +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + @item COLLECTIONS OF DOCUMENTS @@ -5024,25 +5058,27 @@ You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. -@sp 1 + @item AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -@sp 1 +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + @item TRANSLATION @@ -5052,11 +5088,18 @@ Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. -@sp 1 +translation of this License, and all the license notices in the +Document, and any Warrany Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + @item TERMINATION @@ -5067,7 +5110,7 @@ automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. -@sp 1 + @item FUTURE REVISIONS OF THIS LICENSE @@ -5085,7 +5128,6 @@ of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. - @end enumerate @c fakenode --- for prepinfo @@ -5097,27 +5139,41 @@ license notices just after the title page: @smallexample @group - Copyright (C) @var{year} @var{your name}. Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 + under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; - with the Invariant Sections being @var{list their titles}, with the - Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end group @end smallexample -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + + @node Index, , GNU Free Documentation License, Top @comment node-name, next, previous, up diff --git a/doc/pgawk.1 b/doc/pgawk.1 new file mode 100644 index 00000000..d2b3f4f0 --- /dev/null +++ b/doc/pgawk.1 @@ -0,0 +1 @@ +.so gawk.1 diff --git a/doc/texinfo.tex b/doc/texinfo.tex index df62a127..555a0770 100644 --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -3,10 +3,10 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2002-03-26.08} +\def\texinfoversion{2003-02-03.16} % -% Copyright (C) 1985, 86, 88, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, -% 2000, 01, 02 Free Software Foundation, Inc. +% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 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 @@ -29,19 +29,17 @@ % % Please try the latest version of texinfo.tex before submitting bug % reports; you can get the latest version from: -% ftp://ftp.gnu.org/gnu/texinfo.tex +% ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex % (and all GNU mirrors, see http://www.gnu.org/order/ftp.html) -% ftp://texinfo.org/texinfo/texinfo.tex % ftp://tug.org/tex/texinfo.tex % (and all CTAN mirrors, see http://www.ctan.org), % and /home/gd/gnu/doc/texinfo.tex on the GNU machines. % +% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. +% % The texinfo.tex in any given Texinfo distribution could well be out % of date, so if that's what you're using, please check. % -% Texinfo has a small home page at http://texinfo.org/ and also -% http://www.gnu.org/software/texinfo. -% % Send bug reports to bug-texinfo@gnu.org. Please include including a % complete document in each bug report with which we can reproduce the % problem. Patches are, of course, greatly appreciated. @@ -57,9 +55,10 @@ % The extra TeX runs get the cross-reference information correct. % Sometimes one run after texindex suffices, and sometimes you need more % than two; texi2dvi does it as many times as necessary. -% -% It is possible to adapt texinfo.tex for other languages. You can get -% the existing language-specific files from the full Texinfo distribution. +% +% It is possible to adapt texinfo.tex for other languages, to some +% extent. You can get the existing language-specific files from the +% full Texinfo distribution. \message{Loading texinfo [version \texinfoversion]:} @@ -69,6 +68,13 @@ \everyjob{\message{[Texinfo version \texinfoversion]}% \catcode`+=\active \catcode`\_=\active} +\message{Basics,} +\chardef\other=12 + +% We never want plain's outer \+ definition in Texinfo. +% For @tex, we can use \tabalign. +\let\+ = \relax + % Save some parts of plain tex whose names we will redefine. \let\ptexb=\b \let\ptexbullet=\bullet @@ -79,19 +85,16 @@ \let\ptexend=\end \let\ptexequiv=\equiv \let\ptexexclam=\! +\let\ptexgtr=> +\let\ptexhat=^ \let\ptexi=\i \let\ptexlbrace=\{ +\let\ptexless=< +\let\ptexplus=+ \let\ptexrbrace=\} \let\ptexstar=\* \let\ptext=\t -% We never want plain's outer \+ definition in Texinfo. -% For @tex, we can use \tabalign. -\let\+ = \relax - -\message{Basics,} -\chardef\other=12 - % If this character appears in an error message or help string, it % starts a new line in the output. \newlinechar = `^^J @@ -138,40 +141,64 @@ \ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi \ifx\putwordDeftypefun\undefined\gdef\putwordDeftypefun{Function}\fi +% In some macros, we cannot use the `\? notation---the left quote is +% in some cases the escape char. +\chardef\colonChar = `\: +\chardef\commaChar = `\, +\chardef\dotChar = `\. +\chardef\equalChar = `\= +\chardef\exclamChar= `\! +\chardef\questChar = `\? +\chardef\semiChar = `\; +\chardef\spaceChar = `\ % +\chardef\underChar = `\_ + % Ignore a token. % \def\gobble#1{} +% True if #1 is the empty string, i.e., called like `\ifempty{}'. +% +\def\ifempty#1{\ifemptyx #1\emptymarkA\emptymarkB}% +\def\ifemptyx#1#2\emptymarkB{\ifx #1\emptymarkA}% + +% Hyphenation fixes. \hyphenation{ap-pen-dix} \hyphenation{mini-buf-fer mini-buf-fers} \hyphenation{eshell} \hyphenation{white-space} % Margin to add to right of even pages, to left of odd pages. -\newdimen \bindingoffset -\newdimen \normaloffset +\newdimen\bindingoffset +\newdimen\normaloffset \newdimen\pagewidth \newdimen\pageheight % Sometimes it is convenient to have everything in the transcript file % and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. +% since that produces some useless output on the terminal. We also make +% some effort to order the tracing commands to reduce output in the log +% file; cf. trace.sty in LaTeX. % \def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\ifx\eTeXversion\undefined -\def\loggingall{\tracingcommands2 \tracingstats2 - \tracingpages1 \tracingoutput1 \tracinglostchars1 - \tracingmacros2 \tracingparagraphs1 \tracingrestores1 - \showboxbreadth\maxdimen\showboxdepth\maxdimen -}% -\else -\def\loggingall{\tracingcommands3 \tracingstats2 - \tracingpages1 \tracingoutput1 \tracinglostchars1 - \tracingmacros2 \tracingparagraphs1 \tracingrestores1 - \tracingscantokens1 \tracingassigns1 \tracingifs1 - \tracinggroups1 \tracingnesting2 - \showboxbreadth\maxdimen\showboxdepth\maxdimen +\def\loggingall{% + \tracingstats2 + \tracingpages1 + \tracinglostchars2 % 2 gives us more in etex + \tracingparagraphs1 + \tracingoutput1 + \tracingmacros2 + \tracingrestores1 + \showboxbreadth\maxdimen \showboxdepth\maxdimen + \ifx\eTeXversion\undefined\else % etex gives us more logging + \tracingscantokens1 + \tracingifs1 + \tracinggroups1 + \tracingnesting2 + \tracingassigns1 + \fi + \tracingcommands3 % 3 gives us more in etex + \errorcontextlines\maxdimen }% -\fi % add check for \lastpenalty to plain's definitions. If the last thing % we did was a \nobreak, we don't want to insert more space. @@ -276,7 +303,7 @@ \egroup % \vbox from first cropmarks clause \fi }% end of \shipout\vbox - }% end of group with \turnoffactive + }% end of group with \normalturnoffactive \advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi } @@ -436,17 +463,6 @@ } -% Single-spacing is done by various environments (specifically, in -% \nonfillstart and \quotations). -\newskip\singlespaceskip \singlespaceskip = 12.5pt -\def\singlespace{% - % Why was this kern here? It messes up equalizing space above and below - % environments. --karl, 6may93 - %{\advance \baselineskip by -\singlespaceskip - %\kern \baselineskip}% - \setleading\singlespaceskip -} - %% Simple single-character @ commands % @@ prints an @ @@ -466,16 +482,19 @@ \let\{=\mylbrace \let\}=\myrbrace \begingroup - % Definitions to produce actual \{ & \} command in an index. - \catcode`\{ = 12 \catcode`\} = 12 + % Definitions to produce \{ and \} commands for indices, + % and @{ and @} for the aux file. + \catcode`\{ = \other \catcode`\} = \other \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\@ = 0 \catcode`\\ = 12 - @gdef@lbracecmd[\{]% - @gdef@rbracecmd[\}]% -@endgroup + \catcode`\! = 0 \catcode`\\ = \other + !gdef!lbracecmd[\{]% + !gdef!rbracecmd[\}]% + !gdef!lbraceatcmd[@{]% + !gdef!rbraceatcmd[@}]% +!endgroup % Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent -% Others are defined by plain TeX: @` @' @" @^ @~ @= @v @H. +% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. \let\, = \c \let\dotaccent = \. \def\ringaccent#1{{\accent23 #1}} @@ -484,7 +503,7 @@ \let\udotaccent = \d % Other special characters: @questiondown @exclamdown -% Plain TeX defines: @AA @AE @O @OE @L (and lowercase versions) @ss. +% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. \def\questiondown{?`} \def\exclamdown{!`} @@ -539,6 +558,16 @@ % therefore, no glue is inserted, and the space between the headline and % the text is small, which looks bad. % +% Another complication is that the group might be very large. This can +% cause the glue on the previous page to be unduly stretched, because it +% does not have much material. In this case, it's better to add an +% explicit \vfill so that the extra space is at the bottom. The +% threshold for doing this is if the group is more than \vfilllimit +% percent of a page (\vfilllimit can be changed inside of @tex). +% +\newbox\groupbox +\def\vfilllimit{0.7} +% \def\group{\begingroup \ifnum\catcode13=\active \else \errhelp = \groupinvalidhelp @@ -552,10 +581,22 @@ % above. But it's pretty close. \def\Egroup{% \egroup % End the \vtop. + % \dimen0 is the vertical size of the group's box. + \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox + % \dimen2 is how much space is left on the page (more or less). + \dimen2 = \pageheight \advance\dimen2 by -\pagetotal + % if the group doesn't fit on the current page, and it's a big big + % group, force a page break. + \ifdim \dimen0 > \dimen2 + \ifdim \pagetotal < \vfilllimit\pageheight + \page + \fi + \fi + \copy\groupbox \endgroup % End the \group. }% % - \vtop\bgroup + \setbox\groupbox = \vtop\bgroup % We have to put a strut on the last line in case the @group is in % the midst of an example, rather than completely enclosing it. % Otherwise, the interline space between the last line of the group @@ -753,30 +794,36 @@ where each line of input produces a line of output.} % @include file insert text of that file as input. % 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 + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other \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}% + \let\value=\expandablevalue \input\thisfile \endgroup} \def\thisfile{} -% @center line outputs that line, centered - -\def\center{\parsearg\centerzzz} -\def\centerzzz #1{{\advance\hsize by -\leftskip -\advance\hsize by -\rightskip -\centerline{#1}}} +% @center line +% outputs that line, centered. +% +\def\center{\parsearg\docenter} +\def\docenter#1{{% + \ifhmode \hfil\break \fi + \advance\hsize by -\leftskip + \advance\hsize by -\rightskip + \line{\hfil \ignorespaces#1\unskip \hfil}% + \ifhmode \break \fi +}} % @sp n outputs n lines of vertical space @@ -841,11 +888,6 @@ where each line of input produces a line of output.} % to set catcodes according to plain TeX first, to allow for subscripts, % superscripts, special math chars, etc. % -% @math does not do math typesetting in section titles, index -% entries, and other such contexts where the catcodes are set before -% @math gets a chance to work. This could perhaps be fixed, but for now -% at least we can have real math in the main text, where it's needed most. -% \let\implicitmath = $%$ font-lock fix % % One complication: _ usually means subscripts, but it could also mean @@ -853,9 +895,9 @@ where each line of input produces a line of output.} % _ within @math be active (mathcode "8000), and distinguish by seeing % if the current family is \slfam, which is what @var uses. % -{\catcode95 = \active % 95 = _ +{\catcode\underChar = \active \gdef\mathunderscore{% - \catcode95=\active + \catcode\underChar=\active \def_{\ifnum\fam=\slfam \_\else\sb\fi}% }} % @@ -871,9 +913,27 @@ where each line of input produces a line of output.} \tex \mathcode`\_="8000 \mathunderscore \let\\ = \mathbackslash + \mathactive \implicitmath\finishmath} \def\finishmath#1{#1\implicitmath\Etex} +% Some active characters (such as <) are spaced differently in math. +% We have to reset their definitions in case the @math was an +% argument to a command which set the catcodes (such as @item or @section). +% +{ + \catcode`^ = \active + \catcode`< = \active + \catcode`> = \active + \catcode`+ = \active + \gdef\mathactive{% + \let^ = \ptexhat + \let< = \ptexless + \let> = \ptexgtr + \let+ = \ptexplus + } +} + % @bullet and @minus need the same treatment as @math, just above. \def\bullet{\implicitmath\ptexbullet\implicitmath} \def\minus{\implicitmath-\implicitmath} @@ -965,7 +1025,7 @@ where each line of input produces a line of output.} \ifx\empty\imagewidth\else width \imagewidth \fi \ifx\empty\imageheight\else height \imageheight \fi \ifnum\pdftexversion<13 - #1.pdf% + #1.pdf% \else {#1.pdf}% \fi @@ -987,40 +1047,39 @@ where each line of input produces a line of output.} \openin 1 \jobname.toc \ifeof 1\else\begingroup \closein 1 - \indexnofonts - \def\tt{} - \let\_ = \normalunderscore % Thanh's hack / proper braces in bookmarks \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace % \def\chapentry ##1##2##3{} - \let\appendixentry = \chapentry - \def\unnumbchapentry ##1##2{} \def\secentry ##1##2##3##4{\advancenumber{chap##2}} - \def\unnumbsecentry ##1##2##3{\advancenumber{chap##2}} \def\subsecentry ##1##2##3##4##5{\advancenumber{sec##2.##3}} - \def\unnumbsubsecentry ##1##2##3##4{\advancenumber{sec##2.##3}} \def\subsubsecentry ##1##2##3##4##5##6{\advancenumber{subsec##2.##3.##4}} - \def\unnumbsubsubsecentry ##1##2##3##4##5{\advancenumber{subsec##2.##3.##4}} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry \input \jobname.toc \def\chapentry ##1##2##3{% \pdfoutline goto name{\pdfmkpgn{##3}}count-\expnumber{chap##2}{##1}} - \let\appendixentry = \chapentry - \def\unnumbchapentry ##1##2{% - \pdfoutline goto name{\pdfmkpgn{##2}}{##1}} \def\secentry ##1##2##3##4{% \pdfoutline goto name{\pdfmkpgn{##4}}count-\expnumber{sec##2.##3}{##1}} - \def\unnumbsecentry ##1##2##3{% - \pdfoutline goto name{\pdfmkpgn{##3}}{##1}} \def\subsecentry ##1##2##3##4##5{% \pdfoutline goto name{\pdfmkpgn{##5}}count-\expnumber{subsec##2.##3.##4}{##1}} - \def\unnumbsubsecentry ##1##2##3##4{% - \pdfoutline goto name{\pdfmkpgn{##4}}{##1}} \def\subsubsecentry ##1##2##3##4##5##6{% \pdfoutline goto name{\pdfmkpgn{##6}}{##1}} - \def\unnumbsubsubsecentry ##1##2##3##4##5{% - \pdfoutline goto name{\pdfmkpgn{##5}}{##1}} + \let\appendixentry = \chapentry + \let\unnumbchapentry = \chapentry + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry + % + % Make special characters normal for writing to the pdf file. + % + \indexnofonts + \let\tt=\relax + \turnoffactive \input \jobname.toc \endgroup\fi }} @@ -1170,7 +1229,7 @@ where each line of input produces a line of output.} \newcount\mainmagstep \ifx\bigger\relax % not really supported. - \let\mainmagstep=\magstep1 + \mainmagstep=\magstep1 \setfont\textrm\rmshape{12}{1000} \setfont\texttt\ttshape{12}{1000} \else @@ -1178,9 +1237,10 @@ where each line of input produces a line of output.} \setfont\textrm\rmshape{10}{\mainmagstep} \setfont\texttt\ttshape{10}{\mainmagstep} \fi -% Instead of cmb10, you many want to use cmbx10. +% Instead of cmb10, you may want to use cmbx10. % cmbx10 is a prettier font on its own, but cmb10 -% looks better when embedded in a line with cmr10. +% looks better when embedded in a line with cmr10 +% (in Bob's opinion). \setfont\textbf\bfshape{10}{\mainmagstep} \setfont\textit\itshape{10}{\mainmagstep} \setfont\textsl\slshape{10}{\mainmagstep} @@ -1231,6 +1291,7 @@ where each line of input produces a line of output.} \font\titlei=cmmi12 scaled \magstep3 \font\titlesy=cmsy10 scaled \magstep4 \def\authorrm{\secrm} +\def\authortt{\sectt} % Chapter (and unnumbered) fonts (17.28pt). \setfont\chaprm\rmbshape{12}{\magstep2} @@ -1328,7 +1389,25 @@ where each line of input produces a line of output.} \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy \let\tenttsl=\smallerttsl \resetmathfonts \setleading{9.5pt}} -\let\smallexamplefonts = \smallerfonts + +% Set the fonts to use with the @small... environments. +\let\smallexamplefonts = \smallfonts + +% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample +% can fit this many characters: +% 8.5x11=86 smallbook=72 a4=90 a5=69 +% If we use \smallerfonts (8pt), then we can fit this many characters: +% 8.5x11=90+ smallbook=80 a4=90+ a5=77 +% For me, subjectively, the few extra characters that fit aren't worth +% the additional smallness of 8pt. So I'm making the default 9pt. +% +% By the way, for comparison, here's what fits with @example (10pt): +% 8.5x11=71 smallbook=60 a4=75 a5=58 +% +% I wish we used A4 paper on this side of the Atlantic. +% +% --karl, 24jan03. + % Set up the default fonts, so we can use them for creating boxes. % @@ -1345,6 +1424,7 @@ where each line of input produces a line of output.} \setfont\shortcontrm\rmshape{12}{1000} \setfont\shortcontbf\bxshape{12}{1000} \setfont\shortcontsl\slshape{12}{1000} +\setfont\shortconttt\ttshape{12}{1000} %% Add scribe-like font environments, plus @l for inline lisp (usually sans %% serif) and @ii for TeX italic @@ -1352,8 +1432,8 @@ where each line of input produces a line of output.} % \smartitalic{ARG} outputs arg in italics, followed by an italic correction % unless the following character is such as not to need one. \def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else\/\fi\fi\fi} -\def\smartslanted#1{{\sl #1}\futurelet\next\smartitalicx} -\def\smartitalic#1{{\it #1}\futurelet\next\smartitalicx} +\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} +\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} \let\i=\smartitalic \let\var=\smartslanted @@ -1371,6 +1451,17 @@ where each line of input produces a line of output.} \def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} \def\restorehyphenation{\hyphenchar\font = `- } +% Set sfcode to normal for the chars that usually have another value. +% Can't use plain's \frenchspacing because it uses the `\x notation, and +% sometimes \x has an active definition that messes things up. +% +\catcode`@=11 + \def\frenchspacing{% + \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m + \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m + } +\catcode`@=\other + \def\t#1{% {\tt \rawbackslash \frenchspacing #1}% \null @@ -1470,15 +1561,17 @@ where each line of input produces a line of output.} \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% \else\ifx\arg\wordcode \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% + \else + \errhelp = \EMsimple + \errmessage{Unknown @kbdinputstyle `\arg'}% \fi\fi\fi } \def\worddistinct{distinct} \def\wordexample{example} \def\wordcode{code} -% Default is kbdinputdistinct. (Too much of a hassle to call the macro, -% the catcodes are wrong for parsearg to work.) -\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl} +% Default is `distinct.' +\kbdinputstyle distinct \def\xkey{\key} \def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% @@ -1592,7 +1685,8 @@ where each line of input produces a line of output.} \let\subtitlerm=\tenrm \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}% % - \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines}% + \def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines + \let\tt=\authortt}% % % Leave some space at the very top of the page. \vglue\titlepagetopglue @@ -1873,10 +1967,18 @@ where each line of input produces a line of output.} % \parskip glue -- logically it's part of the @item we just started. \nobreak \vskip-\parskip % - % Stop a page break at the \parskip glue coming up. Unfortunately + % Stop a page break at the \parskip glue coming up. (Unfortunately % we can't prevent a possible page break at the following - % \baselineskip glue. - \nobreak + % \baselineskip glue.) However, if what follows is an environment + % such as @example, there will be no \parskip glue; then + % the negative vskip we just would cause the example and the item to + % crash together. So we use this bizarre value of 10001 as a signal + % to \aboveenvbreak to insert \parskip glue after all. + % (Possibly there are other commands that could be followed by + % @example which need the same treatment, but not section titles; or + % maybe section titles are the only special case and they should be + % penalty 10001...) + \penalty 10001 \endgroup \itemxneedsnegativevskipfalse \else @@ -1982,11 +2084,6 @@ where each line of input produces a line of output.} \def\itemcontents{#1}% \let\item=\itemizeitem} -% Set sfcode to normal for the chars that usually have another value. -% These are `.?!:;,' -\def\frenchspacing{\sfcode46=1000 \sfcode63=1000 \sfcode33=1000 - \sfcode58=1000 \sfcode59=1000 \sfcode44=1000 } - % \splitoff TOKENS\endmark defines \first to be the first token in % TOKENS, and \rest to be the remainder. % @@ -2208,8 +2305,8 @@ where each line of input produces a line of output.} \let\go\pickupwholefraction \else \global\advance\colcount by 1 - \setbox0=\hbox{#1\unskip }% Add a normal word space as a separator; - % typically that is always in the input, anyway. + \setbox0=\hbox{#1\unskip\space}% 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 @@ -2224,18 +2321,18 @@ where each line of input produces a line of output.} \go } -% This used to have \hskip1sp. But then the space in a template line is -% not enough. That is bad. So let's go back to just & until we -% encounter the problem it was intended to solve again. -% --karl, nathan@acm.org, 20apr99. -\def\tab{&} - % @multitable ... @end multitable definitions: % \def\multitable{\parsearg\dotable} \def\dotable#1{\bgroup \vskip\parskip - \let\item\crcr + \let\item=\crcrwithfootnotes + % A \tab used to include \hskip1sp. But then the space in a template + % line is not enough. That is bad. So let's go back to just & until + % we encounter the problem it was intended to solve again. --karl, + % nathan@acm.org, 20apr99. + \let\tab=&% + \let\startfootins=\startsavedfootnote \tolerance=9500 \hbadness=9500 \setmultitablespacing @@ -2243,7 +2340,11 @@ where each line of input produces a line of output.} \parindent=\multitableparindent \overfullrule=0pt \global\colcount=0 - \def\Emultitable{\global\setpercentfalse\cr\egroup\egroup}% + \def\Emultitable{% + \global\setpercentfalse + \crcrwithfootnotes\crcr + \egroup\egroup + }% % % To parse everything between @multitable and @item: \setuptable#1 \endsetuptable @@ -2332,6 +2433,25 @@ width0pt\relax} \fi %% than skip between lines in the table. \fi} +% In case a @footnote appears inside an alignment, save the footnote +% text to a box and make the \insert when a row of the table is +% finished. Otherwise, the insertion is lost, it never migrates to the +% main vertical list. --kasal, 22jan03. +% +\newbox\savedfootnotes +% +% \dotable \let's \startfootins to this, so that \dofootnote will call +% it instead of starting the insertion right away. +\def\startsavedfootnote{% + \global\setbox\savedfootnotes = \vbox\bgroup + \unvbox\savedfootnotes +} +\def\crcrwithfootnotes{% + \crcr + \ifvoid\savedfootnotes \else + \noalign{\insert\footins{\box\savedfootnotes}}% + \fi +} \message{conditionals,} % Prevent errors for section commands. @@ -2367,65 +2487,117 @@ width0pt\relax} \fi % and so want to turn off most commands, in case they are used % incorrectly. % +% We use \empty instead of \relax for the @def... commands, so that \end +% doesn't throw an error. For instance: +% @ignore +% @deffn ... +% @end deffn +% @end ignore +% +% The @end deffn is going to get expanded, because we're trying to allow +% nested conditionals. But we don't want to expand the actual @deffn, +% since it might be syntactically correct and intended to be ignored. +% Since \end checks for \relax, using \empty does not cause an error. +% \def\ignoremorecommands{% \let\defcodeindex = \relax - \let\defcv = \relax - \let\deffn = \relax - \let\deffnx = \relax + \let\defcv = \empty + \let\defcvx = \empty + \let\Edefcv = \empty + \let\deffn = \empty + \let\deffnx = \empty + \let\Edeffn = \empty \let\defindex = \relax - \let\defivar = \relax - \let\defmac = \relax - \let\defmethod = \relax - \let\defop = \relax - \let\defopt = \relax - \let\defspec = \relax - \let\deftp = \relax - \let\deftypefn = \relax - \let\deftypefun = \relax - \let\deftypeivar = \relax - \let\deftypeop = \relax - \let\deftypevar = \relax - \let\deftypevr = \relax - \let\defun = \relax - \let\defvar = \relax - \let\defvr = \relax - \let\ref = \relax - \let\xref = \relax - \let\printindex = \relax - \let\pxref = \relax - \let\settitle = \relax - \let\setchapternewpage = \relax - \let\setchapterstyle = \relax - \let\everyheading = \relax + \let\defivar = \empty + \let\defivarx = \empty + \let\Edefivar = \empty + \let\defmac = \empty + \let\defmacx = \empty + \let\Edefmac = \empty + \let\defmethod = \empty + \let\defmethodx = \empty + \let\Edefmethod = \empty + \let\defop = \empty + \let\defopx = \empty + \let\Edefop = \empty + \let\defopt = \empty + \let\defoptx = \empty + \let\Edefopt = \empty + \let\defspec = \empty + \let\defspecx = \empty + \let\Edefspec = \empty + \let\deftp = \empty + \let\deftpx = \empty + \let\Edeftp = \empty + \let\deftypefn = \empty + \let\deftypefnx = \empty + \let\Edeftypefn = \empty + \let\deftypefun = \empty + \let\deftypefunx = \empty + \let\Edeftypefun = \empty + \let\deftypeivar = \empty + \let\deftypeivarx = \empty + \let\Edeftypeivar = \empty + \let\deftypemethod = \empty + \let\deftypemethodx = \empty + \let\Edeftypemethod = \empty + \let\deftypeop = \empty + \let\deftypeopx = \empty + \let\Edeftypeop = \empty + \let\deftypevar = \empty + \let\deftypevarx = \empty + \let\Edeftypevar = \empty + \let\deftypevr = \empty + \let\deftypevrx = \empty + \let\Edeftypevr = \empty + \let\defun = \empty + \let\defunx = \empty + \let\Edefun = \empty + \let\defvar = \empty + \let\defvarx = \empty + \let\Edefvar = \empty + \let\defvr = \empty + \let\defvrx = \empty + \let\Edefvr = \empty + \let\clear = \relax + \let\down = \relax + \let\evenfooting = \relax \let\evenheading = \relax - \let\oddheading = \relax \let\everyfooting = \relax - \let\evenfooting = \relax - \let\oddfooting = \relax + \let\everyheading = \relax \let\headings = \relax \let\include = \relax + \let\item = \relax \let\lowersections = \relax - \let\down = \relax + \let\oddfooting = \relax + \let\oddheading = \relax + \let\printindex = \relax + \let\pxref = \relax \let\raisesections = \relax - \let\up = \relax + \let\ref = \relax \let\set = \relax - \let\clear = \relax - \let\item = \relax + \let\setchapternewpage = \relax + \let\setchapterstyle = \relax + \let\settitle = \relax + \let\up = \relax + \let\verbatiminclude = \relax + \let\xref = \relax } -% Ignore @ignore, @ifhtml, @ifinfo, @ifplaintext, @ifnottex, @html, @menu, -% @direntry, and @documentdescription. +% Ignore @ignore, @ifhtml, @ifinfo, and the like. % -\def\ignore{\doignore{ignore}} +\def\direntry{\doignore{direntry}} +\def\documentdescriptionword{documentdescription} +\def\documentdescription{\doignore{documentdescription}} +\def\html{\doignore{html}} \def\ifhtml{\doignore{ifhtml}} \def\ifinfo{\doignore{ifinfo}} -\def\ifplaintext{\doignore{ifplaintext}} \def\ifnottex{\doignore{ifnottex}} -\def\html{\doignore{html}} +\def\ifplaintext{\doignore{ifplaintext}} +\def\ifxml{\doignore{ifxml}} +\def\ignore{\doignore{ignore}} \def\menu{\doignore{menu}} -\def\direntry{\doignore{direntry}} -\def\documentdescription{\doignore{documentdescription}} -\def\documentdescriptionword{documentdescription} +\def\xml{\doignore{xml}} % @dircategory CATEGORY -- specify a category of the dir file % which this file should belong to. Ignore this in TeX. @@ -2443,7 +2615,7 @@ width0pt\relax} \fi \long\def\doignoretext##1@end #1{\enddoignore}% % % Make sure that spaces turn into tokens that match what \doignoretext wants. - \catcode32 = 10 + \catcode\spaceChar = 10 % % Ignore braces, too, so mismatched braces don't cause trouble. \catcode`\{ = 9 @@ -2485,7 +2657,7 @@ width0pt\relax} \fi \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.org/pub/gnu/TeX.README.)} + \immediate\write16{ (See ftp://ftp.gnu.org/non-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.} @@ -2507,8 +2679,8 @@ width0pt\relax} \fi % We must actually expand the ignored text to look for the @end % command, so that nested ignore constructs work. Thus, we put the % text into a \vbox and then do nothing with the result. To minimize - % the change of memory overflow, we follow the approach outlined on - % page 401 of the TeXbook: make the current font be a dummy font. + % the chance of memory overflow, we follow the approach outlined on + % page 401 of the TeXbook. % \setbox0 = \vbox\bgroup % Don't complain about control sequences we have declared \outer. @@ -2529,8 +2701,8 @@ width0pt\relax} \fi % % Set the current font to be \nullfont, a TeX primitive, and define % all the font commands to also use \nullfont. We don't use - % dummy.tfm, as suggested in the TeXbook, because not all sites - % might have that installed. Therefore, math mode will still + % dummy.tfm, as suggested in the TeXbook, because some sites + % might not have that installed. Therefore, math mode will still % produce output, but that should be an extremely small amount of % stuff compared to the main input. % @@ -2559,7 +2731,7 @@ width0pt\relax} \fi % Do minimal line-breaking. \pretolerance = 10000 % - % Do not execute instructions in @tex + % Do not execute instructions in @tex. \def\tex{\doignore{tex}}% % Do not execute macro definitions. % `c' is a comment character, so the word `macro' will get cut off. @@ -2604,7 +2776,7 @@ width0pt\relax} \fi % we're called from @code, as @code{@value{foo-bar_}}. So \let any % such active characters to their normal equivalents. \gdef\value{\begingroup - \catcode`\-=12 \catcode`\_=12 + \catcode`\-=\other \catcode`\_=\other \indexbreaks \let_\normalunderscore \valuexxx} } @@ -2613,15 +2785,17 @@ width0pt\relax} \fi % We have this subroutine so that we can handle at least some @value's % properly in indexes (we \let\value to this in \indexdummies). Ones % whose names contain - or _ still won't work, but we can't do anything -% about that. The command has to be fully expandable, since the result -% winds up in the index file. This means that if the variable's value -% contains other Texinfo commands, it's almost certain it will fail -% (although perhaps we could fix that with sufficient work to do a -% one-level expansion on the result, instead of complete). +% about that. The command has to be fully expandable (if the variable +% is set), since the result winds up in the index file. This means that +% if the variable's value contains other Texinfo commands, it's almost +% certain it will fail (although perhaps we could fix that with +% sufficient work to do a one-level expansion on the result, instead of +% complete). % \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax {[No value for ``#1'']}% + \message{Variable `#1', used in @value, is not set.}% \else \csname SET#1\endcsname \fi @@ -2630,13 +2804,14 @@ width0pt\relax} \fi % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. % -\def\ifset{\parsearg\ifsetxxx} -\def\ifsetxxx #1{% +\def\ifset{\parsearg\doifset} +\def\doifset#1{% \expandafter\ifx\csname SET#1\endcsname\relax - \expandafter\ifsetfail + \let\next=\ifsetfail \else - \expandafter\ifsetsucceed + \let\next=\ifsetsucceed \fi + \next } \def\ifsetsucceed{\conditionalsucceed{ifset}} \def\ifsetfail{\nestedignore{ifset}} @@ -2645,13 +2820,14 @@ width0pt\relax} \fi % @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been % defined with @set, or has been undefined with @clear. % -\def\ifclear{\parsearg\ifclearxxx} -\def\ifclearxxx #1{% +\def\ifclear{\parsearg\doifclear} +\def\doifclear#1{% \expandafter\ifx\csname SET#1\endcsname\relax - \expandafter\ifclearsucceed + \let\next=\ifclearsucceed \else - \expandafter\ifclearfail + \let\next=\ifclearfail \fi + \next } \def\ifclearsucceed{\conditionalsucceed{ifclear}} \def\ifclearfail{\nestedignore{ifclear}} @@ -2670,28 +2846,13 @@ width0pt\relax} \fi \defineunmatchedend{ifnotinfo} \defineunmatchedend{ifnotplaintext} -% We can't just want to start a group at @iftex (etc.) and end it at -% @end iftex, since then @set commands inside the conditional have no -% effect (they'd get reverted at the end of the group). So we must -% define \Eiftex to redefine itself to be its previous value. (We can't -% just define it to fail again with an ``unmatched end'' error, since -% the @ifset might be nested.) -% -\def\conditionalsucceed#1{% - \edef\temp{% - % Remember the current value of \E#1. - \let\nece{prevE#1} = \nece{E#1}% - % - % At the `@end #1', redefine \E#1 to be its previous value. - \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% - }% - \temp -} - -% We need to expand lots of \csname's, but we don't want to expand the -% control sequences after we've constructed them. +% True conditional. Since \set globally defines its variables, we can +% just start and end a group (to keep the @end definition undefined at +% the outer level). % -\def\nece#1{\expandafter\noexpand\csname#1\endcsname} +\def\conditionalsucceed#1{\begingroup + \expandafter\def\csname E#1\endcsname{\endgroup}% +} % @defininfoenclose. \let\definfoenclose=\comment @@ -2784,104 +2945,166 @@ width0pt\relax} \fi \def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} \def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} -% 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.) +% Take care of Texinfo commands that can appear in an index entry. +% Since there are some commands we want to expand, and others we don't, +% we have to laboriously prevent expansion for those that we don't. % \def\indexdummies{% -\def\ { }% -\def\@{@}% change to @@ when we switch to @ as escape char in aux files. -% Need these in case \tex is in effect and \{ is a \delimiter again. -% But can't use \lbracecmd and \rbracecmd because texindex assumes -% braces and backslashes are used only as delimiters. -\let\{ = \mylbrace -\let\} = \myrbrace -\def\_{{\realbackslash _}}% -\normalturnoffactive -% -% Take care of the plain tex accent commands. -\def\,##1{\realbackslash ,{##1}}% -\def\"{\realbackslash "}% -\def\`{\realbackslash `}% -\def\'{\realbackslash '}% -\def\^{\realbackslash ^}% -\def\~{\realbackslash ~}% -\def\={\realbackslash =}% -\def\b{\realbackslash b}% -\def\c{\realbackslash c}% -\def\d{\realbackslash d}% -\def\u{\realbackslash u}% -\def\v{\realbackslash v}% -\def\H{\realbackslash H}% -\def\dotless##1{\realbackslash dotless {##1}}% -% Take care of the plain tex special European modified letters. -\def\AA{\realbackslash AA}% -\def\AE{\realbackslash AE}% -\def\L{\realbackslash L}% -\def\OE{\realbackslash OE}% -\def\O{\realbackslash O}% -\def\aa{\realbackslash aa}% -\def\ae{\realbackslash ae}% -\def\l{\realbackslash l}% -\def\oe{\realbackslash oe}% -\def\o{\realbackslash o}% -\def\ss{\realbackslash ss}% -% -% Although these internals commands shouldn't show up, sometimes they do. -\def\bf{\realbackslash bf }% -\def\gtr{\realbackslash gtr}% -\def\hat{\realbackslash hat}% -\def\less{\realbackslash less}% -%\def\rm{\realbackslash rm }% -\def\sf{\realbackslash sf}% -\def\sl{\realbackslash sl }% -\def\tclose##1{\realbackslash tclose {##1}}% -\def\tt{\realbackslash tt}% -% -\def\b##1{\realbackslash b {##1}}% -\def\i##1{\realbackslash i {##1}}% -\def\sc##1{\realbackslash sc {##1}}% -\def\t##1{\realbackslash t {##1}}% -\def\r##1{\realbackslash r {##1}}% -% -\def\TeX{\realbackslash TeX}% -\def\acronym##1{\realbackslash acronym {##1}}% -\def\cite##1{\realbackslash cite {##1}}% -\def\code##1{\realbackslash code {##1}}% -\def\command##1{\realbackslash command {##1}}% -\def\dfn##1{\realbackslash dfn {##1}}% -\def\dots{\realbackslash dots }% -\def\emph##1{\realbackslash emph {##1}}% -\def\env##1{\realbackslash env {##1}}% -\def\file##1{\realbackslash file {##1}}% -\def\kbd##1{\realbackslash kbd {##1}}% -\def\key##1{\realbackslash key {##1}}% -\def\math##1{\realbackslash math {##1}}% -\def\option##1{\realbackslash option {##1}}% -\def\samp##1{\realbackslash samp {##1}}% -\def\strong##1{\realbackslash strong {##1}}% -\def\uref##1{\realbackslash uref {##1}}% -\def\url##1{\realbackslash url {##1}}% -\def\var##1{\realbackslash var {##1}}% -\def\w{\realbackslash w }% -% -% These math commands don't seem likely to be used in index entries. -\def\copyright{\realbackslash copyright}% -\def\equiv{\realbackslash equiv}% -\def\error{\realbackslash error}% -\def\expansion{\realbackslash expansion}% -\def\point{\realbackslash point}% -\def\print{\realbackslash print}% -\def\result{\realbackslash result}% -% -% Handle some cases of @value -- where the variable name does not -% contain - or _, and the value does not contain any -% (non-fully-expandable) commands. -\let\value = \expandablevalue -% -\unsepspaces -% Turn off macro expansion -\turnoffmacros + \def\@{@}% change to @@ when we switch to @ as escape char in index files. + \def\ {\realbackslash\space }% + % Need these in case \tex is in effect and \{ is a \delimiter again. + % But can't use \lbracecmd and \rbracecmd because texindex assumes + % braces and backslashes are used only as delimiters. + \let\{ = \mylbrace + \let\} = \myrbrace + % + % \definedummyword defines \#1 as \realbackslash #1\space, thus + % effectively preventing its expansion. This is used only for control + % words, not control letters, because the \space would be incorrect + % for control characters, but is needed to separate the control word + % from whatever follows. + % + % For control letters, we have \definedummyletter, which omits the + % space. + % + % These can be used both for control words that take an argument and + % those that do not. If it is followed by {arg} in the input, then + % that will dutifully get written to the index (or wherever). + % + \def\definedummyword##1{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{\realbackslash ##1}% + }% + % + % Do the redefinitions. + \commondummies +} + +% For the aux file, @ is the escape character. So we want to redefine +% everything using @ instead of \realbackslash. When everything uses +% @, this will be simpler. +% +\def\atdummies{% + \def\@{@@}% + \def\ {@ }% + \let\{ = \lbraceatcmd + \let\} = \rbraceatcmd + % + % (See comments in \indexdummies.) + \def\definedummyword##1{% + \expandafter\def\csname ##1\endcsname{@##1\space}% + }% + \def\definedummyletter##1{% + \expandafter\def\csname ##1\endcsname{@##1}% + }% + % + % Do the redefinitions. + \commondummies +} + +% Called from \indexdummies and \atdummies. \definedummyword and +% \definedummyletter must be defined first. +% +\def\commondummies{% + % + \normalturnoffactive + % + % Control letters and accents. + \definedummyletter{_}% + \definedummyletter{,}% + \definedummyletter{"}% + \definedummyletter{`}% + \definedummyletter{'}% + \definedummyletter{^}% + \definedummyletter{~}% + \definedummyletter{=}% + \definedummyword{u}% + \definedummyword{v}% + \definedummyword{H}% + \definedummyword{dotaccent}% + \definedummyword{ringaccent}% + \definedummyword{tieaccent}% + \definedummyword{ubaraccent}% + \definedummyword{udotaccent}% + \definedummyword{dotless}% + % + % Other non-English letters. + \definedummyword{AA}% + \definedummyword{AE}% + \definedummyword{L}% + \definedummyword{OE}% + \definedummyword{O}% + \definedummyword{aa}% + \definedummyword{ae}% + \definedummyword{l}% + \definedummyword{oe}% + \definedummyword{o}% + \definedummyword{ss}% + % + % Although these internal commands shouldn't show up, sometimes they do. + \definedummyword{bf}% + \definedummyword{gtr}% + \definedummyword{hat}% + \definedummyword{less}% + \definedummyword{sf}% + \definedummyword{sl}% + \definedummyword{tclose}% + \definedummyword{tt}% + % + % Texinfo font commands. + \definedummyword{b}% + \definedummyword{i}% + \definedummyword{r}% + \definedummyword{sc}% + \definedummyword{t}% + % + \definedummyword{TeX}% + \definedummyword{acronym}% + \definedummyword{cite}% + \definedummyword{code}% + \definedummyword{command}% + \definedummyword{dfn}% + \definedummyword{dots}% + \definedummyword{emph}% + \definedummyword{env}% + \definedummyword{file}% + \definedummyword{kbd}% + \definedummyword{key}% + \definedummyword{math}% + \definedummyword{option}% + \definedummyword{samp}% + \definedummyword{strong}% + \definedummyword{uref}% + \definedummyword{url}% + \definedummyword{var}% + \definedummyword{w}% + % + % Assorted special characters. + \definedummyword{bullet}% + \definedummyword{copyright}% + \definedummyword{dots}% + \definedummyword{enddots}% + \definedummyword{equiv}% + \definedummyword{error}% + \definedummyword{expansion}% + \definedummyword{minus}% + \definedummyword{pounds}% + \definedummyword{point}% + \definedummyword{print}% + \definedummyword{result}% + % + % Handle some cases of @value -- where the variable name does not + % contain - or _, and the value does not contain any + % (non-fully-expandable) commands. + \let\value = \expandablevalue + % + % Normal spaces, not active ones. + \unsepspaces + % + % No macro expansion. + \turnoffmacros } % If an index command is used in an @example environment, any spaces @@ -2890,83 +3113,86 @@ width0pt\relax} \fi {\obeyspaces \gdef\unsepspaces{\obeyspaces\let =\space}} -% \indexnofonts no-ops all font-change commands. -% This is used when outputting the strings to sort the index by. -\def\indexdummyfont#1{#1} + +% \indexnofonts is used when outputting the strings to sort the index +% by, and when constructing control sequence names. It eliminates all +% control sequences and just writes whatever the best ASCII sort string +% would be for a given command (usually its argument). +% \def\indexdummytex{TeX} \def\indexdummydots{...} - +% \def\indexnofonts{% -\def\@{@}% -% how to handle braces? -\def\_{\normalunderscore}% -% -\let\,=\indexdummyfont -\let\"=\indexdummyfont -\let\`=\indexdummyfont -\let\'=\indexdummyfont -\let\^=\indexdummyfont -\let\~=\indexdummyfont -\let\==\indexdummyfont -\let\b=\indexdummyfont -\let\c=\indexdummyfont -\let\d=\indexdummyfont -\let\u=\indexdummyfont -\let\v=\indexdummyfont -\let\H=\indexdummyfont -\let\dotless=\indexdummyfont -% Take care of the plain tex special European modified letters. -\def\AA{AA}% -\def\AE{AE}% -\def\L{L}% -\def\OE{OE}% -\def\O{O}% -\def\aa{aa}% -\def\ae{ae}% -\def\l{l}% -\def\oe{oe}% -\def\o{o}% -\def\ss{ss}% -% -% Don't no-op \tt, since it isn't a user-level command -% and is used in the definitions of the active chars like <, >, |, etc. -% Likewise with the other plain tex font commands. -%\let\tt=\indexdummyfont -% -\let\b=\indexdummyfont -\let\i=\indexdummyfont -\let\r=\indexdummyfont -\let\sc=\indexdummyfont -\let\t=\indexdummyfont -% -\let\TeX=\indexdummytex -\let\acronym=\indexdummyfont -\let\cite=\indexdummyfont -\let\code=\indexdummyfont -\let\command=\indexdummyfont -\let\dfn=\indexdummyfont -\let\dots=\indexdummydots -\let\emph=\indexdummyfont -\let\env=\indexdummyfont -\let\file=\indexdummyfont -\let\kbd=\indexdummyfont -\let\key=\indexdummyfont -\let\math=\indexdummyfont -\let\option=\indexdummyfont -\let\samp=\indexdummyfont -\let\strong=\indexdummyfont -\let\uref=\indexdummyfont -\let\url=\indexdummyfont -\let\var=\indexdummyfont -\let\w=\indexdummyfont -} - -% To define \realbackslash, we must make \ not be an escape. -% We must first make another character (@) an escape -% so we do not become unable to do a definition. - -{\catcode`\@=0 \catcode`\\=\other - @gdef@realbackslash{\}} + \def\ { }% + \def\@{@}% + % how to handle braces? + \def\_{\normalunderscore}% + % + \let\,=\asis + \let\"=\asis + \let\`=\asis + \let\'=\asis + \let\^=\asis + \let\~=\asis + \let\==\asis + \let\u=\asis + \let\v=\asis + \let\H=\asis + \let\dotaccent=\asis + \let\ringaccent=\asis + \let\tieaccent=\asis + \let\ubaraccent=\asis + \let\udotaccent=\asis + \let\dotless=\asis + % + % Other non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\aa{aa}% + \def\ae{ae}% + \def\l{l}% + \def\oe{oe}% + \def\o{o}% + \def\ss{ss}% + \def\exclamdown{!}% + \def\questiondown{?}% + % + % Don't no-op \tt, since it isn't a user-level command + % and is used in the definitions of the active chars like <, >, |, etc. + % Likewise with the other plain tex font commands. + %\let\tt=\asis + % + % Texinfo font commands. + \let\b=\asis + \let\i=\asis + \let\r=\asis + \let\sc=\asis + \let\t=\asis + % + \let\TeX=\indexdummytex + \let\acronym=\asis + \let\cite=\asis + \let\code=\asis + \let\command=\asis + \let\dfn=\asis + \let\dots=\indexdummydots + \let\emph=\asis + \let\env=\asis + \let\file=\asis + \let\kbd=\asis + \let\key=\asis + \let\math=\asis + \let\option=\asis + \let\samp=\asis + \let\strong=\asis + \let\uref=\asis + \let\url=\asis + \let\var=\asis + \let\w=\asis +} \let\indexbackslash=0 %overridden during \printindex. \let\SETmarginindex=\relax % put index entries in margin (undocumented)? @@ -2998,28 +3224,24 @@ width0pt\relax} \fi \def\rawbackslashxx{\indexbackslash}% \indexbackslash isn't defined now % so it will be output as is; and it will print as backslash. % - \def\thirdarg{#3}% - % - % If third arg is present, precede it with space in sort key. - \ifx\thirdarg\emptymacro - \let\subentry = \empty - \else - \def\subentry{ #3}% - \fi - % - % First process the index entry with all font commands turned - % off to get the string to sort by. - {\indexnofonts \xdef\indexsorttmp{#2\subentry}}% - % - % Now the real index entry with the fonts. + % The main index entry text. \toks0 = {#2}% % - % If the third (subentry) arg is present, add it to the index - % line to write. + % If third arg is present, precede it with space in sort key. + \def\thirdarg{#3}% \ifx\thirdarg\emptymacro \else - \toks0 = \expandafter{\the\toks0{#3}}% + % If the third (subentry) arg is present, add it to the index + % line to write. + \toks0 = \expandafter{\the\toks0 \space #3}% \fi % + % Process the index entry with all font commands turned off, to + % get the string to sort by. + {\indexnofonts + \edef\temp{\the\toks0}% need full expansion + \xdef\indexsorttmp{\temp}% + }% + % % Set up the complete index entry, with both the sort key and % the original text, including any font commands. We write % three arguments to \entry to the .?? file (four in the @@ -3050,12 +3272,11 @@ width0pt\relax} \fi \iflinks \ifvmode \skip0 = \lastskip - \ifdim\lastskip = 0pt \else \nobreak\vskip-\lastskip \fi + \ifdim\lastskip = 0pt \else \nobreak\vskip-\skip0 \fi \fi % \temp % do the write % - % \ifvmode \ifdim\skip0 = 0pt \else \nobreak\vskip\skip0 \fi \fi \fi }% @@ -3531,42 +3752,41 @@ width0pt\relax} \fi \outer\def\chapter{\parsearg\chapteryyy} \def\chapteryyy #1{\numhead0{#1}} % normally numhead0 calls chapterzzz \def\chapterzzz #1{% -\secno=0 \subsecno=0 \subsubsecno=0 -\global\advance \chapno by 1 \message{\putwordChapter\space \the\chapno}% -\chapmacro {#1}{\the\chapno}% -\gdef\thissection{#1}% -\gdef\thischaptername{#1}% -% We don't substitute the actual chapter name into \thischapter -% because we don't want its macros evaluated now. -\xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash chapentry{\the\toks0}% - {\the\chapno}}}% -\temp -\donoderef -\global\let\section = \numberedsec -\global\let\subsection = \numberedsubsec -\global\let\subsubsection = \numberedsubsubsec -} + \secno=0 \subsecno=0 \subsubsecno=0 + \global\advance \chapno by 1 \message{\putwordChapter\space \the\chapno}% + \chapmacro {#1}{\the\chapno}% + \gdef\thissection{#1}% + \gdef\thischaptername{#1}% + % We don't substitute the actual chapter name into \thischapter + % because we don't want its macros evaluated now. + \xdef\thischapter{\putwordChapter{} \the\chapno: \noexpand\thischaptername}% + \writetocentry{chap}{#1}{{\the\chapno}} + \donoderef + \global\let\section = \numberedsec + \global\let\subsection = \numberedsubsec + \global\let\subsubsection = \numberedsubsubsec +} + +% we use \chapno to avoid indenting back +\def\appendixbox#1{% + \setbox0 = \hbox{\putwordAppendix{} \the\chapno}% + \hbox to \wd0{#1\hss}} \outer\def\appendix{\parsearg\appendixyyy} \def\appendixyyy #1{\apphead0{#1}} % normally apphead0 calls appendixzzz \def\appendixzzz #1{% -\secno=0 \subsecno=0 \subsubsecno=0 -\global\advance \appendixno by 1 -\message{\putwordAppendix\space \appendixletter}% -\chapmacro {#1}{\putwordAppendix{} \appendixletter}% -\gdef\thissection{#1}% -\gdef\thischaptername{#1}% -\xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash appendixentry{\the\toks0}% - {\appendixletter}}}% -\temp -\appendixnoderef -\global\let\section = \appendixsec -\global\let\subsection = \appendixsubsec -\global\let\subsubsection = \appendixsubsubsec + \secno=0 \subsecno=0 \subsubsecno=0 + \global\advance \appendixno by 1 + \message{\putwordAppendix\space \appendixletter}% + \chapmacro {#1}{\appendixbox{\putwordAppendix{} \appendixletter}}% + \gdef\thissection{#1}% + \gdef\thischaptername{#1}% + \xdef\thischapter{\putwordAppendix{} \appendixletter: \noexpand\thischaptername}% + \writetocentry{appendix}{#1}{{\appendixletter}} + \appendixnoderef + \global\let\section = \appendixsec + \global\let\subsection = \appendixsubsec + \global\let\subsubsection = \appendixsubsubsec } % @centerchap is like @unnumbered, but the heading is centered. @@ -3579,150 +3799,121 @@ width0pt\relax} \fi \outer\def\unnumbered{\parsearg\unnumberedyyy} \def\unnumberedyyy #1{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz \def\unnumberedzzz #1{% -\secno=0 \subsecno=0 \subsubsecno=0 -% -% This used to be simply \message{#1}, but TeX fully expands the -% argument to \message. Therefore, if #1 contained @-commands, TeX -% expanded them. For example, in `@unnumbered The @cite{Book}', TeX -% expanded @cite (which turns out to cause errors because \cite is meant -% to be executed, not expanded). -% -% Anyway, we don't want the fully-expanded definition of @cite to appear -% as a result of the \message, we just want `@cite' itself. We use -% \the<toks register> to achieve this: TeX expands \the<toks> only once, -% simply yielding the contents of <toks register>. (We also do this for -% the toc entries.) -\toks0 = {#1}\message{(\the\toks0)}% -% -\unnumbchapmacro {#1}% -\gdef\thischapter{#1}\gdef\thissection{#1}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbchapentry{\the\toks0}}}% -\temp -\unnumbnoderef -\global\let\section = \unnumberedsec -\global\let\subsection = \unnumberedsubsec -\global\let\subsubsection = \unnumberedsubsubsec + \secno=0 \subsecno=0 \subsubsecno=0 + % + % This used to be simply \message{#1}, but TeX fully expands the + % argument to \message. Therefore, if #1 contained @-commands, TeX + % expanded them. For example, in `@unnumbered The @cite{Book}', TeX + % expanded @cite (which turns out to cause errors because \cite is meant + % to be executed, not expanded). + % + % Anyway, we don't want the fully-expanded definition of @cite to appear + % as a result of the \message, we just want `@cite' itself. We use + % \the<toks register> to achieve this: TeX expands \the<toks> only once, + % simply yielding the contents of <toks register>. (We also do this for + % the toc entries.) + \toks0 = {#1}\message{(\the\toks0)}% + % + \unnumbchapmacro {#1}% + \gdef\thischapter{#1}\gdef\thissection{#1}% + \writetocentry{unnumbchap}{#1}{{\the\chapno}} + \unnumbnoderef + \global\let\section = \unnumberedsec + \global\let\subsection = \unnumberedsubsec + \global\let\subsubsection = \unnumberedsubsubsec } % Sections. \outer\def\numberedsec{\parsearg\secyyy} \def\secyyy #1{\numhead1{#1}} % normally calls seczzz \def\seczzz #1{% -\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % -\gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}% - {\the\chapno}{\the\secno}}}% -\temp -\donoderef -\nobreak + \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % + \gdef\thissection{#1}\secheading {#1}{\the\chapno}{\the\secno}% + \writetocentry{sec}{#1}{{\the\chapno}{\the\secno}} + \donoderef + \nobreak } \outer\def\appendixsection{\parsearg\appendixsecyyy} \outer\def\appendixsec{\parsearg\appendixsecyyy} \def\appendixsecyyy #1{\apphead1{#1}} % normally calls appendixsectionzzz \def\appendixsectionzzz #1{% -\subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % -\gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash secentry{\the\toks0}% - {\appendixletter}{\the\secno}}}% -\temp -\appendixnoderef -\nobreak + \subsecno=0 \subsubsecno=0 \global\advance \secno by 1 % + \gdef\thissection{#1}\secheading {#1}{\appendixletter}{\the\secno}% + \writetocentry{sec}{#1}{{\appendixletter}{\the\secno}} + \appendixnoderef + \nobreak } \outer\def\unnumberedsec{\parsearg\unnumberedsecyyy} \def\unnumberedsecyyy #1{\unnmhead1{#1}} % normally calls unnumberedseczzz \def\unnumberedseczzz #1{% -\plainsecheading {#1}\gdef\thissection{#1}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsecentry% - {\the\toks0}{\the\chapno}}}% -\temp -\unnumbnoderef -\nobreak + \plainsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsec}{#1}{{\the\chapno}{\the\secno}} + \unnumbnoderef + \nobreak } % Subsections. \outer\def\numberedsubsec{\parsearg\numberedsubsecyyy} \def\numberedsubsecyyy #1{\numhead2{#1}} % normally calls numberedsubseczzz \def\numberedsubseczzz #1{% -\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % -\subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}% - {\the\chapno}{\the\secno}{\the\subsecno}}}% -\temp -\donoderef -\nobreak + \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % + \subsecheading {#1}{\the\chapno}{\the\secno}{\the\subsecno}% + \writetocentry{subsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} + \donoderef + \nobreak } \outer\def\appendixsubsec{\parsearg\appendixsubsecyyy} \def\appendixsubsecyyy #1{\apphead2{#1}} % normally calls appendixsubseczzz \def\appendixsubseczzz #1{% -\gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % -\subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash subsecentry{\the\toks0}% - {\appendixletter}{\the\secno}{\the\subsecno}}}% -\temp -\appendixnoderef -\nobreak + \gdef\thissection{#1}\subsubsecno=0 \global\advance \subsecno by 1 % + \subsecheading {#1}{\appendixletter}{\the\secno}{\the\subsecno}% + \writetocentry{subsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}} + \appendixnoderef + \nobreak } \outer\def\unnumberedsubsec{\parsearg\unnumberedsubsecyyy} \def\unnumberedsubsecyyy #1{\unnmhead2{#1}} %normally calls unnumberedsubseczzz \def\unnumberedsubseczzz #1{% -\plainsubsecheading {#1}\gdef\thissection{#1}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsecentry% - {\the\toks0}{\the\chapno}{\the\secno}}}% -\temp -\unnumbnoderef -\nobreak + \plainsubsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}} + \unnumbnoderef + \nobreak } % Subsubsections. \outer\def\numberedsubsubsec{\parsearg\numberedsubsubsecyyy} \def\numberedsubsubsecyyy #1{\numhead3{#1}} % normally numberedsubsubseczzz \def\numberedsubsubseczzz #1{% -\gdef\thissection{#1}\global\advance \subsubsecno by 1 % -\subsubsecheading {#1} - {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}% - {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}% -\temp -\donoderef -\nobreak + \gdef\thissection{#1}\global\advance \subsubsecno by 1 % + \subsubsecheading {#1} + {\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}% + \writetocentry{subsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \donoderef + \nobreak } \outer\def\appendixsubsubsec{\parsearg\appendixsubsubsecyyy} \def\appendixsubsubsecyyy #1{\apphead3{#1}} % normally appendixsubsubseczzz \def\appendixsubsubseczzz #1{% -\gdef\thissection{#1}\global\advance \subsubsecno by 1 % -\subsubsecheading {#1} - {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash subsubsecentry{\the\toks0}% - {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}}}% -\temp -\appendixnoderef -\nobreak + \gdef\thissection{#1}\global\advance \subsubsecno by 1 % + \subsubsecheading {#1} + {\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}% + \writetocentry{subsubsec}{#1}{{\appendixletter}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \appendixnoderef + \nobreak } \outer\def\unnumberedsubsubsec{\parsearg\unnumberedsubsubsecyyy} \def\unnumberedsubsubsecyyy #1{\unnmhead3{#1}} %normally unnumberedsubsubseczzz \def\unnumberedsubsubseczzz #1{% -\plainsubsubsecheading {#1}\gdef\thissection{#1}% -\toks0 = {#1}% -\edef\temp{\noexpand\writetocentry{\realbackslash unnumbsubsubsecentry% - {\the\toks0}{\the\chapno}{\the\secno}{\the\subsecno}}}% -\temp -\unnumbnoderef -\nobreak + \plainsubsubsecheading {#1}\gdef\thissection{#1}% + \writetocentry{unnumbsubsubsec}{#1}{{\the\chapno}{\the\secno}{\the\subsecno}{\the\subsubsecno}} + \unnumbnoderef + \nobreak } % These are variants which are not "outer", so they can appear in @ifinfo. @@ -3763,16 +3954,16 @@ width0pt\relax} \fi \def\majorheading{\parsearg\majorheadingzzz} \def\majorheadingzzz #1{% -{\advance\chapheadingskip by 10pt \chapbreak }% -{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} + {\advance\chapheadingskip by 10pt \chapbreak }% + {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} \def\chapheading{\parsearg\chapheadingzzz} \def\chapheadingzzz #1{\chapbreak % -{\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\penalty 200} + {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 + \parindent=0pt\raggedright + \rm #1\hfill}}\bigskip \par\penalty 200} % @heading, @subheading, @subsubheading. \def\heading{\parsearg\plainsecheading} @@ -3918,7 +4109,16 @@ width0pt\relax} \fi \hangindent = \wd0 % zero if no section number \unhbox0 #3}% }% - \ifdim\parskip<10pt \nobreak\kern10pt\nobreak\kern-\parskip\fi \nobreak + % Add extra space after the heading -- either a line space or a + % paragraph space, whichever is more. (Some people like to set + % \parskip to large values for some reason.) Don't allow stretch, though. + \nobreak + \ifdim\parskip>\normalbaselineskip + \kern\parskip + \else + \kern\normalbaselineskip + \fi + \nobreak } @@ -3930,16 +4130,22 @@ width0pt\relax} \fi % Called from @chapter, etc. We supply {\folio} at the end of the % argument, which will end up as the last argument to the \...entry macro. % -% We open the .toc file here instead of at @setfilename or any other -% fixed time so that @contents can be put in the document anywhere. +% Usage: \writetocentry{chap}{The Name of The Game}{{\the\chapno}} +% We open the .toc file for writing here instead of at @setfilename (or +% any other fixed time) so that @contents can be anywhere in the document. % \newif\iftocfileopened -\def\writetocentry#1{% +\def\writetocentry#1#2#3{% \iftocfileopened\else \immediate\openout\tocfile = \jobname.toc \global\tocfileopenedtrue \fi - \iflinks \write\tocfile{#1{\folio}}\fi + % + \iflinks + \toks0 = {#2}% + \edef\temp{\write\tocfile{\realbackslash #1entry{\the\toks0}#3{\folio}}}% + \temp + \fi % % Tell \shipout to create a page destination if we're doing pdf, which % will be the target of the links in the table of contents. We can't @@ -3978,7 +4184,7 @@ width0pt\relax} \fi \advance\hsize by -\contentsrightmargin % Don't use the full line length. % % Roman numerals for page numbers. - \ifnum \pageno>0 \pageno = \lastnegativepageno \fi + \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi } @@ -3995,7 +4201,7 @@ width0pt\relax} \fi \pdfmakeoutlines \endgroup \lastnegativepageno = \pageno - \pageno = \savepageno + \global\pageno = \savepageno } % And just the chapters. @@ -4007,16 +4213,17 @@ width0pt\relax} \fi \let\unnumbchapentry = \shortunnumberedentry % We want a true roman here for the page numbers. \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl + \let\rm=\shortcontrm \let\bf=\shortcontbf + \let\sl=\shortcontsl \let\tt=\shortconttt \rm \hyphenpenalty = 10000 \advance\baselineskip by 1pt % Open it up a little. \def\secentry ##1##2##3##4{} - \def\unnumbsecentry ##1##2##3{} \def\subsecentry ##1##2##3##4##5{} - \def\unnumbsubsecentry ##1##2##3##4{} \def\subsubsecentry ##1##2##3##4##5##6{} - \def\unnumbsubsubsecentry ##1##2##3##4##5{} + \let\unnumbsecentry = \secentry + \let\unnumbsubsecentry = \subsecentry + \let\unnumbsubsubsecentry = \subsubsecentry \openin 1 \jobname.toc \ifeof 1 \else \closein 1 @@ -4026,7 +4233,7 @@ width0pt\relax} \fi \contentsalignmacro % in case @setchapternewpage odd is in effect \endgroup \lastnegativepageno = \pageno - \pageno = \savepageno + \global\pageno = \savepageno } \let\shortcontents = \summarycontents @@ -4049,7 +4256,8 @@ width0pt\relax} \fi } % Appendices, in the main contents. -\def\appendixentry#1#2#3{\dochapentry{\putwordAppendix{} #2\labelspace#1}{#3}} +\def\appendixentry#1#2#3{% + \dochapentry{\appendixbox{\putwordAppendix{} #2}\labelspace#1}{#3}} % % Appendices, in the short toc. \let\shortappendixentry = \shortchapentry @@ -4073,21 +4281,21 @@ width0pt\relax} \fi } % Unnumbered chapters. -\def\unnumbchapentry#1#2{\dochapentry{#1}{#2}} -\def\shortunnumberedentry#1#2{\tocentry{#1}{\doshortpageno\bgroup#2\egroup}} +\def\unnumbchapentry#1#2#3{\dochapentry{#1}{#3}} +\def\shortunnumberedentry#1#2#3{\tocentry{#1}{\doshortpageno\bgroup#3\egroup}} % Sections. \def\secentry#1#2#3#4{\dosecentry{#2.#3\labelspace#1}{#4}} -\def\unnumbsecentry#1#2#3{\dosecentry{#1}{#3}} +\def\unnumbsecentry#1#2#3#4{\dosecentry{#1}{#4}} % Subsections. \def\subsecentry#1#2#3#4#5{\dosubsecentry{#2.#3.#4\labelspace#1}{#5}} -\def\unnumbsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} +\def\unnumbsubsecentry#1#2#3#4#5{\dosubsecentry{#1}{#5}} % And subsubsections. \def\subsubsecentry#1#2#3#4#5#6{% \dosubsubsecentry{#2.#3.#4.#5\labelspace#1}{#6}} -\def\unnumbsubsubsecentry#1#2#3#4#5{\dosubsubsecentry{#1}{#5}} +\def\unnumbsubsubsecentry#1#2#3#4#5#6{\dosubsubsecentry{#1}{#6}} % This parameter controls the indentation of the various levels. \newdimen\tocindent \tocindent = 3pc @@ -4189,14 +4397,14 @@ width0pt\relax} \fi \def\tex{\begingroup \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 - \catcode `\^=7 \catcode `\_=8 \catcode `\~=13 \let~=\tie + \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie \catcode `\%=14 - \catcode 43=12 % plus - \catcode`\"=12 - \catcode`\==12 - \catcode`\|=12 - \catcode`\<=12 - \catcode`\>=12 + \catcode `\+=\other + \catcode `\"=\other + \catcode `\==\other + \catcode `\|=\other + \catcode `\<=\other + \catcode `\>=\other \escapechar=`\\ % \let\b=\ptexb @@ -4250,15 +4458,18 @@ width0pt\relax} \fi % Make spacing and below environment symmetrical. We use \parskip here % to help in doing that, since in @example-like environments \parskip % is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip +% start of the next paragraph will insert \parskip. % \def\aboveenvbreak{{% - \ifnum\lastpenalty < 10000 + % =10000 instead of <10000 because of a special case in \itemzzz, q.v. + \ifnum \lastpenalty=10000 \else \advance\envskipamount by \parskip \endgraf \ifdim\lastskip<\envskipamount \removelastskip - \penalty-50 + % it's not a good place to break if the last penalty was \nobreak + % or better ... + \ifnum\lastpenalty>10000 \else \penalty-50 \fi \vskip\envskipamount \fi \fi @@ -4290,7 +4501,8 @@ width0pt\relax} \fi % \newskip\lskip\newskip\rskip -\long\def\cartouche{% +\def\cartouche{% +\par % can't be in the midst of a paragraph. \begingroup \lskip=\leftskip \rskip=\rightskip \leftskip=0pt\rightskip=0pt %we want these *outside*. @@ -4337,7 +4549,6 @@ width0pt\relax} \fi \inENV % This group ends at the end of the body \hfuzz = 12pt % Don't be fussy \sepspaces % Make spaces be word-separators rather than space tokens. - \singlespace \let\par = \lisppar % don't ignore blank lines \obeylines % each line of input is a line of output \parskip = 0pt @@ -4376,27 +4587,16 @@ width0pt\relax} \fi % @example: Same as @lisp. \def\example{\begingroup \def\Eexample{\nonfillfinish\endgroup}\lisp} -% @small... is usually equivalent to the non-small (@smallbook -% redefines). We must call \example (or whatever) last in the -% definition, since it reads the return following the @example (or -% whatever) command. -% -% This actually allows (for example) @end display inside an -% @smalldisplay. Too bad, but makeinfo will catch the error anyway. -% -\def\smalldisplay{\begingroup\def\Esmalldisplay{\nonfillfinish\endgroup}\display} -\def\smallexample{\begingroup\def\Esmallexample{\nonfillfinish\endgroup}\lisp} -\def\smallformat{\begingroup\def\Esmallformat{\nonfillfinish\endgroup}\format} -\def\smalllisp{\begingroup\def\Esmalllisp{\nonfillfinish\endgroup}\lisp} - -% Real @smallexample and @smalllisp (when @smallbook): use smaller fonts. +% @smallexample and @smalllisp: use smaller fonts. % Originally contributed by Pavel@xerox. -\def\smalllispx{\begingroup +\def\smalllisp{\begingroup \def\Esmalllisp{\nonfillfinish\endgroup}% \def\Esmallexample{\nonfillfinish\endgroup}% \smallexamplefonts \lisp } +\let\smallexample = \smalllisp + % @display: same as @lisp except keep current font. % @@ -4406,9 +4606,9 @@ width0pt\relax} \fi \gobble } % -% @smalldisplay (when @smallbook): @display plus smaller fonts. +% @smalldisplay: @display plus smaller fonts. % -\def\smalldisplayx{\begingroup +\def\smalldisplay{\begingroup \def\Esmalldisplay{\nonfillfinish\endgroup}% \smallexamplefonts \rm \display @@ -4423,9 +4623,9 @@ width0pt\relax} \fi \gobble } % -% @smallformat (when @smallbook): @format plus smaller fonts. +% @smallformat: @format plus smaller fonts. % -\def\smallformatx{\begingroup +\def\smallformat{\begingroup \def\Esmallformat{\nonfillfinish\endgroup}% \smallexamplefonts \rm \format @@ -4452,7 +4652,6 @@ width0pt\relax} \fi \def\quotation{% \begingroup\inENV %This group ends at the end of the @quotation body {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \singlespace \parindent=0pt % We have retained a nonzero parskip for the environment, since we're % doing normal filling. So to avoid extra space below the environment... @@ -4475,10 +4674,14 @@ width0pt\relax} \fi % % [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. % -% [Knuth] p. 344; only we need to do '@' too +% [Knuth] p.344; only we need to do the other characters Texinfo sets +% active too. Otherwise, they get lost as the first character on a +% verbatim line. \def\dospecials{% - \do\ \do\\\do\@\do\{\do\}\do\$\do\&% - \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~} + \do\ \do\\\do\{\do\}\do\$\do\&% + \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% + \do\<\do\>\do\|\do\@\do+\do\"% +} % % [Knuth] p. 380 \def\uncatcodespecials{% @@ -4565,7 +4768,7 @@ width0pt\relax} \fi % % For Texinfo it's a lot easier than for LaTeX, % because texinfo's \verbatim doesn't stop at '\end{verbatim}': -% we need not redefine '\', '{' and '}' +% we need not redefine '\', '{' and '}'. % % Inspired by LaTeX's verbatim command set [latex.ltx] %% Include LaTeX hack for completeness -- never know @@ -4575,9 +4778,14 @@ width0pt\relax} \fi %% \catcode`\\=12|gdef|doverbatim#1@end verbatim[ %% #1|endgroup|def|Everbatim[]|end[verbatim]] %% |endgroup +% \begingroup \catcode`\ =\active - \gdef\doverbatim#1@end verbatim{#1\end{verbatim}} + \obeylines % + % ignore everything up to the first ^^M, that's the newline at the end + % of the @verbatim input line itself. Otherwise we get an extra blank + % line in the output. + \gdef\doverbatim#1^^M#2@end verbatim{#2\end{verbatim}}% \endgroup % \def\verbatim{% @@ -4593,14 +4801,14 @@ width0pt\relax} \fi % Allow normal characters that we make active in the argument (a file name). \def\verbatiminclude{% \begingroup - \catcode`\\=12 - \catcode`~=12 - \catcode`^=12 - \catcode`_=12 - \catcode`|=12 - \catcode`<=12 - \catcode`>=12 - \catcode`+=12 + \catcode`\\=\other + \catcode`~=\other + \catcode`^=\other + \catcode`_=\other + \catcode`|=\other + \catcode`<=\other + \catcode`>=\other + \catcode`+=\other \parsearg\doverbatiminclude } \def\setupverbatiminclude{% @@ -4614,44 +4822,102 @@ width0pt\relax} \fi % Restore active chars for included file. \endgroup \begingroup - \def\thisfile{#1}% - \expandafter\expandafter\setupverbatiminclude\input\thisfile - \endgroup\nonfillfinish\endgroup + \let\value=\expandablevalue + \def\thisfile{#1}% + \expandafter\expandafter\setupverbatiminclude\input\thisfile + \endgroup + \nonfillfinish + \endgroup } % @copying ... @end copying. -% Save the text away for @insertcopying later. +% Save the text away for @insertcopying later. Many commands won't be +% allowed in this context, but that's ok. +% +% We save the uninterpreted tokens, rather than creating a box. +% Saving the text in a box would be much easier, but then all the +% typesetting commands (@smallbook, font changes, etc.) have to be done +% beforehand -- and a) we want @copying to be done first in the source +% file; b) letting users define the frontmatter in as flexible order as +% possible is very desirable. % -\newbox\copyingbox -% \def\copying{\begingroup - \parindent = 0pt % looks wrong on title page - \def\Ecopying{\egroup\endgroup}% - \global\setbox\copyingbox = \vbox\bgroup + % Define a command to swallow text until we reach `@end copying'. + % \ is the escape char in this texinfo.tex file, so it is the + % delimiter for the command; @ will be the escape char when we read + % it, but that doesn't matter. + \long\def\docopying##1\end copying{\gdef\copyingtext{##1}\enddocopying}% + % + % We must preserve ^^M's in the input file; see \insertcopying below. + \catcode`\^^M = \active + \docopying } -% @insertcopying. -% -\def\insertcopying{\unvcopy\copyingbox} +% What we do to finish off the copying text. +% +\def\enddocopying{\endgroup\ignorespaces} +% @insertcopying. Here we must play games with ^^M's. On the one hand, +% we need them to delimit commands such as `@end quotation', so they +% must be active. On the other hand, we certainly don't want every +% end-of-line to be a \par, as would happen with the normal active +% definition of ^^M. On the third hand, two ^^M's in a row should still +% generate a \par. +% +% Our approach is to make ^^M insert a space and a penalty1 normally; +% then it can also check if \lastpenalty=1. If it does, then manually +% do \par. +% +% This messes up the normal definitions of @c[omment], so we redefine +% it. Similarly for @ignore. (These commands are used in the gcc +% manual for man page generation.) +% +% Seems pretty fragile, most line-oriented commands will presumably +% fail, but for the limited use of getting the copying text (which +% should be quite simple) inserted, we can hope it's ok. +% +{\catcode`\^^M=\active % +\gdef\insertcopying{\begingroup % + \parindent = 0pt % looks wrong on title page + \def^^M{% + \ifnum \lastpenalty=1 % + \par % + \else % + \space \penalty 1 % + \fi % + }% + % + % Fix @c[omment] for catcode 13 ^^M's. + \def\c##1^^M{\ignorespaces}% + \let\comment = \c % + % + % Don't bother jumping through all the hoops that \doignore does, it + % would be very hard since the catcodes are already set. + \long\def\ignore##1\end ignore{\ignorespaces}% + % + \copyingtext % +\endgroup}% +} \message{defuns,} % @defun etc. % Allow user to change definition object font (\df) internally -\def\setdeffont #1 {\csname DEF#1\endcsname} +\def\setdeffont#1 {\csname DEF#1\endcsname} \newskip\defbodyindent \defbodyindent=.4in \newskip\defargsindent \defargsindent=50pt -\newskip\deftypemargin \deftypemargin=12pt \newskip\deflastargmargin \deflastargmargin=18pt \newcount\parencount -% define \functionparens, which makes ( and ) and & do special things. -% \functionparens affects the group it is contained in. + +% We want ()&[] to print specially on the defun line. +% \def\activeparens{% -\catcode`\(=\active \catcode`\)=\active \catcode`\&=\active -\catcode`\[=\active \catcode`\]=\active} + \catcode`\(=\active \catcode`\)=\active + \catcode`\&=\active + \catcode`\[=\active \catcode`\]=\active +} % Make control sequences which act like normal parenthesis chars. \let\lparen = ( \let\rparen = ) @@ -4698,88 +4964,124 @@ width0pt\relax} \fi % Active &'s sneak into the index arguments, so make sure it's defined. { - \catcode`& = 13 + \catcode`& = \active \global\let& = \ampnr } -% First, defname, which formats the header line itself. -% #1 should be the function name. -% #2 should be the type of definition, such as "Function". - -\def\defname #1#2{% -% Get the values of \leftskip and \rightskip as they were -% outside the @def... -\dimen2=\leftskip -\advance\dimen2 by -\defbodyindent -\noindent -\setbox0=\hbox{\hskip \deflastargmargin{\rm #2}\hskip \deftypemargin}% -\dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line -\dimen1=\hsize \advance \dimen1 by -\defargsindent %size for continuations -\parshape 2 0in \dimen0 \defargsindent \dimen1 -% Now output arg 2 ("Function" or some such) -% ending at \deftypemargin from the right margin, -% but stuck inside a box of width 0 so it does not interfere with linebreaking -{% Adjust \hsize to exclude the ambient margins, -% so that \rightline will obey them. -\advance \hsize by -\dimen2 -\rlap{\rightline{{\rm #2}\hskip -1.25pc }}}% -% Make all lines underfull and no complaints: -\tolerance=10000 \hbadness=10000 -\advance\leftskip by -\defbodyindent -\exdentamount=\defbodyindent -{\df #1}\enskip % Generate function name -} - -% Actually process the body of a definition -% #1 should be the terminating control sequence, such as \Edefun. -% #2 should be the "another name" control sequence, such as \defunx. -% #3 should be the control sequence that actually processes the header, -% such as \defunheader. - -\def\defparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\activeparens\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % 61 is `=' -\obeylines\activeparens\spacesplit#3} +% \defname, which formats the name of the @def (not the args). +% #1 is the function name. +% #2 is the type of definition, such as "Function". +% +\def\defname#1#2{% + % How we'll output the type name. Putting it in brackets helps + % distinguish it from the body text that may end up on the next line + % just below it. + \ifempty{#2}% + \def\defnametype{}% + \else + \def\defnametype{[\rm #2]}% + \fi + % + % Get the values of \leftskip and \rightskip as they were outside the @def... + \dimen2=\leftskip + \advance\dimen2 by -\defbodyindent + % + % Figure out values for the paragraph shape. + \setbox0=\hbox{\hskip \deflastargmargin{\defnametype}}% + \dimen0=\hsize \advance \dimen0 by -\wd0 % compute size for first line + \dimen1=\hsize \advance \dimen1 by -\defargsindent % size for continuations + \parshape 2 0in \dimen0 \defargsindent \dimen1 + % + % Output arg 2 ("Function" or some such) but stuck inside a box of + % width 0 so it does not interfere with linebreaking. + \noindent + % + {% Adjust \hsize to exclude the ambient margins, + % so that \rightline will obey them. + \advance \hsize by -\dimen2 + \dimen3 = 0pt % was -1.25pc + \rlap{\rightline{\defnametype\kern\dimen3}}% + }% + % + % Allow all lines to be underfull without complaint: + \tolerance=10000 \hbadness=10000 + \advance\leftskip by -\defbodyindent + \exdentamount=\defbodyindent + {\df #1}\enskip % output function name + % \defunargs will be called next to output the arguments, if any. +} +% Common pieces to start any @def... % #1 is the \E... control sequence to end the definition (which we define). -% #2 is the \...x control sequence for consecutive fns (which we define). -% #3 is the control sequence to call to resume processing. +% #2 is the \...x control sequence (which our caller defines). +% #3 is the control sequence to process the header, such as \defunheader. +% +\def\parsebodycommon#1#2#3{% + \begingroup\inENV + % If there are two @def commands in a row, we'll have a \nobreak, + % which is there to keep the function description together with its + % header. But if there's nothing but headers, we want to allow a + % break after all. Check for penalty 10002 (inserted by + % \defargscommonending) instead of 10000, since the sectioning + % commands insert a \penalty10000, and we don't want to allow a break + % between a section heading and a defun. + \ifnum\lastpenalty=10002 \penalty0 \fi + \medbreak + % + % Define the \E... end token that this defining construct specifies + % so that it will exit this group. + \def#1{\endgraf\endgroup\medbreak}% + % + \parindent=0in + \advance\leftskip by \defbodyindent + \exdentamount=\defbodyindent +} + +% Common part of the \...x definitions. +% +\def\defxbodycommon{% + % As with \parsebodycommon above, allow line break if we have multiple + % x headers in a row. It's not a great place, though. + \ifnum\lastpenalty=10000 \penalty1000 \fi + % + \begingroup\obeylines +} + +% Process body of @defun, @deffn, @defmac, etc. +% +\def\defparsebody#1#2#3{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \activeparens \spacesplit#3}% + \catcode\equalChar=\active + \begingroup\obeylines\activeparens + \spacesplit#3% +} + +% #1, #2, #3 are the common arguments (see \parsebodycommon above). % #4, delimited by the space, is the class name. % -\def\defmethparsebody#1#2#3#4 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#4}}} +\def\defmethparsebody#1#2#3#4 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \activeparens \spacesplit{#3{##1}}}% + \begingroup\obeylines\activeparens + % The \empty here prevents misinterpretation of a construct such as + % @deffn {whatever} {Enharmonic comma} + % See comments at \deftpparsebody, although in our case we don't have + % to remove the \empty afterwards, since it is empty. + \spacesplit{#3{#4}}\empty +} % Used for @deftypemethod and @deftypeivar. -% #1 is the \E... control sequence to end the definition (which we define). -% #2 is the \...x control sequence for consecutive fns (which we define). -% #3 is the control sequence to call to resume processing. +% #1, #2, #3 are the common arguments (see \defparsebody). % #4, delimited by a space, is the class name. % #5 is the method's return type. % -\def\deftypemethparsebody#1#2#3#4 #5 {\begingroup\inENV - \medbreak - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 ##2 {\begingroup\obeylines\activeparens\spacesplit{#3{##1}{##2}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent - \begingroup\obeylines\activeparens\spacesplit{#3{#4}{#5}}} +\def\deftypemethparsebody#1#2#3#4 #5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\defxbodycommon \activeparens \spacesplit{#3{##1}{##2}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#4}{#5}}% +} % Used for @deftypeop. The change from \deftypemethparsebody is an % extra argument at the beginning which is the `category', instead of it @@ -4788,64 +5090,48 @@ width0pt\relax} \fi % input at hand. Thus also need a control sequence (passed as #5) for % the \E... definition to assign the category name to. % -\def\deftypeopparsebody#1#2#3#4#5 #6 {\begingroup\inENV - \medbreak - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 ##2 ##3 {% - \def#4{##1}% - \begingroup\obeylines\activeparens\spacesplit{#3{##2}{##3}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent - \begingroup\obeylines\activeparens\spacesplit{#3{#5}{#6}}} - -\def\defopparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\activeparens\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\activeparens\spacesplit{#3{#5}}} +\def\deftypeopparsebody#1#2#3#4#5 #6 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 ##3 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}{##3}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#5}{#6}}% +} + +% For @defop. +\def\defopparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \activeparens \spacesplit{#3{##2}}}% + \begingroup\obeylines\activeparens + \spacesplit{#3{#5}}% +} % These parsing functions are similar to the preceding ones % except that they do not make parens into active characters. % These are used for "variables" since they have no arguments. - -\def\defvarparsebody #1#2#3{\begingroup\inENV% Environment for definitionbody -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2{\begingroup\obeylines\spacesplit#3}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup % -\catcode 61=\active % -\obeylines\spacesplit#3} - -% This is used for \def{tp,vr}parsebody. It could probably be used for -% some of the others, too, with some judicious conditionals. % -\def\parsebodycommon#1#2#3{% - \begingroup\inENV % - \medbreak % - % Define the end token that this defining construct specifies - % so that it will exit this group. - \def#1{\endgraf\endgroup\medbreak}% - \def#2##1 {\begingroup\obeylines\spacesplit{#3{##1}}}% - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent +\def\defvarparsebody #1#2#3{% + \parsebodycommon{#1}{#2}{#3}% + \def#2{\defxbodycommon \spacesplit#3}% + \catcode\equalChar=\active + \begingroup\obeylines + \spacesplit#3% +} + +% @defopvar. +\def\defopvarparsebody #1#2#3#4#5 {% + \parsebodycommon{#1}{#2}{#3}% + \def#2##1 ##2 {\def#4{##1}% + \defxbodycommon \spacesplit{#3{##2}}}% \begingroup\obeylines + \spacesplit{#3{#5}}% } \def\defvrparsebody#1#2#3#4 {% \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines \spacesplit{#3{#4}}% } @@ -4860,6 +5146,8 @@ width0pt\relax} \fi % \def\deftpparsebody #1#2#3#4 {% \parsebodycommon{#1}{#2}{#3}% + \def#2##1 {\defxbodycommon \spacesplit{#3{##1}}}% + \begingroup\obeylines \spacesplit{\parsetpheaderline{#3{#4}}}\empty } @@ -4876,38 +5164,37 @@ width0pt\relax} \fi #1{\removeemptybraces#2\relax}{#3}% }% -\def\defopvarparsebody #1#2#3#4#5 {\begingroup\inENV % -\medbreak % -% Define the end token that this defining construct specifies -% so that it will exit this group. -\def#1{\endgraf\endgroup\medbreak}% -\def#2##1 ##2 {\def#4{##1}% -\begingroup\obeylines\spacesplit{#3{##2}}}% -\parindent=0in -\advance\leftskip by \defbodyindent -\exdentamount=\defbodyindent -\begingroup\obeylines\spacesplit{#3{#5}}} - -% Split up #2 at the first space token. +% Split up #2 (the rest of the input line) at the first space token. % call #1 with two arguments: % the first is all of #2 before the space token, % the second is all of #2 after that space token. % If #2 contains no space token, all of it is passed as the first arg % and the second is passed as empty. - -{\obeylines -\gdef\spacesplit#1#2^^M{\endgroup\spacesplitfoo{#1}#2 \relax\spacesplitfoo}% -\long\gdef\spacesplitfoo#1#2 #3#4\spacesplitfoo{% -\ifx\relax #3% -#1{#2}{}\else #1{#2}{#3#4}\fi}} - -% So much for the things common to all kinds of definitions. +% +{\obeylines % + \gdef\spacesplit#1#2^^M{\endgroup\spacesplitx{#1}#2 \relax\spacesplitx}% + \long\gdef\spacesplitx#1#2 #3#4\spacesplitx{% + \ifx\relax #3% + #1{#2}{}% + \else % + #1{#2}{#3#4}% + \fi}% +} % Define @defun. -% First, define the processing that is wanted for arguments of \defun -% Use this to expand the args and terminate the paragraph they make up +% This is called to end the arguments processing for all the @def... commands. +% +\def\defargscommonending{% + \interlinepenalty = 10000 + \advance\rightskip by 0pt plus 1fil + \endgraf + \nobreak\vskip -\parskip + \penalty 10002 % signal to \parsebodycommon. +} +% This expands the args and terminates the paragraph they comprise. +% \def\defunargs#1{\functionparens \sl % Expand, preventing hyphenation at `-' chars. % Note that groups don't affect changes in \hyphenchar. @@ -4916,9 +5203,7 @@ width0pt\relax} \fi #1% {\tensl\hyphenchar\font=45}% \ifnum\parencount=0 \else \errmessage{Unbalanced parentheses in @def}\fi% -\interlinepenalty=10000 -\advance\rightskip by 0pt plus 1fil -\endgraf\nobreak\vskip -\parskip\nobreak + \defargscommonending } \def\deftypefunargs #1{% @@ -4927,9 +5212,7 @@ width0pt\relax} \fi % Use \boldbraxnoamp, not \functionparens, so that & is not special. \boldbraxnoamp \tclose{#1}% avoid \code because of side effects on active chars -\interlinepenalty=10000 -\advance\rightskip by 0pt plus 1fil -\endgraf\nobreak\vskip -\parskip\nobreak + \defargscommonending } % Do complete processing of one @defun or @defunx line already parsed. @@ -4940,7 +5223,7 @@ width0pt\relax} \fi \def\deffnheader #1#2#3{\doind {fn}{\code{#2}}% \begingroup\defname {#2}{#1}\defunargs{#3}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @defun == @deffn Function @@ -4950,7 +5233,7 @@ width0pt\relax} \fi \def\defunheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index \begingroup\defname {#1}{\putwordDeffunc}% \defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @deftypefun int foobar (int @var{foo}, float @var{bar}) @@ -4964,7 +5247,7 @@ width0pt\relax} \fi \doind {fn}{\code{#2}}% Make entry in function index \begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypefun}% \deftypefunargs {#3}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) @@ -4985,7 +5268,7 @@ width0pt\relax} \fi % at least some C++ text from working \defname {\defheaderxcond#2\relax$.$#3}{#1}% \deftypefunargs {#4}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @defmac == @deffn Macro @@ -4995,7 +5278,7 @@ width0pt\relax} \fi \def\defmacheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index \begingroup\defname {#1}{\putwordDefmac}% \defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @defspec == @deffn Special Form @@ -5005,7 +5288,7 @@ width0pt\relax} \fi \def\defspecheader #1#2{\doind {fn}{\code{#1}}% Make entry in function index \begingroup\defname {#1}{\putwordDefspec}% \defunargs {#2}\endgroup % -\catcode 61=\other % Turn off change made in \defparsebody +\catcode\equalChar=\other % Turn off change made in \defparsebody } % @defop CATEGORY CLASS OPERATION ARG... @@ -5014,9 +5297,11 @@ width0pt\relax} \fi \defopparsebody\Edefop\defopx\defopheader\defoptype} % \def\defopheader#1#2#3{% -\dosubind {fn}{\code{#2}}{\putwordon\ #1}% Make entry in function index -\begingroup\defname {#2}{\defoptype\ \putwordon\ #1}% -\defunargs {#3}\endgroup % + \dosubind{fn}{\code{#2}}{\putwordon\ \code{#1}}% function index entry + \begingroup + \defname{#2}{\defoptype\ \putwordon\ #1}% + \defunargs{#3}% + \endgroup } % @deftypeop CATEGORY CLASS TYPE OPERATION ARG... @@ -5083,9 +5368,11 @@ width0pt\relax} \fi \defopvarparsebody\Edefcv\defcvx\defcvarheader\defcvtype} \def\defcvarheader #1#2#3{% -\dosubind {vr}{\code{#2}}{\putwordof\ #1}% Make entry in var index -\begingroup\defname {#2}{\defcvtype\ \putwordof\ #1}% -\defvarargs {#3}\endgroup % + \dosubind{vr}{\code{#2}}{\putwordof\ \code{#1}}% variable index entry + \begingroup + \defname{#2}{\defcvtype\ \putwordof\ #1}% + \defvarargs{#3}% + \endgroup } % @defivar CLASS VARNAME == @defcv {Instance Variable} CLASS VARNAME @@ -5093,7 +5380,7 @@ width0pt\relax} \fi \def\defivar{\defvrparsebody\Edefivar\defivarx\defivarheader} % \def\defivarheader#1#2#3{% - \dosubind {vr}{\code{#2}}{\putwordof\ #1}% entry in var index + \dosubind{vr}{\code{#2}}{\putwordof\ \code{#1}}% entry in var index \begingroup \defname{#2}{\putwordInstanceVariableof\ #1}% \defvarargs{#3}% @@ -5105,8 +5392,8 @@ width0pt\relax} \fi % This is actually simple: just print them in roman. % This must expand the args and terminate the paragraph they make up \def\defvarargs #1{\normalparens #1% -\interlinepenalty=10000 -\endgraf\nobreak\vskip -\parskip\nobreak} + \defargscommonending +} % @defvr Counter foo-count @@ -5142,8 +5429,7 @@ width0pt\relax} \fi \def\deftypevarheader #1#2{% \dovarind#2 \relax% Make entry in variables index \begingroup\defname {\defheaderxcond#1\relax$.$#2}{\putwordDeftypevar}% -\interlinepenalty=10000 -\endgraf\nobreak\vskip -\parskip\nobreak + \defargscommonending \endgroup} \def\dovarind#1 #2\relax{\doind{vr}{\code{#1}}} @@ -5153,8 +5439,7 @@ width0pt\relax} \fi \def\deftypevrheader #1#2#3{\dovarind#3 \relax% \begingroup\defname {\defheaderxcond#2\relax$.$#3}{#1} -\interlinepenalty=10000 -\endgraf\nobreak\vskip -\parskip\nobreak + \defargscommonending \endgroup} % Now define @deftp @@ -5203,7 +5488,7 @@ width0pt\relax} \fi \def\scanmacro#1{% \begingroup \newlinechar`\^^M % Undo catcode changes of \startcontents and \doprintindex - \catcode`\@=0 \catcode`\\=12 \escapechar=`\@ + \catcode`\@=0 \catcode`\\=\other \escapechar=`\@ % Append \endinput to make sure that TeX does not see the ending newline. \toks0={#1\endinput}% \immediate\openout\macscribble=\jobname.tmp @@ -5217,7 +5502,7 @@ width0pt\relax} \fi \def\scanmacro#1{% \begingroup \newlinechar`\^^M % Undo catcode changes of \startcontents and \doprintindex -\catcode`\@=0 \catcode`\\=12 \escapechar=`\@ +\catcode`\@=0 \catcode`\\=\other \escapechar=`\@ \let\xeatspaces\eatspaces\scantokens{#1\endinput}\endgroup} \fi @@ -5247,7 +5532,7 @@ width0pt\relax} \fi } % Trim a single trailing ^^M off a string. -{\catcode`\^^M=12\catcode`\Q=3% +{\catcode`\^^M=\other \catcode`\Q=3% \gdef\eatcr #1{\eatcra #1Q^^MQ}% \gdef\eatcra#1^^MQ{\eatcrb#1Q}% \gdef\eatcrb#1Q#2Q{#1}% @@ -5262,29 +5547,29 @@ width0pt\relax} \fi % body, and then making it the \newlinechar in \scanmacro. \def\macrobodyctxt{% - \catcode`\~=12 - \catcode`\^=12 - \catcode`\_=12 - \catcode`\|=12 - \catcode`\<=12 - \catcode`\>=12 - \catcode`\+=12 - \catcode`\{=12 - \catcode`\}=12 - \catcode`\@=12 - \catcode`\^^M=12 + \catcode`\~=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\+=\other + \catcode`\{=\other + \catcode`\}=\other + \catcode`\@=\other + \catcode`\^^M=\other \usembodybackslash} \def\macroargctxt{% - \catcode`\~=12 - \catcode`\^=12 - \catcode`\_=12 - \catcode`\|=12 - \catcode`\<=12 - \catcode`\>=12 - \catcode`\+=12 - \catcode`\@=12 - \catcode`\\=12} + \catcode`\~=\other + \catcode`\^=\other + \catcode`\_=\other + \catcode`\|=\other + \catcode`\<=\other + \catcode`\>=\other + \catcode`\+=\other + \catcode`\@=\other + \catcode`\\=\other} % \mbodybackslash is the definition of \ in @macro bodies. % It maps \foo\ => \csname macarg.foo\endcsname => #N @@ -5325,32 +5610,33 @@ width0pt\relax} \fi \else \expandafter\parsemacbody \fi} -\def\unmacro{\parsearg\unmacroxxx} -\def\unmacroxxx#1{% +\def\unmacro{\parsearg\dounmacro} +\def\dounmacro#1{% \if1\csname ismacro.#1\endcsname \global\cslet{#1}{macsave.#1}% \global\expandafter\let \csname ismacro.#1\endcsname=0% - % Remove the macro name from \macrolist + % Remove the macro name from \macrolist: \begingroup - \edef\tempa{\expandafter\noexpand\csname#1\endcsname}% - \def\do##1{% - \def\tempb{##1}% - \ifx\tempa\tempb - % remove this - \else - \toks0 = \expandafter{\newmacrolist\do}% - \edef\newmacrolist{\the\toks0\expandafter\noexpand\tempa}% - \fi}% - \def\newmacrolist{}% - % Execute macro list to define \newmacrolist - \macrolist - \global\let\macrolist\newmacrolist + \expandafter\let\csname#1\endcsname \relax + \let\do\unmacrodo + \xdef\macrolist{\macrolist}% \endgroup \else \errmessage{Macro #1 not defined}% \fi } +% Called by \do from \dounmacro on each macro. The idea is to omit any +% macro definitions that have been changed to \relax. +% +\def\unmacrodo#1{% + \ifx#1\relax + % remove this + \else + \noexpand\do \noexpand #1% + \fi +} + % This makes use of the obscure feature that if the last token of a % <parameter list> is #, then the preceding argument is delimited by % an opening brace, and that opening brace is not consumed. @@ -5533,15 +5819,23 @@ width0pt\relax} \fi \gdef\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} \gdef\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} -% \setref{NAME}{SNT} defines a cross-reference point NAME, namely -% NAME-title, NAME-pg, and NAME-SNT. Called from \foonoderef. We have -% to set \indexdummies so commands such as @code in a section title -% aren't expanded. It would be nicer not to expand the titles in the -% first place, but there's so many layers that that is hard to do. +% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an +% anchor), namely NAME-title (the corresponding @chapter/etc. name), +% NAME-pg (the page number), and NAME-snt (section number and type). +% Called from \foonoderef. +% +% We have to set \indexdummies so commands such as @code in a section +% title aren't expanded. It would be nicer not to expand the titles in +% the first place, but there's so many layers that that is hard to do. % +% Likewise, use \turnoffactive so that punctuation chars such as underscore +% and backslash work in node names. +% \def\setref#1#2{{% - \indexdummies + \atdummies \pdfmkdest{#1}% + % + \turnoffactive \dosetq{#1-title}{Ytitle}% \dosetq{#1-pg}{Ypagenumber}% \dosetq{#1-snt}{#2}% @@ -5593,7 +5887,7 @@ width0pt\relax} \fi \ifpdf \leavevmode \getfilename{#4}% - {\normalturnoffactive + {\turnoffactive \otherbackslash \ifnum\filenamelength>0 \startlink attr{/Border [0 0 0]}% goto file{\the\filename.pdf} name{#1}% @@ -5613,7 +5907,7 @@ width0pt\relax} \fi % into the usual \leavevmode...\vrule stuff for purposes of % printing. So we \turnoffactive for the \refx-snt, back on for the % printing, back off for the \refx-pg. - {\normalturnoffactive + {\turnoffactive \otherbackslash % Only output a following space if the -snt ref is nonempty; for % @unnumbered and @anchor, it won't be. \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% @@ -5622,73 +5916,74 @@ width0pt\relax} \fi % [mynode], [\printednodename],\space % page 3 - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \turnoffactive \otherbackslash \putwordpage\tie\refx{#1-pg}{}% \fi \endlink \endgroup} -% \dosetq is the interface for calls from other macros - -% Use \normalturnoffactive so that punctuation chars such as underscore -% and backslash work in node names. (\turnoffactive doesn't do \.) +% \dosetq is called from \setref to do the actual \write (\iflinks). +% \def\dosetq#1#2{% {\let\folio=0% - \normalturnoffactive \edef\next{\write\auxfile{\internalsetq{#1}{#2}}}% - \iflinks - \next - \fi + \iflinks \next \fi }% } -% \internalsetq {foo}{page} expands into -% CHARACTERS 'xrdef {foo}{...expansion of \Ypage...} -% When the aux file is read, ' is the escape character - -\def\internalsetq #1#2{'xrdef {#1}{\csname #2\endcsname}} - -% Things to be expanded by \internalsetq +% \internalsetq{foo}{page} expands into +% CHARACTERS @xrdef{foo}{...expansion of \page...} +\def\internalsetq#1#2{@xrdef{#1}{\csname #2\endcsname}} +% Things to be expanded by \internalsetq. +% \def\Ypagenumber{\folio} - \def\Ytitle{\thissection} - \def\Ynothing{} - \def\Ysectionnumberandtype{% -\ifnum\secno=0 \putwordChapter\xreftie\the\chapno % -\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno % -\else \ifnum \subsubsecno=0 % -\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno % -\else % -\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno % -\fi \fi \fi } + \ifnum\secno=0 + \putwordChapter@tie \the\chapno + \else \ifnum\subsecno=0 + \putwordSection@tie \the\chapno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno + \else + \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} \def\Yappendixletterandtype{% -\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}% -\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno % -\else \ifnum \subsubsecno=0 % -\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno % -\else % -\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno % -\fi \fi \fi } - -\gdef\xreftie{'tie} + \ifnum\secno=0 + \putwordAppendix@tie @char\the\appendixno{}% + \else \ifnum\subsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno + \else \ifnum\subsubsecno=0 + \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno + \else + \putwordSection@tie + @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno + \fi\fi\fi +} % Use TeX 3.0's \inputlineno to get the line number, for better error % messages, but if we're using an old version of TeX, don't do anything. % \ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Non-3.0. + \let\linenumber = \empty % Pre-3.0. \else \def\linenumber{\the\inputlineno:\space} \fi % Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. % If its value is nonempty, SUFFIX is output afterward. - +% \def\refx#1#2{% - \expandafter\ifx\csname X#1\endcsname\relax + {% + \indexnofonts + \otherbackslash + \expandafter\global\expandafter\let\expandafter\thisrefX + \csname X#1\endcsname + }% + \ifx\thisrefX\relax % If not defined, say something at least. \angleleft un\-de\-fined\angleright \iflinks @@ -5703,19 +5998,14 @@ width0pt\relax} \fi \fi \else % It's defined, so just use it. - \csname X#1\endcsname + \thisrefX \fi #2% Output the suffix in any case. } % This is the macro invoked by entries in the aux file. % -\def\xrdef#1{\begingroup - % Reenable \ as an escape while reading the second argument. - \catcode`\\ = 0 - \afterassignment\endgroup - \expandafter\gdef\csname X#1\endcsname -} +\def\xrdef#1{\expandafter\gdef\csname X#1\endcsname} % Read the last existing aux file, if any. No error if none exists. \def\readauxfile{\begingroup @@ -5746,9 +6036,7 @@ width0pt\relax} \fi \catcode`\^^]=\other \catcode`\^^^=\other \catcode`\^^_=\other - \catcode`\@=\other - \catcode`\^=\other - % It was suggested to define this as 7, which would allow ^^e4 etc. + % It was suggested to set the catcode of ^ to 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 ^ @@ -5761,6 +6049,9 @@ width0pt\relax} \fi % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter % and then to call \auxhat in \setq. % + \catcode`\^=\other + % + % Special characters. Should be turned off anyway, but... \catcode`\~=\other \catcode`\[=\other \catcode`\]=\other @@ -5772,7 +6063,9 @@ width0pt\relax} \fi \catcode`\$=\other \catcode`\#=\other \catcode`\&=\other + \catcode`\%=\other \catcode`+=\other % avoid \+ for paranoia even though we've turned it off + % % Make the characters 128-255 be printing characters {% \count 1=128 @@ -5782,17 +6075,18 @@ width0pt\relax} \fi \ifnum \count 1<256 \loop \fi }% }% - % 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 ^^ + % 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`\\=\other + % + % @ is our escape character in .aux files. \catcode`\{=1 \catcode`\}=2 - \catcode`\%=\other - \catcode`\'=0 - \catcode`\\=\other + \catcode`\@=0 % \openin 1 \jobname.aux \ifeof 1 \else @@ -5837,7 +6131,7 @@ width0pt\relax} \fi % Remove inadvertent blank space before typesetting the footnote number. \unskip \thisfootno\@sf - \footnotezzz + \dofootnote }% % Don't bother with the trickery in plain.tex to not require the @@ -5847,10 +6141,17 @@ width0pt\relax} \fi % \parseargline fail inside footnotes because the tokens are fixed when % the footnote is read. --karl, 16nov96. % -\long\gdef\footnotezzz{\insert\footins\bgroup +% The start of the footnote looks usually like this: +\gdef\startfootins{\insert\footins\bgroup} +% +% ... but this macro is redefined inside @multitable. +% +\gdef\dofootnote{% + \startfootins % 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. + \hsize=\pagewidth \interlinepenalty\interfootnotelinepenalty \splittopskip\ht\strutbox % top baseline for broken footnotes \splitmaxdepth\dp\strutbox @@ -5880,12 +6181,6 @@ width0pt\relax} \fi \footstrut \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\par\egroup} - }%end \catcode `\@=11 % @| inserts a changebar to the left of the current line. It should @@ -5932,8 +6227,8 @@ width0pt\relax} \fi \openin 1 = epsf.tex \ifeof 1 \else \closein 1 - % Do not bother showing banner with post-v2.7 epsf.tex (available in - % doc/epsf.tex until it shows up on ctan). + % Do not bother showing banner with epsf.tex v2.7k (available in + % doc/epsf.tex and on ctan). \def\epsfannounce{\toks0 = }% \input epsf.tex \fi @@ -6058,11 +6353,13 @@ should work if nowhere else does.} } % Parameters in order: 1) textheight; 2) textwidth; 3) voffset; -% 4) hoffset; 5) binding offset; 6) topskip. We also call -% \setleading{\textleading}, so the caller should define \textleading. -% The caller should also set \parskip. +% 4) hoffset; 5) binding offset; 6) topskip; 7) physical page height; 8) +% physical page width. +% +% We also call \setleading{\textleading}, so the caller should define +% \textleading. The caller should also set \parskip. % -\def\internalpagesizes#1#2#3#4#5#6{% +\def\internalpagesizes#1#2#3#4#5#6#7#8{% \voffset = #3\relax \topskip = #6\relax \splittopskip = \topskip @@ -6081,28 +6378,27 @@ should work if nowhere else does.} \normaloffset = #4\relax \bindingoffset = #5\relax % + \ifpdf + \pdfpageheight #7\relax + \pdfpagewidth #8\relax + \fi + % \setleading{\textleading} % \parindent = \defaultparindent \setemergencystretch } -% Use `small' versions. -% -\def\smallenvironments{% - \let\smalldisplay = \smalldisplayx - \let\smallexample = \smalllispx - \let\smallformat = \smallformatx - \let\smalllisp = \smalllispx -} - % @letterpaper (the default). \def\letterpaper{{\globaldefs = 1 \parskip = 3pt plus 2pt minus 1pt \textleading = 13.2pt % % If page is nothing but text, make it come out even. - \internalpagesizes{46\baselineskip}{6in}{\voffset}{.25in}{\bindingoffset}{36pt}% + \internalpagesizes{46\baselineskip}{6in}% + {\voffset}{.25in}% + {\bindingoffset}{36pt}% + {11in}{8.5in}% }} % Use @smallbook to reset parameters for 7x9.5 (or so) format. @@ -6110,26 +6406,42 @@ should work if nowhere else does.} \parskip = 2pt plus 1pt \textleading = 12pt % - \internalpagesizes{7.5in}{5.in}{\voffset}{.25in}{\bindingoffset}{16pt}% + \internalpagesizes{7.5in}{5in}% + {\voffset}{.25in}% + {\bindingoffset}{16pt}% + {9.25in}{7in}% % \lispnarrowing = 0.3in \tolerance = 700 \hfuzz = 1pt \contentsrightmargin = 0pt - \deftypemargin = 0pt \defbodyindent = .5cm - \smallenvironments }} % Use @afourpaper to print on European A4 paper. \def\afourpaper{{\globaldefs = 1 \parskip = 3pt plus 2pt minus 1pt - \textleading = 12pt + \textleading = 13.2pt % - \internalpagesizes{53\baselineskip}{160mm}{\voffset}{4mm}{\bindingoffset}{44pt}% + % Double-side printing via postscript on Laserjet 4050 + % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. + % To change the settings for a different printer or situation, adjust + % \normaloffset until the front-side and back-side texts align. Then + % do the same for \bindingoffset. You can set these for testing in + % your texinfo source file like this: + % @tex + % \global\normaloffset = -6mm + % \global\bindingoffset = 10mm + % @end tex + \internalpagesizes{51\baselineskip}{160mm} + {\voffset}{\hoffset}% + {\bindingoffset}{44pt}% + {297mm}{210mm}% % \tolerance = 700 \hfuzz = 1pt + \contentsrightmargin = 0pt + \defbodyindent = 5mm }} % Use @afivepaper to print on European A5 paper. @@ -6139,37 +6451,40 @@ should work if nowhere else does.} \parskip = 2pt plus 1pt minus 0.1pt \textleading = 12.5pt % - \internalpagesizes{166mm}{120mm}{\voffset}{-8mm}{\bindingoffset}{8pt}% + \internalpagesizes{160mm}{120mm}% + {\voffset}{\hoffset}% + {\bindingoffset}{8pt}% + {210mm}{148mm}% % \lispnarrowing = 0.2in \tolerance = 800 \hfuzz = 1.2pt - \contentsrightmargin = 0mm - \deftypemargin = 0pt + \contentsrightmargin = 0pt \defbodyindent = 2mm \tableindent = 12mm - % - \smallenvironments }} -% A specific text layout, 24x15cm overall, intended for A4 paper. Top margin -% 29mm, hence bottom margin 28mm, nominal side margin 3cm. +% A specific text layout, 24x15cm overall, intended for A4 paper. \def\afourlatex{{\globaldefs = 1 - \textleading = 13.6pt - % \afourpaper - \internalpagesizes{237mm}{150mm}{3.6mm}{3.6mm}{3mm}{7mm}% + \internalpagesizes{237mm}{150mm}% + {\voffset}{4.6mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% % - % Must explicitly reset to 0 because we call \afourpaper, apparently, - % although this does not entirely make sense. + % Must explicitly reset to 0 because we call \afourpaper. \globaldefs = 0 }} -% Use @afourwide to print on European A4 paper in wide format. -\def\afourwide{% +% Use @afourwide to print on A4 paper in landscape format. +\def\afourwide{{\globaldefs = 1 \afourpaper - \internalpagesizes{6.5in}{9.5in}{\hoffset}{\normaloffset}{\bindingoffset}{7mm}% -} + \internalpagesizes{241mm}{165mm}% + {\voffset}{-2.95mm}% + {\bindingoffset}{7mm}% + {297mm}{210mm}% + \globaldefs = 0 +}} % @pagesizes TEXTHEIGHT[,TEXTWIDTH] % Perhaps we should allow setting the margins, \topskip, \parskip, @@ -6184,7 +6499,16 @@ should work if nowhere else does.} \parskip = 3pt plus 2pt minus 1pt \setleading{\textleading}% % - \internalpagesizes{#1}{\hsize}{\voffset}{\normaloffset}{\bindingoffset}{44pt}% + \dimen0 = #1 + \advance\dimen0 by \voffset + % + \dimen2 = \hsize + \advance\dimen2 by \normaloffset + % + \internalpagesizes{#1}{\hsize}% + {\voffset}{\normaloffset}% + {\bindingoffset}{44pt}% + {\dimen0}{\dimen2}% }} % Set default to letter. @@ -6248,7 +6572,7 @@ should work if nowhere else does.} \catcode`\_=\active \def_{\ifusingtt\normalunderscore\_} % Subroutine for the previous macro. -\def\_{\leavevmode \kern.06em \vbox{\hrule width.3em height.1ex}} +\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } \catcode`\|=\active \def|{{\tt\char124}} @@ -6262,8 +6586,6 @@ should work if nowhere else does.} \def+{{\tt \char 43}} \catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix -%\catcode 27=\active -%\def^^[{$\diamondsuit$} % Set up an active definition for =, but don't enable it most of the time. {\catcode`\==\active @@ -6280,44 +6602,46 @@ should work if nowhere else does.} \catcode`\@=0 -% \rawbackslashxx output one backslash character in current font +% \rawbackslashxx outputs one backslash character in current font, +% as in \char`\\. \global\chardef\rawbackslashxx=`\\ -%{\catcode`\\=\other -%@gdef@rawbackslashxx{\}} -% \rawbackslash redefines \ as input to do \rawbackslashxx. +% \rawbackslash defines an active \ to do \rawbackslashxx. +% \otherbackslash defines an active \ to be a literal `\' character with +% catcode other. {\catcode`\\=\active -@gdef@rawbackslash{@let\=@rawbackslashxx }} + @gdef@rawbackslash{@let\=@rawbackslashxx} + @gdef@otherbackslash{@let\=@realbackslash} +} + +% \realbackslash is an actual character `\' with catcode other. +{\catcode`\\=\other @gdef@realbackslash{\}} % \normalbackslash outputs one backslash in fixed width font. \def\normalbackslash{{\tt\rawbackslashxx}} -% \catcode 17=0 % Define control-q \catcode`\\=\active % Used sometimes to turn off (effectively) the active characters % even after parsing them. -@def@turnoffactive{@let"=@normaldoublequote -@let\=@realbackslash -@let~=@normaltilde -@let^=@normalcaret -@let_=@normalunderscore -@let|=@normalverticalbar -@let<=@normalless -@let>=@normalgreater -@let+=@normalplus -@let$=@normaldollar}%$ font-lock fix - -@def@normalturnoffactive{@let"=@normaldoublequote -@let\=@normalbackslash -@let~=@normaltilde -@let^=@normalcaret -@let_=@normalunderscore -@let|=@normalverticalbar -@let<=@normalless -@let>=@normalgreater -@let+=@normalplus -@let$=@normaldollar}%$ font-lock fix +@def@turnoffactive{% + @let"=@normaldoublequote + @let\=@realbackslash + @let~=@normaltilde + @let^=@normalcaret + @let_=@normalunderscore + @let|=@normalverticalbar + @let<=@normalless + @let>=@normalgreater + @let+=@normalplus + @let$=@normaldollar %$ font-lock fix +} + +% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of +% the literal character `\'. (Thus, \ is not expandable when this is in +% effect.) +% +@def@normalturnoffactive{@turnoffactive @let\=@normalbackslash} % Make _ and + \other characters, temporarily. % This is canceled by @fixbackslash. |