Imported from /home/lorry/working-area/delta_m4-tarball/m4-1.4.17.tar.xz.HEADm4-1.4.17master

12 files changed, 21091 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..d701edd
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,43 @@
+## Makefile.am - template for generating Makefile via Automake
+##
+## Copyright (C) 2006-2013 Free Software Foundation, Inc.
+##
+## This file is part of GNU M4.
+##
+## GNU M4 is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## GNU M4 is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+##
+## This file written by Eric Blake <ebb9@byu.net>
+
+info_TEXINFOS = m4.texi
+m4_TEXINFOS = fdl-1.3.texi gpl-3.0.texi
+man_MANS = $(srcdir)/m4.1
+EXTRA_DIST = $(man_MANS) gendocs_template
+MAINTAINERCLEANFILES = $(man_MANS) gendocs_template
+SUFFIXES = .1
+HELP2MAN = $(SHELL) $(top_srcdir)/build-aux/missing --run help2man
+
+# Depend on ../.version for version, m4.c for usage text.  Do not depend on
+# built m4 executable, since not everyone has help2man or perl.
+# Build the man page once in the srcdir, rather than in every VPATH build
+# dir, to match how automake builds info pages.  This is safe for 'make
+# distcheck' since it is distributed pre-built.
+$(srcdir)/m4.1: $(top_srcdir)/.version $(top_srcdir)/src/m4.c
+	@if test -x ../src/m4$(EXEEXT) ; then \
+	  echo "Updating man page m4.1" ; \
+	  $(HELP2MAN) --name="macro processor" --source='$(PACKAGE_STRING)' \
+	    --info-page=m4 --output=$@ ../src/m4$(EXEEXT) ; \
+	else \
+	  echo "WARNING: The \`man' page \`$@' cannot be updated yet."; \
+	  echo "         Retry once the program executable is ready."; \
+	fi
diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..47ed88a
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,1948 @@
+# Makefile.in generated by automake 1.14 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994-2013 Free Software Foundation, Inc.
+
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+VPATH = @srcdir@
+am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)'
+am__make_running_with_option = \
+  case $${target_option-} in \
+      ?) ;; \
+      *) echo "am__make_running_with_option: internal error: invalid" \
+              "target option '$${target_option-}' specified" >&2; \
+         exit 1;; \
+  esac; \
+  has_opt=no; \
+  sane_makeflags=$$MAKEFLAGS; \
+  if $(am__is_gnu_make); then \
+    sane_makeflags=$$MFLAGS; \
+  else \
+    case $$MAKEFLAGS in \
+      *\\[\ \	]*) \
+        bs=\\; \
+        sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
+          | sed "s/$$bs$$bs[$$bs $$bs	]*//g"`;; \
+    esac; \
+  fi; \
+  skip_next=no; \
+  strip_trailopt () \
+  { \
+    flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
+  }; \
+  for flg in $$sane_makeflags; do \
+    test $$skip_next = yes && { skip_next=no; continue; }; \
+    case $$flg in \
+      *=*|--*) continue;; \
+        -*I) strip_trailopt 'I'; skip_next=yes;; \
+      -*I?*) strip_trailopt 'I';; \
+        -*O) strip_trailopt 'O'; skip_next=yes;; \
+      -*O?*) strip_trailopt 'O';; \
+        -*l) strip_trailopt 'l'; skip_next=yes;; \
+      -*l?*) strip_trailopt 'l';; \
+      -[dEDm]) skip_next=yes;; \
+      -[JT]) skip_next=yes;; \
+    esac; \
+    case $$flg in \
+      *$$target_option*) has_opt=yes; break;; \
+    esac; \
+  done; \
+  test $$has_opt = yes
+am__make_dryrun = (target_option=n; $(am__make_running_with_option))
+am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+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)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+subdir = doc
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am \
+	$(m4_TEXINFOS) $(top_srcdir)/build-aux/mdate-sh \
+	$(srcdir)/version.texi $(srcdir)/stamp-vti \
+	$(top_srcdir)/build-aux/texinfo.tex
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/m4/00gnulib.m4 \
+	$(top_srcdir)/m4/alloca.m4 $(top_srcdir)/m4/ansi-c++.m4 \
+	$(top_srcdir)/m4/asm-underscore.m4 $(top_srcdir)/m4/assert.m4 \
+	$(top_srcdir)/m4/autobuild.m4 $(top_srcdir)/m4/btowc.m4 \
+	$(top_srcdir)/m4/c-stack.m4 $(top_srcdir)/m4/canonicalize.m4 \
+	$(top_srcdir)/m4/close-stream.m4 $(top_srcdir)/m4/close.m4 \
+	$(top_srcdir)/m4/closedir.m4 $(top_srcdir)/m4/closein.m4 \
+	$(top_srcdir)/m4/closeout.m4 $(top_srcdir)/m4/codeset.m4 \
+	$(top_srcdir)/m4/config-h.m4 $(top_srcdir)/m4/configmake.m4 \
+	$(top_srcdir)/m4/dirent_h.m4 $(top_srcdir)/m4/dirname.m4 \
+	$(top_srcdir)/m4/double-slash-root.m4 $(top_srcdir)/m4/dup.m4 \
+	$(top_srcdir)/m4/dup2.m4 $(top_srcdir)/m4/eealloc.m4 \
+	$(top_srcdir)/m4/environ.m4 $(top_srcdir)/m4/errno_h.m4 \
+	$(top_srcdir)/m4/error.m4 $(top_srcdir)/m4/execute.m4 \
+	$(top_srcdir)/m4/exponentd.m4 $(top_srcdir)/m4/exponentf.m4 \
+	$(top_srcdir)/m4/exponentl.m4 $(top_srcdir)/m4/extensions.m4 \
+	$(top_srcdir)/m4/extern-inline.m4 \
+	$(top_srcdir)/m4/fatal-signal.m4 $(top_srcdir)/m4/fclose.m4 \
+	$(top_srcdir)/m4/fcntl-o.m4 $(top_srcdir)/m4/fcntl.m4 \
+	$(top_srcdir)/m4/fcntl_h.m4 $(top_srcdir)/m4/fdopen.m4 \
+	$(top_srcdir)/m4/fflush.m4 $(top_srcdir)/m4/filenamecat.m4 \
+	$(top_srcdir)/m4/float_h.m4 $(top_srcdir)/m4/fopen.m4 \
+	$(top_srcdir)/m4/fpending.m4 $(top_srcdir)/m4/fpieee.m4 \
+	$(top_srcdir)/m4/fpurge.m4 $(top_srcdir)/m4/freadahead.m4 \
+	$(top_srcdir)/m4/freading.m4 $(top_srcdir)/m4/frexp.m4 \
+	$(top_srcdir)/m4/frexpl.m4 $(top_srcdir)/m4/fseek.m4 \
+	$(top_srcdir)/m4/fseeko.m4 $(top_srcdir)/m4/fstat.m4 \
+	$(top_srcdir)/m4/ftell.m4 $(top_srcdir)/m4/ftello.m4 \
+	$(top_srcdir)/m4/getcwd.m4 $(top_srcdir)/m4/getdtablesize.m4 \
+	$(top_srcdir)/m4/getopt.m4 $(top_srcdir)/m4/getpagesize.m4 \
+	$(top_srcdir)/m4/gettimeofday.m4 $(top_srcdir)/m4/glibc21.m4 \
+	$(top_srcdir)/m4/gnulib-common.m4 \
+	$(top_srcdir)/m4/gnulib-comp.m4 \
+	$(top_srcdir)/m4/include_next.m4 \
+	$(top_srcdir)/m4/intlmacosx.m4 $(top_srcdir)/m4/intmax_t.m4 \
+	$(top_srcdir)/m4/inttypes-pri.m4 $(top_srcdir)/m4/inttypes.m4 \
+	$(top_srcdir)/m4/inttypes_h.m4 $(top_srcdir)/m4/isnand.m4 \
+	$(top_srcdir)/m4/isnanf.m4 $(top_srcdir)/m4/isnanl.m4 \
+	$(top_srcdir)/m4/langinfo_h.m4 $(top_srcdir)/m4/largefile.m4 \
+	$(top_srcdir)/m4/lcmessage.m4 $(top_srcdir)/m4/ldexp.m4 \
+	$(top_srcdir)/m4/ldexpl.m4 $(top_srcdir)/m4/lib-ld.m4 \
+	$(top_srcdir)/m4/lib-link.m4 $(top_srcdir)/m4/lib-prefix.m4 \
+	$(top_srcdir)/m4/libsigsegv.m4 $(top_srcdir)/m4/link.m4 \
+	$(top_srcdir)/m4/localcharset.m4 $(top_srcdir)/m4/locale-fr.m4 \
+	$(top_srcdir)/m4/locale-ja.m4 $(top_srcdir)/m4/locale-tr.m4 \
+	$(top_srcdir)/m4/locale-zh.m4 $(top_srcdir)/m4/locale_h.m4 \
+	$(top_srcdir)/m4/localeconv.m4 $(top_srcdir)/m4/localename.m4 \
+	$(top_srcdir)/m4/lock.m4 $(top_srcdir)/m4/longlong.m4 \
+	$(top_srcdir)/m4/lseek.m4 $(top_srcdir)/m4/lstat.m4 \
+	$(top_srcdir)/m4/malloc.m4 $(top_srcdir)/m4/malloca.m4 \
+	$(top_srcdir)/m4/manywarnings.m4 $(top_srcdir)/m4/math_h.m4 \
+	$(top_srcdir)/m4/mbrtowc.m4 $(top_srcdir)/m4/mbsinit.m4 \
+	$(top_srcdir)/m4/mbstate_t.m4 $(top_srcdir)/m4/mbtowc.m4 \
+	$(top_srcdir)/m4/memchr.m4 $(top_srcdir)/m4/mkdtemp.m4 \
+	$(top_srcdir)/m4/mkstemp.m4 $(top_srcdir)/m4/mmap-anon.m4 \
+	$(top_srcdir)/m4/mode_t.m4 $(top_srcdir)/m4/msvc-inval.m4 \
+	$(top_srcdir)/m4/msvc-nothrow.m4 $(top_srcdir)/m4/multiarch.m4 \
+	$(top_srcdir)/m4/nl_langinfo.m4 $(top_srcdir)/m4/nocrash.m4 \
+	$(top_srcdir)/m4/off_t.m4 $(top_srcdir)/m4/open.m4 \
+	$(top_srcdir)/m4/opendir.m4 $(top_srcdir)/m4/pathmax.m4 \
+	$(top_srcdir)/m4/pipe2.m4 $(top_srcdir)/m4/posix_spawn.m4 \
+	$(top_srcdir)/m4/printf-frexp.m4 \
+	$(top_srcdir)/m4/printf-frexpl.m4 $(top_srcdir)/m4/printf.m4 \
+	$(top_srcdir)/m4/putenv.m4 $(top_srcdir)/m4/quotearg.m4 \
+	$(top_srcdir)/m4/raise.m4 $(top_srcdir)/m4/rawmemchr.m4 \
+	$(top_srcdir)/m4/readdir.m4 $(top_srcdir)/m4/readlink.m4 \
+	$(top_srcdir)/m4/regex.m4 $(top_srcdir)/m4/rename.m4 \
+	$(top_srcdir)/m4/rmdir.m4 $(top_srcdir)/m4/sched_h.m4 \
+	$(top_srcdir)/m4/secure_getenv.m4 $(top_srcdir)/m4/setenv.m4 \
+	$(top_srcdir)/m4/setlocale.m4 $(top_srcdir)/m4/sig_atomic_t.m4 \
+	$(top_srcdir)/m4/sigaction.m4 $(top_srcdir)/m4/signal_h.m4 \
+	$(top_srcdir)/m4/signalblocking.m4 $(top_srcdir)/m4/signbit.m4 \
+	$(top_srcdir)/m4/sigpipe.m4 $(top_srcdir)/m4/size_max.m4 \
+	$(top_srcdir)/m4/sleep.m4 $(top_srcdir)/m4/snprintf.m4 \
+	$(top_srcdir)/m4/spawn-pipe.m4 $(top_srcdir)/m4/spawn_h.m4 \
+	$(top_srcdir)/m4/ssize_t.m4 $(top_srcdir)/m4/stat.m4 \
+	$(top_srcdir)/m4/stdarg.m4 $(top_srcdir)/m4/stdbool.m4 \
+	$(top_srcdir)/m4/stddef_h.m4 $(top_srcdir)/m4/stdint.m4 \
+	$(top_srcdir)/m4/stdint_h.m4 $(top_srcdir)/m4/stdio_h.m4 \
+	$(top_srcdir)/m4/stdlib_h.m4 $(top_srcdir)/m4/strchrnul.m4 \
+	$(top_srcdir)/m4/strdup.m4 $(top_srcdir)/m4/strerror.m4 \
+	$(top_srcdir)/m4/string_h.m4 $(top_srcdir)/m4/strndup.m4 \
+	$(top_srcdir)/m4/strnlen.m4 $(top_srcdir)/m4/strsignal.m4 \
+	$(top_srcdir)/m4/strstr.m4 $(top_srcdir)/m4/strtod.m4 \
+	$(top_srcdir)/m4/symlink.m4 $(top_srcdir)/m4/sys_socket_h.m4 \
+	$(top_srcdir)/m4/sys_stat_h.m4 $(top_srcdir)/m4/sys_time_h.m4 \
+	$(top_srcdir)/m4/sys_types_h.m4 $(top_srcdir)/m4/sys_wait_h.m4 \
+	$(top_srcdir)/m4/tempname.m4 $(top_srcdir)/m4/threadlib.m4 \
+	$(top_srcdir)/m4/time_h.m4 $(top_srcdir)/m4/tls.m4 \
+	$(top_srcdir)/m4/tmpdir.m4 $(top_srcdir)/m4/ungetc.m4 \
+	$(top_srcdir)/m4/unistd-safer.m4 $(top_srcdir)/m4/unistd_h.m4 \
+	$(top_srcdir)/m4/unlocked-io.m4 $(top_srcdir)/m4/vasnprintf.m4 \
+	$(top_srcdir)/m4/vasprintf-posix.m4 \
+	$(top_srcdir)/m4/vasprintf.m4 $(top_srcdir)/m4/version-etc.m4 \
+	$(top_srcdir)/m4/wait-process.m4 $(top_srcdir)/m4/waitpid.m4 \
+	$(top_srcdir)/m4/warnings.m4 $(top_srcdir)/m4/wchar_h.m4 \
+	$(top_srcdir)/m4/wchar_t.m4 $(top_srcdir)/m4/wcrtomb.m4 \
+	$(top_srcdir)/m4/wctob.m4 $(top_srcdir)/m4/wctomb.m4 \
+	$(top_srcdir)/m4/wctype_h.m4 $(top_srcdir)/m4/wint_t.m4 \
+	$(top_srcdir)/m4/write.m4 $(top_srcdir)/m4/xalloc.m4 \
+	$(top_srcdir)/m4/xsize.m4 $(top_srcdir)/m4/xstrndup.m4 \
+	$(top_srcdir)/m4/xvasprintf.m4 $(top_srcdir)/acinclude.m4 \
+	$(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+mkinstalldirs = $(install_sh) -d
+CONFIG_HEADER = $(top_builddir)/lib/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+AM_V_P = $(am__v_P_@AM_V@)
+am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
+am__v_P_0 = false
+am__v_P_1 = :
+AM_V_GEN = $(am__v_GEN_@AM_V@)
+am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
+am__v_GEN_0 = @echo "  GEN     " $@;
+am__v_GEN_1 = 
+AM_V_at = $(am__v_at_@AM_V@)
+am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
+am__v_at_0 = @
+am__v_at_1 = 
+SOURCES =
+DIST_SOURCES =
+AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
+am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
+am__v_DVIPS_0 = @echo "  DVIPS   " $@;
+am__v_DVIPS_1 = 
+AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
+am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
+am__v_MAKEINFO_0 = @echo "  MAKEINFO" $@;
+am__v_MAKEINFO_1 = 
+AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
+am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
+am__v_INFOHTML_0 = @echo "  INFOHTML" $@;
+am__v_INFOHTML_1 = 
+AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
+am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
+am__v_TEXI2DVI_0 = @echo "  TEXI2DVI" $@;
+am__v_TEXI2DVI_1 = 
+AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
+am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
+am__v_TEXI2PDF_0 = @echo "  TEXI2PDF" $@;
+am__v_TEXI2PDF_1 = 
+AM_V_texinfo = $(am__v_texinfo_@AM_V@)
+am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
+am__v_texinfo_0 = -q
+am__v_texinfo_1 = 
+AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
+am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
+am__v_texidevnull_0 = > /dev/null
+am__v_texidevnull_1 = 
+INFO_DEPS = $(srcdir)/m4.info
+TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex
+am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux
+DVIS = m4.dvi
+PDFS = m4.pdf
+PSS = m4.ps
+HTMLS = m4.html
+TEXINFOS = m4.texi
+TEXI2DVI = texi2dvi
+TEXI2PDF = $(TEXI2DVI) --pdf --batch
+MAKEINFOHTML = $(MAKEINFO) --html
+AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
+DVIPS = dvips
+am__can_run_installinfo = \
+  case $$AM_UPDATE_INFO_DIR in \
+    n|no|NO) false;; \
+    *) (install-info --version) >/dev/null 2>&1;; \
+  esac
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+    $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+    *) f=$$p;; \
+  esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+  srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+  for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+  for p in $$list; do echo "$$p $$p"; done | \
+  sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+  $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+    if (++n[$$2] == $(am__install_max)) \
+      { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+    END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+  sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+  sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+am__uninstall_files_from_dir = { \
+  test -z "$$files" \
+    || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
+    || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
+         $(am__cd) "$$dir" && rm -f $$files; }; \
+  }
+man1dir = $(mandir)/man1
+NROFF = nroff
+MANS = $(man_MANS)
+am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+pkglibexecdir = @pkglibexecdir@
+ACLOCAL = @ACLOCAL@
+ALLOCA = @ALLOCA@
+ALLOCA_H = @ALLOCA_H@
+AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
+APPLE_UNIVERSAL_BUILD = @APPLE_UNIVERSAL_BUILD@
+AR = @AR@
+ARFLAGS = @ARFLAGS@
+ASM_SYMBOL_PREFIX = @ASM_SYMBOL_PREFIX@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@
+BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@
+BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@
+BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@
+BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CONFIG_INCLUDE = @CONFIG_INCLUDE@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CXX_CHOICE = @CXX_CHOICE@
+CYGPATH_W = @CYGPATH_W@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+EGREP = @EGREP@
+EMULTIHOP_HIDDEN = @EMULTIHOP_HIDDEN@
+EMULTIHOP_VALUE = @EMULTIHOP_VALUE@
+ENOLINK_HIDDEN = @ENOLINK_HIDDEN@
+ENOLINK_VALUE = @ENOLINK_VALUE@
+EOVERFLOW_HIDDEN = @EOVERFLOW_HIDDEN@
+EOVERFLOW_VALUE = @EOVERFLOW_VALUE@
+ERRNO_H = @ERRNO_H@
+EXEEXT = @EXEEXT@
+FLOAT_H = @FLOAT_H@
+GETOPT_H = @GETOPT_H@
+GLIBC21 = @GLIBC21@
+GNULIB_ACOSF = @GNULIB_ACOSF@
+GNULIB_ACOSL = @GNULIB_ACOSL@
+GNULIB_ALPHASORT = @GNULIB_ALPHASORT@
+GNULIB_ASINF = @GNULIB_ASINF@
+GNULIB_ASINL = @GNULIB_ASINL@
+GNULIB_ATAN2F = @GNULIB_ATAN2F@
+GNULIB_ATANF = @GNULIB_ATANF@
+GNULIB_ATANL = @GNULIB_ATANL@
+GNULIB_ATOLL = @GNULIB_ATOLL@
+GNULIB_BTOWC = @GNULIB_BTOWC@
+GNULIB_CALLOC_POSIX = @GNULIB_CALLOC_POSIX@
+GNULIB_CANONICALIZE_FILE_NAME = @GNULIB_CANONICALIZE_FILE_NAME@
+GNULIB_CBRT = @GNULIB_CBRT@
+GNULIB_CBRTF = @GNULIB_CBRTF@
+GNULIB_CBRTL = @GNULIB_CBRTL@
+GNULIB_CEIL = @GNULIB_CEIL@
+GNULIB_CEILF = @GNULIB_CEILF@
+GNULIB_CEILL = @GNULIB_CEILL@
+GNULIB_CHDIR = @GNULIB_CHDIR@
+GNULIB_CHOWN = @GNULIB_CHOWN@
+GNULIB_CLOSE = @GNULIB_CLOSE@
+GNULIB_CLOSEDIR = @GNULIB_CLOSEDIR@
+GNULIB_COPYSIGN = @GNULIB_COPYSIGN@
+GNULIB_COPYSIGNF = @GNULIB_COPYSIGNF@
+GNULIB_COPYSIGNL = @GNULIB_COPYSIGNL@
+GNULIB_COSF = @GNULIB_COSF@
+GNULIB_COSHF = @GNULIB_COSHF@
+GNULIB_COSL = @GNULIB_COSL@
+GNULIB_DIRFD = @GNULIB_DIRFD@
+GNULIB_DPRINTF = @GNULIB_DPRINTF@
+GNULIB_DUP = @GNULIB_DUP@
+GNULIB_DUP2 = @GNULIB_DUP2@
+GNULIB_DUP3 = @GNULIB_DUP3@
+GNULIB_DUPLOCALE = @GNULIB_DUPLOCALE@
+GNULIB_ENVIRON = @GNULIB_ENVIRON@
+GNULIB_EUIDACCESS = @GNULIB_EUIDACCESS@
+GNULIB_EXP2 = @GNULIB_EXP2@
+GNULIB_EXP2F = @GNULIB_EXP2F@
+GNULIB_EXP2L = @GNULIB_EXP2L@
+GNULIB_EXPF = @GNULIB_EXPF@
+GNULIB_EXPL = @GNULIB_EXPL@
+GNULIB_EXPM1 = @GNULIB_EXPM1@
+GNULIB_EXPM1F = @GNULIB_EXPM1F@
+GNULIB_EXPM1L = @GNULIB_EXPM1L@
+GNULIB_FABSF = @GNULIB_FABSF@
+GNULIB_FABSL = @GNULIB_FABSL@
+GNULIB_FACCESSAT = @GNULIB_FACCESSAT@
+GNULIB_FCHDIR = @GNULIB_FCHDIR@
+GNULIB_FCHMODAT = @GNULIB_FCHMODAT@
+GNULIB_FCHOWNAT = @GNULIB_FCHOWNAT@
+GNULIB_FCLOSE = @GNULIB_FCLOSE@
+GNULIB_FCNTL = @GNULIB_FCNTL@
+GNULIB_FDATASYNC = @GNULIB_FDATASYNC@
+GNULIB_FDOPEN = @GNULIB_FDOPEN@
+GNULIB_FDOPENDIR = @GNULIB_FDOPENDIR@
+GNULIB_FFLUSH = @GNULIB_FFLUSH@
+GNULIB_FFSL = @GNULIB_FFSL@
+GNULIB_FFSLL = @GNULIB_FFSLL@
+GNULIB_FGETC = @GNULIB_FGETC@
+GNULIB_FGETS = @GNULIB_FGETS@
+GNULIB_FLOOR = @GNULIB_FLOOR@
+GNULIB_FLOORF = @GNULIB_FLOORF@
+GNULIB_FLOORL = @GNULIB_FLOORL@
+GNULIB_FMA = @GNULIB_FMA@
+GNULIB_FMAF = @GNULIB_FMAF@
+GNULIB_FMAL = @GNULIB_FMAL@
+GNULIB_FMOD = @GNULIB_FMOD@
+GNULIB_FMODF = @GNULIB_FMODF@
+GNULIB_FMODL = @GNULIB_FMODL@
+GNULIB_FOPEN = @GNULIB_FOPEN@
+GNULIB_FPRINTF = @GNULIB_FPRINTF@
+GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@
+GNULIB_FPURGE = @GNULIB_FPURGE@
+GNULIB_FPUTC = @GNULIB_FPUTC@
+GNULIB_FPUTS = @GNULIB_FPUTS@
+GNULIB_FREAD = @GNULIB_FREAD@
+GNULIB_FREOPEN = @GNULIB_FREOPEN@
+GNULIB_FREXP = @GNULIB_FREXP@
+GNULIB_FREXPF = @GNULIB_FREXPF@
+GNULIB_FREXPL = @GNULIB_FREXPL@
+GNULIB_FSCANF = @GNULIB_FSCANF@
+GNULIB_FSEEK = @GNULIB_FSEEK@
+GNULIB_FSEEKO = @GNULIB_FSEEKO@
+GNULIB_FSTAT = @GNULIB_FSTAT@
+GNULIB_FSTATAT = @GNULIB_FSTATAT@
+GNULIB_FSYNC = @GNULIB_FSYNC@
+GNULIB_FTELL = @GNULIB_FTELL@
+GNULIB_FTELLO = @GNULIB_FTELLO@
+GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@
+GNULIB_FUTIMENS = @GNULIB_FUTIMENS@
+GNULIB_FWRITE = @GNULIB_FWRITE@
+GNULIB_GETC = @GNULIB_GETC@
+GNULIB_GETCHAR = @GNULIB_GETCHAR@
+GNULIB_GETCWD = @GNULIB_GETCWD@
+GNULIB_GETDELIM = @GNULIB_GETDELIM@
+GNULIB_GETDOMAINNAME = @GNULIB_GETDOMAINNAME@
+GNULIB_GETDTABLESIZE = @GNULIB_GETDTABLESIZE@
+GNULIB_GETGROUPS = @GNULIB_GETGROUPS@
+GNULIB_GETHOSTNAME = @GNULIB_GETHOSTNAME@
+GNULIB_GETLINE = @GNULIB_GETLINE@
+GNULIB_GETLOADAVG = @GNULIB_GETLOADAVG@
+GNULIB_GETLOGIN = @GNULIB_GETLOGIN@
+GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@
+GNULIB_GETPAGESIZE = @GNULIB_GETPAGESIZE@
+GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@
+GNULIB_GETTIMEOFDAY = @GNULIB_GETTIMEOFDAY@
+GNULIB_GETUSERSHELL = @GNULIB_GETUSERSHELL@
+GNULIB_GL_M4_UNISTD_H_GETOPT = @GNULIB_GL_M4_UNISTD_H_GETOPT@
+GNULIB_GRANTPT = @GNULIB_GRANTPT@
+GNULIB_GROUP_MEMBER = @GNULIB_GROUP_MEMBER@
+GNULIB_HYPOT = @GNULIB_HYPOT@
+GNULIB_HYPOTF = @GNULIB_HYPOTF@
+GNULIB_HYPOTL = @GNULIB_HYPOTL@
+GNULIB_ILOGB = @GNULIB_ILOGB@
+GNULIB_ILOGBF = @GNULIB_ILOGBF@
+GNULIB_ILOGBL = @GNULIB_ILOGBL@
+GNULIB_IMAXABS = @GNULIB_IMAXABS@
+GNULIB_IMAXDIV = @GNULIB_IMAXDIV@
+GNULIB_ISATTY = @GNULIB_ISATTY@
+GNULIB_ISFINITE = @GNULIB_ISFINITE@
+GNULIB_ISINF = @GNULIB_ISINF@
+GNULIB_ISNAN = @GNULIB_ISNAN@
+GNULIB_ISNAND = @GNULIB_ISNAND@
+GNULIB_ISNANF = @GNULIB_ISNANF@
+GNULIB_ISNANL = @GNULIB_ISNANL@
+GNULIB_ISWBLANK = @GNULIB_ISWBLANK@
+GNULIB_ISWCTYPE = @GNULIB_ISWCTYPE@
+GNULIB_LCHMOD = @GNULIB_LCHMOD@
+GNULIB_LCHOWN = @GNULIB_LCHOWN@
+GNULIB_LDEXPF = @GNULIB_LDEXPF@
+GNULIB_LDEXPL = @GNULIB_LDEXPL@
+GNULIB_LINK = @GNULIB_LINK@
+GNULIB_LINKAT = @GNULIB_LINKAT@
+GNULIB_LOCALECONV = @GNULIB_LOCALECONV@
+GNULIB_LOG = @GNULIB_LOG@
+GNULIB_LOG10 = @GNULIB_LOG10@
+GNULIB_LOG10F = @GNULIB_LOG10F@
+GNULIB_LOG10L = @GNULIB_LOG10L@
+GNULIB_LOG1P = @GNULIB_LOG1P@
+GNULIB_LOG1PF = @GNULIB_LOG1PF@
+GNULIB_LOG1PL = @GNULIB_LOG1PL@
+GNULIB_LOG2 = @GNULIB_LOG2@
+GNULIB_LOG2F = @GNULIB_LOG2F@
+GNULIB_LOG2L = @GNULIB_LOG2L@
+GNULIB_LOGB = @GNULIB_LOGB@
+GNULIB_LOGBF = @GNULIB_LOGBF@
+GNULIB_LOGBL = @GNULIB_LOGBL@
+GNULIB_LOGF = @GNULIB_LOGF@
+GNULIB_LOGL = @GNULIB_LOGL@
+GNULIB_LSEEK = @GNULIB_LSEEK@
+GNULIB_LSTAT = @GNULIB_LSTAT@
+GNULIB_MALLOC_POSIX = @GNULIB_MALLOC_POSIX@
+GNULIB_MBRLEN = @GNULIB_MBRLEN@
+GNULIB_MBRTOWC = @GNULIB_MBRTOWC@
+GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@
+GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@
+GNULIB_MBSCHR = @GNULIB_MBSCHR@
+GNULIB_MBSCSPN = @GNULIB_MBSCSPN@
+GNULIB_MBSINIT = @GNULIB_MBSINIT@
+GNULIB_MBSLEN = @GNULIB_MBSLEN@
+GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@
+GNULIB_MBSNLEN = @GNULIB_MBSNLEN@
+GNULIB_MBSNRTOWCS = @GNULIB_MBSNRTOWCS@
+GNULIB_MBSPBRK = @GNULIB_MBSPBRK@
+GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@
+GNULIB_MBSRCHR = @GNULIB_MBSRCHR@
+GNULIB_MBSRTOWCS = @GNULIB_MBSRTOWCS@
+GNULIB_MBSSEP = @GNULIB_MBSSEP@
+GNULIB_MBSSPN = @GNULIB_MBSSPN@
+GNULIB_MBSSTR = @GNULIB_MBSSTR@
+GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@
+GNULIB_MBTOWC = @GNULIB_MBTOWC@
+GNULIB_MEMCHR = @GNULIB_MEMCHR@
+GNULIB_MEMMEM = @GNULIB_MEMMEM@
+GNULIB_MEMPCPY = @GNULIB_MEMPCPY@
+GNULIB_MEMRCHR = @GNULIB_MEMRCHR@
+GNULIB_MKDIRAT = @GNULIB_MKDIRAT@
+GNULIB_MKDTEMP = @GNULIB_MKDTEMP@
+GNULIB_MKFIFO = @GNULIB_MKFIFO@
+GNULIB_MKFIFOAT = @GNULIB_MKFIFOAT@
+GNULIB_MKNOD = @GNULIB_MKNOD@
+GNULIB_MKNODAT = @GNULIB_MKNODAT@
+GNULIB_MKOSTEMP = @GNULIB_MKOSTEMP@
+GNULIB_MKOSTEMPS = @GNULIB_MKOSTEMPS@
+GNULIB_MKSTEMP = @GNULIB_MKSTEMP@
+GNULIB_MKSTEMPS = @GNULIB_MKSTEMPS@
+GNULIB_MKTIME = @GNULIB_MKTIME@
+GNULIB_MODF = @GNULIB_MODF@
+GNULIB_MODFF = @GNULIB_MODFF@
+GNULIB_MODFL = @GNULIB_MODFL@
+GNULIB_NANOSLEEP = @GNULIB_NANOSLEEP@
+GNULIB_NL_LANGINFO = @GNULIB_NL_LANGINFO@
+GNULIB_NONBLOCKING = @GNULIB_NONBLOCKING@
+GNULIB_OBSTACK_PRINTF = @GNULIB_OBSTACK_PRINTF@
+GNULIB_OBSTACK_PRINTF_POSIX = @GNULIB_OBSTACK_PRINTF_POSIX@
+GNULIB_OPEN = @GNULIB_OPEN@
+GNULIB_OPENAT = @GNULIB_OPENAT@
+GNULIB_OPENDIR = @GNULIB_OPENDIR@
+GNULIB_PCLOSE = @GNULIB_PCLOSE@
+GNULIB_PERROR = @GNULIB_PERROR@
+GNULIB_PIPE = @GNULIB_PIPE@
+GNULIB_PIPE2 = @GNULIB_PIPE2@
+GNULIB_POPEN = @GNULIB_POPEN@
+GNULIB_POSIX_OPENPT = @GNULIB_POSIX_OPENPT@
+GNULIB_POSIX_SPAWN = @GNULIB_POSIX_SPAWN@
+GNULIB_POSIX_SPAWNATTR_DESTROY = @GNULIB_POSIX_SPAWNATTR_DESTROY@
+GNULIB_POSIX_SPAWNATTR_GETFLAGS = @GNULIB_POSIX_SPAWNATTR_GETFLAGS@
+GNULIB_POSIX_SPAWNATTR_GETPGROUP = @GNULIB_POSIX_SPAWNATTR_GETPGROUP@
+GNULIB_POSIX_SPAWNATTR_GETSCHEDPARAM = @GNULIB_POSIX_SPAWNATTR_GETSCHEDPARAM@
+GNULIB_POSIX_SPAWNATTR_GETSCHEDPOLICY = @GNULIB_POSIX_SPAWNATTR_GETSCHEDPOLICY@
+GNULIB_POSIX_SPAWNATTR_GETSIGDEFAULT = @GNULIB_POSIX_SPAWNATTR_GETSIGDEFAULT@
+GNULIB_POSIX_SPAWNATTR_GETSIGMASK = @GNULIB_POSIX_SPAWNATTR_GETSIGMASK@
+GNULIB_POSIX_SPAWNATTR_INIT = @GNULIB_POSIX_SPAWNATTR_INIT@
+GNULIB_POSIX_SPAWNATTR_SETFLAGS = @GNULIB_POSIX_SPAWNATTR_SETFLAGS@
+GNULIB_POSIX_SPAWNATTR_SETPGROUP = @GNULIB_POSIX_SPAWNATTR_SETPGROUP@
+GNULIB_POSIX_SPAWNATTR_SETSCHEDPARAM = @GNULIB_POSIX_SPAWNATTR_SETSCHEDPARAM@
+GNULIB_POSIX_SPAWNATTR_SETSCHEDPOLICY = @GNULIB_POSIX_SPAWNATTR_SETSCHEDPOLICY@
+GNULIB_POSIX_SPAWNATTR_SETSIGDEFAULT = @GNULIB_POSIX_SPAWNATTR_SETSIGDEFAULT@
+GNULIB_POSIX_SPAWNATTR_SETSIGMASK = @GNULIB_POSIX_SPAWNATTR_SETSIGMASK@
+GNULIB_POSIX_SPAWNP = @GNULIB_POSIX_SPAWNP@
+GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE@
+GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2@
+GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN@
+GNULIB_POSIX_SPAWN_FILE_ACTIONS_DESTROY = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_DESTROY@
+GNULIB_POSIX_SPAWN_FILE_ACTIONS_INIT = @GNULIB_POSIX_SPAWN_FILE_ACTIONS_INIT@
+GNULIB_POWF = @GNULIB_POWF@
+GNULIB_PREAD = @GNULIB_PREAD@
+GNULIB_PRINTF = @GNULIB_PRINTF@
+GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@
+GNULIB_PTHREAD_SIGMASK = @GNULIB_PTHREAD_SIGMASK@
+GNULIB_PTSNAME = @GNULIB_PTSNAME@
+GNULIB_PTSNAME_R = @GNULIB_PTSNAME_R@
+GNULIB_PUTC = @GNULIB_PUTC@
+GNULIB_PUTCHAR = @GNULIB_PUTCHAR@
+GNULIB_PUTENV = @GNULIB_PUTENV@
+GNULIB_PUTS = @GNULIB_PUTS@
+GNULIB_PWRITE = @GNULIB_PWRITE@
+GNULIB_RAISE = @GNULIB_RAISE@
+GNULIB_RANDOM = @GNULIB_RANDOM@
+GNULIB_RANDOM_R = @GNULIB_RANDOM_R@
+GNULIB_RAWMEMCHR = @GNULIB_RAWMEMCHR@
+GNULIB_READ = @GNULIB_READ@
+GNULIB_READDIR = @GNULIB_READDIR@
+GNULIB_READLINK = @GNULIB_READLINK@
+GNULIB_READLINKAT = @GNULIB_READLINKAT@
+GNULIB_REALLOC_POSIX = @GNULIB_REALLOC_POSIX@
+GNULIB_REALPATH = @GNULIB_REALPATH@
+GNULIB_REMAINDER = @GNULIB_REMAINDER@
+GNULIB_REMAINDERF = @GNULIB_REMAINDERF@
+GNULIB_REMAINDERL = @GNULIB_REMAINDERL@
+GNULIB_REMOVE = @GNULIB_REMOVE@
+GNULIB_RENAME = @GNULIB_RENAME@
+GNULIB_RENAMEAT = @GNULIB_RENAMEAT@
+GNULIB_REWINDDIR = @GNULIB_REWINDDIR@
+GNULIB_RINT = @GNULIB_RINT@
+GNULIB_RINTF = @GNULIB_RINTF@
+GNULIB_RINTL = @GNULIB_RINTL@
+GNULIB_RMDIR = @GNULIB_RMDIR@
+GNULIB_ROUND = @GNULIB_ROUND@
+GNULIB_ROUNDF = @GNULIB_ROUNDF@
+GNULIB_ROUNDL = @GNULIB_ROUNDL@
+GNULIB_RPMATCH = @GNULIB_RPMATCH@
+GNULIB_SCANDIR = @GNULIB_SCANDIR@
+GNULIB_SCANF = @GNULIB_SCANF@
+GNULIB_SECURE_GETENV = @GNULIB_SECURE_GETENV@
+GNULIB_SETENV = @GNULIB_SETENV@
+GNULIB_SETHOSTNAME = @GNULIB_SETHOSTNAME@
+GNULIB_SETLOCALE = @GNULIB_SETLOCALE@
+GNULIB_SIGACTION = @GNULIB_SIGACTION@
+GNULIB_SIGNAL_H_SIGPIPE = @GNULIB_SIGNAL_H_SIGPIPE@
+GNULIB_SIGNBIT = @GNULIB_SIGNBIT@
+GNULIB_SIGPROCMASK = @GNULIB_SIGPROCMASK@
+GNULIB_SINF = @GNULIB_SINF@
+GNULIB_SINHF = @GNULIB_SINHF@
+GNULIB_SINL = @GNULIB_SINL@
+GNULIB_SLEEP = @GNULIB_SLEEP@
+GNULIB_SNPRINTF = @GNULIB_SNPRINTF@
+GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@
+GNULIB_SQRTF = @GNULIB_SQRTF@
+GNULIB_SQRTL = @GNULIB_SQRTL@
+GNULIB_STAT = @GNULIB_STAT@
+GNULIB_STDIO_H_NONBLOCKING = @GNULIB_STDIO_H_NONBLOCKING@
+GNULIB_STDIO_H_SIGPIPE = @GNULIB_STDIO_H_SIGPIPE@
+GNULIB_STPCPY = @GNULIB_STPCPY@
+GNULIB_STPNCPY = @GNULIB_STPNCPY@
+GNULIB_STRCASESTR = @GNULIB_STRCASESTR@
+GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@
+GNULIB_STRDUP = @GNULIB_STRDUP@
+GNULIB_STRERROR = @GNULIB_STRERROR@
+GNULIB_STRERROR_R = @GNULIB_STRERROR_R@
+GNULIB_STRNCAT = @GNULIB_STRNCAT@
+GNULIB_STRNDUP = @GNULIB_STRNDUP@
+GNULIB_STRNLEN = @GNULIB_STRNLEN@
+GNULIB_STRPBRK = @GNULIB_STRPBRK@
+GNULIB_STRPTIME = @GNULIB_STRPTIME@
+GNULIB_STRSEP = @GNULIB_STRSEP@
+GNULIB_STRSIGNAL = @GNULIB_STRSIGNAL@
+GNULIB_STRSTR = @GNULIB_STRSTR@
+GNULIB_STRTOD = @GNULIB_STRTOD@
+GNULIB_STRTOIMAX = @GNULIB_STRTOIMAX@
+GNULIB_STRTOK_R = @GNULIB_STRTOK_R@
+GNULIB_STRTOLL = @GNULIB_STRTOLL@
+GNULIB_STRTOULL = @GNULIB_STRTOULL@
+GNULIB_STRTOUMAX = @GNULIB_STRTOUMAX@
+GNULIB_STRVERSCMP = @GNULIB_STRVERSCMP@
+GNULIB_SYMLINK = @GNULIB_SYMLINK@
+GNULIB_SYMLINKAT = @GNULIB_SYMLINKAT@
+GNULIB_SYSTEM_POSIX = @GNULIB_SYSTEM_POSIX@
+GNULIB_TANF = @GNULIB_TANF@
+GNULIB_TANHF = @GNULIB_TANHF@
+GNULIB_TANL = @GNULIB_TANL@
+GNULIB_TIMEGM = @GNULIB_TIMEGM@
+GNULIB_TIME_R = @GNULIB_TIME_R@
+GNULIB_TMPFILE = @GNULIB_TMPFILE@
+GNULIB_TOWCTRANS = @GNULIB_TOWCTRANS@
+GNULIB_TRUNC = @GNULIB_TRUNC@
+GNULIB_TRUNCF = @GNULIB_TRUNCF@
+GNULIB_TRUNCL = @GNULIB_TRUNCL@
+GNULIB_TTYNAME_R = @GNULIB_TTYNAME_R@
+GNULIB_UNISTD_H_NONBLOCKING = @GNULIB_UNISTD_H_NONBLOCKING@
+GNULIB_UNISTD_H_SIGPIPE = @GNULIB_UNISTD_H_SIGPIPE@
+GNULIB_UNLINK = @GNULIB_UNLINK@
+GNULIB_UNLINKAT = @GNULIB_UNLINKAT@
+GNULIB_UNLOCKPT = @GNULIB_UNLOCKPT@
+GNULIB_UNSETENV = @GNULIB_UNSETENV@
+GNULIB_USLEEP = @GNULIB_USLEEP@
+GNULIB_UTIMENSAT = @GNULIB_UTIMENSAT@
+GNULIB_VASPRINTF = @GNULIB_VASPRINTF@
+GNULIB_VDPRINTF = @GNULIB_VDPRINTF@
+GNULIB_VFPRINTF = @GNULIB_VFPRINTF@
+GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@
+GNULIB_VFSCANF = @GNULIB_VFSCANF@
+GNULIB_VPRINTF = @GNULIB_VPRINTF@
+GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@
+GNULIB_VSCANF = @GNULIB_VSCANF@
+GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@
+GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@
+GNULIB_WAITPID = @GNULIB_WAITPID@
+GNULIB_WCPCPY = @GNULIB_WCPCPY@
+GNULIB_WCPNCPY = @GNULIB_WCPNCPY@
+GNULIB_WCRTOMB = @GNULIB_WCRTOMB@
+GNULIB_WCSCASECMP = @GNULIB_WCSCASECMP@
+GNULIB_WCSCAT = @GNULIB_WCSCAT@
+GNULIB_WCSCHR = @GNULIB_WCSCHR@
+GNULIB_WCSCMP = @GNULIB_WCSCMP@
+GNULIB_WCSCOLL = @GNULIB_WCSCOLL@
+GNULIB_WCSCPY = @GNULIB_WCSCPY@
+GNULIB_WCSCSPN = @GNULIB_WCSCSPN@
+GNULIB_WCSDUP = @GNULIB_WCSDUP@
+GNULIB_WCSLEN = @GNULIB_WCSLEN@
+GNULIB_WCSNCASECMP = @GNULIB_WCSNCASECMP@
+GNULIB_WCSNCAT = @GNULIB_WCSNCAT@
+GNULIB_WCSNCMP = @GNULIB_WCSNCMP@
+GNULIB_WCSNCPY = @GNULIB_WCSNCPY@
+GNULIB_WCSNLEN = @GNULIB_WCSNLEN@
+GNULIB_WCSNRTOMBS = @GNULIB_WCSNRTOMBS@
+GNULIB_WCSPBRK = @GNULIB_WCSPBRK@
+GNULIB_WCSRCHR = @GNULIB_WCSRCHR@
+GNULIB_WCSRTOMBS = @GNULIB_WCSRTOMBS@
+GNULIB_WCSSPN = @GNULIB_WCSSPN@
+GNULIB_WCSSTR = @GNULIB_WCSSTR@
+GNULIB_WCSTOK = @GNULIB_WCSTOK@
+GNULIB_WCSWIDTH = @GNULIB_WCSWIDTH@
+GNULIB_WCSXFRM = @GNULIB_WCSXFRM@
+GNULIB_WCTOB = @GNULIB_WCTOB@
+GNULIB_WCTOMB = @GNULIB_WCTOMB@
+GNULIB_WCTRANS = @GNULIB_WCTRANS@
+GNULIB_WCTYPE = @GNULIB_WCTYPE@
+GNULIB_WCWIDTH = @GNULIB_WCWIDTH@
+GNULIB_WMEMCHR = @GNULIB_WMEMCHR@
+GNULIB_WMEMCMP = @GNULIB_WMEMCMP@
+GNULIB_WMEMCPY = @GNULIB_WMEMCPY@
+GNULIB_WMEMMOVE = @GNULIB_WMEMMOVE@
+GNULIB_WMEMSET = @GNULIB_WMEMSET@
+GNULIB_WRITE = @GNULIB_WRITE@
+GNULIB__EXIT = @GNULIB__EXIT@
+GREP = @GREP@
+HAVE_ACOSF = @HAVE_ACOSF@
+HAVE_ACOSL = @HAVE_ACOSL@
+HAVE_ALPHASORT = @HAVE_ALPHASORT@
+HAVE_ASINF = @HAVE_ASINF@
+HAVE_ASINL = @HAVE_ASINL@
+HAVE_ATAN2F = @HAVE_ATAN2F@
+HAVE_ATANF = @HAVE_ATANF@
+HAVE_ATANL = @HAVE_ATANL@
+HAVE_ATOLL = @HAVE_ATOLL@
+HAVE_BTOWC = @HAVE_BTOWC@
+HAVE_CANONICALIZE_FILE_NAME = @HAVE_CANONICALIZE_FILE_NAME@
+HAVE_CBRT = @HAVE_CBRT@
+HAVE_CBRTF = @HAVE_CBRTF@
+HAVE_CBRTL = @HAVE_CBRTL@
+HAVE_CHOWN = @HAVE_CHOWN@
+HAVE_CLOSEDIR = @HAVE_CLOSEDIR@
+HAVE_COPYSIGN = @HAVE_COPYSIGN@
+HAVE_COPYSIGNL = @HAVE_COPYSIGNL@
+HAVE_COSF = @HAVE_COSF@
+HAVE_COSHF = @HAVE_COSHF@
+HAVE_COSL = @HAVE_COSL@
+HAVE_DECL_ACOSL = @HAVE_DECL_ACOSL@
+HAVE_DECL_ASINL = @HAVE_DECL_ASINL@
+HAVE_DECL_ATANL = @HAVE_DECL_ATANL@
+HAVE_DECL_CBRTF = @HAVE_DECL_CBRTF@
+HAVE_DECL_CBRTL = @HAVE_DECL_CBRTL@
+HAVE_DECL_CEILF = @HAVE_DECL_CEILF@
+HAVE_DECL_CEILL = @HAVE_DECL_CEILL@
+HAVE_DECL_COPYSIGNF = @HAVE_DECL_COPYSIGNF@
+HAVE_DECL_COSL = @HAVE_DECL_COSL@
+HAVE_DECL_DIRFD = @HAVE_DECL_DIRFD@
+HAVE_DECL_ENVIRON = @HAVE_DECL_ENVIRON@
+HAVE_DECL_EXP2 = @HAVE_DECL_EXP2@
+HAVE_DECL_EXP2F = @HAVE_DECL_EXP2F@
+HAVE_DECL_EXP2L = @HAVE_DECL_EXP2L@
+HAVE_DECL_EXPL = @HAVE_DECL_EXPL@
+HAVE_DECL_EXPM1L = @HAVE_DECL_EXPM1L@
+HAVE_DECL_FCHDIR = @HAVE_DECL_FCHDIR@
+HAVE_DECL_FDATASYNC = @HAVE_DECL_FDATASYNC@
+HAVE_DECL_FDOPENDIR = @HAVE_DECL_FDOPENDIR@
+HAVE_DECL_FLOORF = @HAVE_DECL_FLOORF@
+HAVE_DECL_FLOORL = @HAVE_DECL_FLOORL@
+HAVE_DECL_FPURGE = @HAVE_DECL_FPURGE@
+HAVE_DECL_FREXPL = @HAVE_DECL_FREXPL@
+HAVE_DECL_FSEEKO = @HAVE_DECL_FSEEKO@
+HAVE_DECL_FTELLO = @HAVE_DECL_FTELLO@
+HAVE_DECL_GETDELIM = @HAVE_DECL_GETDELIM@
+HAVE_DECL_GETDOMAINNAME = @HAVE_DECL_GETDOMAINNAME@
+HAVE_DECL_GETLINE = @HAVE_DECL_GETLINE@
+HAVE_DECL_GETLOADAVG = @HAVE_DECL_GETLOADAVG@
+HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@
+HAVE_DECL_GETPAGESIZE = @HAVE_DECL_GETPAGESIZE@
+HAVE_DECL_GETUSERSHELL = @HAVE_DECL_GETUSERSHELL@
+HAVE_DECL_IMAXABS = @HAVE_DECL_IMAXABS@
+HAVE_DECL_IMAXDIV = @HAVE_DECL_IMAXDIV@
+HAVE_DECL_LDEXPL = @HAVE_DECL_LDEXPL@
+HAVE_DECL_LOCALTIME_R = @HAVE_DECL_LOCALTIME_R@
+HAVE_DECL_LOG10L = @HAVE_DECL_LOG10L@
+HAVE_DECL_LOG2 = @HAVE_DECL_LOG2@
+HAVE_DECL_LOG2F = @HAVE_DECL_LOG2F@
+HAVE_DECL_LOG2L = @HAVE_DECL_LOG2L@
+HAVE_DECL_LOGB = @HAVE_DECL_LOGB@
+HAVE_DECL_LOGL = @HAVE_DECL_LOGL@
+HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@
+HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@
+HAVE_DECL_OBSTACK_PRINTF = @HAVE_DECL_OBSTACK_PRINTF@
+HAVE_DECL_REMAINDER = @HAVE_DECL_REMAINDER@
+HAVE_DECL_REMAINDERL = @HAVE_DECL_REMAINDERL@
+HAVE_DECL_RINTF = @HAVE_DECL_RINTF@
+HAVE_DECL_ROUND = @HAVE_DECL_ROUND@
+HAVE_DECL_ROUNDF = @HAVE_DECL_ROUNDF@
+HAVE_DECL_ROUNDL = @HAVE_DECL_ROUNDL@
+HAVE_DECL_SETENV = @HAVE_DECL_SETENV@
+HAVE_DECL_SETHOSTNAME = @HAVE_DECL_SETHOSTNAME@
+HAVE_DECL_SINL = @HAVE_DECL_SINL@
+HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@
+HAVE_DECL_SQRTL = @HAVE_DECL_SQRTL@
+HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@
+HAVE_DECL_STRERROR_R = @HAVE_DECL_STRERROR_R@
+HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@
+HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@
+HAVE_DECL_STRSIGNAL = @HAVE_DECL_STRSIGNAL@
+HAVE_DECL_STRTOIMAX = @HAVE_DECL_STRTOIMAX@
+HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@
+HAVE_DECL_STRTOUMAX = @HAVE_DECL_STRTOUMAX@
+HAVE_DECL_TANL = @HAVE_DECL_TANL@
+HAVE_DECL_TRUNC = @HAVE_DECL_TRUNC@
+HAVE_DECL_TRUNCF = @HAVE_DECL_TRUNCF@
+HAVE_DECL_TRUNCL = @HAVE_DECL_TRUNCL@
+HAVE_DECL_TTYNAME_R = @HAVE_DECL_TTYNAME_R@
+HAVE_DECL_UNSETENV = @HAVE_DECL_UNSETENV@
+HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@
+HAVE_DECL_WCTOB = @HAVE_DECL_WCTOB@
+HAVE_DECL_WCWIDTH = @HAVE_DECL_WCWIDTH@
+HAVE_DIRENT_H = @HAVE_DIRENT_H@
+HAVE_DPRINTF = @HAVE_DPRINTF@
+HAVE_DUP2 = @HAVE_DUP2@
+HAVE_DUP3 = @HAVE_DUP3@
+HAVE_DUPLOCALE = @HAVE_DUPLOCALE@
+HAVE_EUIDACCESS = @HAVE_EUIDACCESS@
+HAVE_EXPF = @HAVE_EXPF@
+HAVE_EXPL = @HAVE_EXPL@
+HAVE_EXPM1 = @HAVE_EXPM1@
+HAVE_EXPM1F = @HAVE_EXPM1F@
+HAVE_FABSF = @HAVE_FABSF@
+HAVE_FABSL = @HAVE_FABSL@
+HAVE_FACCESSAT = @HAVE_FACCESSAT@
+HAVE_FCHDIR = @HAVE_FCHDIR@
+HAVE_FCHMODAT = @HAVE_FCHMODAT@
+HAVE_FCHOWNAT = @HAVE_FCHOWNAT@
+HAVE_FCNTL = @HAVE_FCNTL@
+HAVE_FDATASYNC = @HAVE_FDATASYNC@
+HAVE_FDOPENDIR = @HAVE_FDOPENDIR@
+HAVE_FEATURES_H = @HAVE_FEATURES_H@
+HAVE_FFSL = @HAVE_FFSL@
+HAVE_FFSLL = @HAVE_FFSLL@
+HAVE_FMA = @HAVE_FMA@
+HAVE_FMAF = @HAVE_FMAF@
+HAVE_FMAL = @HAVE_FMAL@
+HAVE_FMODF = @HAVE_FMODF@
+HAVE_FMODL = @HAVE_FMODL@
+HAVE_FREXPF = @HAVE_FREXPF@
+HAVE_FSEEKO = @HAVE_FSEEKO@
+HAVE_FSTATAT = @HAVE_FSTATAT@
+HAVE_FSYNC = @HAVE_FSYNC@
+HAVE_FTELLO = @HAVE_FTELLO@
+HAVE_FTRUNCATE = @HAVE_FTRUNCATE@
+HAVE_FUTIMENS = @HAVE_FUTIMENS@
+HAVE_GETDTABLESIZE = @HAVE_GETDTABLESIZE@
+HAVE_GETGROUPS = @HAVE_GETGROUPS@
+HAVE_GETHOSTNAME = @HAVE_GETHOSTNAME@
+HAVE_GETLOGIN = @HAVE_GETLOGIN@
+HAVE_GETOPT_H = @HAVE_GETOPT_H@
+HAVE_GETPAGESIZE = @HAVE_GETPAGESIZE@
+HAVE_GETSUBOPT = @HAVE_GETSUBOPT@
+HAVE_GETTIMEOFDAY = @HAVE_GETTIMEOFDAY@
+HAVE_GRANTPT = @HAVE_GRANTPT@
+HAVE_GROUP_MEMBER = @HAVE_GROUP_MEMBER@
+HAVE_HYPOTF = @HAVE_HYPOTF@
+HAVE_HYPOTL = @HAVE_HYPOTL@
+HAVE_ILOGB = @HAVE_ILOGB@
+HAVE_ILOGBF = @HAVE_ILOGBF@
+HAVE_ILOGBL = @HAVE_ILOGBL@
+HAVE_INTTYPES_H = @HAVE_INTTYPES_H@
+HAVE_ISNAND = @HAVE_ISNAND@
+HAVE_ISNANF = @HAVE_ISNANF@
+HAVE_ISNANL = @HAVE_ISNANL@
+HAVE_ISWBLANK = @HAVE_ISWBLANK@
+HAVE_ISWCNTRL = @HAVE_ISWCNTRL@
+HAVE_LANGINFO_CODESET = @HAVE_LANGINFO_CODESET@
+HAVE_LANGINFO_ERA = @HAVE_LANGINFO_ERA@
+HAVE_LANGINFO_H = @HAVE_LANGINFO_H@
+HAVE_LANGINFO_T_FMT_AMPM = @HAVE_LANGINFO_T_FMT_AMPM@
+HAVE_LANGINFO_YESEXPR = @HAVE_LANGINFO_YESEXPR@
+HAVE_LCHMOD = @HAVE_LCHMOD@
+HAVE_LCHOWN = @HAVE_LCHOWN@
+HAVE_LDEXPF = @HAVE_LDEXPF@
+HAVE_LIBSIGSEGV = @HAVE_LIBSIGSEGV@
+HAVE_LINK = @HAVE_LINK@
+HAVE_LINKAT = @HAVE_LINKAT@
+HAVE_LOG10F = @HAVE_LOG10F@
+HAVE_LOG10L = @HAVE_LOG10L@
+HAVE_LOG1P = @HAVE_LOG1P@
+HAVE_LOG1PF = @HAVE_LOG1PF@
+HAVE_LOG1PL = @HAVE_LOG1PL@
+HAVE_LOGBF = @HAVE_LOGBF@
+HAVE_LOGBL = @HAVE_LOGBL@
+HAVE_LOGF = @HAVE_LOGF@
+HAVE_LOGL = @HAVE_LOGL@
+HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@
+HAVE_LSTAT = @HAVE_LSTAT@
+HAVE_MBRLEN = @HAVE_MBRLEN@
+HAVE_MBRTOWC = @HAVE_MBRTOWC@
+HAVE_MBSINIT = @HAVE_MBSINIT@
+HAVE_MBSLEN = @HAVE_MBSLEN@
+HAVE_MBSNRTOWCS = @HAVE_MBSNRTOWCS@
+HAVE_MBSRTOWCS = @HAVE_MBSRTOWCS@
+HAVE_MEMCHR = @HAVE_MEMCHR@
+HAVE_MEMPCPY = @HAVE_MEMPCPY@
+HAVE_MKDIRAT = @HAVE_MKDIRAT@
+HAVE_MKDTEMP = @HAVE_MKDTEMP@
+HAVE_MKFIFO = @HAVE_MKFIFO@
+HAVE_MKFIFOAT = @HAVE_MKFIFOAT@
+HAVE_MKNOD = @HAVE_MKNOD@
+HAVE_MKNODAT = @HAVE_MKNODAT@
+HAVE_MKOSTEMP = @HAVE_MKOSTEMP@
+HAVE_MKOSTEMPS = @HAVE_MKOSTEMPS@
+HAVE_MKSTEMP = @HAVE_MKSTEMP@
+HAVE_MKSTEMPS = @HAVE_MKSTEMPS@
+HAVE_MODFF = @HAVE_MODFF@
+HAVE_MODFL = @HAVE_MODFL@
+HAVE_MSVC_INVALID_PARAMETER_HANDLER = @HAVE_MSVC_INVALID_PARAMETER_HANDLER@
+HAVE_NANOSLEEP = @HAVE_NANOSLEEP@
+HAVE_NL_LANGINFO = @HAVE_NL_LANGINFO@
+HAVE_OPENAT = @HAVE_OPENAT@
+HAVE_OPENDIR = @HAVE_OPENDIR@
+HAVE_OS_H = @HAVE_OS_H@
+HAVE_PCLOSE = @HAVE_PCLOSE@
+HAVE_PIPE = @HAVE_PIPE@
+HAVE_PIPE2 = @HAVE_PIPE2@
+HAVE_POPEN = @HAVE_POPEN@
+HAVE_POSIX_OPENPT = @HAVE_POSIX_OPENPT@
+HAVE_POSIX_SIGNALBLOCKING = @HAVE_POSIX_SIGNALBLOCKING@
+HAVE_POSIX_SPAWN = @HAVE_POSIX_SPAWN@
+HAVE_POSIX_SPAWNATTR_T = @HAVE_POSIX_SPAWNATTR_T@
+HAVE_POSIX_SPAWN_FILE_ACTIONS_T = @HAVE_POSIX_SPAWN_FILE_ACTIONS_T@
+HAVE_POWF = @HAVE_POWF@
+HAVE_PREAD = @HAVE_PREAD@
+HAVE_PTHREAD_SIGMASK = @HAVE_PTHREAD_SIGMASK@
+HAVE_PTSNAME = @HAVE_PTSNAME@
+HAVE_PTSNAME_R = @HAVE_PTSNAME_R@
+HAVE_PWRITE = @HAVE_PWRITE@
+HAVE_RAISE = @HAVE_RAISE@
+HAVE_RANDOM = @HAVE_RANDOM@
+HAVE_RANDOM_H = @HAVE_RANDOM_H@
+HAVE_RANDOM_R = @HAVE_RANDOM_R@
+HAVE_RAWMEMCHR = @HAVE_RAWMEMCHR@
+HAVE_READDIR = @HAVE_READDIR@
+HAVE_READLINK = @HAVE_READLINK@
+HAVE_READLINKAT = @HAVE_READLINKAT@
+HAVE_REALPATH = @HAVE_REALPATH@
+HAVE_REMAINDER = @HAVE_REMAINDER@
+HAVE_REMAINDERF = @HAVE_REMAINDERF@
+HAVE_RENAMEAT = @HAVE_RENAMEAT@
+HAVE_REWINDDIR = @HAVE_REWINDDIR@
+HAVE_RINT = @HAVE_RINT@
+HAVE_RINTL = @HAVE_RINTL@
+HAVE_RPMATCH = @HAVE_RPMATCH@
+HAVE_SAME_LONG_DOUBLE_AS_DOUBLE = @HAVE_SAME_LONG_DOUBLE_AS_DOUBLE@
+HAVE_SCANDIR = @HAVE_SCANDIR@
+HAVE_SCHED_H = @HAVE_SCHED_H@
+HAVE_SECURE_GETENV = @HAVE_SECURE_GETENV@
+HAVE_SETENV = @HAVE_SETENV@
+HAVE_SETHOSTNAME = @HAVE_SETHOSTNAME@
+HAVE_SIGACTION = @HAVE_SIGACTION@
+HAVE_SIGHANDLER_T = @HAVE_SIGHANDLER_T@
+HAVE_SIGINFO_T = @HAVE_SIGINFO_T@
+HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@
+HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@
+HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@
+HAVE_SIGSET_T = @HAVE_SIGSET_T@
+HAVE_SINF = @HAVE_SINF@
+HAVE_SINHF = @HAVE_SINHF@
+HAVE_SINL = @HAVE_SINL@
+HAVE_SLEEP = @HAVE_SLEEP@
+HAVE_SPAWN_H = @HAVE_SPAWN_H@
+HAVE_SQRTF = @HAVE_SQRTF@
+HAVE_SQRTL = @HAVE_SQRTL@
+HAVE_STDINT_H = @HAVE_STDINT_H@
+HAVE_STPCPY = @HAVE_STPCPY@
+HAVE_STPNCPY = @HAVE_STPNCPY@
+HAVE_STRCASESTR = @HAVE_STRCASESTR@
+HAVE_STRCHRNUL = @HAVE_STRCHRNUL@
+HAVE_STRPBRK = @HAVE_STRPBRK@
+HAVE_STRPTIME = @HAVE_STRPTIME@
+HAVE_STRSEP = @HAVE_STRSEP@
+HAVE_STRTOD = @HAVE_STRTOD@
+HAVE_STRTOLL = @HAVE_STRTOLL@
+HAVE_STRTOULL = @HAVE_STRTOULL@
+HAVE_STRUCT_RANDOM_DATA = @HAVE_STRUCT_RANDOM_DATA@
+HAVE_STRUCT_SCHED_PARAM = @HAVE_STRUCT_SCHED_PARAM@
+HAVE_STRUCT_SIGACTION_SA_SIGACTION = @HAVE_STRUCT_SIGACTION_SA_SIGACTION@
+HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@
+HAVE_STRVERSCMP = @HAVE_STRVERSCMP@
+HAVE_SYMLINK = @HAVE_SYMLINK@
+HAVE_SYMLINKAT = @HAVE_SYMLINKAT@
+HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@
+HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@
+HAVE_SYS_LOADAVG_H = @HAVE_SYS_LOADAVG_H@
+HAVE_SYS_PARAM_H = @HAVE_SYS_PARAM_H@
+HAVE_SYS_TIME_H = @HAVE_SYS_TIME_H@
+HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@
+HAVE_TANF = @HAVE_TANF@
+HAVE_TANHF = @HAVE_TANHF@
+HAVE_TANL = @HAVE_TANL@
+HAVE_TIMEGM = @HAVE_TIMEGM@
+HAVE_TYPE_VOLATILE_SIG_ATOMIC_T = @HAVE_TYPE_VOLATILE_SIG_ATOMIC_T@
+HAVE_UNISTD_H = @HAVE_UNISTD_H@
+HAVE_UNLINKAT = @HAVE_UNLINKAT@
+HAVE_UNLOCKPT = @HAVE_UNLOCKPT@
+HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@
+HAVE_USLEEP = @HAVE_USLEEP@
+HAVE_UTIMENSAT = @HAVE_UTIMENSAT@
+HAVE_VASPRINTF = @HAVE_VASPRINTF@
+HAVE_VDPRINTF = @HAVE_VDPRINTF@
+HAVE_WCHAR_H = @HAVE_WCHAR_H@
+HAVE_WCHAR_T = @HAVE_WCHAR_T@
+HAVE_WCPCPY = @HAVE_WCPCPY@
+HAVE_WCPNCPY = @HAVE_WCPNCPY@
+HAVE_WCRTOMB = @HAVE_WCRTOMB@
+HAVE_WCSCASECMP = @HAVE_WCSCASECMP@
+HAVE_WCSCAT = @HAVE_WCSCAT@
+HAVE_WCSCHR = @HAVE_WCSCHR@
+HAVE_WCSCMP = @HAVE_WCSCMP@
+HAVE_WCSCOLL = @HAVE_WCSCOLL@
+HAVE_WCSCPY = @HAVE_WCSCPY@
+HAVE_WCSCSPN = @HAVE_WCSCSPN@
+HAVE_WCSDUP = @HAVE_WCSDUP@
+HAVE_WCSLEN = @HAVE_WCSLEN@
+HAVE_WCSNCASECMP = @HAVE_WCSNCASECMP@
+HAVE_WCSNCAT = @HAVE_WCSNCAT@
+HAVE_WCSNCMP = @HAVE_WCSNCMP@
+HAVE_WCSNCPY = @HAVE_WCSNCPY@
+HAVE_WCSNLEN = @HAVE_WCSNLEN@
+HAVE_WCSNRTOMBS = @HAVE_WCSNRTOMBS@
+HAVE_WCSPBRK = @HAVE_WCSPBRK@
+HAVE_WCSRCHR = @HAVE_WCSRCHR@
+HAVE_WCSRTOMBS = @HAVE_WCSRTOMBS@
+HAVE_WCSSPN = @HAVE_WCSSPN@
+HAVE_WCSSTR = @HAVE_WCSSTR@
+HAVE_WCSTOK = @HAVE_WCSTOK@
+HAVE_WCSWIDTH = @HAVE_WCSWIDTH@
+HAVE_WCSXFRM = @HAVE_WCSXFRM@
+HAVE_WCTRANS_T = @HAVE_WCTRANS_T@
+HAVE_WCTYPE_H = @HAVE_WCTYPE_H@
+HAVE_WCTYPE_T = @HAVE_WCTYPE_T@
+HAVE_WINSOCK2_H = @HAVE_WINSOCK2_H@
+HAVE_WINT_T = @HAVE_WINT_T@
+HAVE_WMEMCHR = @HAVE_WMEMCHR@
+HAVE_WMEMCMP = @HAVE_WMEMCMP@
+HAVE_WMEMCPY = @HAVE_WMEMCPY@
+HAVE_WMEMMOVE = @HAVE_WMEMMOVE@
+HAVE_WMEMSET = @HAVE_WMEMSET@
+HAVE_XLOCALE_H = @HAVE_XLOCALE_H@
+HAVE__BOOL = @HAVE__BOOL@
+HAVE__EXIT = @HAVE__EXIT@
+INCLUDE_NEXT = @INCLUDE_NEXT@
+INCLUDE_NEXT_AS_FIRST_DIRECTIVE = @INCLUDE_NEXT_AS_FIRST_DIRECTIVE@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+INT32_MAX_LT_INTMAX_MAX = @INT32_MAX_LT_INTMAX_MAX@
+INT64_MAX_EQ_LONG_MAX = @INT64_MAX_EQ_LONG_MAX@
+INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@
+LDFLAGS = @LDFLAGS@
+LIBCSTACK = @LIBCSTACK@
+LIBINTL = @LIBINTL@
+LIBM4_LIBDEPS = @LIBM4_LIBDEPS@
+LIBM4_LTLIBDEPS = @LIBM4_LTLIBDEPS@
+LIBMULTITHREAD = @LIBMULTITHREAD@
+LIBOBJS = @LIBOBJS@
+LIBPTH = @LIBPTH@
+LIBPTH_PREFIX = @LIBPTH_PREFIX@
+LIBS = @LIBS@
+LIBSIGSEGV = @LIBSIGSEGV@
+LIBSIGSEGV_PREFIX = @LIBSIGSEGV_PREFIX@
+LIBTESTS_LIBDEPS = @LIBTESTS_LIBDEPS@
+LIBTHREAD = @LIBTHREAD@
+LOCALCHARSET_TESTS_ENVIRONMENT = @LOCALCHARSET_TESTS_ENVIRONMENT@
+LOCALE_FR = @LOCALE_FR@
+LOCALE_FR_UTF8 = @LOCALE_FR_UTF8@
+LOCALE_JA = @LOCALE_JA@
+LOCALE_TR_UTF8 = @LOCALE_TR_UTF8@
+LOCALE_ZH_CN = @LOCALE_ZH_CN@
+LTLIBCSTACK = @LTLIBCSTACK@
+LTLIBINTL = @LTLIBINTL@
+LTLIBMULTITHREAD = @LTLIBMULTITHREAD@
+LTLIBOBJS = @LTLIBOBJS@
+LTLIBPTH = @LTLIBPTH@
+LTLIBSIGSEGV = @LTLIBSIGSEGV@
+LTLIBTHREAD = @LTLIBTHREAD@
+M4_LIBOBJS = @M4_LIBOBJS@
+M4_LTLIBOBJS = @M4_LTLIBOBJS@
+M4tests_LIBOBJS = @M4tests_LIBOBJS@
+M4tests_LTLIBOBJS = @M4tests_LTLIBOBJS@
+M4tests_WITNESS = @M4tests_WITNESS@
+MAKEINFO = @MAKEINFO@
+MKDIR_P = @MKDIR_P@
+NEXT_AS_FIRST_DIRECTIVE_DIRENT_H = @NEXT_AS_FIRST_DIRECTIVE_DIRENT_H@
+NEXT_AS_FIRST_DIRECTIVE_ERRNO_H = @NEXT_AS_FIRST_DIRECTIVE_ERRNO_H@
+NEXT_AS_FIRST_DIRECTIVE_FCNTL_H = @NEXT_AS_FIRST_DIRECTIVE_FCNTL_H@
+NEXT_AS_FIRST_DIRECTIVE_FLOAT_H = @NEXT_AS_FIRST_DIRECTIVE_FLOAT_H@
+NEXT_AS_FIRST_DIRECTIVE_GETOPT_H = @NEXT_AS_FIRST_DIRECTIVE_GETOPT_H@
+NEXT_AS_FIRST_DIRECTIVE_INTTYPES_H = @NEXT_AS_FIRST_DIRECTIVE_INTTYPES_H@
+NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H = @NEXT_AS_FIRST_DIRECTIVE_LANGINFO_H@
+NEXT_AS_FIRST_DIRECTIVE_LOCALE_H = @NEXT_AS_FIRST_DIRECTIVE_LOCALE_H@
+NEXT_AS_FIRST_DIRECTIVE_MATH_H = @NEXT_AS_FIRST_DIRECTIVE_MATH_H@
+NEXT_AS_FIRST_DIRECTIVE_SCHED_H = @NEXT_AS_FIRST_DIRECTIVE_SCHED_H@
+NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H = @NEXT_AS_FIRST_DIRECTIVE_SIGNAL_H@
+NEXT_AS_FIRST_DIRECTIVE_SPAWN_H = @NEXT_AS_FIRST_DIRECTIVE_SPAWN_H@
+NEXT_AS_FIRST_DIRECTIVE_STDARG_H = @NEXT_AS_FIRST_DIRECTIVE_STDARG_H@
+NEXT_AS_FIRST_DIRECTIVE_STDDEF_H = @NEXT_AS_FIRST_DIRECTIVE_STDDEF_H@
+NEXT_AS_FIRST_DIRECTIVE_STDINT_H = @NEXT_AS_FIRST_DIRECTIVE_STDINT_H@
+NEXT_AS_FIRST_DIRECTIVE_STDIO_H = @NEXT_AS_FIRST_DIRECTIVE_STDIO_H@
+NEXT_AS_FIRST_DIRECTIVE_STDLIB_H = @NEXT_AS_FIRST_DIRECTIVE_STDLIB_H@
+NEXT_AS_FIRST_DIRECTIVE_STRING_H = @NEXT_AS_FIRST_DIRECTIVE_STRING_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_STAT_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TIME_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_TYPES_H@
+NEXT_AS_FIRST_DIRECTIVE_SYS_WAIT_H = @NEXT_AS_FIRST_DIRECTIVE_SYS_WAIT_H@
+NEXT_AS_FIRST_DIRECTIVE_TIME_H = @NEXT_AS_FIRST_DIRECTIVE_TIME_H@
+NEXT_AS_FIRST_DIRECTIVE_UNISTD_H = @NEXT_AS_FIRST_DIRECTIVE_UNISTD_H@
+NEXT_AS_FIRST_DIRECTIVE_WCHAR_H = @NEXT_AS_FIRST_DIRECTIVE_WCHAR_H@
+NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H = @NEXT_AS_FIRST_DIRECTIVE_WCTYPE_H@
+NEXT_DIRENT_H = @NEXT_DIRENT_H@
+NEXT_ERRNO_H = @NEXT_ERRNO_H@
+NEXT_FCNTL_H = @NEXT_FCNTL_H@
+NEXT_FLOAT_H = @NEXT_FLOAT_H@
+NEXT_GETOPT_H = @NEXT_GETOPT_H@
+NEXT_INTTYPES_H = @NEXT_INTTYPES_H@
+NEXT_LANGINFO_H = @NEXT_LANGINFO_H@
+NEXT_LOCALE_H = @NEXT_LOCALE_H@
+NEXT_MATH_H = @NEXT_MATH_H@
+NEXT_SCHED_H = @NEXT_SCHED_H@
+NEXT_SIGNAL_H = @NEXT_SIGNAL_H@
+NEXT_SPAWN_H = @NEXT_SPAWN_H@
+NEXT_STDARG_H = @NEXT_STDARG_H@
+NEXT_STDDEF_H = @NEXT_STDDEF_H@
+NEXT_STDINT_H = @NEXT_STDINT_H@
+NEXT_STDIO_H = @NEXT_STDIO_H@
+NEXT_STDLIB_H = @NEXT_STDLIB_H@
+NEXT_STRING_H = @NEXT_STRING_H@
+NEXT_SYS_STAT_H = @NEXT_SYS_STAT_H@
+NEXT_SYS_TIME_H = @NEXT_SYS_TIME_H@
+NEXT_SYS_TYPES_H = @NEXT_SYS_TYPES_H@
+NEXT_SYS_WAIT_H = @NEXT_SYS_WAIT_H@
+NEXT_TIME_H = @NEXT_TIME_H@
+NEXT_UNISTD_H = @NEXT_UNISTD_H@
+NEXT_WCHAR_H = @NEXT_WCHAR_H@
+NEXT_WCTYPE_H = @NEXT_WCTYPE_H@
+OBJEXT = @OBJEXT@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PRAGMA_COLUMNS = @PRAGMA_COLUMNS@
+PRAGMA_SYSTEM_HEADER = @PRAGMA_SYSTEM_HEADER@
+PRIPTR_PREFIX = @PRIPTR_PREFIX@
+PRI_MACROS_BROKEN = @PRI_MACROS_BROKEN@
+PTHREAD_H_DEFINES_STRUCT_TIMESPEC = @PTHREAD_H_DEFINES_STRUCT_TIMESPEC@
+PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@
+RANLIB = @RANLIB@
+REPLACE_BTOWC = @REPLACE_BTOWC@
+REPLACE_CALLOC = @REPLACE_CALLOC@
+REPLACE_CANONICALIZE_FILE_NAME = @REPLACE_CANONICALIZE_FILE_NAME@
+REPLACE_CBRTF = @REPLACE_CBRTF@
+REPLACE_CBRTL = @REPLACE_CBRTL@
+REPLACE_CEIL = @REPLACE_CEIL@
+REPLACE_CEILF = @REPLACE_CEILF@
+REPLACE_CEILL = @REPLACE_CEILL@
+REPLACE_CHOWN = @REPLACE_CHOWN@
+REPLACE_CLOSE = @REPLACE_CLOSE@
+REPLACE_CLOSEDIR = @REPLACE_CLOSEDIR@
+REPLACE_DIRFD = @REPLACE_DIRFD@
+REPLACE_DPRINTF = @REPLACE_DPRINTF@
+REPLACE_DUP = @REPLACE_DUP@
+REPLACE_DUP2 = @REPLACE_DUP2@
+REPLACE_DUPLOCALE = @REPLACE_DUPLOCALE@
+REPLACE_EXP2 = @REPLACE_EXP2@
+REPLACE_EXP2L = @REPLACE_EXP2L@
+REPLACE_EXPM1 = @REPLACE_EXPM1@
+REPLACE_EXPM1F = @REPLACE_EXPM1F@
+REPLACE_FABSL = @REPLACE_FABSL@
+REPLACE_FCHOWNAT = @REPLACE_FCHOWNAT@
+REPLACE_FCLOSE = @REPLACE_FCLOSE@
+REPLACE_FCNTL = @REPLACE_FCNTL@
+REPLACE_FDOPEN = @REPLACE_FDOPEN@
+REPLACE_FDOPENDIR = @REPLACE_FDOPENDIR@
+REPLACE_FFLUSH = @REPLACE_FFLUSH@
+REPLACE_FLOOR = @REPLACE_FLOOR@
+REPLACE_FLOORF = @REPLACE_FLOORF@
+REPLACE_FLOORL = @REPLACE_FLOORL@
+REPLACE_FMA = @REPLACE_FMA@
+REPLACE_FMAF = @REPLACE_FMAF@
+REPLACE_FMAL = @REPLACE_FMAL@
+REPLACE_FMOD = @REPLACE_FMOD@
+REPLACE_FMODF = @REPLACE_FMODF@
+REPLACE_FMODL = @REPLACE_FMODL@
+REPLACE_FOPEN = @REPLACE_FOPEN@
+REPLACE_FPRINTF = @REPLACE_FPRINTF@
+REPLACE_FPURGE = @REPLACE_FPURGE@
+REPLACE_FREOPEN = @REPLACE_FREOPEN@
+REPLACE_FREXP = @REPLACE_FREXP@
+REPLACE_FREXPF = @REPLACE_FREXPF@
+REPLACE_FREXPL = @REPLACE_FREXPL@
+REPLACE_FSEEK = @REPLACE_FSEEK@
+REPLACE_FSEEKO = @REPLACE_FSEEKO@
+REPLACE_FSTAT = @REPLACE_FSTAT@
+REPLACE_FSTATAT = @REPLACE_FSTATAT@
+REPLACE_FTELL = @REPLACE_FTELL@
+REPLACE_FTELLO = @REPLACE_FTELLO@
+REPLACE_FTRUNCATE = @REPLACE_FTRUNCATE@
+REPLACE_FUTIMENS = @REPLACE_FUTIMENS@
+REPLACE_GETCWD = @REPLACE_GETCWD@
+REPLACE_GETDELIM = @REPLACE_GETDELIM@
+REPLACE_GETDOMAINNAME = @REPLACE_GETDOMAINNAME@
+REPLACE_GETGROUPS = @REPLACE_GETGROUPS@
+REPLACE_GETLINE = @REPLACE_GETLINE@
+REPLACE_GETLOGIN_R = @REPLACE_GETLOGIN_R@
+REPLACE_GETPAGESIZE = @REPLACE_GETPAGESIZE@
+REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@
+REPLACE_HUGE_VAL = @REPLACE_HUGE_VAL@
+REPLACE_HYPOT = @REPLACE_HYPOT@
+REPLACE_HYPOTF = @REPLACE_HYPOTF@
+REPLACE_HYPOTL = @REPLACE_HYPOTL@
+REPLACE_ILOGB = @REPLACE_ILOGB@
+REPLACE_ILOGBF = @REPLACE_ILOGBF@
+REPLACE_ISATTY = @REPLACE_ISATTY@
+REPLACE_ISFINITE = @REPLACE_ISFINITE@
+REPLACE_ISINF = @REPLACE_ISINF@
+REPLACE_ISNAN = @REPLACE_ISNAN@
+REPLACE_ISWBLANK = @REPLACE_ISWBLANK@
+REPLACE_ISWCNTRL = @REPLACE_ISWCNTRL@
+REPLACE_ITOLD = @REPLACE_ITOLD@
+REPLACE_LCHOWN = @REPLACE_LCHOWN@
+REPLACE_LDEXPL = @REPLACE_LDEXPL@
+REPLACE_LINK = @REPLACE_LINK@
+REPLACE_LINKAT = @REPLACE_LINKAT@
+REPLACE_LOCALECONV = @REPLACE_LOCALECONV@
+REPLACE_LOCALTIME_R = @REPLACE_LOCALTIME_R@
+REPLACE_LOG = @REPLACE_LOG@
+REPLACE_LOG10 = @REPLACE_LOG10@
+REPLACE_LOG10F = @REPLACE_LOG10F@
+REPLACE_LOG10L = @REPLACE_LOG10L@
+REPLACE_LOG1P = @REPLACE_LOG1P@
+REPLACE_LOG1PF = @REPLACE_LOG1PF@
+REPLACE_LOG1PL = @REPLACE_LOG1PL@
+REPLACE_LOG2 = @REPLACE_LOG2@
+REPLACE_LOG2F = @REPLACE_LOG2F@
+REPLACE_LOG2L = @REPLACE_LOG2L@
+REPLACE_LOGB = @REPLACE_LOGB@
+REPLACE_LOGBF = @REPLACE_LOGBF@
+REPLACE_LOGBL = @REPLACE_LOGBL@
+REPLACE_LOGF = @REPLACE_LOGF@
+REPLACE_LOGL = @REPLACE_LOGL@
+REPLACE_LSEEK = @REPLACE_LSEEK@
+REPLACE_LSTAT = @REPLACE_LSTAT@
+REPLACE_MALLOC = @REPLACE_MALLOC@
+REPLACE_MBRLEN = @REPLACE_MBRLEN@
+REPLACE_MBRTOWC = @REPLACE_MBRTOWC@
+REPLACE_MBSINIT = @REPLACE_MBSINIT@
+REPLACE_MBSNRTOWCS = @REPLACE_MBSNRTOWCS@
+REPLACE_MBSRTOWCS = @REPLACE_MBSRTOWCS@
+REPLACE_MBSTATE_T = @REPLACE_MBSTATE_T@
+REPLACE_MBTOWC = @REPLACE_MBTOWC@
+REPLACE_MEMCHR = @REPLACE_MEMCHR@
+REPLACE_MEMMEM = @REPLACE_MEMMEM@
+REPLACE_MKDIR = @REPLACE_MKDIR@
+REPLACE_MKFIFO = @REPLACE_MKFIFO@
+REPLACE_MKNOD = @REPLACE_MKNOD@
+REPLACE_MKSTEMP = @REPLACE_MKSTEMP@
+REPLACE_MKTIME = @REPLACE_MKTIME@
+REPLACE_MODF = @REPLACE_MODF@
+REPLACE_MODFF = @REPLACE_MODFF@
+REPLACE_MODFL = @REPLACE_MODFL@
+REPLACE_NAN = @REPLACE_NAN@
+REPLACE_NANOSLEEP = @REPLACE_NANOSLEEP@
+REPLACE_NL_LANGINFO = @REPLACE_NL_LANGINFO@
+REPLACE_NULL = @REPLACE_NULL@
+REPLACE_OBSTACK_PRINTF = @REPLACE_OBSTACK_PRINTF@
+REPLACE_OPEN = @REPLACE_OPEN@
+REPLACE_OPENAT = @REPLACE_OPENAT@
+REPLACE_OPENDIR = @REPLACE_OPENDIR@
+REPLACE_PERROR = @REPLACE_PERROR@
+REPLACE_POPEN = @REPLACE_POPEN@
+REPLACE_POSIX_SPAWN = @REPLACE_POSIX_SPAWN@
+REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE = @REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE@
+REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 = @REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDDUP2@
+REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN = @REPLACE_POSIX_SPAWN_FILE_ACTIONS_ADDOPEN@
+REPLACE_PREAD = @REPLACE_PREAD@
+REPLACE_PRINTF = @REPLACE_PRINTF@
+REPLACE_PTHREAD_SIGMASK = @REPLACE_PTHREAD_SIGMASK@
+REPLACE_PTSNAME = @REPLACE_PTSNAME@
+REPLACE_PTSNAME_R = @REPLACE_PTSNAME_R@
+REPLACE_PUTENV = @REPLACE_PUTENV@
+REPLACE_PWRITE = @REPLACE_PWRITE@
+REPLACE_RAISE = @REPLACE_RAISE@
+REPLACE_RANDOM_R = @REPLACE_RANDOM_R@
+REPLACE_READ = @REPLACE_READ@
+REPLACE_READLINK = @REPLACE_READLINK@
+REPLACE_REALLOC = @REPLACE_REALLOC@
+REPLACE_REALPATH = @REPLACE_REALPATH@
+REPLACE_REMAINDER = @REPLACE_REMAINDER@
+REPLACE_REMAINDERF = @REPLACE_REMAINDERF@
+REPLACE_REMAINDERL = @REPLACE_REMAINDERL@
+REPLACE_REMOVE = @REPLACE_REMOVE@
+REPLACE_RENAME = @REPLACE_RENAME@
+REPLACE_RENAMEAT = @REPLACE_RENAMEAT@
+REPLACE_RMDIR = @REPLACE_RMDIR@
+REPLACE_ROUND = @REPLACE_ROUND@
+REPLACE_ROUNDF = @REPLACE_ROUNDF@
+REPLACE_ROUNDL = @REPLACE_ROUNDL@
+REPLACE_SETENV = @REPLACE_SETENV@
+REPLACE_SETLOCALE = @REPLACE_SETLOCALE@
+REPLACE_SIGNBIT = @REPLACE_SIGNBIT@
+REPLACE_SIGNBIT_USING_GCC = @REPLACE_SIGNBIT_USING_GCC@
+REPLACE_SLEEP = @REPLACE_SLEEP@
+REPLACE_SNPRINTF = @REPLACE_SNPRINTF@
+REPLACE_SPRINTF = @REPLACE_SPRINTF@
+REPLACE_SQRTL = @REPLACE_SQRTL@
+REPLACE_STAT = @REPLACE_STAT@
+REPLACE_STDIO_READ_FUNCS = @REPLACE_STDIO_READ_FUNCS@
+REPLACE_STDIO_WRITE_FUNCS = @REPLACE_STDIO_WRITE_FUNCS@
+REPLACE_STPNCPY = @REPLACE_STPNCPY@
+REPLACE_STRCASESTR = @REPLACE_STRCASESTR@
+REPLACE_STRCHRNUL = @REPLACE_STRCHRNUL@
+REPLACE_STRDUP = @REPLACE_STRDUP@
+REPLACE_STRERROR = @REPLACE_STRERROR@
+REPLACE_STRERROR_R = @REPLACE_STRERROR_R@
+REPLACE_STRNCAT = @REPLACE_STRNCAT@
+REPLACE_STRNDUP = @REPLACE_STRNDUP@
+REPLACE_STRNLEN = @REPLACE_STRNLEN@
+REPLACE_STRSIGNAL = @REPLACE_STRSIGNAL@
+REPLACE_STRSTR = @REPLACE_STRSTR@
+REPLACE_STRTOD = @REPLACE_STRTOD@
+REPLACE_STRTOIMAX = @REPLACE_STRTOIMAX@
+REPLACE_STRTOK_R = @REPLACE_STRTOK_R@
+REPLACE_STRUCT_LCONV = @REPLACE_STRUCT_LCONV@
+REPLACE_STRUCT_TIMEVAL = @REPLACE_STRUCT_TIMEVAL@
+REPLACE_SYMLINK = @REPLACE_SYMLINK@
+REPLACE_TIMEGM = @REPLACE_TIMEGM@
+REPLACE_TMPFILE = @REPLACE_TMPFILE@
+REPLACE_TOWLOWER = @REPLACE_TOWLOWER@
+REPLACE_TRUNC = @REPLACE_TRUNC@
+REPLACE_TRUNCF = @REPLACE_TRUNCF@
+REPLACE_TRUNCL = @REPLACE_TRUNCL@
+REPLACE_TTYNAME_R = @REPLACE_TTYNAME_R@
+REPLACE_UNLINK = @REPLACE_UNLINK@
+REPLACE_UNLINKAT = @REPLACE_UNLINKAT@
+REPLACE_UNSETENV = @REPLACE_UNSETENV@
+REPLACE_USLEEP = @REPLACE_USLEEP@
+REPLACE_UTIMENSAT = @REPLACE_UTIMENSAT@
+REPLACE_VASPRINTF = @REPLACE_VASPRINTF@
+REPLACE_VDPRINTF = @REPLACE_VDPRINTF@
+REPLACE_VFPRINTF = @REPLACE_VFPRINTF@
+REPLACE_VPRINTF = @REPLACE_VPRINTF@
+REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@
+REPLACE_VSPRINTF = @REPLACE_VSPRINTF@
+REPLACE_WCRTOMB = @REPLACE_WCRTOMB@
+REPLACE_WCSNRTOMBS = @REPLACE_WCSNRTOMBS@
+REPLACE_WCSRTOMBS = @REPLACE_WCSRTOMBS@
+REPLACE_WCSWIDTH = @REPLACE_WCSWIDTH@
+REPLACE_WCTOB = @REPLACE_WCTOB@
+REPLACE_WCTOMB = @REPLACE_WCTOMB@
+REPLACE_WCWIDTH = @REPLACE_WCWIDTH@
+REPLACE_WRITE = @REPLACE_WRITE@
+SCHED_H = @SCHED_H@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@
+SIZE_T_SUFFIX = @SIZE_T_SUFFIX@
+STDARG_H = @STDARG_H@
+STDBOOL_H = @STDBOOL_H@
+STDDEF_H = @STDDEF_H@
+STDINT_H = @STDINT_H@
+STRIP = @STRIP@
+SYS_TIME_H_DEFINES_STRUCT_TIMESPEC = @SYS_TIME_H_DEFINES_STRUCT_TIMESPEC@
+TIME_H_DEFINES_STRUCT_TIMESPEC = @TIME_H_DEFINES_STRUCT_TIMESPEC@
+UINT32_MAX_LT_UINTMAX_MAX = @UINT32_MAX_LT_UINTMAX_MAX@
+UINT64_MAX_EQ_ULONG_MAX = @UINT64_MAX_EQ_ULONG_MAX@
+UNDEFINE_STRTOK_R = @UNDEFINE_STRTOK_R@
+UNISTD_H_HAVE_WINSOCK2_H = @UNISTD_H_HAVE_WINSOCK2_H@
+UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS = @UNISTD_H_HAVE_WINSOCK2_H_AND_USE_SOCKETS@
+VERSION = @VERSION@
+WARN_CFLAGS = @WARN_CFLAGS@
+WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@
+WERROR_CFLAGS = @WERROR_CFLAGS@
+WINDOWS_64_BIT_OFF_T = @WINDOWS_64_BIT_OFF_T@
+WINDOWS_64_BIT_ST_SIZE = @WINDOWS_64_BIT_ST_SIZE@
+WINT_T_SUFFIX = @WINT_T_SUFFIX@
+abs_aux_dir = @abs_aux_dir@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+lispdir = @lispdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target_alias = @target_alias@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+info_TEXINFOS = m4.texi
+m4_TEXINFOS = fdl-1.3.texi gpl-3.0.texi
+man_MANS = $(srcdir)/m4.1
+EXTRA_DIST = $(man_MANS) gendocs_template
+MAINTAINERCLEANFILES = $(man_MANS) gendocs_template
+SUFFIXES = .1
+HELP2MAN = $(SHELL) $(top_srcdir)/build-aux/missing --run help2man
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .1 .dvi .html .info .pdf .ps .texi
+$(srcdir)/Makefile.in:  $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu doc/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure:  $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4):  $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+.texi.info:
+	$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
+	am__cwd=`pwd` && $(am__cd) $(srcdir) && \
+	rm -rf $$backupdir && mkdir $$backupdir && \
+	if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
+	  for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
+	    if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
+	  done; \
+	else :; fi && \
+	cd "$$am__cwd"; \
+	if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $@ $<; \
+	then \
+	  rc=0; \
+	  $(am__cd) $(srcdir); \
+	else \
+	  rc=$$?; \
+	  $(am__cd) $(srcdir) && \
+	  $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
+	fi; \
+	rm -rf $$backupdir; exit $$rc
+
+.texi.dvi:
+	$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
+	$<
+
+.texi.pdf:
+	$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
+	$<
+
+.texi.html:
+	$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
+	$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $(@:.html=.htp) $<; \
+	then \
+	  rm -rf $@ && mv $(@:.html=.htp) $@; \
+	else \
+	  rm -rf $(@:.html=.htp); exit 1; \
+	fi
+$(srcdir)/m4.info: m4.texi $(srcdir)/version.texi $(m4_TEXINFOS)
+m4.dvi: m4.texi $(srcdir)/version.texi $(m4_TEXINFOS)
+m4.pdf: m4.texi $(srcdir)/version.texi $(m4_TEXINFOS)
+m4.html: m4.texi $(srcdir)/version.texi $(m4_TEXINFOS)
+$(srcdir)/version.texi:  $(srcdir)/stamp-vti
+$(srcdir)/stamp-vti: m4.texi $(top_srcdir)/configure
+	@(dir=.; test -f ./m4.texi || dir=$(srcdir); \
+	set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/m4.texi`; \
+	echo "@set UPDATED $$1 $$2 $$3"; \
+	echo "@set UPDATED-MONTH $$2 $$3"; \
+	echo "@set EDITION $(VERSION)"; \
+	echo "@set VERSION $(VERSION)") > vti.tmp
+	@cmp -s vti.tmp $(srcdir)/version.texi \
+	  || (echo "Updating $(srcdir)/version.texi"; \
+	      cp vti.tmp $(srcdir)/version.texi)
+	-@rm -f vti.tmp
+	@cp $(srcdir)/version.texi $@
+
+mostlyclean-vti:
+	-rm -f vti.tmp
+
+maintainer-clean-vti:
+	-rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
+.dvi.ps:
+	$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	$(DVIPS) $(AM_V_texinfo) -o $@ $<
+
+uninstall-dvi-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(dvidir)/$$f"; \
+	done
+
+uninstall-html-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
+	  rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
+	done
+
+uninstall-info-am:
+	@$(PRE_UNINSTALL)
+	@if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
+	    if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
+	    then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
+	  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 test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
+	     echo " cd '$(DESTDIR)$(infodir)' && 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
+
+uninstall-pdf-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
+	done
+
+uninstall-ps-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(psdir)/$$f"; \
+	done
+
+dist-info: $(INFO_DEPS)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  case $$base in \
+	    $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$base; then d=.; else d=$(srcdir); fi; \
+	  base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
+	    if test -f $$file; then \
+	      relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+	      test -f "$(distdir)/$$relfile" || \
+		cp -p $$file "$(distdir)/$$relfile"; \
+	    else :; fi; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -rf m4.t2d m4.t2p
+
+clean-aminfo:
+	-test -z "m4.dvi m4.pdf m4.ps m4.html" \
+	|| rm -rf m4.dvi m4.pdf m4.ps m4.html
+
+maintainer-clean-aminfo:
+	@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
+install-man1: $(man_MANS)
+	@$(NORMAL_INSTALL)
+	@list1=''; \
+	list2='$(man_MANS)'; \
+	test -n "$(man1dir)" \
+	  && test -n "`echo $$list1$$list2`" \
+	  || exit 0; \
+	echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
+	$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
+	{ for i in $$list1; do echo "$$i"; done;  \
+	if test -n "$$list2"; then \
+	  for i in $$list2; do echo "$$i"; done \
+	    | sed -n '/\.1[a-z]*$$/p'; \
+	fi; \
+	} | while read p; do \
+	  if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; echo "$$p"; \
+	done | \
+	sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+	sed 'N;N;s,\n, ,g' | { \
+	list=; while read file base inst; do \
+	  if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+	    echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+	    $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
+	  fi; \
+	done; \
+	for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+	while read files; do \
+	  test -z "$$files" || { \
+	    echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
+	    $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
+	done; }
+
+uninstall-man1:
+	@$(NORMAL_UNINSTALL)
+	@list=''; test -n "$(man1dir)" || exit 0; \
+	files=`{ for i in $$list; do echo "$$i"; done; \
+	l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.1[a-z]*$$/p'; \
+	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+	dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
+tags TAGS:
+
+ctags CTAGS:
+
+cscope cscopelist:
+
+
+distdir: $(DISTFILES)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
+	list='$(DISTFILES)'; \
+	  dist_files=`for file in $$list; do echo $$file; done | \
+	  sed -e "s|^$$srcdirstrip/||;t" \
+	      -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
+	case $$dist_files in \
+	  */*) $(MKDIR_P) `echo "$$dist_files" | \
+			   sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
+			   sort -u` ;; \
+	esac; \
+	for file in $$dist_files; do \
+	  if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+	  if test -d $$d/$$file; then \
+	    dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
+	    if test -d "$(distdir)/$$file"; then \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
+	      cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
+	      find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
+	    fi; \
+	    cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
+	  else \
+	    test -f "$(distdir)/$$file" \
+	    || cp -p $$d/$$file "$(distdir)/$$file" \
+	    || exit 1; \
+	  fi; \
+	done
+	$(MAKE) $(AM_MAKEFLAGS) \
+	  top_distdir="$(top_distdir)" distdir="$(distdir)" \
+	  dist-info
+check-am: all-am
+check: check-am
+all-am: Makefile $(INFO_DEPS) $(MANS)
+installdirs:
+	for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
+	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+	done
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	if test -z '$(STRIP)'; then \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	      install; \
+	else \
+	  $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	    install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	    "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
+	fi
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+clean: clean-am
+
+clean-am: clean-aminfo clean-generic mostlyclean-am
+
+distclean: distclean-am
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am: $(DVIS)
+
+html: html-am
+
+html-am: $(HTMLS)
+
+info: info-am
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am install-man
+
+install-dvi: install-dvi-am
+
+install-dvi-am: $(DVIS)
+	@$(NORMAL_INSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
+	done
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am: $(HTMLS)
+	@$(NORMAL_INSTALL)
+	@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  $(am__strip_dir) \
+	  d2=$$d$$p; \
+	  if test -d "$$d2"; then \
+	    echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
+	  else \
+	    list2="$$list2 $$d2"; \
+	  fi; \
+	done; \
+	test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+	done; }
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
+	fi; \
+	for file in $$list; do \
+	  case $$file in \
+	    $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  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 \
+	      echo "$$ifile"; \
+	    else : ; fi; \
+	  done; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
+	@$(POST_INSTALL)
+	@if $(am__can_run_installinfo); then \
+	  list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	  for file in $$list; do \
+	    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
+
+install-pdf: install-pdf-am
+
+install-pdf-am: $(PDFS)
+	@$(NORMAL_INSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
+install-ps: install-ps-am
+
+install-ps-am: $(PSS)
+	@$(NORMAL_INSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	if test -n "$$list"; then \
+	  echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
+	  $(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
+	fi; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+	maintainer-clean-generic maintainer-clean-vti
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti
+
+pdf: pdf-am
+
+pdf-am: $(PDFS)
+
+ps: ps-am
+
+ps-am: $(PSS)
+
+uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
+	uninstall-man uninstall-pdf-am uninstall-ps-am
+
+uninstall-man: uninstall-man1
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
+	cscopelist-am ctags-am dist-info distclean distclean-generic \
+	distdir dvi dvi-am html html-am info info-am install \
+	install-am install-data install-data-am install-dvi \
+	install-dvi-am install-exec install-exec-am install-html \
+	install-html-am install-info install-info-am install-man \
+	install-man1 install-pdf install-pdf-am install-ps \
+	install-ps-am install-strip installcheck installcheck-am \
+	installdirs maintainer-clean maintainer-clean-aminfo \
+	maintainer-clean-generic maintainer-clean-vti mostlyclean \
+	mostlyclean-aminfo mostlyclean-generic mostlyclean-vti pdf \
+	pdf-am ps ps-am tags-am uninstall uninstall-am \
+	uninstall-dvi-am uninstall-html-am uninstall-info-am \
+	uninstall-man uninstall-man1 uninstall-pdf-am uninstall-ps-am
+
+
+# Depend on ../.version for version, m4.c for usage text.  Do not depend on
+# built m4 executable, since not everyone has help2man or perl.
+# Build the man page once in the srcdir, rather than in every VPATH build
+# dir, to match how automake builds info pages.  This is safe for 'make
+# distcheck' since it is distributed pre-built.
+$(srcdir)/m4.1: $(top_srcdir)/.version $(top_srcdir)/src/m4.c
+	@if test -x ../src/m4$(EXEEXT) ; then \
+	  echo "Updating man page m4.1" ; \
+	  $(HELP2MAN) --name="macro processor" --source='$(PACKAGE_STRING)' \
+	    --info-page=m4 --output=$@ ../src/m4$(EXEEXT) ; \
+	else \
+	  echo "WARNING: The \`man' page \`$@' cannot be updated yet."; \
+	  echo "         Retry once the program executable is ready."; \
+	fi
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/doc/fdl-1.3.texi b/doc/fdl-1.3.texi
new file mode 100644
index 0000000..9c3bbe5
--- /dev/null
+++ b/doc/fdl-1.3.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+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
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+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.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+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.  (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.  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.  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, 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, 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, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and 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 material
+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.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+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
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+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.
+
+@item
+COPYING IN QUANTITY
+
+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 title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+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 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.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+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 fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+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
+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.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+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,
+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
+may not be included in the Modified Version.
+
+@item
+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
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+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
+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.
+
+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 of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+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.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+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, 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
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+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.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+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.
+
+@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, 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 in 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 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
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+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, and all the license notices in the
+Document, and any Warranty 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
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+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.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+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.3
+  or any later version published by the Free Software Foundation;
+  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 Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}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:
diff --git a/doc/gendocs_template b/doc/gendocs_template
new file mode 100644
index 0000000..63fbe53
--- /dev/null
+++ b/doc/gendocs_template
@@ -0,0 +1,87 @@
+<!--#include virtual="/server/header.html" -->
+<title>%%TITLE%% - GNU Project - Free Software Foundation (FSF)</title>
+<!--#include virtual="/server/banner.html" -->
+<h2>%%TITLE%%</h2>
+
+<address>Free Software Foundation</address>
+<address>last updated %%DATE%%</address>
+
+<p>This manual (%%PACKAGE%%) is available in the following formats:</p>
+
+<ul>
+<li><a href="%%PACKAGE%%.html">HTML
+    (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+<li><a href="html_node/index.html">HTML</a> - with one web page per
+    node.</li>
+%%IF HTML_SECTION%%
+<li><a href="html_section/index.html">HTML</a> - with one web page per
+    section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="html_chapter/index.html">HTML</a> - with one web page per
+    chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html.gz">HTML compressed
+    (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+    one web page.</li>
+<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+    (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per node.</li>
+%%IF HTML_SECTION%%
+<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
+    (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+    (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.info.tar.gz">Info document
+    (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li>
+<li><a href="%%PACKAGE%%.txt">ASCII text
+    (%%ASCII_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+    (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+    (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.pdf">PDF file
+    (%%PDF_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+    (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li>
+</ul>
+
+<p>You can <a href="http://shop.fsf.org/">buy printed copies of
+some manuals</a> (among other items) from the Free Software Foundation;
+this helps support FSF activities.</p>
+
+<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
+script</a>.)</p>
+
+<!-- If needed, change the copyright block at the bottom. In general,
+     all pages on the GNU web server should have the section about
+     verbatim copying.  Please do NOT remove this without talking
+     with the webmasters first.
+     Please make sure the copyright date is consistent with the document
+     and that it is like this: "2001, 2002", not this: "2001-2002". -->
+</div><!-- for id="content", starts in the include above -->
+<!--#include virtual="/server/footer.html" -->
+<div id="footer">
+
+<p>Please send general FSF &amp; GNU inquiries to
+<a href="mailto:gnu@gnu.org">&lt;gnu@gnu.org&gt;</a>.
+There are also <a href="/contact/">other ways to contact</a>
+the FSF.<br />
+Please send broken links and other corrections or suggestions to
+<a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
+
+<p>Copyright &copy; 2013 Free Software Foundation, Inc.</p>
+
+<p>Verbatim copying and distribution of this entire article are
+permitted worldwide, without royalty, in any medium, provided this
+notice, and the copyright notice, are preserved.</p>
+
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/gpl-3.0.texi b/doc/gpl-3.0.texi
new file mode 100644
index 0000000..0e2e212
--- /dev/null
+++ b/doc/gpl-3.0.texi
@@ -0,0 +1,717 @@
+@c The GNU General Public License.
+@center Version 3, 29 June 2007
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+@end display
+
+@heading Preamble
+
+The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom
+to share and change all versions of a program---to make sure it remains
+free software for all its users.  We, the Free Software Foundation,
+use the GNU General Public License for most of our software; it
+applies also to any other work released this way by its authors.  You
+can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you
+have certain responsibilities if you distribute copies of the
+software, or if you modify it: responsibilities to respect the freedom
+of others.
+
+For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too,
+receive or can get the source code.  And you must show them these
+terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the
+manufacturer can do so.  This is fundamentally incompatible with the
+aim of protecting users' freedom to change the software.  The
+systematic pattern of such abuse occurs in the area of products for
+individuals to use, which is precisely where it is most unacceptable.
+Therefore, we have designed this version of the GPL to prohibit the
+practice for those products.  If such problems arise substantially in
+other domains, we stand ready to extend this provision to those
+domains in future versions of the GPL, as needed to protect the
+freedom of users.
+
+Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish
+to avoid the special danger that patents applied to a free program
+could make it effectively proprietary.  To prevent this, the GPL
+assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+@heading TERMS AND CONDITIONS
+
+@enumerate 0
+@item Definitions.
+
+``This License'' refers to version 3 of the GNU General Public License.
+
+``Copyright'' also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+``The Program'' refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as ``you''.  ``Licensees'' and
+``recipients'' may be individuals or organizations.
+
+To ``modify'' a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy.  The resulting work is called a ``modified version'' of
+the earlier work or a work ``based on'' the earlier work.
+
+A ``covered work'' means either the unmodified Program or a work based
+on the Program.
+
+To ``propagate'' a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To ``convey'' a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays ``Appropriate Legal Notices'' to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+@item Source Code.
+
+The ``source code'' for a work means the preferred form of the work for
+making modifications to it.  ``Object code'' means any non-source form
+of a work.
+
+A ``Standard Interface'' means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+The ``System Libraries'' of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+``Major Component'', in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The ``Corresponding Source'' for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+@item Basic Permissions.
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright.  Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+@item Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+@item Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+@item Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+@enumerate a
+@item
+The work must carry prominent notices stating that you modified it,
+and giving a relevant date.
+
+@item
+The work must carry prominent notices stating that it is released
+under this License and any conditions added under section 7.  This
+requirement modifies the requirement in section 4 to ``keep intact all
+notices''.
+
+@item
+You must license the entire work, as a whole, under this License to
+anyone who comes into possession of a copy.  This License will
+therefore apply, along with any applicable section 7 additional terms,
+to the whole of the work, and all its parts, regardless of how they
+are packaged.  This License gives no permission to license the work in
+any other way, but it does not invalidate such permission if you have
+separately received it.
+
+@item
+If the work has interactive user interfaces, each must display
+Appropriate Legal Notices; however, if the Program has interactive
+interfaces that do not display Appropriate Legal Notices, your work
+need not make them do so.
+@end enumerate
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+``aggregate'' if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+@item  Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+@enumerate a
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by the
+Corresponding Source fixed on a durable physical medium customarily
+used for software interchange.
+
+@item
+Convey the object code in, or embodied in, a physical product
+(including a physical distribution medium), accompanied by a written
+offer, valid for at least three years and valid for as long as you
+offer spare parts or customer support for that product model, to give
+anyone who possesses the object code either (1) a copy of the
+Corresponding Source for all the software in the product that is
+covered by this License, on a durable physical medium customarily used
+for software interchange, for a price no more than your reasonable
+cost of physically performing this conveying of source, or (2) access
+to copy the Corresponding Source from a network server at no charge.
+
+@item
+Convey individual copies of the object code with a copy of the written
+offer to provide the Corresponding Source.  This alternative is
+allowed only occasionally and noncommercially, and only if you
+received the object code with such an offer, in accord with subsection
+6b.
+
+@item
+Convey the object code by offering access from a designated place
+(gratis or for a charge), and offer equivalent access to the
+Corresponding Source in the same way through the same place at no
+further charge.  You need not require recipients to copy the
+Corresponding Source along with the object code.  If the place to copy
+the object code is a network server, the Corresponding Source may be
+on a different server (operated by you or a third party) that supports
+equivalent copying facilities, provided you maintain clear directions
+next to the object code saying where to find the Corresponding Source.
+Regardless of what server hosts the Corresponding Source, you remain
+obligated to ensure that it is available for as long as needed to
+satisfy these requirements.
+
+@item
+Convey the object code using peer-to-peer transmission, provided you
+inform other peers where the object code and Corresponding Source of
+the work are being offered to the general public at no charge under
+subsection 6d.
+
+@end enumerate
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A ``User Product'' is either (1) a ``consumer product'', which means any
+tangible personal property which is normally used for personal,
+family, or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling.  In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage.  For a particular product received by a particular user,
+``normally used'' refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product.  A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+``Installation Information'' for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source.  The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed.  Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+@item Additional Terms.
+
+``Additional permissions'' are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+@enumerate a
+@item
+Disclaiming warranty or limiting liability differently from the terms
+of sections 15 and 16 of this License; or
+
+@item
+Requiring preservation of specified reasonable legal notices or author
+attributions in that material or in the Appropriate Legal Notices
+displayed by works containing it; or
+
+@item
+Prohibiting misrepresentation of the origin of that material, or
+requiring that modified versions of such material be marked in
+reasonable ways as different from the original version; or
+
+@item
+Limiting the use for publicity purposes of names of licensors or
+authors of the material; or
+
+@item
+Declining to grant rights under trademark law for use of some trade
+names, trademarks, or service marks; or
+
+@item
+Requiring indemnification of licensors and authors of that material by
+anyone who conveys the material (or modified versions of it) with
+contractual assumptions of liability to the recipient, for any
+liability that these contractual assumptions directly impose on those
+licensors and authors.
+@end enumerate
+
+All other non-permissive additional terms are considered ``further
+restrictions'' within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+@item Termination.
+
+You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+@item Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run
+a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+@item Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+An ``entity transaction'' is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+@item Patents.
+
+A ``contributor'' is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's ``contributor version''.
+
+A contributor's ``essential patent claims'' are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, ``control'' includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a ``patent license'' is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To ``grant'' such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  ``Knowingly relying'' means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is ``discriminatory'' if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License.  You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+@item No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey
+a covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all.  For example, if you agree
+to terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+@item Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+@item Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU General Public License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies that a certain numbered version of the GNU General Public
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that numbered version or
+of any later version published by the Free Software Foundation.  If
+the Program does not specify a version number of the GNU General
+Public License, you may choose any version ever published by the Free
+Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU General Public License can be used, that proxy's public
+statement of acceptance of a version permanently authorizes you to
+choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+@item Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW@.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+@item Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+@item Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+@end enumerate
+
+@heading END OF TERMS AND CONDITIONS
+
+@heading How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and a brief idea of what it does.}
+Copyright (C) @var{year} @var{name of author}
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at
+your option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see @url{http://www.gnu.org/licenses/}.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+@smallexample
+@var{program} Copyright (C) @var{year} @var{name of author}
+This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type @samp{show c} for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, your
+program's commands might be different; for a GUI interface, you would
+use an ``about box''.
+
+You should also get your employer (if you work as a programmer) or school,
+if any, to sign a ``copyright disclaimer'' for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+@url{http://www.gnu.org/licenses/}.
+
+The GNU General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may 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.  But
+first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
diff --git a/doc/m4.1 b/doc/m4.1
new file mode 100644
index 0000000..51233f0
--- /dev/null
+++ b/doc/m4.1
@@ -0,0 +1,151 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.43.3.
+.TH M4 "1" "September 2013" "GNU M4 1.4.17" "User Commands"
+.SH NAME
+m4 \- macro processor
+.SH SYNOPSIS
+.B m4
+[\fIOPTION\fR]... [\fIFILE\fR]...
+.SH DESCRIPTION
+Process macros in FILEs.  If no FILE or if FILE is `\-', standard input
+is read.
+.PP
+Mandatory or optional arguments to long options are mandatory or optional
+for short options too.
+.SS "Operation modes:"
+.TP
+\fB\-\-help\fR
+display this help and exit
+.TP
+\fB\-\-version\fR
+output version information and exit
+.TP
+\fB\-E\fR, \fB\-\-fatal\-warnings\fR
+once: warnings become errors, twice: stop
+execution at first error
+.TP
+\fB\-i\fR, \fB\-\-interactive\fR
+unbuffer output, ignore interrupts
+.TP
+\fB\-P\fR, \fB\-\-prefix\-builtins\fR
+force a `m4_' prefix to all builtins
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR, \fB\-\-silent\fR
+suppress some warnings for builtins
+.TP
+\fB\-\-warn\-macro\-sequence\fR[=\fIREGEXP\fR]
+warn if macro definition matches REGEXP,
+.IP
+default \e$\e({[^}]*}\e|[0\-9][0\-9]+\e)
+.SS "Preprocessor features:"
+.TP
+\fB\-D\fR, \fB\-\-define=NAME\fR[=\fIVALUE\fR]
+define NAME as having VALUE, or empty
+.TP
+\fB\-I\fR, \fB\-\-include\fR=\fIDIRECTORY\fR
+append DIRECTORY to include path
+.TP
+\fB\-s\fR, \fB\-\-synclines\fR
+generate `#line NUM "FILE"' lines
+.TP
+\fB\-U\fR, \fB\-\-undefine\fR=\fINAME\fR
+undefine NAME
+.SS "Limits control:"
+.TP
+\fB\-g\fR, \fB\-\-gnu\fR
+override \fB\-G\fR to re\-enable GNU extensions
+.TP
+\fB\-G\fR, \fB\-\-traditional\fR
+suppress all GNU extensions
+.TP
+\fB\-H\fR, \fB\-\-hashsize\fR=\fIPRIME\fR
+set symbol lookup hash table size [509]
+.TP
+\fB\-L\fR, \fB\-\-nesting\-limit\fR=\fINUMBER\fR
+change nesting limit, 0 for unlimited [0]
+.SS "Frozen state files:"
+.TP
+\fB\-F\fR, \fB\-\-freeze\-state\fR=\fIFILE\fR
+produce a frozen state on FILE at end
+.TP
+\fB\-R\fR, \fB\-\-reload\-state\fR=\fIFILE\fR
+reload a frozen state from FILE at start
+.SS "Debugging:"
+.TP
+\fB\-d\fR, \fB\-\-debug\fR[=\fIFLAGS\fR]
+set debug level (no FLAGS implies `aeq')
+.TP
+\fB\-\-debugfile\fR[=\fIFILE\fR]
+redirect debug and trace output to FILE
+(default stderr, discard if empty string)
+.TP
+\fB\-l\fR, \fB\-\-arglength\fR=\fINUM\fR
+restrict macro tracing size
+.TP
+\fB\-t\fR, \fB\-\-trace\fR=\fINAME\fR
+trace NAME when it is defined
+.SS "FLAGS is any of:"
+.TP
+a
+show actual arguments
+.TP
+c
+show before collect, after collect and after call
+.TP
+e
+show expansion
+.TP
+f
+say current input file name
+.TP
+i
+show changes in input files
+.TP
+l
+say current input line number
+.TP
+p
+show results of path searches
+.TP
+q
+quote values as necessary, with a or e flag
+.TP
+t
+trace for all macro calls, not only traceon'ed
+.TP
+x
+add a unique macro call id, useful with c flag
+.TP
+V
+shorthand for all of the above flags
+.PP
+If defined, the environment variable `M4PATH' is a colon\-separated list
+of directories included after any specified by `\-I'.
+.PP
+Exit status is 0 for success, 1 for failure, 63 for frozen file version
+mismatch, or whatever value was passed to the m4exit macro.
+.SH AUTHOR
+Written by Rene' Seindal.
+.SH "REPORTING BUGS"
+Report bugs to: bug\-m4@gnu.org
+.br
+GNU M4 home page: <http://www.gnu.org/software/m4/>
+.br
+General help using GNU software: <http://www.gnu.org/gethelp/>
+.SH COPYRIGHT
+Copyright \(co 2013 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH "SEE ALSO"
+The full documentation for
+.B m4
+is maintained as a Texinfo manual.  If the
+.B info
+and
+.B m4
+programs are properly installed at your site, the command
+.IP
+.B info m4
+.PP
+should give you access to the complete manual.
diff --git a/doc/m4.info b/doc/m4.info
new file mode 100644
index 0000000..a75386b
--- /dev/null
+++ b/doc/m4.info
@@ -0,0 +1,133 @@
+This is m4.info, produced by makeinfo version 5.1 from m4.texi.
+
+This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
+package containing an implementation of the m4 macro language.
+
+   Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; 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."
+INFO-DIR-SECTION Text creation and manipulation
+START-INFO-DIR-ENTRY
+* M4: (m4).                     A powerful macro processor.
+END-INFO-DIR-ENTRY
+
+
+Indirect:
+m4.info-1: 813
+m4.info-2: 301580
+
+Tag Table:
+(Indirect)
+Node: Top813
+Node: Preliminaries9617
+Node: Intro10303
+Node: History11934
+Node: Bugs16028
+Node: Manual17279
+Node: Invoking m420671
+Node: Operation modes22815
+Node: Preprocessor features25782
+Node: Limits control28878
+Node: Frozen state32775
+Node: Debugging options33574
+Node: Command line files35554
+Node: Syntax37127
+Node: Names38246
+Node: Quoted strings38708
+Node: Comments39357
+Node: Other tokens40234
+Node: Input processing40812
+Ref: Input processing-Footnote-148738
+Node: Macros48933
+Node: Invocation49427
+Node: Inhibiting Invocation50228
+Node: Macro Arguments54364
+Node: Quoting Arguments57423
+Node: Macro expansion59546
+Node: Definitions60247
+Node: Define61032
+Node: Arguments63468
+Node: Pseudo Arguments67138
+Node: Undefine70680
+Node: Defn71810
+Node: Pushdef76254
+Node: Indir78879
+Node: Builtin81002
+Node: Conditionals83219
+Node: Ifdef84161
+Node: Ifelse85022
+Node: Shift88335
+Node: Forloop98803
+Node: Foreach101440
+Node: Stacks106928
+Node: Composition109968
+Node: Debugging115907
+Node: Dumpdef116492
+Node: Trace117845
+Node: Debug Levels121402
+Node: Debug Output126093
+Node: Input Control127372
+Node: Dnl127909
+Node: Changequote129808
+Node: Changecom135890
+Node: Changeword139568
+Node: M4wrap145009
+Node: File Inclusion149005
+Node: Include149322
+Node: Search Path152030
+Node: Diversions152947
+Node: Divert154630
+Node: Undivert157155
+Node: Divnum160477
+Node: Cleardivert160941
+Node: Text handling162145
+Node: Len162868
+Node: Index macro163253
+Node: Regexp164125
+Node: Substr166656
+Node: Translit167700
+Node: Patsubst170420
+Node: Format174943
+Node: Arithmetic178134
+Node: Incr178583
+Node: Eval179356
+Node: Shell commands187288
+Node: Platform macros188210
+Node: Syscmd190325
+Node: Esyscmd192605
+Node: Sysval194114
+Node: Mkstemp195796
+Node: Miscellaneous199746
+Node: Errprint200179
+Node: Location201396
+Node: M4exit204167
+Node: Frozen files206252
+Node: Using frozen files207034
+Node: Frozen file format210299
+Node: Compatibility213365
+Node: Extensions214430
+Node: Incompatibilities218297
+Node: Other Incompatibilities227211
+Node: Answers229857
+Node: Improved exch230639
+Node: Improved forloop231177
+Node: Improved foreach236507
+Node: Improved copy249467
+Node: Improved m4wrap253421
+Node: Improved cleardivert255845
+Node: Improved capitalize256826
+Node: Improved fatal_error261686
+Node: Copying This Package262746
+Node: GNU General Public License263225
+Node: Copying This Manual301580
+Node: GNU Free Documentation License302100
+Node: Indices327210
+Node: Macro index327490
+Node: Concept index333873
+
+End Tag Table
diff --git a/doc/m4.info-1 b/doc/m4.info-1
new file mode 100644
index 0000000..db2ee65
--- /dev/null
+++ b/doc/m4.info-1
@@ -0,0 +1,7818 @@
+This is m4.info, produced by makeinfo version 5.1 from m4.texi.
+
+This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
+package containing an implementation of the m4 macro language.
+
+   Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; 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."
+INFO-DIR-SECTION Text creation and manipulation
+START-INFO-DIR-ENTRY
+* M4: (m4).                     A powerful macro processor.
+END-INFO-DIR-ENTRY
+
+
+File: m4.info,  Node: Top,  Next: Preliminaries,  Up: (dir)
+
+GNU M4
+******
+
+This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
+package containing an implementation of the m4 macro language.
+
+   Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; 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."
+
+   GNU 'm4' is an implementation of the traditional UNIX macro
+processor.  It is mostly SVR4 compatible, although it has some
+extensions (for example, handling more than 9 positional parameters to
+macros).  'm4' also has builtin functions for including files, running
+shell commands, doing arithmetic, etc.  Autoconf needs GNU 'm4' for
+generating 'configure' scripts, but not for running them.
+
+   GNU 'm4' was originally written by Rene' Seindal, with subsequent
+changes by Franc,ois Pinard and other volunteers on the Internet.  All
+names and email addresses can be found in the files 'm4-1.4.17/AUTHORS'
+and 'm4-1.4.17/THANKS' from the GNU M4 distribution.
+
+   This is release 1.4.17.  It is now considered stable: future releases
+in the 1.4.x series are only meant to fix bugs, increase speed, or
+improve documentation.  However...
+
+   An experimental feature, which would improve 'm4' usefulness, allows
+for changing the syntax for what is a "word" in 'm4'.  You should use:
+     ./configure --enable-changeword
+if you want this feature compiled in.  The current implementation slows
+down 'm4' considerably and is hardly acceptable.  In the future, 'm4'
+2.0 will come with a different set of new features that provide similar
+capabilities, but without the inefficiencies, so changeword will go away
+and _you should not count on it_.
+
+* Menu:
+
+* Preliminaries::               Introduction and preliminaries
+* Invoking m4::                 Invoking 'm4'
+* Syntax::                      Lexical and syntactic conventions
+
+* Macros::                      How to invoke macros
+* Definitions::                 How to define new macros
+* Conditionals::                Conditionals, loops, and recursion
+
+* Debugging::                   How to debug macros and input
+
+* Input Control::               Input control
+* File Inclusion::              File inclusion
+* Diversions::                  Diverting and undiverting output
+
+* Text handling::               Macros for text handling
+* Arithmetic::                  Macros for doing arithmetic
+* Shell commands::              Macros for running shell commands
+* Miscellaneous::               Miscellaneous builtin macros
+* Frozen files::                Fast loading of frozen state
+
+* Compatibility::               Compatibility with other versions of 'm4'
+* Answers::                     Correct version of some examples
+
+* Copying This Package::        How to make copies of the overall M4 package
+* Copying This Manual::         How to make copies of this manual
+* Indices::                     Indices of concepts and macros
+
+ -- The Detailed Node Listing --
+
+Introduction and preliminaries
+
+* Intro::                       Introduction to 'm4'
+* History::                     Historical references
+* Bugs::                        Problems and bugs
+* Manual::                      Using this manual
+
+Invoking 'm4'
+
+* Operation modes::             Command line options for operation modes
+* Preprocessor features::       Command line options for preprocessor features
+* Limits control::              Command line options for limits control
+* Frozen state::                Command line options for frozen state
+* Debugging options::           Command line options for debugging
+* Command line files::          Specifying input files on the command line
+
+Lexical and syntactic conventions
+
+* Names::                       Macro names
+* Quoted strings::              Quoting input to 'm4'
+* Comments::                    Comments in 'm4' input
+* Other tokens::                Other kinds of input tokens
+* Input processing::            How 'm4' copies input to output
+
+How to invoke macros
+
+* Invocation::                  Macro invocation
+* Inhibiting Invocation::       Preventing macro invocation
+* Macro Arguments::             Macro arguments
+* Quoting Arguments::           On Quoting Arguments to macros
+* Macro expansion::             Expanding macros
+
+How to define new macros
+
+* Define::                      Defining a new macro
+* Arguments::                   Arguments to macros
+* Pseudo Arguments::            Special arguments to macros
+* Undefine::                    Deleting a macro
+* Defn::                        Renaming macros
+* Pushdef::                     Temporarily redefining macros
+
+* Indir::                       Indirect call of macros
+* Builtin::                     Indirect call of builtins
+
+Conditionals, loops, and recursion
+
+* Ifdef::                       Testing if a macro is defined
+* Ifelse::                      If-else construct, or multibranch
+* Shift::                       Recursion in 'm4'
+* Forloop::                     Iteration by counting
+* Foreach::                     Iteration by list contents
+* Stacks::                      Working with definition stacks
+* Composition::                 Building macros with macros
+
+How to debug macros and input
+
+* Dumpdef::                     Displaying macro definitions
+* Trace::                       Tracing macro calls
+* Debug Levels::                Controlling debugging output
+* Debug Output::                Saving debugging output
+
+Input control
+
+* Dnl::                         Deleting whitespace in input
+* Changequote::                 Changing the quote characters
+* Changecom::                   Changing the comment delimiters
+* Changeword::                  Changing the lexical structure of words
+* M4wrap::                      Saving text until end of input
+
+File inclusion
+
+* Include::                     Including named files
+* Search Path::                 Searching for include files
+
+Diverting and undiverting output
+
+* Divert::                      Diverting output
+* Undivert::                    Undiverting output
+* Divnum::                      Diversion numbers
+* Cleardivert::                 Discarding diverted text
+
+Macros for text handling
+
+* Len::                         Calculating length of strings
+* Index macro::                 Searching for substrings
+* Regexp::                      Searching for regular expressions
+* Substr::                      Extracting substrings
+* Translit::                    Translating characters
+* Patsubst::                    Substituting text by regular expression
+* Format::                      Formatting strings (printf-like)
+
+Macros for doing arithmetic
+
+* Incr::                        Decrement and increment operators
+* Eval::                        Evaluating integer expressions
+
+Macros for running shell commands
+
+* Platform macros::             Determining the platform
+* Syscmd::                      Executing simple commands
+* Esyscmd::                     Reading the output of commands
+* Sysval::                      Exit status
+* Mkstemp::                     Making temporary files
+
+Miscellaneous builtin macros
+
+* Errprint::                    Printing error messages
+* Location::                    Printing current location
+* M4exit::                      Exiting from 'm4'
+
+Fast loading of frozen state
+
+* Using frozen files::          Using frozen files
+* Frozen file format::          Frozen file format
+
+Compatibility with other versions of 'm4'
+
+* Extensions::                  Extensions in GNU M4
+* Incompatibilities::           Facilities in System V m4 not in GNU M4
+* Other Incompatibilities::     Other incompatibilities
+
+Correct version of some examples
+
+* Improved exch::               Solution for 'exch'
+* Improved forloop::            Solution for 'forloop'
+* Improved foreach::            Solution for 'foreach'
+* Improved copy::               Solution for 'copy'
+* Improved m4wrap::             Solution for 'm4wrap'
+* Improved cleardivert::        Solution for 'cleardivert'
+* Improved capitalize::         Solution for 'capitalize'
+* Improved fatal_error::        Solution for 'fatal_error'
+
+How to make copies of the overall M4 package
+
+* GNU General Public License::  License for copying the M4 package
+
+How to make copies of this manual
+
+* GNU Free Documentation License::  License for copying this manual
+
+Indices of concepts and macros
+
+* Macro index::                 Index for all 'm4' macros
+* Concept index::               Index for many concepts
+
+
+
+File: m4.info,  Node: Preliminaries,  Next: Invoking m4,  Prev: Top,  Up: Top
+
+1 Introduction and preliminaries
+********************************
+
+This first chapter explains what GNU 'm4' is, where 'm4' comes from, how
+to read and use this documentation, how to call the 'm4' program, and
+how to report bugs about it.  It concludes by giving tips for reading
+the remainder of the manual.
+
+   The following chapters then detail all the features of the 'm4'
+language.
+
+* Menu:
+
+* Intro::                       Introduction to 'm4'
+* History::                     Historical references
+* Bugs::                        Problems and bugs
+* Manual::                      Using this manual
+
+
+File: m4.info,  Node: Intro,  Next: History,  Up: Preliminaries
+
+1.1 Introduction to 'm4'
+========================
+
+'m4' is a macro processor, in the sense that it copies its input to the
+output, expanding macros as it goes.  Macros are either builtin or
+user-defined, and can take any number of arguments.  Besides just doing
+macro expansion, 'm4' has builtin functions for including named files,
+running shell commands, doing integer arithmetic, manipulating text in
+various ways, performing recursion, etc.... 'm4' can be used either as a
+front-end to a compiler, or as a macro processor in its own right.
+
+   The 'm4' macro processor is widely available on all UNIXes, and has
+been standardized by POSIX. Usually, only a small percentage of users
+are aware of its existence.  However, those who find it often become
+committed users.  The popularity of GNU Autoconf, which requires GNU
+'m4' for _generating_ 'configure' scripts, is an incentive for many to
+install it, while these people will not themselves program in 'm4'.  GNU
+'m4' is mostly compatible with the System V, Release 4 version, except
+for some minor differences.  *Note Compatibility::, for more details.
+
+   Some people find 'm4' to be fairly addictive.  They first use 'm4'
+for simple problems, then take bigger and bigger challenges, learning
+how to write complex sets of 'm4' macros along the way.  Once really
+addicted, users pursue writing of sophisticated 'm4' applications even
+to solve simple problems, devoting more time debugging their 'm4'
+scripts than doing real work.  Beware that 'm4' may be dangerous for the
+health of compulsive programmers.
+
+
+File: m4.info,  Node: History,  Next: Bugs,  Prev: Intro,  Up: Preliminaries
+
+1.2 Historical references
+=========================
+
+Macro languages were invented early in the history of computing.  In the
+1950s Alan Perlis suggested that the macro language be independent of
+the language being processed.  Techniques such as conditional and
+recursive macros, and using macros to define other macros, were
+described by Doug McIlroy of Bell Labs in "Macro Instruction Extensions
+of Compiler Languages", _Communications of the ACM_ 3, 4 (1960), 214-20,
+<http://dx.doi.org/10.1145/367177.367223>.
+
+   An important precursor of 'm4' was GPM; see C. Strachey, "A general
+purpose macrogenerator", _Computer Journal_ 8, 3 (1965), 225-41,
+<http://dx.doi.org/10.1093/comjnl/8.3.225>.  GPM is also succinctly
+described in David Gries's book _Compiler Construction for Digital
+Computers_, Wiley (1971).  Strachey was a brilliant programmer: GPM fit
+into 250 machine instructions!
+
+   Inspired by GPM while visiting Strachey's Lab in 1968, McIlroy wrote
+a model preprocessor in that fit into a page of Snobol 3 code, and
+McIlroy and Robert Morris developed a series of further models at Bell
+Labs.  Andrew D. Hall followed up with M6, a general purpose macro
+processor used to port the Fortran source code of the Altran computer
+algebra system; see Hall's "The M6 Macro Processor", Computing Science
+Technical Report #2, Bell Labs (1972),
+<http://cm.bell-labs.com/cm/cs/cstr/2.pdf>.  M6's source code consisted
+of about 600 Fortran statements.  Its name was the first of the 'm4'
+line.
+
+   The Brian Kernighan and P.J. Plauger book _Software Tools_,
+Addison-Wesley (1976), describes and implements a Unix macro-processor
+language, which inspired Dennis Ritchie to write 'm3', a macro processor
+for the AP-3 minicomputer.
+
+   Kernighan and Ritchie then joined forces to develop the original
+'m4', described in "The M4 Macro Processor", Bell Laboratories (1977),
+<http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf>.  It had only
+21 builtin macros.
+
+   While 'GPM' was more _pure_, 'm4' is meant to deal with the true
+intricacies of real life: macros can be recognized without being
+pre-announced, skipping whitespace or end-of-lines is easier, more
+constructs are builtin instead of derived, etc.
+
+   Originally, the Kernighan and Plauger macro-processor, and then 'm3',
+formed the engine for the Rational FORTRAN preprocessor, that is, the
+'Ratfor' equivalent of 'cpp'.  Later, 'm4' was used as a front-end for
+'Ratfor', 'C' and 'Cobol'.
+
+   Rene' Seindal released his implementation of 'm4', GNU 'm4', in 1990,
+with the aim of removing the artificial limitations in many of the
+traditional 'm4' implementations, such as maximum line length, macro
+size, or number of macros.
+
+   The late Professor A. Dain Samples described and implemented a
+further evolution in the form of 'M5': "User's Guide to the M5 Macro
+Language: 2nd edition", Electronic Announcement on comp.compilers
+newsgroup (1992).
+
+   Franc,ois Pinard took over maintenance of GNU 'm4' in 1992, until
+1994 when he released GNU 'm4' 1.4, which was the stable release for 10
+years.  It was at this time that GNU Autoconf decided to require GNU
+'m4' as its underlying engine, since all other implementations of 'm4'
+had too many limitations.
+
+   More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
+addressed some long standing bugs in the venerable 1.4 release.  Then in
+2005, Gary V. Vaughan collected together the many patches to GNU 'm4'
+1.4 that were floating around the net and released 1.4.3 and 1.4.4.  And
+in 2006, Eric Blake joined the team and prepared patches for the release
+of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.  More bug fixes were incorporated in
+2007, with releases 1.4.9 and 1.4.10.  Eric continued with some
+portability fixes for 1.4.11 and 1.4.12 in 2008, 1.4.13 in 2009, 1.4.14
+and 1.4.15 in 2010, and 1.4.16 in 2011.
+
+   Meanwhile, development has continued on new features for 'm4', such
+as dynamic module loading and additional builtins.  When complete, GNU
+'m4' 2.0 will start a new series of releases.
+
+
+File: m4.info,  Node: Bugs,  Next: Manual,  Prev: History,  Up: Preliminaries
+
+1.3 Problems and bugs
+=====================
+
+If you have problems with GNU M4 or think you've found a bug, please
+report it.  Before reporting a bug, make sure you've actually found a
+real bug.  Carefully reread the documentation and see if it really says
+you can do what you're trying to do.  If it's not clear whether you
+should be able to do something or not, report that too; it's a bug in
+the documentation!
+
+   Before reporting a bug or trying to fix it yourself, try to isolate
+it to the smallest possible input file that reproduces the problem.
+Then send us the input file and the exact results 'm4' gave you.  Also
+say what you expected to occur; this will help us decide whether the
+problem was really in the documentation.
+
+   Once you've got a precise problem, send e-mail to <bug-m4@gnu.org>.
+Please include the version number of 'm4' you are using.  You can get
+this information with the command 'm4 --version'.  Also provide details
+about the platform you are executing on.
+
+   Non-bug suggestions are always welcome as well.  If you have
+questions about things that are unclear in the documentation or are just
+obscure features, please report them too.
+
+
+File: m4.info,  Node: Manual,  Prev: Bugs,  Up: Preliminaries
+
+1.4 Using this manual
+=====================
+
+This manual contains a number of examples of 'm4' input and output, and
+a simple notation is used to distinguish input, output and error
+messages from 'm4'.  Examples are set out from the normal text, and
+shown in a fixed width font, like this
+
+     This is an example of an example!
+
+   To distinguish input from output, all output from 'm4' is prefixed by
+the string '=>', and all error messages by the string 'error->'.  When
+showing how command line options affect matters, the command line is
+shown with a prompt '$ 'like this'', otherwise, you can assume that a
+simple 'm4' invocation will work.  Thus:
+
+     $ command line to invoke m4
+     Example of input line
+     =>Output line from m4
+     error->and an error message
+
+   The sequence '^D' in an example indicates the end of the input file.
+The sequence '<NL>' refers to the newline character.  The majority of
+these examples are self-contained, and you can run them with similar
+results by invoking 'm4 -d'.  In fact, the testsuite that is bundled in
+the GNU M4 package consists of the examples in this document!  Some of
+the examples assume that your current directory is located where you
+unpacked the installation, so if you plan on following along, you may
+find it helpful to do this now:
+
+     $ cd m4-1.4.17
+
+   As each of the predefined macros in 'm4' is described, a prototype
+call of the macro will be shown, giving descriptive names to the
+arguments, e.g.,
+
+ -- Composite: example (STRING, [COUNT = '1']
+     [ARGUMENT]This is a sample prototype.  There is not really a macro
+     named 'example', but this documents that if there were, it would be
+     a Composite macro, rather than a Builtin.  It requires at least one
+     argument, STRING.  Remember that in 'm4', there must not be a space
+     between the macro name and the opening parenthesis, unless it was
+     intended to call the macro without any arguments.  The brackets
+     around COUNT and ARGUMENT show that these arguments are optional.
+     If COUNT is omitted, the macro behaves as if count were '1',
+     whereas if ARGUMENT is omitted, the macro behaves as if it were the
+     empty string.  A blank argument is not the same as an omitted
+     argument.  For example, 'example(`a')', 'example(`a',`1')', and
+     'example(`a',`1',)' would behave identically with COUNT set to '1';
+     while 'example(`a',)' and 'example(`a',`')' would explicitly pass
+     the empty string for COUNT.  The ellipses ('...') show that the
+     macro processes additional arguments after ARGUMENT, rather than
+     ignoring them.
+
+   All macro arguments in 'm4' are strings, but some are given special
+interpretation, e.g., as numbers, file names, regular expressions, etc.
+The documentation for each macro will state how the parameters are
+interpreted, and what happens if the argument cannot be parsed according
+to the desired interpretation.  Unless specified otherwise, a parameter
+specified to be a number is parsed as a decimal, even if the argument
+has leading zeros; and parsing the empty string as a number results in 0
+rather than an error, although a warning will be issued.
+
+   This document consistently writes and uses "builtin", without a
+hyphen, as if it were an English word.  This is how the 'builtin'
+primitive is spelled within 'm4'.
+
+
+File: m4.info,  Node: Invoking m4,  Next: Syntax,  Prev: Preliminaries,  Up: Top
+
+2 Invoking 'm4'
+***************
+
+The format of the 'm4' command is:
+
+     m4 [OPTION...] [FILE...]
+
+   All options begin with '-', or if long option names are used, with
+'--'.  A long option name need not be written completely, any
+unambiguous prefix is sufficient.  POSIX requires 'm4' to recognize
+arguments intermixed with files, even when 'POSIXLY_CORRECT' is set in
+the environment.  Most options take effect at startup regardless of
+their position, but some are documented below as taking effect after any
+files that occurred earlier in the command line.  The argument '--' is a
+marker to denote the end of options.
+
+   With short options, options that do not take arguments may be
+combined into a single command line argument with subsequent options,
+options with mandatory arguments may be provided either as a single
+command line argument or as two arguments, and options with optional
+arguments must be provided as a single argument.  In other words, 'm4
+-QPDfoo -d a -df' is equivalent to 'm4 -Q -P -D foo -d -df -- ./a',
+although the latter form is considered canonical.
+
+   With long options, options with mandatory arguments may be provided
+with an equal sign ('=') in a single argument, or as two arguments, and
+options with optional arguments must be provided as a single argument.
+In other words, 'm4 --def foo --debug a' is equivalent to 'm4
+--define=foo --debug= -- ./a', although the latter form is considered
+canonical (not to mention more robust, in case a future version of 'm4'
+introduces an option named '--default').
+
+   'm4' understands the following options, grouped by functionality.
+
+* Menu:
+
+* Operation modes::             Command line options for operation modes
+* Preprocessor features::       Command line options for preprocessor features
+* Limits control::              Command line options for limits control
+* Frozen state::                Command line options for frozen state
+* Debugging options::           Command line options for debugging
+* Command line files::          Specifying input files on the command line
+
+
+File: m4.info,  Node: Operation modes,  Next: Preprocessor features,  Up: Invoking m4
+
+2.1 Command line options for operation modes
+============================================
+
+Several options control the overall operation of 'm4':
+
+'--help'
+     Print a help summary on standard output, then immediately exit 'm4'
+     without reading any input files or performing any other actions.
+
+'--version'
+     Print the version number of the program on standard output, then
+     immediately exit 'm4' without reading any input files or performing
+     any other actions.
+
+'-E'
+'--fatal-warnings'
+     Controls the effect of warnings.  If unspecified, then execution
+     continues and exit status is unaffected when a warning is printed.
+     If specified exactly once, warnings become fatal; when one is
+     issued, execution continues, but the exit status will be non-zero.
+     If specified multiple times, then execution halts with non-zero
+     status the first time a warning is issued.  The introduction of
+     behavior levels is new to M4 1.4.9; for behavior consistent with
+     earlier versions, you should specify '-E' twice.
+
+'-i'
+'--interactive'
+'-e'
+     Makes this invocation of 'm4' interactive.  This means that all
+     output will be unbuffered, and interrupts will be ignored.  The
+     spelling '-e' exists for compatibility with other 'm4'
+     implementations, and issues a warning because it may be withdrawn
+     in a future version of GNU M4.
+
+'-P'
+'--prefix-builtins'
+     Internally modify _all_ builtin macro names so they all start with
+     the prefix 'm4_'.  For example, using this option, one should write
+     'm4_define' instead of 'define', and 'm4___file__' instead of
+     '__file__'.  This option has no effect if '-R' is also specified.
+
+'-Q'
+'--quiet'
+'--silent'
+     Suppress warnings, such as missing or superfluous arguments in
+     macro calls, or treating the empty string as zero.
+
+'--warn-macro-sequence[=REGEXP]'
+     Issue a warning if the regular expression REGEXP has a non-empty
+     match in any macro definition (either by 'define' or 'pushdef').
+     Empty matches are ignored; therefore, supplying the empty string as
+     REGEXP disables any warning.  If the optional REGEXP is not
+     supplied, then the default regular expression is
+     '\$\({[^}]*}\|[0-9][0-9]+\)' (a literal '$' followed by multiple
+     digits or by an open brace), since these sequences will change
+     semantics in the default operation of GNU M4 2.0 (due to a change
+     in how more than 9 arguments in a macro definition will be handled,
+     *note Arguments::).  Providing an alternate regular expression can
+     provide a useful reverse lookup feature of finding where a macro is
+     defined to have a given definition.
+
+'-W REGEXP'
+'--word-regexp=REGEXP'
+     Use REGEXP as an alternative syntax for macro names.  This
+     experimental option will not be present in all GNU 'm4'
+     implementations (*note Changeword::).
+
+
+File: m4.info,  Node: Preprocessor features,  Next: Limits control,  Prev: Operation modes,  Up: Invoking m4
+
+2.2 Command line options for preprocessor features
+==================================================
+
+Several options allow 'm4' to behave more like a preprocessor.  Macro
+definitions and deletions can be made on the command line, the search
+path can be altered, and the output file can track where the input came
+from.  These features occur with the following options:
+
+'-D NAME[=VALUE]'
+'--define=NAME[=VALUE]'
+     This enters NAME into the symbol table.  If '=VALUE' is missing,
+     the value is taken to be the empty string.  The VALUE can be any
+     string, and the macro can be defined to take arguments, just as if
+     it was defined from within the input.  This option may be given
+     more than once; order with respect to file names is significant,
+     and redefining the same NAME loses the previous value.
+
+'-I DIRECTORY'
+'--include=DIRECTORY'
+     Make 'm4' search DIRECTORY for included files that are not found in
+     the current working directory.  *Note Search Path::, for more
+     details.  This option may be given more than once.
+
+'-s'
+'--synclines'
+     Generate synchronization lines, for use by the C preprocessor or
+     other similar tools.  Order is significant with respect to file
+     names.  This option is useful, for example, when 'm4' is used as a
+     front end to a compiler.  Source file name and line number
+     information is conveyed by directives of the form '#line LINENUM
+     "FILE"', which are inserted as needed into the middle of the
+     output.  Such directives mean that the following line originated or
+     was expanded from the contents of input file FILE at line LINENUM.
+     The '"FILE"' part is often omitted when the file name did not
+     change from the previous directive.
+
+     Synchronization directives are always given on complete lines by
+     themselves.  When a synchronization discrepancy occurs in the
+     middle of an output line, the associated synchronization directive
+     is delayed until the next newline that does not occur in the middle
+     of a quoted string or comment.
+
+          define(`twoline', `1
+          2')
+          =>#line 2 "stdin"
+          =>
+          changecom(`/*', `*/')
+          =>
+          define(`comment', `/*1
+          2*/')
+          =>#line 5
+          =>
+          dnl no line
+          hello
+          =>#line 7
+          =>hello
+          twoline
+          =>1
+          =>#line 8
+          =>2
+          comment
+          =>/*1
+          =>2*/
+          one comment `two
+          three'
+          =>#line 10
+          =>one /*1
+          =>2*/ two
+          =>three
+          goodbye
+          =>#line 12
+          =>goodbye
+
+'-U NAME'
+'--undefine=NAME'
+     This deletes any predefined meaning NAME might have.  Obviously,
+     only predefined macros can be deleted in this way.  This option may
+     be given more than once; undefining a NAME that does not have a
+     definition is silently ignored.  Order is significant with respect
+     to file names.
+
+
+File: m4.info,  Node: Limits control,  Next: Frozen state,  Prev: Preprocessor features,  Up: Invoking m4
+
+2.3 Command line options for limits control
+===========================================
+
+There are some limits within 'm4' that can be tuned.  For compatibility,
+'m4' also accepts some options that control limits in other
+implementations, but which are automatically unbounded (limited only by
+your hardware and operating system constraints) in GNU 'm4'.
+
+'-g'
+'--gnu'
+     Enable all the extensions in this implementation.  In this release
+     of M4, this option is always on by default; it is currently only
+     useful when overriding a prior use of '--traditional'.  However,
+     having GNU behavior as default makes it impossible to write a
+     strictly POSIX-compliant client that avoids all incompatible GNU M4
+     extensions, since such a client would have to use the non-POSIX
+     command-line option to force full POSIX behavior.  Thus, a future
+     version of M4 will be changed to implicitly use the option
+     '--traditional' if the environment variable 'POSIXLY_CORRECT' is
+     set.  Projects that intentionally use GNU extensions should
+     consider using '--gnu' to state their intentions, so that the
+     project will not mysteriously break if the user upgrades to a newer
+     M4 and has 'POSIXLY_CORRECT' set in their environment.
+
+'-G'
+'--traditional'
+     Suppress all the extensions made in this implementation, compared
+     to the System V version.  *Note Compatibility::, for a list of
+     these.
+
+'-H NUM'
+'--hashsize=NUM'
+     Make the internal hash table for symbol lookup be NUM entries big.
+     For better performance, the number should be prime, but this is not
+     checked.  The default is 509 entries.  It should not be necessary
+     to increase this value, unless you define an excessive number of
+     macros.
+
+'-L NUM'
+'--nesting-limit=NUM'
+     Artificially limit the nesting of macro calls to NUM levels,
+     stopping program execution if this limit is ever exceeded.  When
+     not specified, nesting defaults to unlimited on platforms that can
+     detect stack overflow, and to 1024 levels otherwise.  A value of
+     zero means unlimited; but then heavily nested code could
+     potentially cause a stack overflow.
+
+     The precise effect of this option is more correctly associated with
+     textual nesting than dynamic recursion.  It has been useful when
+     some complex 'm4' input was generated by mechanical means, and also
+     in diagnosing recursive algorithms that do not scale well.  Most
+     users never need to change this option from its default.
+
+     This option does _not_ have the ability to break endless rescanning
+     loops, since these do not necessarily consume much memory or stack
+     space.  Through clever usage of rescanning loops, one can request
+     complex, time-consuming computations from 'm4' with useful results.
+     Putting limitations in this area would break 'm4' power.  There are
+     many pathological cases: 'define(`a', `a')a' is only the simplest
+     example (but *note Compatibility::).  Expecting GNU 'm4' to detect
+     these would be a little like expecting a compiler system to detect
+     and diagnose endless loops: it is a quite _hard_ problem in
+     general, if not undecidable!
+
+'-B NUM'
+'-S NUM'
+'-T NUM'
+     These options are present for compatibility with System V 'm4', but
+     do nothing in this implementation.  They may disappear in future
+     releases, and issue a warning to that effect.
+
+'-N NUM'
+'--diversions=NUM'
+     These options are present only for compatibility with previous
+     versions of GNU 'm4', and were controlling the number of possible
+     diversions which could be used at the same time.  They do nothing,
+     because there is no fixed limit anymore.  They may disappear in
+     future releases, and issue a warning to that effect.
+
+
+File: m4.info,  Node: Frozen state,  Next: Debugging options,  Prev: Limits control,  Up: Invoking m4
+
+2.4 Command line options for frozen state
+=========================================
+
+GNU 'm4' comes with a feature of freezing internal state (*note Frozen
+files::).  This can be used to speed up 'm4' execution when reusing a
+common initialization script.
+
+'-F FILE'
+'--freeze-state=FILE'
+     Once execution is finished, write out the frozen state on the
+     specified FILE.  It is conventional, but not required, for FILE to
+     end in '.m4f'.
+
+'-R FILE'
+'--reload-state=FILE'
+     Before execution starts, recover the internal state from the
+     specified frozen FILE.  The options '-D', '-U', and '-t' take
+     effect after state is reloaded, but before the input files are
+     read.
+
+
+File: m4.info,  Node: Debugging options,  Next: Command line files,  Prev: Frozen state,  Up: Invoking m4
+
+2.5 Command line options for debugging
+======================================
+
+Finally, there are several options for aiding in debugging 'm4' scripts.
+
+'-d[FLAGS]'
+'--debug[=FLAGS]'
+     Set the debug-level according to the flags FLAGS.  The debug-level
+     controls the format and amount of information presented by the
+     debugging functions.  *Note Debug Levels::, for more details on the
+     format and meaning of FLAGS.  If omitted, FLAGS defaults to 'aeq'.
+
+'--debugfile[=FILE]'
+'-o FILE'
+'--error-output=FILE'
+     Redirect 'dumpdef' output, debug messages, and trace output to the
+     named FILE.  Warnings, error messages, and 'errprint' output are
+     still printed to standard error.  If these options are not used, or
+     if FILE is unspecified (only possible for '--debugfile'), debug
+     output goes to standard error; if FILE is the empty string, debug
+     output is discarded.  *Note Debug Output::, for more details.  The
+     option '--debugfile' may be given more than once, and order is
+     significant with respect to file names.  The spellings '-o' and
+     '--error-output' are misleading and inconsistent with other GNU
+     tools; for now they are silently accepted as synonyms of
+     '--debugfile' and only recognized once, but in a future version of
+     M4, using them will cause a warning to be issued.
+
+'-l NUM'
+'--arglength=NUM'
+     Restrict the size of the output generated by macro tracing to NUM
+     characters per trace line.  If unspecified or zero, output is
+     unlimited.  *Note Debug Levels::, for more details.
+
+'-t NAME'
+'--trace=NAME'
+     This enables tracing for the macro NAME, at any point where it is
+     defined.  NAME need not be defined when this option is given.  This
+     option may be given more than once, and order is significant with
+     respect to file names.  *Note Trace::, for more details.
+
+
+File: m4.info,  Node: Command line files,  Prev: Debugging options,  Up: Invoking m4
+
+2.6 Specifying input files on the command line
+==============================================
+
+The remaining arguments on the command line are taken to be input file
+names.  If no names are present, standard input is read.  A file name of
+'-' is taken to mean standard input.  It is conventional, but not
+required, for input files to end in '.m4'.
+
+   The input files are read in the sequence given.  Standard input can
+be read more than once, so the file name '-' may appear multiple times
+on the command line; this makes a difference when input is from a
+terminal or other special file type.  It is an error if an input file
+ends in the middle of argument collection, a comment, or a quoted
+string.
+
+   The options '--define' ('-D'), '--undefine' ('-U'), '--synclines'
+('-s'), and '--trace' ('-t') only take effect after processing input
+from any file names that occur earlier on the command line.  For
+example, assume the file 'foo' contains:
+
+     $ cat foo
+     bar
+
+   The text 'bar' can then be redefined over multiple uses of 'foo':
+
+     $ m4 -Dbar=hello foo -Dbar=world foo
+     =>hello
+     =>world
+
+   If none of the input files invoked 'm4exit' (*note M4exit::), the
+exit status of 'm4' will be 0 for success, 1 for general failure (such
+as problems with reading an input file), and 63 for version mismatch
+(*note Using frozen files::).
+
+   If you need to read a file whose name starts with a '-', you can
+specify it as './-file', or use '--' to mark the end of options.
+
+
+File: m4.info,  Node: Syntax,  Next: Macros,  Prev: Invoking m4,  Up: Top
+
+3 Lexical and syntactic conventions
+***********************************
+
+As 'm4' reads its input, it separates it into "tokens".  A token is
+either a name, a quoted string, or any single character, that is not a
+part of either a name or a string.  Input to 'm4' can also contain
+comments.  GNU 'm4' does not yet understand multibyte locales; all
+operations are byte-oriented rather than character-oriented (although if
+your locale uses a single byte encoding, such as ISO-8859-1, you will
+not notice a difference).  However, 'm4' is eight-bit clean, so you can
+use non-ASCII characters in quoted strings (*note Changequote::),
+comments (*note Changecom::), and macro names (*note Indir::), with the
+exception of the NUL character (the zero byte ''\0'').
+
+* Menu:
+
+* Names::                       Macro names
+* Quoted strings::              Quoting input to 'm4'
+* Comments::                    Comments in 'm4' input
+* Other tokens::                Other kinds of input tokens
+* Input processing::            How 'm4' copies input to output
+
+
+File: m4.info,  Node: Names,  Next: Quoted strings,  Up: Syntax
+
+3.1 Macro names
+===============
+
+A name is any sequence of letters, digits, and the character '_'
+(underscore), where the first character is not a digit.  'm4' will use
+the longest such sequence found in the input.  If a name has a macro
+definition, it will be subject to macro expansion (*note Macros::).
+Names are case-sensitive.
+
+   Examples of legal names are: 'foo', '_tmp', and 'name01'.
+
+
+File: m4.info,  Node: Quoted strings,  Next: Comments,  Prev: Names,  Up: Syntax
+
+3.2 Quoting input to 'm4'
+=========================
+
+A quoted string is a sequence of characters surrounded by quote strings,
+defaulting to '`' and ''', where the nested begin and end quotes within
+the string are balanced.  The value of a string token is the text, with
+one level of quotes stripped off.  Thus
+
+     `'
+     =>
+
+is the empty string, and double-quoting turns into single-quoting.
+
+     ``quoted''
+     =>`quoted'
+
+   The quote characters can be changed at any time, using the builtin
+macro 'changequote'.  *Note Changequote::, for more information.
+
+
+File: m4.info,  Node: Comments,  Next: Other tokens,  Prev: Quoted strings,  Up: Syntax
+
+3.3 Comments in 'm4' input
+==========================
+
+Comments in 'm4' are normally delimited by the characters '#' and
+newline.  All characters between the comment delimiters are ignored, but
+the entire comment (including the delimiters) is passed through to the
+output--comments are _not_ discarded by 'm4'.
+
+   Comments cannot be nested, so the first newline after a '#' ends the
+comment.  The commenting effect of the begin-comment string can be
+inhibited by quoting it.
+
+     $ m4
+     `quoted text' # `commented text'
+     =>quoted text # `commented text'
+     `quoting inhibits' `#' `comments'
+     =>quoting inhibits # comments
+
+   The comment delimiters can be changed to any string at any time,
+using the builtin macro 'changecom'.  *Note Changecom::, for more
+information.
+
+
+File: m4.info,  Node: Other tokens,  Next: Input processing,  Prev: Comments,  Up: Syntax
+
+3.4 Other kinds of input tokens
+===============================
+
+Any character, that is neither a part of a name, nor of a quoted string,
+nor a comment, is a token by itself.  When not in the context of macro
+expansion, all of these tokens are just copied to output.  However,
+during macro expansion, whitespace characters (space, tab, newline,
+formfeed, carriage return, vertical tab), parentheses ('(' and ')'),
+comma (','), and dollar ('$') have additional roles, explained later.
+
+
+File: m4.info,  Node: Input processing,  Prev: Other tokens,  Up: Syntax
+
+3.5 How 'm4' copies input to output
+===================================
+
+As 'm4' reads the input token by token, it will copy each token directly
+to the output immediately.
+
+   The exception is when it finds a word with a macro definition.  In
+that case 'm4' will calculate the macro's expansion, possibly reading
+more input to get the arguments.  It then inserts the expansion in front
+of the remaining input.  In other words, the resulting text from a macro
+call will be read and parsed into tokens again.
+
+   'm4' expands a macro as soon as possible.  If it finds a macro call
+when collecting the arguments to another, it will expand the second call
+first.  This process continues until there are no more macro calls to
+expand and all the input has been consumed.
+
+   For a running example, examine how 'm4' handles this input:
+
+     format(`Result is %d', eval(`2**15'))
+
+First, 'm4' sees that the token 'format' is a macro name, so it collects
+the tokens '(', '`Result is %d'', ',', and ' ', before encountering
+another potential macro.  Sure enough, 'eval' is a macro name, so the
+nested argument collection picks up '(', '`2**15'', and ')', invoking
+the eval macro with the lone argument of '2**15'.  The expansion of
+'eval(2**15)' is '32768', which is then rescanned as the five tokens
+'3', '2', '7', '6', and '8'; and combined with the next ')', the format
+macro now has all its arguments, as if the user had typed:
+
+     format(`Result is %d', 32768)
+
+The format macro expands to 'Result is 32768', and we have another round
+of scanning for the tokens 'Result', ' ', 'is', ' ', '3', '2', '7', '6',
+and '8'.  None of these are macros, so the final output is
+
+     =>Result is 32768
+
+   As a more complicated example, we will contrast an actual code
+example from the Gnulib project(1), showing both a buggy approach and
+the desired results.  The user desires to output a shell assignment
+statement that takes its argument and turns it into a shell variable by
+converting it to uppercase and prepending a prefix.  The original
+attempt looks like this:
+
+     changequote([,])dnl
+     define([gl_STRING_MODULE_INDICATOR],
+       [
+         dnl comment
+         GNULIB_]translit([$1],[a-z],[A-Z])[=1
+       ])dnl
+       gl_STRING_MODULE_INDICATOR([strcase])
+     =>  
+     =>        GNULIB_strcase=1
+     =>  
+
+   Oops - the argument did not get capitalized.  And although the manual
+is not able to easily show it, both lines that appear empty actually
+contain two trailing spaces.  By stepping through the parse, it is easy
+to see what happened.  First, 'm4' sees the token 'changequote', which
+it recognizes as a macro, followed by '(', '[', ',', ']', and ')' to
+form the argument list.  The macro expands to the empty string, but
+changes the quoting characters to something more useful for generating
+shell code (unbalanced '`' and ''' appear all the time in shell scripts,
+but unbalanced '[]' tend to be rare).  Also in the first line, 'm4' sees
+the token 'dnl', which it recognizes as a builtin macro that consumes
+the rest of the line, resulting in no output for that line.
+
+   The second line starts a macro definition.  'm4' sees the token
+'define', which it recognizes as a macro, followed by a '(',
+'[gl_STRING_MODULE_INDICATOR]', and ','.  Because an unquoted comma was
+encountered, the first argument is known to be the expansion of the
+single-quoted string token, or 'gl_STRING_MODULE_INDICATOR'.  Next, 'm4'
+sees '<NL>', ' ', and ' ', but this whitespace is discarded as part of
+argument collection.  Then comes a rather lengthy single-quoted string
+token, '[<NL>    dnl comment<NL>    GNULIB_]'.  This is followed by the
+token 'translit', which 'm4' recognizes as a macro name, so a nested
+macro expansion has started.
+
+   The arguments to the 'translit' are found by the tokens '(', '[$1]',
+',', '[a-z]', ',', '[A-Z]', and finally ')'.  All three string arguments
+are expanded (or in other words, the quotes are stripped), and since
+neither '$' nor '1' need capitalization, the result of the macro is
+'$1'.  This expansion is rescanned, resulting in the two literal
+characters '$' and '1'.
+
+   Scanning of the outer macro resumes, and picks up with '[=1<NL>  ]',
+and finally ')'.  The collected pieces of expanded text are
+concatenated, with the end result that the macro
+'gl_STRING_MODULE_INDICATOR' is now defined to be the sequence
+'<NL>    dnl comment<NL>    GNULIB_$1=1<NL>  '.  Once again, 'dnl' is
+recognized and avoids a newline in the output.
+
+   The final line is then parsed, beginning with ' ' and ' ' that are
+output literally.  Then 'gl_STRING_MODULE_INDICATOR' is recognized as a
+macro name, with an argument list of '(', '[strcase]', and ')'.  Since
+the definition of the macro contains the sequence '$1', that sequence is
+replaced with the argument 'strcase' prior to starting the rescan.  The
+rescan sees '<NL>' and four spaces, which are output literally, then
+'dnl', which discards the text ' comment<NL>'.  Next comes four more
+spaces, also output literally, and the token 'GNULIB_strcase', which
+resulted from the earlier parameter substitution.  Since that is not a
+macro name, it is output literally, followed by the literal tokens '=',
+'1', '<NL>', and two more spaces.  Finally, the original '<NL>' seen
+after the macro invocation is scanned and output literally.
+
+   Now for a corrected approach.  This rearranges the use of newlines
+and whitespace so that less whitespace is output (which, although
+harmless to shell scripts, can be visually unappealing), and fixes the
+quoting issues so that the capitalization occurs when the macro
+'gl_STRING_MODULE_INDICATOR' is invoked, rather then when it is defined.
+It also adds another layer of quoting to the first argument of
+'translit', to ensure that the output will be rescanned as a string
+rather than a potential uppercase macro name needing further expansion.
+
+     changequote([,])dnl
+     define([gl_STRING_MODULE_INDICATOR],
+       [dnl comment
+       GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl
+     ])dnl
+       gl_STRING_MODULE_INDICATOR([strcase])
+     =>    GNULIB_STRCASE=1
+
+   The parsing of the first line is unchanged.  The second line sees the
+name of the macro to define, then sees the discarded '<NL>' and two
+spaces, as before.  But this time, the next token is '[dnl
+comment<NL>  GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl<NL>]', which
+includes nested quotes, followed by ')' to end the macro definition and
+'dnl' to skip the newline.  No early expansion of 'translit' occurs, so
+the entire string becomes the definition of the macro.
+
+   The final line is then parsed, beginning with two spaces that are
+output literally, and an invocation of 'gl_STRING_MODULE_INDICATOR' with
+the argument 'strcase'.  Again, the '$1' in the macro definition is
+substituted prior to rescanning.  Rescanning first encounters 'dnl', and
+discards ' comment<NL>'.  Then two spaces are output literally.  Next
+comes the token 'GNULIB_', but that is not a macro, so it is output
+literally.  The token '[]' is an empty string, so it does not affect
+output.  Then the token 'translit' is encountered.
+
+   This time, the arguments to 'translit' are parsed as '(',
+'[[strcase]]', ',', ' ', '[a-z]', ',', ' ', '[A-Z]', and ')'.  The two
+spaces are discarded, and the translit results in the desired result
+'[STRCASE]'.  This is rescanned, but since it is a string, the quotes
+are stripped and the only output is a literal 'STRCASE'.  Then the
+scanner sees '=' and '1', which are output literally, followed by 'dnl'
+which discards the rest of the definition of
+'gl_STRING_MODULE_INDICATOR'.  The newline at the end of output is the
+literal '<NL>' that appeared after the invocation of the macro.
+
+   The order in which 'm4' expands the macros can be further explored
+using the trace facilities of GNU 'm4' (*note Trace::).
+
+   ---------- Footnotes ----------
+
+   (1) Derived from a patch in
+<http://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html>,
+and a followup patch in
+<http://lists.gnu.org/archive/html/bug-gnulib/2007-02/msg00000.html>
+
+
+File: m4.info,  Node: Macros,  Next: Definitions,  Prev: Syntax,  Up: Top
+
+4 How to invoke macros
+**********************
+
+This chapter covers macro invocation, macro arguments and how macro
+expansion is treated.
+
+* Menu:
+
+* Invocation::                  Macro invocation
+* Inhibiting Invocation::       Preventing macro invocation
+* Macro Arguments::             Macro arguments
+* Quoting Arguments::           On Quoting Arguments to macros
+* Macro expansion::             Expanding macros
+
+
+File: m4.info,  Node: Invocation,  Next: Inhibiting Invocation,  Up: Macros
+
+4.1 Macro invocation
+====================
+
+Macro invocations has one of the forms
+
+     name
+
+which is a macro invocation without any arguments, or
+
+     name(arg1, arg2, ..., argN)
+
+which is a macro invocation with N arguments.  Macros can have any
+number of arguments.  All arguments are strings, but different macros
+might interpret the arguments in different ways.
+
+   The opening parenthesis _must_ follow the NAME directly, with no
+spaces in between.  If it does not, the macro is called with no
+arguments at all.
+
+   For a macro call to have no arguments, the parentheses _must_ be left
+out.  The macro call
+
+     name()
+
+is a macro call with one argument, which is the empty string, not a call
+with no arguments.
+
+
+File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros
+
+4.2 Preventing macro invocation
+===============================
+
+An innovation of the 'm4' language, compared to some of its predecessors
+(like Strachey's 'GPM', for example), is the ability to recognize macro
+calls without resorting to any special, prefixed invocation character.
+While generally useful, this feature might sometimes be the source of
+spurious, unwanted macro calls.  So, GNU 'm4' offers several mechanisms
+or techniques for inhibiting the recognition of names as macro calls.
+
+   First of all, many builtin macros cannot meaningfully be called
+without arguments.  As a GNU extension, for any of these macros,
+whenever an opening parenthesis does not immediately follow their name,
+the builtin macro call is not triggered.  This solves the most usual
+cases, like for 'include' or 'eval'.  Later in this document, the
+sentence "This macro is recognized only with parameters" refers to this
+specific provision of GNU M4, also known as a blind builtin macro.  For
+the builtins defined by POSIX that bear this disclaimer, POSIX
+specifically states that invoking those builtins without arguments is
+unspecified, because many other implementations simply invoke the
+builtin as though it were given one empty argument instead.
+
+     $ m4
+     eval
+     =>eval
+     eval(`1')
+     =>1
+
+   There is also a command line option ('--prefix-builtins', or '-P',
+*note Invoking m4: Operation modes.) that renames all builtin macros
+with a prefix of 'm4_' at startup.  The option has no effect whatsoever
+on user defined macros.  For example, with this option, one has to write
+'m4_dnl' and even 'm4_m4exit'.  It also has no effect on whether a macro
+requires parameters.
+
+     $ m4 -P
+     eval
+     =>eval
+     eval(`1')
+     =>eval(1)
+     m4_eval
+     =>m4_eval
+     m4_eval(`1')
+     =>1
+
+   Another alternative is to redefine problematic macros to a name less
+likely to cause conflicts, using *note Definitions::.
+
+   If your version of GNU 'm4' has the 'changeword' feature compiled in,
+it offers far more flexibility in specifying the syntax of macro names,
+both builtin or user-defined.  *Note Changeword::, for more information
+on this experimental feature.
+
+   Of course, the simplest way to prevent a name from being interpreted
+as a call to an existing macro is to quote it.  The remainder of this
+section studies a little more deeply how quoting affects macro
+invocation, and how quoting can be used to inhibit macro invocation.
+
+   Even if quoting is usually done over the whole macro name, it can
+also be done over only a few characters of this name (provided, of
+course, that the unquoted portions are not also a macro).  It is also
+possible to quote the empty string, but this works only _inside_ the
+name.  For example:
+
+     `divert'
+     =>divert
+     `d'ivert
+     =>divert
+     di`ver't
+     =>divert
+     div`'ert
+     =>divert
+
+all yield the string 'divert'.  While in both:
+
+     `'divert
+     =>
+     divert`'
+     =>
+
+the 'divert' builtin macro will be called, which expands to the empty
+string.
+
+   The output of macro evaluations is always rescanned.  In the
+following example, the input 'x`'y' yields the string 'bCD', exactly as
+if 'm4' has been given 'substr(ab`'cde, `1', `3')' as input:
+
+     define(`cde', `CDE')
+     =>
+     define(`x', `substr(ab')
+     =>
+     define(`y', `cde, `1', `3')')
+     =>
+     x`'y
+     =>bCD
+
+   Unquoted strings on either side of a quoted string are subject to
+being recognized as macro names.  In the following example, quoting the
+empty string allows for the second 'macro' to be recognized as such:
+
+     define(`macro', `m')
+     =>
+     macro(`m')macro
+     =>mmacro
+     macro(`m')`'macro
+     =>mm
+
+   Quoting may prevent recognizing as a macro name the concatenation of
+a macro expansion with the surrounding characters.  In this example:
+
+     define(`macro', `di$1')
+     =>
+     macro(`v')`ert'
+     =>divert
+     macro(`v')ert
+     =>
+
+the input will produce the string 'divert'.  When the quotes were
+removed, the 'divert' builtin was called instead.
+
+
+File: m4.info,  Node: Macro Arguments,  Next: Quoting Arguments,  Prev: Inhibiting Invocation,  Up: Macros
+
+4.3 Macro arguments
+===================
+
+When a name is seen, and it has a macro definition, it will be expanded
+as a macro.
+
+   If the name is followed by an opening parenthesis, the arguments will
+be collected before the macro is called.  If too few arguments are
+supplied, the missing arguments are taken to be the empty string.
+However, some builtins are documented to behave differently for a
+missing optional argument than for an explicit empty string.  If there
+are too many arguments, the excess arguments are ignored.  Unquoted
+leading whitespace is stripped off all arguments, but whitespace
+generated by a macro expansion or occurring after a macro that expanded
+to an empty string remains intact.  Whitespace includes space, tab,
+newline, carriage return, vertical tab, and formfeed.
+
+     define(`macro', `$1')
+     =>
+     macro( unquoted leading space lost)
+     =>unquoted leading space lost
+     macro(` quoted leading space kept')
+     => quoted leading space kept
+     macro(
+      divert `unquoted space kept after expansion')
+     => unquoted space kept after expansion
+     macro(macro(`
+     ')`whitespace from expansion kept')
+     =>
+     =>whitespace from expansion kept
+     macro(`unquoted trailing whitespace kept'
+     )
+     =>unquoted trailing whitespace kept
+     =>
+
+   Normally 'm4' will issue warnings if a builtin macro is called with
+an inappropriate number of arguments, but it can be suppressed with the
+'--quiet' command line option (or '--silent', or '-Q', *note Invoking
+m4: Operation modes.).  For user defined macros, there is no check of
+the number of arguments given.
+
+     $ m4
+     index(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `index'
+     =>0
+     index(`abc',)
+     =>0
+     index(`abc', `b', `ignored')
+     error->m4:stdin:3: Warning: excess arguments to builtin `index' ignored
+     =>1
+
+     $ m4 -Q
+     index(`abc')
+     =>0
+     index(`abc',)
+     =>0
+     index(`abc', `b', `ignored')
+     =>1
+
+   Macros are expanded normally during argument collection, and whatever
+commas, quotes and parentheses that might show up in the resulting
+expanded text will serve to define the arguments as well.  Thus, if FOO
+expands to ', b, c', the macro call
+
+     bar(a foo, d)
+
+is a macro call with four arguments, which are 'a ', 'b', 'c' and 'd'.
+To understand why the first argument contains whitespace, remember that
+unquoted leading whitespace is never part of an argument, but trailing
+whitespace always is.
+
+   It is possible for a macro's definition to change during argument
+collection, in which case the expansion uses the definition that was in
+effect at the time the opening '(' was seen.
+
+     define(`f', `1')
+     =>
+     f(define(`f', `2'))
+     =>1
+     f
+     =>2
+
+   It is an error if the end of file occurs while collecting arguments.
+
+     hello world
+     =>hello world
+     define(
+     ^D
+     error->m4:stdin:2: ERROR: end of file in argument list
+
+
+File: m4.info,  Node: Quoting Arguments,  Next: Macro expansion,  Prev: Macro Arguments,  Up: Macros
+
+4.4 On Quoting Arguments to macros
+==================================
+
+Each argument has unquoted leading whitespace removed.  Within each
+argument, all unquoted parentheses must match.  For example, if FOO is a
+macro,
+
+     foo(() (`(') `(')
+
+is a macro call, with one argument, whose value is '() (() ('.  Commas
+separate arguments, except when they occur inside quotes, comments, or
+unquoted parentheses.  *Note Pseudo Arguments::, for examples.
+
+   It is common practice to quote all arguments to macros, unless you
+are sure you want the arguments expanded.  Thus, in the above example
+with the parentheses, the 'right' way to do it is like this:
+
+     foo(`() (() (')
+
+   It is, however, in certain cases necessary (because nested expansion
+must occur to create the arguments for the outer macro) or convenient
+(because it uses fewer characters) to leave out quotes for some
+arguments, and there is nothing wrong in doing it.  It just makes life a
+bit harder, if you are not careful to follow a consistent quoting style.
+For consistency, this manual follows the rule of thumb that each layer
+of parentheses introduces another layer of single quoting, except when
+showing the consequences of quoting rules.  This is done even when the
+quoted string cannot be a macro, such as with integers when you have not
+changed the syntax via 'changeword' (*note Changeword::).
+
+   The quoting rule of thumb of one level of quoting per parentheses has
+a nice property: when a macro name appears inside parentheses, you can
+determine when it will be expanded.  If it is not quoted, it will be
+expanded prior to the outer macro, so that its expansion becomes the
+argument.  If it is single-quoted, it will be expanded after the outer
+macro.  And if it is double-quoted, it will be used as literal text
+instead of a macro name.
+
+     define(`active', `ACT, IVE')
+     =>
+     define(`show', `$1 $1')
+     =>
+     show(active)
+     =>ACT ACT
+     show(`active')
+     =>ACT, IVE ACT, IVE
+     show(``active'')
+     =>active active
+
+
+File: m4.info,  Node: Macro expansion,  Prev: Quoting Arguments,  Up: Macros
+
+4.5 Macro expansion
+===================
+
+When the arguments, if any, to a macro call have been collected, the
+macro is expanded, and the expansion text is pushed back onto the input
+(unquoted), and reread.  The expansion text from one macro call might
+therefore result in more macros being called, if the calls are included,
+completely or partially, in the first macro calls' expansion.
+
+   Taking a very simple example, if FOO expands to 'bar', and BAR
+expands to 'Hello', the input
+
+     $ m4 -Dbar=Hello -Dfoo=bar
+     foo
+     =>Hello
+
+will expand first to 'bar', and when this is reread and expanded, into
+'Hello'.
+
+
+File: m4.info,  Node: Definitions,  Next: Conditionals,  Prev: Macros,  Up: Top
+
+5 How to define new macros
+**************************
+
+Macros can be defined, redefined and deleted in several different ways.
+Also, it is possible to redefine a macro without losing a previous
+value, and bring back the original value at a later time.
+
+* Menu:
+
+* Define::                      Defining a new macro
+* Arguments::                   Arguments to macros
+* Pseudo Arguments::            Special arguments to macros
+* Undefine::                    Deleting a macro
+* Defn::                        Renaming macros
+* Pushdef::                     Temporarily redefining macros
+
+* Indir::                       Indirect call of macros
+* Builtin::                     Indirect call of builtins
+
+
+File: m4.info,  Node: Define,  Next: Arguments,  Up: Definitions
+
+5.1 Defining a macro
+====================
+
+The normal way to define or redefine macros is to use the builtin
+'define':
+
+ -- Builtin: define (NAME, [EXPANSION]
+     Defines NAME to expand to EXPANSION.  If EXPANSION is not given, it
+     is taken to be empty.
+
+     The expansion of 'define' is void.  The macro 'define' is
+     recognized only with parameters.
+
+   The following example defines the macro FOO to expand to the text
+'Hello World.'.
+
+     define(`foo', `Hello world.')
+     =>
+     foo
+     =>Hello world.
+
+   The empty line in the output is there because the newline is not a
+part of the macro definition, and it is consequently copied to the
+output.  This can be avoided by use of the macro 'dnl'.  *Note Dnl::,
+for details.
+
+   The first argument to 'define' should be quoted; otherwise, if the
+macro is already defined, you will be defining a different macro.  This
+example shows the problems with underquoting, since we did not want to
+redefine 'one':
+
+     define(foo, one)
+     =>
+     define(foo, two)
+     =>
+     one
+     =>two
+
+   GNU 'm4' normally replaces only the _topmost_ definition of a macro
+if it has several definitions from 'pushdef' (*note Pushdef::).  Some
+other implementations of 'm4' replace all definitions of a macro with
+'define'.  *Note Incompatibilities::, for more details.
+
+   As a GNU extension, the first argument to 'define' does not have to
+be a simple word.  It can be any text string, even the empty string.  A
+macro with a non-standard name cannot be invoked in the normal way, as
+the name is not recognized.  It can only be referenced by the builtins
+'indir' (*note Indir::) and 'defn' (*note Defn::).
+
+   Arrays and associative arrays can be simulated by using non-standard
+macro names.
+
+ -- Composite: array (INDEX)
+ -- Composite: array_set (INDEX, [VALUE]
+     Provide access to entries within an array.  'array' reads the entry
+     at location INDEX, and 'array_set' assigns VALUE to location INDEX.
+
+     define(`array', `defn(format(``array[%d]'', `$1'))')
+     =>
+     define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
+     =>
+     array_set(`4', `array element no. 4')
+     =>
+     array_set(`17', `array element no. 17')
+     =>
+     array(`4')
+     =>array element no. 4
+     array(eval(`10 + 7'))
+     =>array element no. 17
+
+   Change the '%d' to '%s' and it is an associative array.
+
+
+File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions
+
+5.2 Arguments to macros
+=======================
+
+Macros can have arguments.  The Nth argument is denoted by '$n' in the
+expansion text, and is replaced by the Nth actual argument, when the
+macro is expanded.  Replacement of arguments happens before rescanning,
+regardless of how many nesting levels of quoting appear in the
+expansion.  Here is an example of a macro with two arguments.
+
+ -- Composite: exch (ARG1, ARG2)
+     Expands to ARG2 followed by ARG1, effectively exchanging their
+     order.
+
+     define(`exch', `$2, $1')
+     =>
+     exch(`arg1', `arg2')
+     =>arg2, arg1
+
+   This can be used, for example, if you like the arguments to 'define'
+to be reversed.
+
+     define(`exch', `$2, $1')
+     =>
+     define(exch(``expansion text'', ``macro''))
+     =>
+     macro
+     =>expansion text
+
+   *Note Quoting Arguments::, for an explanation of the double quotes.
+(You should try and improve this example so that clients of 'exch' do
+not have to double quote; or *note Answers: Improved exch.).
+
+   As a special case, the zeroth argument, '$0', is always the name of
+the macro being expanded.
+
+     define(`test', ``Macro name: $0'')
+     =>
+     test
+     =>Macro name: test
+
+   If you want quoted text to appear as part of the expansion text,
+remember that quotes can be nested in quoted strings.  Thus, in
+
+     define(`foo', `This is macro `foo'.')
+     =>
+     foo
+     =>This is macro foo.
+
+The 'foo' in the expansion text is _not_ expanded, since it is a quoted
+string, and not a name.
+
+   GNU 'm4' allows the number following the '$' to consist of one or
+more digits, allowing macros to have any number of arguments.  The
+extension of accepting multiple digits is incompatible with POSIX, and
+is different than traditional implementations of 'm4', which only
+recognize one digit.  Therefore, future versions of GNU M4 will phase
+out this feature.  To portably access beyond the ninth argument, you can
+use the 'argn' macro documented later (*note Shift::).
+
+   POSIX also states that '$' followed immediately by '{' in a macro
+definition is implementation-defined.  This version of M4 passes the
+literal characters '${' through unchanged, but M4 2.0 will implement an
+optional feature similar to 'sh', where '${11}' expands to the eleventh
+argument, to replace the current recognition of '$11'.  Meanwhile, if
+you want to guarantee that you will get a literal '${' in output when
+expanding a macro, even when you upgrade to M4 2.0, you can use nested
+quoting to your advantage:
+
+     define(`foo', `single quoted $`'{1} output')
+     =>
+     define(`bar', ``double quoted $'`{2} output'')
+     =>
+     foo(`a', `b')
+     =>single quoted ${1} output
+     bar(`a', `b')
+     =>double quoted ${2} output
+
+   To help you detect places in your M4 input files that might change in
+behavior due to the changed behavior of M4 2.0, you can use the
+'--warn-macro-sequence' command-line option (*note Invoking m4:
+Operation modes.) with the default regular expression.  This will add a
+warning any time a macro definition includes '$' followed by multiple
+digits, or by '{'.  The warning is not enabled by default, because it
+triggers a number of warnings in Autoconf 2.61 (and Autoconf uses '-E'
+to treat warnings as errors), and because it will still be possible to
+restore older behavior in M4 2.0.
+
+     $ m4 --warn-macro-sequence
+     define(`foo', `$001 ${1} $1')
+     error->m4:stdin:1: Warning: definition of `foo' contains sequence `$001'
+     error->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}'
+     =>
+     foo(`bar')
+     =>bar ${1} bar
+
+
+File: m4.info,  Node: Pseudo Arguments,  Next: Undefine,  Prev: Arguments,  Up: Definitions
+
+5.3 Special arguments to macros
+===============================
+
+There is a special notation for the number of actual arguments supplied,
+and for all the actual arguments.
+
+   The number of actual arguments in a macro call is denoted by '$#' in
+the expansion text.
+
+ -- Composite: nargs (...)
+     Expands to a count of the number of arguments supplied.
+
+     define(`nargs', `$#')
+     =>
+     nargs
+     =>0
+     nargs()
+     =>1
+     nargs(`arg1', `arg2', `arg3')
+     =>3
+     nargs(`commas can be quoted, like this')
+     =>1
+     nargs(arg1#inside comments, commas do not separate arguments
+     still arg1)
+     =>1
+     nargs((unquoted parentheses, like this, group arguments))
+     =>1
+
+   Remember that '#' defaults to the comment character; if you forget
+quotes to inhibit the comment behavior, your macro definition may not
+end where you expected.
+
+     dnl Attempt to define a macro to just `$#'
+     define(underquoted, $#)
+     oops)
+     =>
+     underquoted
+     =>0)
+     =>oops
+
+   The notation '$*' can be used in the expansion text to denote all the
+actual arguments, unquoted, with commas in between.  For example
+
+     define(`echo', `$*')
+     =>
+     echo(arg1,    arg2, arg3 , arg4)
+     =>arg1,arg2,arg3 ,arg4
+
+   Often each argument should be quoted, and the notation '$@' handles
+that.  It is just like '$*', except that it quotes each argument.  A
+simple example of that is:
+
+     define(`echo', `$@')
+     =>
+     echo(arg1,    arg2, arg3 , arg4)
+     =>arg1,arg2,arg3 ,arg4
+
+   Where did the quotes go?  Of course, they were eaten, when the
+expanded text were reread by 'm4'.  To show the difference, try
+
+     define(`echo1', `$*')
+     =>
+     define(`echo2', `$@')
+     =>
+     define(`foo', `This is macro `foo'.')
+     =>
+     echo1(foo)
+     =>This is macro This is macro foo..
+     echo1(`foo')
+     =>This is macro foo.
+     echo2(foo)
+     =>This is macro foo.
+     echo2(`foo')
+     =>foo
+
+*Note Trace::, if you do not understand this.  As another example of the
+difference, remember that comments encountered in arguments are passed
+untouched to the macro, and that quoting disables comments.
+
+     define(`echo1', `$*')
+     =>
+     define(`echo2', `$@')
+     =>
+     define(`foo', `bar')
+     =>
+     echo1(#foo'foo
+     foo)
+     =>#foo'foo
+     =>bar
+     echo2(#foo'foo
+     foo)
+     =>#foobar
+     =>bar'
+
+   A '$' sign in the expansion text, that is not followed by anything
+'m4' understands, is simply copied to the macro expansion, as any other
+text is.
+
+     define(`foo', `$$$ hello $$$')
+     =>
+     foo
+     =>$$$ hello $$$
+
+   If you want a macro to expand to something like '$12', the judicious
+use of nested quoting can put a safe character between the '$' and the
+next character, relying on the rescanning to remove the nested quote.
+This will prevent 'm4' from interpreting the '$' sign as a reference to
+an argument.
+
+     define(`foo', `no nested quote: $1')
+     =>
+     foo(`arg')
+     =>no nested quote: arg
+     define(`foo', `nested quote around $: `$'1')
+     =>
+     foo(`arg')
+     =>nested quote around $: $1
+     define(`foo', `nested empty quote after $: $`'1')
+     =>
+     foo(`arg')
+     =>nested empty quote after $: $1
+     define(`foo', `nested quote around next character: $`1'')
+     =>
+     foo(`arg')
+     =>nested quote around next character: $1
+     define(`foo', `nested quote around both: `$1'')
+     =>
+     foo(`arg')
+     =>nested quote around both: arg
+
+
+File: m4.info,  Node: Undefine,  Next: Defn,  Prev: Pseudo Arguments,  Up: Definitions
+
+5.4 Deleting a macro
+====================
+
+A macro definition can be removed with 'undefine':
+
+ -- Builtin: undefine (NAME...)
+     For each argument, remove the macro NAME.  The macro names must
+     necessarily be quoted, since they will be expanded otherwise.
+
+     The expansion of 'undefine' is void.  The macro 'undefine' is
+     recognized only with parameters.
+
+     foo bar blah
+     =>foo bar blah
+     define(`foo', `some')define(`bar', `other')define(`blah', `text')
+     =>
+     foo bar blah
+     =>some other text
+     undefine(`foo')
+     =>
+     foo bar blah
+     =>foo other text
+     undefine(`bar', `blah')
+     =>
+     foo bar blah
+     =>foo bar blah
+
+   Undefining a macro inside that macro's expansion is safe; the macro
+still expands to the definition that was in effect at the '('.
+
+     define(`f', ``$0':$1')
+     =>
+     f(f(f(undefine(`f')`hello world')))
+     =>f:f:f:hello world
+     f(`bye')
+     =>f(bye)
+
+   It is not an error for NAME to have no macro definition.  In that
+case, 'undefine' does nothing.
+
+
+File: m4.info,  Node: Defn,  Next: Pushdef,  Prev: Undefine,  Up: Definitions
+
+5.5 Renaming macros
+===================
+
+It is possible to rename an already defined macro.  To do this, you need
+the builtin 'defn':
+
+ -- Builtin: defn (NAME...)
+     Expands to the _quoted definition_ of each NAME.  If an argument is
+     not a defined macro, the expansion for that argument is empty.
+
+     If NAME is a user-defined macro, the quoted definition is simply
+     the quoted expansion text.  If, instead, there is only one NAME and
+     it is a builtin, the expansion is a special token, which points to
+     the builtin's internal definition.  This token is only meaningful
+     as the second argument to 'define' (and 'pushdef'), and is silently
+     converted to an empty string in most other contexts.  Combining a
+     builtin with anything else is not supported; a warning is issued
+     and the builtin is omitted from the final expansion.
+
+     The macro 'defn' is recognized only with parameters.
+
+   Its normal use is best understood through an example, which shows how
+to rename 'undefine' to 'zap':
+
+     define(`zap', defn(`undefine'))
+     =>
+     zap(`undefine')
+     =>
+     undefine(`zap')
+     =>undefine(zap)
+
+   In this way, 'defn' can be used to copy macro definitions, and also
+definitions of builtin macros.  Even if the original macro is removed,
+the other name can still be used to access the definition.
+
+   The fact that macro definitions can be transferred also explains why
+you should use '$0', rather than retyping a macro's name in its
+definition:
+
+     define(`foo', `This is `$0'')
+     =>
+     define(`bar', defn(`foo'))
+     =>
+     bar
+     =>This is bar
+
+   Macros used as string variables should be referred through 'defn', to
+avoid unwanted expansion of the text:
+
+     define(`string', `The macro dnl is very useful
+     ')
+     =>
+     string
+     =>The macro 
+     defn(`string')
+     =>The macro dnl is very useful
+     =>
+
+   However, it is important to remember that 'm4' rescanning is purely
+textual.  If an unbalanced end-quote string occurs in a macro
+definition, the rescan will see that embedded quote as the termination
+of the quoted string, and the remainder of the macro's definition will
+be rescanned unquoted.  Thus it is a good idea to avoid unbalanced
+end-quotes in macro definitions or arguments to macros.
+
+     define(`foo', a'a)
+     =>
+     define(`a', `A')
+     =>
+     define(`echo', `$@')
+     =>
+     foo
+     =>A'A
+     defn(`foo')
+     =>aA'
+     echo(foo)
+     =>AA'
+
+   On the other hand, it is possible to exploit the fact that 'defn' can
+concatenate multiple macros prior to the rescanning phase, in order to
+join the definitions of macros that, in isolation, have unbalanced
+quotes.  This is particularly useful when one has used several macros to
+accumulate text that M4 should rescan as a whole.  In the example below,
+note how the use of 'defn' on 'l' in isolation opens a string, which is
+not closed until the next line; but used on 'l' and 'r' together results
+in nested quoting.
+
+     define(`l', `<[>')define(`r', `<]>')
+     =>
+     changequote(`[', `]')
+     =>
+     defn([l])defn([r])
+     ])
+     =><[>]defn([r])
+     =>)
+     defn([l], [r])
+     =><[>][<]>
+
+   Using 'defn' to generate special tokens for builtin macros outside of
+expected contexts can sometimes trigger warnings.  But most of the time,
+such tokens are silently converted to the empty string.
+
+     $ m4 -d
+     defn(`defn')
+     =>
+     define(defn(`divnum'), `cannot redefine a builtin token')
+     error->m4:stdin:2: Warning: define: invalid macro name ignored
+     =>
+     divnum
+     =>0
+     len(defn(`divnum'))
+     =>0
+
+   Also note that 'defn' with multiple arguments can only join text
+macros, not builtins, although a future version of GNU M4 may lift this
+restriction.
+
+     $ m4 -d
+     define(`a', `A')define(`AA', `b')
+     =>
+     traceon(`defn', `define')
+     =>
+     defn(`a', `divnum', `a')
+     error->m4:stdin:3: Warning: cannot concatenate builtin `divnum'
+     error->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A''
+     =>AA
+     define(`mydivnum', defn(`divnum', `divnum'))mydivnum
+     error->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
+     error->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
+     error->m4trace: -2- defn(`divnum', `divnum')
+     error->m4trace: -1- define(`mydivnum', `')
+     =>
+     traceoff(`defn', `define')
+     =>
+
+
+File: m4.info,  Node: Pushdef,  Next: Indir,  Prev: Defn,  Up: Definitions
+
+5.6 Temporarily redefining macros
+=================================
+
+It is possible to redefine a macro temporarily, reverting to the
+previous definition at a later time.  This is done with the builtins
+'pushdef' and 'popdef':
+
+ -- Builtin: pushdef (NAME, [EXPANSION]
+ -- Builtin: popdef (NAME...)
+     Analogous to 'define' and 'undefine'.
+
+     These macros work in a stack-like fashion.  A macro is temporarily
+     redefined with 'pushdef', which replaces an existing definition of
+     NAME, while saving the previous definition, before the new one is
+     installed.  If there is no previous definition, 'pushdef' behaves
+     exactly like 'define'.
+
+     If a macro has several definitions (of which only one is
+     accessible), the topmost definition can be removed with 'popdef'.
+     If there is no previous definition, 'popdef' behaves like
+     'undefine'.
+
+     The expansion of both 'pushdef' and 'popdef' is void.  The macros
+     'pushdef' and 'popdef' are recognized only with parameters.
+
+     define(`foo', `Expansion one.')
+     =>
+     foo
+     =>Expansion one.
+     pushdef(`foo', `Expansion two.')
+     =>
+     foo
+     =>Expansion two.
+     pushdef(`foo', `Expansion three.')
+     =>
+     pushdef(`foo', `Expansion four.')
+     =>
+     popdef(`foo')
+     =>
+     foo
+     =>Expansion three.
+     popdef(`foo', `foo')
+     =>
+     foo
+     =>Expansion one.
+     popdef(`foo')
+     =>
+     foo
+     =>foo
+
+   If a macro with several definitions is redefined with 'define', the
+topmost definition is _replaced_ with the new definition.  If it is
+removed with 'undefine', _all_ the definitions are removed, and not only
+the topmost one.  However, POSIX allows other implementations that treat
+'define' as replacing an entire stack of definitions with a single new
+definition, so to be portable to other implementations, it may be worth
+explicitly using 'popdef' and 'pushdef' rather than relying on the GNU
+behavior of 'define'.
+
+     define(`foo', `Expansion one.')
+     =>
+     foo
+     =>Expansion one.
+     pushdef(`foo', `Expansion two.')
+     =>
+     foo
+     =>Expansion two.
+     define(`foo', `Second expansion two.')
+     =>
+     foo
+     =>Second expansion two.
+     undefine(`foo')
+     =>
+     foo
+     =>foo
+
+   Local variables within macros are made with 'pushdef' and 'popdef'.
+At the start of the macro a new definition is pushed, within the macro
+it is manipulated and at the end it is popped, revealing the former
+definition.
+
+   It is possible to temporarily redefine a builtin with 'pushdef' and
+'defn'.
+
+
+File: m4.info,  Node: Indir,  Next: Builtin,  Prev: Pushdef,  Up: Definitions
+
+5.7 Indirect call of macros
+===========================
+
+Any macro can be called indirectly with 'indir':
+
+ -- Builtin: indir (NAME, [ARGS...]
+     Results in a call to the macro NAME, which is passed the rest of
+     the arguments ARGS.  If NAME is not defined, an error message is
+     printed, and the expansion is void.
+
+     The macro 'indir' is recognized only with parameters.
+
+   This can be used to call macros with computed or "invalid" names
+('define' allows such names to be defined):
+
+     define(`$$internal$macro', `Internal macro (name `$0')')
+     =>
+     $$internal$macro
+     =>$$internal$macro
+     indir(`$$internal$macro')
+     =>Internal macro (name $$internal$macro)
+
+   The point is, here, that larger macro packages can have private
+macros defined, that will not be called by accident.  They can _only_ be
+called through the builtin 'indir'.
+
+   One other point to observe is that argument collection occurs before
+'indir' invokes NAME, so if argument collection changes the value of
+NAME, that will be reflected in the final expansion.  This is different
+than the behavior when invoking macros directly, where the definition
+that was in effect before argument collection is used.
+
+     $ m4 -d
+     define(`f', `1')
+     =>
+     f(define(`f', `2'))
+     =>1
+     indir(`f', define(`f', `3'))
+     =>3
+     indir(`f', undefine(`f'))
+     error->m4:stdin:4: undefined macro `f'
+     =>
+
+   When handed the result of 'defn' (*note Defn::) as one of its
+arguments, 'indir' defers to the invoked NAME for whether a token
+representing a builtin is recognized or flattened to the empty string.
+
+     $ m4 -d
+     indir(defn(`defn'), `divnum')
+     error->m4:stdin:1: Warning: indir: invalid macro name ignored
+     =>
+     indir(`define', defn(`defn'), `divnum')
+     error->m4:stdin:2: Warning: define: invalid macro name ignored
+     =>
+     indir(`define', `foo', defn(`divnum'))
+     =>
+     foo
+     =>0
+     indir(`divert', defn(`foo'))
+     error->m4:stdin:5: empty string treated as 0 in builtin `divert'
+     =>
+
+
+File: m4.info,  Node: Builtin,  Prev: Indir,  Up: Definitions
+
+5.8 Indirect call of builtins
+=============================
+
+Builtin macros can be called indirectly with 'builtin':
+
+ -- Builtin: builtin (NAME, [ARGS...]
+     Results in a call to the builtin NAME, which is passed the rest of
+     the arguments ARGS.  If NAME does not name a builtin, an error
+     message is printed, and the expansion is void.
+
+     The macro 'builtin' is recognized only with parameters.
+
+   This can be used even if NAME has been given another definition that
+has covered the original, or been undefined so that no macro maps to the
+builtin.
+
+     pushdef(`define', `hidden')
+     =>
+     undefine(`undefine')
+     =>
+     define(`foo', `bar')
+     =>hidden
+     foo
+     =>foo
+     builtin(`define', `foo', defn(`divnum'))
+     =>
+     foo
+     =>0
+     builtin(`define', `foo', `BAR')
+     =>
+     foo
+     =>BAR
+     undefine(`foo')
+     =>undefine(foo)
+     foo
+     =>BAR
+     builtin(`undefine', `foo')
+     =>
+     foo
+     =>foo
+
+   The NAME argument only matches the original name of the builtin, even
+when the '--prefix-builtins' option (or '-P', *note Invoking m4:
+Operation modes.) is in effect.  This is different from 'indir', which
+only tracks current macro names.
+
+     $ m4 -P
+     m4_builtin(`divnum')
+     =>0
+     m4_builtin(`m4_divnum')
+     error->m4:stdin:2: undefined builtin `m4_divnum'
+     =>
+     m4_indir(`divnum')
+     error->m4:stdin:3: undefined macro `divnum'
+     =>
+     m4_indir(`m4_divnum')
+     =>0
+
+   Note that 'indir' and 'builtin' can be used to invoke builtins
+without arguments, even when they normally require parameters to be
+recognized; but it will provoke a warning, and result in a void
+expansion.
+
+     builtin
+     =>builtin
+     builtin()
+     error->m4:stdin:2: undefined builtin `'
+     =>
+     builtin(`builtin')
+     error->m4:stdin:3: Warning: too few arguments to builtin `builtin'
+     =>
+     builtin(`builtin',)
+     error->m4:stdin:4: undefined builtin `'
+     =>
+     builtin(`builtin', ``'
+     ')
+     error->m4:stdin:5: undefined builtin ``'
+     error->'
+     =>
+     indir(`index')
+     error->m4:stdin:7: Warning: too few arguments to builtin `index'
+     =>
+
+
+File: m4.info,  Node: Conditionals,  Next: Debugging,  Prev: Definitions,  Up: Top
+
+6 Conditionals, loops, and recursion
+************************************
+
+Macros, expanding to plain text, perhaps with arguments, are not quite
+enough.  We would like to have macros expand to different things, based
+on decisions taken at run-time.  For that, we need some kind of
+conditionals.  Also, we would like to have some kind of loop construct,
+so we could do something a number of times, or while some condition is
+true.
+
+* Menu:
+
+* Ifdef::                       Testing if a macro is defined
+* Ifelse::                      If-else construct, or multibranch
+* Shift::                       Recursion in 'm4'
+* Forloop::                     Iteration by counting
+* Foreach::                     Iteration by list contents
+* Stacks::                      Working with definition stacks
+* Composition::                 Building macros with macros
+
+
+File: m4.info,  Node: Ifdef,  Next: Ifelse,  Up: Conditionals
+
+6.1 Testing if a macro is defined
+=================================
+
+There are two different builtin conditionals in 'm4'.  The first is
+'ifdef':
+
+ -- Builtin: ifdef (NAME, STRING-1, [STRING-2]
+     If NAME is defined as a macro, 'ifdef' expands to STRING-1,
+     otherwise to STRING-2.  If STRING-2 is omitted, it is taken to be
+     the empty string (according to the normal rules).
+
+     The macro 'ifdef' is recognized only with parameters.
+
+     ifdef(`foo', ``foo' is defined', ``foo' is not defined')
+     =>foo is not defined
+     define(`foo', `')
+     =>
+     ifdef(`foo', ``foo' is defined', ``foo' is not defined')
+     =>foo is defined
+     ifdef(`no_such_macro', `yes', `no', `extra argument')
+     error->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored
+     =>no
+
+
+File: m4.info,  Node: Ifelse,  Next: Shift,  Prev: Ifdef,  Up: Conditionals
+
+6.2 If-else construct, or multibranch
+=====================================
+
+The other conditional, 'ifelse', is much more powerful.  It can be used
+as a way to introduce a long comment, as an if-else construct, or as a
+multibranch, depending on the number of arguments supplied:
+
+ -- Builtin: ifelse (COMMENT)
+ -- Builtin: ifelse (STRING-1, STRING-2, EQUAL, [NOT-EQUAL]
+ -- Builtin: ifelse (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4,
+          EQUAL-2, ..., [NOT-EQUAL]
+     Used with only one argument, the 'ifelse' simply discards it and
+     produces no output.
+
+     If called with three or four arguments, 'ifelse' expands into
+     EQUAL, if STRING-1 and STRING-2 are equal (character for
+     character), otherwise it expands to NOT-EQUAL.  A final fifth
+     argument is ignored, after triggering a warning.
+
+     If called with six or more arguments, and STRING-1 and STRING-2 are
+     equal, 'ifelse' expands into EQUAL-1, otherwise the first three
+     arguments are discarded and the processing starts again.
+
+     The macro 'ifelse' is recognized only with parameters.
+
+   Using only one argument is a common 'm4' idiom for introducing a
+block comment, as an alternative to repeatedly using 'dnl'.  This
+special usage is recognized by GNU 'm4', so that in this case, the
+warning about missing arguments is never triggered.
+
+     ifelse(`some comments')
+     =>
+     ifelse(`foo', `bar')
+     error->m4:stdin:2: Warning: too few arguments to builtin `ifelse'
+     =>
+
+   Using three or four arguments provides decision points.
+
+     ifelse(`foo', `bar', `true')
+     =>
+     ifelse(`foo', `foo', `true')
+     =>true
+     define(`foo', `bar')
+     =>
+     ifelse(foo, `bar', `true', `false')
+     =>true
+     ifelse(foo, `foo', `true', `false')
+     =>false
+
+   Notice how the first argument was used unquoted; it is common to
+compare the expansion of a macro with a string.  With this macro, you
+can now reproduce the behavior of blind builtins, where the macro is
+recognized only with arguments.
+
+     define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')')
+     =>
+     foo
+     =>foo
+     foo()
+     =>arguments:1
+     foo(`a', `b', `c')
+     =>arguments:3
+
+   For an example of a way to make defining blind macros easier, see
+*note Composition::.
+
+   The macro 'ifelse' can take more than four arguments.  If given more
+than four arguments, 'ifelse' works like a 'case' or 'switch' statement
+in traditional programming languages.  If STRING-1 and STRING-2 are
+equal, 'ifelse' expands into EQUAL-1, otherwise the procedure is
+repeated with the first three arguments discarded.  This calls for an
+example:
+
+     ifelse(`foo', `bar', `third', `gnu', `gnats')
+     error->m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored
+     =>gnu
+     ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth')
+     =>
+     ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh')
+     =>seventh
+     ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8')
+     error->m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored
+     =>7
+
+   Naturally, the normal case will be slightly more advanced than these
+examples.  A common use of 'ifelse' is in macros implementing loops of
+various kinds.
+
+
+File: m4.info,  Node: Shift,  Next: Forloop,  Prev: Ifelse,  Up: Conditionals
+
+6.3 Recursion in 'm4'
+=====================
+
+There is no direct support for loops in 'm4', but macros can be
+recursive.  There is no limit on the number of recursion levels, other
+than those enforced by your hardware and operating system.
+
+   Loops can be programmed using recursion and the conditionals
+described previously.
+
+   There is a builtin macro, 'shift', which can, among other things, be
+used for iterating through the actual arguments to a macro:
+
+ -- Builtin: shift (ARG1, ...)
+     Takes any number of arguments, and expands to all its arguments
+     except ARG1, separated by commas, with each argument quoted.
+
+     The macro 'shift' is recognized only with parameters.
+
+     shift
+     =>shift
+     shift(`bar')
+     =>
+     shift(`foo', `bar', `baz')
+     =>bar,baz
+
+   An example of the use of 'shift' is this macro:
+
+ -- Composite: reverse (...)
+     Takes any number of arguments, and reverses their order.
+
+   It is implemented as:
+
+     define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
+                               `reverse(shift($@)), `$1'')')
+     =>
+     reverse
+     =>
+     reverse(`foo')
+     =>foo
+     reverse(`foo', `bar', `gnats', `and gnus')
+     =>and gnus, gnats, bar, foo
+
+   While not a very interesting macro, it does show how simple loops can
+be made with 'shift', 'ifelse' and recursion.  It also shows that
+'shift' is usually used with '$@'.  Another example of this is an
+implementation of a short-circuiting conditional operator.
+
+ -- Composite: cond (TEST-1, STRING-1, EQUAL-1, [TEST-2]
+     Similar to 'ifelse', where an equal comparison between the first
+     two strings results in the third, otherwise the first three
+     arguments are discarded and the process repeats.  The difference is
+     that each TEST-<N> is expanded only when it is encountered.  This
+     means that every third argument to 'cond' is normally given one
+     more level of quoting than the corresponding argument to 'ifelse'.
+
+   Here is the implementation of 'cond', along with a demonstration of
+how it can short-circuit the side effects in 'side'.  Notice how all the
+unquoted side effects happen regardless of how many comparisons are made
+with 'ifelse', compared with only the relevant effects with 'cond'.
+
+     define(`cond',
+     `ifelse(`$#', `1', `$1',
+             `ifelse($1, `$2', `$3',
+                     `$0(shift(shift(shift($@))))')')')dnl
+     define(`side', `define(`counter', incr(counter))$1')dnl
+     define(`example1',
+     `define(`counter', `0')dnl
+     ifelse(side(`$1'), `yes', `one comparison: ',
+            side(`$1'), `no', `two comparisons: ',
+            side(`$1'), `maybe', `three comparisons: ',
+            `side(`default answer: ')')counter')dnl
+     define(`example2',
+     `define(`counter', `0')dnl
+     cond(`side(`$1')', `yes', `one comparison: ',
+          `side(`$1')', `no', `two comparisons: ',
+          `side(`$1')', `maybe', `three comparisons: ',
+          `side(`default answer: ')')counter')dnl
+     example1(`yes')
+     =>one comparison: 3
+     example1(`no')
+     =>two comparisons: 3
+     example1(`maybe')
+     =>three comparisons: 3
+     example1(`feeling rather indecisive today')
+     =>default answer: 4
+     example2(`yes')
+     =>one comparison: 1
+     example2(`no')
+     =>two comparisons: 2
+     example2(`maybe')
+     =>three comparisons: 3
+     example2(`feeling rather indecisive today')
+     =>default answer: 4
+
+   Another common task that requires iteration is joining a list of
+arguments into a single string.
+
+ -- Composite: join ([SEPARATOR]
+ -- Composite: joinall ([SEPARATOR]
+     Generate a single-quoted string, consisting of each ARG separated
+     by SEPARATOR.  While 'joinall' always outputs a SEPARATOR between
+     arguments, 'join' avoids the SEPARATOR for an empty ARG.
+
+   Here are some examples of its usage, based on the implementation
+'m4-1.4.17/examples/join.m4' distributed in this package:
+
+     $ m4 -I examples
+     include(`join.m4')
+     =>
+     join,join(`-'),join(`-', `'),join(`-', `', `')
+     =>,,,
+     joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `')
+     =>,,,-
+     join(`-', `1')
+     =>1
+     join(`-', `1', `2', `3')
+     =>1-2-3
+     join(`', `1', `2', `3')
+     =>123
+     join(`-', `', `1', `', `', `2', `')
+     =>1-2
+     joinall(`-', `', `1', `', `', `2', `')
+     =>-1---2-
+     join(`,', `1', `2', `3')
+     =>1,2,3
+     define(`nargs', `$#')dnl
+     nargs(join(`,', `1', `2', `3'))
+     =>1
+
+   Examining the implementation shows some interesting points about
+several m4 programming idioms.
+
+     $ m4 -I examples
+     undivert(`join.m4')dnl
+     =>divert(`-1')
+     =># join(sep, args) - join each non-empty ARG into a single
+     =># string, with each element separated by SEP
+     =>define(`join',
+     =>`ifelse(`$#', `2', ``$2'',
+     =>  `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')')
+     =>define(`_join',
+     =>`ifelse(`$#$2', `2', `',
+     =>  `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@)))')')
+     =># joinall(sep, args) - join each ARG, including empty ones,
+     =># into a single string, with each element separated by SEP
+     =>define(`joinall', ``$2'_$0(`$1', shift($@))')
+     =>define(`_joinall',
+     =>`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')')
+     =>divert`'dnl
+
+   First, notice that this implementation creates helper macros '_join'
+and '_joinall'.  This division of labor makes it easier to output the
+correct number of SEPARATOR instances: 'join' and 'joinall' are
+responsible for the first argument, without a separator, while '_join'
+and '_joinall' are responsible for all remaining arguments, always
+outputting a separator when outputting an argument.
+
+   Next, observe how 'join' decides to iterate to itself, because the
+first ARG was empty, or to output the argument and swap over to '_join'.
+If the argument is non-empty, then the nested 'ifelse' results in an
+unquoted '_', which is concatenated with the '$0' to form the next macro
+name to invoke.  The 'joinall' implementation is simpler since it does
+not have to suppress empty ARG; it always executes once then defers to
+'_joinall'.
+
+   Another important idiom is the idea that SEPARATOR is reused for each
+iteration.  Each iteration has one less argument, but rather than
+discarding '$1' by iterating with '$0(shift($@))', the macro discards
+'$2' by using '$0(`$1', shift(shift($@)))'.
+
+   Next, notice that it is possible to compare more than one condition
+in a single 'ifelse' test.  The test of '$#$2' against '2' allows
+'_join' to iterate for two separate reasons--either there are still more
+than two arguments, or there are exactly two arguments but the last
+argument is not empty.
+
+   Finally, notice that these macros require exactly two arguments to
+terminate recursion, but that they still correctly result in empty
+output when given no ARGS (i.e., zero or one macro argument).  On the
+first pass when there are too few arguments, the 'shift' results in no
+output, but leaves an empty string to serve as the required second
+argument for the second pass.  Put another way, '`$1', shift($@)' is not
+the same as '$@', since only the former guarantees at least two
+arguments.
+
+   Sometimes, a recursive algorithm requires adding quotes to each
+element, or treating multiple arguments as a single element:
+
+ -- Composite: quote (...)
+ -- Composite: dquote (...)
+ -- Composite: dquote_elt (...)
+     Takes any number of arguments, and adds quoting.  With 'quote',
+     only one level of quoting is added, effectively removing whitespace
+     after commas and turning multiple arguments into a single string.
+     With 'dquote', two levels of quoting are added, one around each
+     element, and one around the list.  And with 'dquote_elt', two
+     levels of quoting are added around each element.
+
+   An actual implementation of these three macros is distributed as
+'m4-1.4.17/examples/quote.m4' in this package.  First, let's examine
+their usage:
+
+     $ m4 -I examples
+     include(`quote.m4')
+     =>
+     -quote-dquote-dquote_elt-
+     =>----
+     -quote()-dquote()-dquote_elt()-
+     =>--`'-`'-
+     -quote(`1')-dquote(`1')-dquote_elt(`1')-
+     =>-1-`1'-`1'-
+     -quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')-
+     =>-1,2-`1',`2'-`1',`2'-
+     define(`n', `$#')dnl
+     -n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))-
+     =>-1-1-2-
+     dquote(dquote_elt(`1', `2'))
+     =>``1'',``2''
+     dquote_elt(dquote(`1', `2'))
+     =>``1',`2''
+
+   The last two lines show that when given two arguments, 'dquote'
+results in one string, while 'dquote_elt' results in two.  Now, examine
+the implementation.  Note that 'quote' and 'dquote_elt' make decisions
+based on their number of arguments, so that when called without
+arguments, they result in nothing instead of a quoted empty string; this
+is so that it is possible to distinguish between no arguments and an
+empty first argument.  'dquote', on the other hand, results in a string
+no matter what, since it is still possible to tell whether it was
+invoked without arguments based on the resulting string.
+
+     $ m4 -I examples
+     undivert(`quote.m4')dnl
+     =>divert(`-1')
+     =># quote(args) - convert args to single-quoted string
+     =>define(`quote', `ifelse(`$#', `0', `', ``$*'')')
+     =># dquote(args) - convert args to quoted list of quoted strings
+     =>define(`dquote', ``$@'')
+     =># dquote_elt(args) - convert args to list of double-quoted strings
+     =>define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''',
+     =>                             ```$1'',$0(shift($@))')')
+     =>divert`'dnl
+
+   It is worth pointing out that 'quote(ARGS)' is more efficient than
+'joinall(`,', ARGS)' for producing the same output.
+
+   One more useful macro based on 'shift' allows portably selecting an
+arbitrary argument (usually greater than the ninth argument), without
+relying on the GNU extension of multi-digit arguments (*note
+Arguments::).
+
+ -- Composite: argn (N, ...)
+     Expands to argument N out of the remaining arguments.  N must be a
+     positive number.  Usually invoked as 'argn(`N',$@)'.
+
+   It is implemented as:
+
+     define(`argn', `ifelse(`$1', 1, ``$2'',
+       `argn(decr(`$1'), shift(shift($@)))')')
+     =>
+     argn(`1', `a')
+     =>a
+     define(`foo', `argn(`11', $@)')
+     =>
+     foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
+     =>k
+
+
+File: m4.info,  Node: Forloop,  Next: Foreach,  Prev: Shift,  Up: Conditionals
+
+6.4 Iteration by counting
+=========================
+
+Here is an example of a loop macro that implements a simple for loop.
+
+ -- Composite: forloop (ITERATOR, START, END, TEXT)
+     Takes the name in ITERATOR, which must be a valid macro name, and
+     successively assign it each integer value from START to END,
+     inclusive.  For each assignment to ITERATOR, append TEXT to the
+     expansion of the 'forloop'.  TEXT may refer to ITERATOR.  Any
+     definition of ITERATOR prior to this invocation is restored.
+
+   It can, for example, be used for simple counting:
+
+     $ m4 -I examples
+     include(`forloop.m4')
+     =>
+     forloop(`i', `1', `8', `i ')
+     =>1 2 3 4 5 6 7 8 
+
+   For-loops can be nested, like:
+
+     $ m4 -I examples
+     include(`forloop.m4')
+     =>
+     forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
+     ')
+     => (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
+     => (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
+     => (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
+     => (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
+     =>
+
+   The implementation of the 'forloop' macro is fairly straightforward.
+The 'forloop' macro itself is simply a wrapper, which saves the previous
+definition of the first argument, calls the internal macro '_forloop',
+and re-establishes the saved definition of the first argument.
+
+   The macro '_forloop' expands the fourth argument once, and tests to
+see if the iterator has reached the final value.  If it has not
+finished, it increments the iterator (using the predefined macro 'incr',
+*note Incr::), and recurses.
+
+   Here is an actual implementation of 'forloop', distributed as
+'m4-1.4.17/examples/forloop.m4' in this package:
+
+     $ m4 -I examples
+     undivert(`forloop.m4')dnl
+     =>divert(`-1')
+     =># forloop(var, from, to, stmt) - simple version
+     =>define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')')
+     =>define(`_forloop',
+     =>       `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')')
+     =>divert`'dnl
+
+   Notice the careful use of quotes.  Certain macro arguments are left
+unquoted, each for its own reason.  Try to find out _why_ these
+arguments are left unquoted, and see what happens if they are quoted.
+(As presented, these two macros are useful but not very robust for
+general use.  They lack even basic error handling for cases like START
+less than END, END not numeric, or ITERATOR not being a macro name.  See
+if you can improve these macros; or *note Answers: Improved forloop.).
+
+
+File: m4.info,  Node: Foreach,  Next: Stacks,  Prev: Forloop,  Up: Conditionals
+
+6.5 Iteration by list contents
+==============================
+
+Here is an example of a loop macro that implements list iteration.
+
+ -- Composite: foreach (ITERATOR, PAREN-LIST, TEXT)
+ -- Composite: foreachq (ITERATOR, QUOTE-LIST, TEXT)
+     Takes the name in ITERATOR, which must be a valid macro name, and
+     successively assign it each value from PAREN-LIST or QUOTE-LIST.
+     In 'foreach', PAREN-LIST is a comma-separated list of elements
+     contained in parentheses.  In 'foreachq', QUOTE-LIST is a
+     comma-separated list of elements contained in a quoted string.  For
+     each assignment to ITERATOR, append TEXT to the overall expansion.
+     TEXT may refer to ITERATOR.  Any definition of ITERATOR prior to
+     this invocation is restored.
+
+   As an example, this displays each word in a list inside of a
+sentence, using an implementation of 'foreach' distributed as
+'m4-1.4.17/examples/foreach.m4', and 'foreachq' in
+'m4-1.4.17/examples/foreachq.m4'.
+
+     $ m4 -I examples
+     include(`foreach.m4')
+     =>
+     foreach(`x', (foo, bar, foobar), `Word was: x
+     ')dnl
+     =>Word was: foo
+     =>Word was: bar
+     =>Word was: foobar
+     include(`foreachq.m4')
+     =>
+     foreachq(`x', `foo, bar, foobar', `Word was: x
+     ')dnl
+     =>Word was: foo
+     =>Word was: bar
+     =>Word was: foobar
+
+   It is possible to be more complex; each element of the PAREN-LIST or
+QUOTE-LIST can itself be a list, to pass as further arguments to a
+helper macro.  This example generates a shell case statement:
+
+     $ m4 -I examples
+     include(`foreach.m4')
+     =>
+     define(`_case', `  $1)
+         $2=" $1";;
+     ')dnl
+     define(`_cat', `$1$2')dnl
+     case $`'1 in
+     =>case $1 in
+     foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
+             `_cat(`_case', x)')dnl
+     =>  a)
+     =>    vara=" a";;
+     =>  b)
+     =>    varb=" b";;
+     =>  c)
+     =>    varc=" c";;
+     esac
+     =>esac
+
+   The implementation of the 'foreach' macro is a bit more involved; it
+is a wrapper around two helper macros.  First, '_arg1' is needed to grab
+the first element of a list.  Second, '_foreach' implements the
+recursion, successively walking through the original list.  Here is a
+simple implementation of 'foreach':
+
+     $ m4 -I examples
+     undivert(`foreach.m4')dnl
+     =>divert(`-1')
+     =># foreach(x, (item_1, item_2, ..., item_n), stmt)
+     =>#   parenthesized list, simple version
+     =>define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')')
+     =>define(`_arg1', `$1')
+     =>define(`_foreach', `ifelse(`$2', `()', `',
+     =>  `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')')
+     =>divert`'dnl
+
+   Unfortunately, that implementation is not robust to macro names as
+list elements.  Each iteration of '_foreach' is stripping another layer
+of quotes, leading to erratic results if list elements are not already
+fully expanded.  The first cut at implementing 'foreachq' takes this
+into account.  Also, when using quoted elements in a PAREN-LIST, the
+overall list must be quoted.  A QUOTE-LIST has the nice property of
+requiring fewer characters to create a list containing the same quoted
+elements.  To see the difference between the two macros, we attempt to
+pass double-quoted macro names in a list, expecting the macro name on
+output after one layer of quotes is removed during list iteration and
+the final layer removed during the final rescan:
+
+     $ m4 -I examples
+     define(`a', `1')define(`b', `2')define(`c', `3')
+     =>
+     include(`foreach.m4')
+     =>
+     include(`foreachq.m4')
+     =>
+     foreach(`x', `(``a'', ``(b'', ``c)'')', `x
+     ')
+     =>1
+     =>(2)1
+     =>
+     =>, x
+     =>)
+     foreachq(`x', ```a'', ``(b'', ``c)''', `x
+     ')dnl
+     =>a
+     =>(b
+     =>c)
+
+   Obviously, 'foreachq' did a better job; here is its implementation:
+
+     $ m4 -I examples
+     undivert(`foreachq.m4')dnl
+     =>include(`quote.m4')dnl
+     =>divert(`-1')
+     =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
+     =>#   quoted list, simple version
+     =>define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')')
+     =>define(`_arg1', `$1')
+     =>define(`_foreachq', `ifelse(quote($2), `', `',
+     =>  `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')')
+     =>divert`'dnl
+
+   Notice that '_foreachq' had to use the helper macro 'quote' defined
+earlier (*note Shift::), to ensure that the embedded 'ifelse' call does
+not go haywire if a list element contains a comma.  Unfortunately, this
+implementation of 'foreachq' has its own severe flaw.  Whereas the
+'foreach' implementation was linear, this macro is quadratic in the
+number of list elements, and is much more likely to trip up the limit
+set by the command line option '--nesting-limit' (or '-L', *note
+Invoking m4: Limits control.).  Additionally, this implementation does
+not expand 'defn(`ITERATOR')' very well, when compared with 'foreach'.
+
+     $ m4 -I examples
+     include(`foreach.m4')include(`foreachq.m4')
+     =>
+     foreach(`name', `(`a', `b')', ` defn(`name')')
+     => a b
+     foreachq(`name', ``a', `b'', ` defn(`name')')
+     => _arg1(`a', `b') _arg1(shift(`a', `b'))
+
+   It is possible to have robust iteration with linear behavior and sane
+ITERATOR contents for either list style.  See if you can learn from the
+best elements of both of these implementations to create robust macros
+(or *note Answers: Improved foreach.).
+
+
+File: m4.info,  Node: Stacks,  Next: Composition,  Prev: Foreach,  Up: Conditionals
+
+6.6 Working with definition stacks
+==================================
+
+Thanks to 'pushdef', manipulation of a stack is an intrinsic operation
+in 'm4'.  Normally, only the topmost definition in a stack is important,
+but sometimes, it is desirable to manipulate the entire definition
+stack.
+
+ -- Composite: stack_foreach (MACRO, ACTION)
+ -- Composite: stack_foreach_lifo (MACRO, ACTION)
+     For each of the 'pushdef' definitions associated with MACRO, invoke
+     the macro ACTION with a single argument of that definition.
+     'stack_foreach' visits the oldest definition first, while
+     'stack_foreach_lifo' visits the current definition first.  ACTION
+     should not modify or dereference MACRO.  There are a few special
+     macros, such as 'defn', which cannot be used as the MACRO
+     parameter.
+
+   A sample implementation of these macros is distributed in the file
+'m4-1.4.17/examples/stack.m4'.
+
+     $ m4 -I examples
+     include(`stack.m4')
+     =>
+     pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
+     =>
+     define(`show', ``$1'
+     ')
+     =>
+     stack_foreach(`a', `show')dnl
+     =>1
+     =>2
+     =>3
+     stack_foreach_lifo(`a', `show')dnl
+     =>3
+     =>2
+     =>1
+
+   Now for the implementation.  Note the definition of a helper macro,
+'_stack_reverse', which destructively swaps the contents of one stack of
+definitions into the reverse order in the temporary macro 'tmp-$1'.  By
+calling the helper twice, the original order is restored back into the
+macro '$1'; since the operation is destructive, this explains why '$1'
+must not be modified or dereferenced during the traversal.  The caller
+can then inject additional code to pass the definition currently being
+visited to '$2'.  The choice of helper names is intentional; since '-'
+is not valid as part of a macro name, there is no risk of conflict with
+a valid macro name, and the code is guaranteed to use 'defn' where
+necessary.  Finally, note that any macro used in the traversal of a
+'pushdef' stack, such as 'pushdef' or 'defn', cannot be handled by
+'stack_foreach', since the macro would temporarily be undefined during
+the algorithm.
+
+     $ m4 -I examples
+     undivert(`stack.m4')dnl
+     =>divert(`-1')
+     =># stack_foreach(macro, action)
+     =># Invoke ACTION with a single argument of each definition
+     =># from the definition stack of MACRO, starting with the oldest.
+     =>define(`stack_foreach',
+     =>`_stack_reverse(`$1', `tmp-$1')'dnl
+     =>`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')')
+     =># stack_foreach_lifo(macro, action)
+     =># Invoke ACTION with a single argument of each definition
+     =># from the definition stack of MACRO, starting with the newest.
+     =>define(`stack_foreach_lifo',
+     =>`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl
+     =>`_stack_reverse(`tmp-$1', `$1')')
+     =>define(`_stack_reverse',
+     =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@)')')
+     =>divert`'dnl
+
+
+File: m4.info,  Node: Composition,  Prev: Stacks,  Up: Conditionals
+
+6.7 Building macros with macros
+===============================
+
+Since m4 is a macro language, it is possible to write macros that can
+build other macros.  First on the list is a way to automate the creation
+of blind macros.
+
+ -- Composite: define_blind (NAME, [VALUE]
+     Defines NAME as a blind macro, such that NAME will expand to VALUE
+     only when given explicit arguments.  VALUE should not be the result
+     of 'defn' (*note Defn::).  This macro is only recognized with
+     parameters, and results in an empty string.
+
+   Defining a macro to define another macro can be a bit tricky.  We
+want to use a literal '$#' in the argument to the nested 'define'.
+However, if '$' and '#' are adjacent in the definition of
+'define_blind', then it would be expanded as the number of arguments to
+'define_blind' rather than the intended number of arguments to NAME.
+The solution is to pass the difficult characters through extra arguments
+to a helper macro '_define_blind'.  When composing macros, it is a
+common idiom to need a helper macro to concatenate text that forms
+parameters in the composed macro, rather than interpreting the text as a
+parameter of the composing macro.
+
+   As for the limitation against using 'defn', there are two reasons.
+If a macro was previously defined with 'define_blind', then it can
+safely be renamed to a new blind macro using plain 'define'; using
+'define_blind' to rename it just adds another layer of 'ifelse',
+occupying memory and slowing down execution.  And if a macro is a
+builtin, then it would result in an attempt to define a macro consisting
+of both text and a builtin token; this is not supported, and the builtin
+token is flattened to an empty string.
+
+   With that explanation, here's the definition, and some sample usage.
+Notice that 'define_blind' is itself a blind macro.
+
+     $ m4 -d
+     define(`define_blind', `ifelse(`$#', `0', ``$0'',
+     `_$0(`$1', `$2', `$'`#', `$'`0')')')
+     =>
+     define(`_define_blind', `define(`$1',
+     `ifelse(`$3', `0', ``$4'', `$2')')')
+     =>
+     define_blind
+     =>define_blind
+     define_blind(`foo', `arguments were $*')
+     =>
+     foo
+     =>foo
+     foo(`bar')
+     =>arguments were bar
+     define(`blah', defn(`foo'))
+     =>
+     blah
+     =>blah
+     blah(`a', `b')
+     =>arguments were a,b
+     defn(`blah')
+     =>ifelse(`$#', `0', ``$0'', `arguments were $*')
+
+   Another interesting composition tactic is argument "currying", or
+factoring a macro that takes multiple arguments for use in a context
+that provides exactly one argument.
+
+ -- Composite: curry (MACRO, ...)
+     Expand to a macro call that takes exactly one argument, then
+     appends that argument to the original arguments and invokes MACRO
+     with the resulting list of arguments.
+
+   A demonstration of currying makes the intent of this macro a little
+more obvious.  The macro 'stack_foreach' mentioned earlier is an example
+of a context that provides exactly one argument to a macro name.  But
+coupled with currying, we can invoke 'reverse' with two arguments for
+each definition of a macro stack.  This example uses the file
+'m4-1.4.17/examples/curry.m4' included in the distribution.
+
+     $ m4 -I examples
+     include(`curry.m4')include(`stack.m4')
+     =>
+     define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
+                               `reverse(shift($@)), `$1'')')
+     =>
+     pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
+     =>
+     stack_foreach(`a', `:curry(`reverse', `4')')
+     =>:1, 4:2, 4:3, 4
+     curry(`curry', `reverse', `1')(`2')(`3')
+     =>3, 2, 1
+
+   Now for the implementation.  Notice how 'curry' leaves off with a
+macro name but no open parenthesis, while still in the middle of
+collecting arguments for '$1'.  The macro '_curry' is the helper macro
+that takes one argument, then adds it to the list and finally supplies
+the closing parenthesis.  The use of a comma inside the 'shift' call
+allows currying to also work for a macro that takes one argument,
+although it often makes more sense to invoke that macro directly rather
+than going through 'curry'.
+
+     $ m4 -I examples
+     undivert(`curry.m4')dnl
+     =>divert(`-1')
+     =># curry(macro, args)
+     =># Expand to a macro call that takes one argument, then invoke
+     =># macro(args, extra).
+     =>define(`curry', `$1(shift($@,)_$0')
+     =>define(`_curry', ``$1')')
+     =>divert`'dnl
+
+   Unfortunately, with M4 1.4.x, 'curry' is unable to handle builtin
+tokens, which are silently flattened to the empty string when passed
+through another text macro.  This limitation will be lifted in a future
+release of M4.
+
+   Putting the last few concepts together, it is possible to copy or
+rename an entire stack of macro definitions.
+
+ -- Composite: copy (SOURCE, DEST)
+ -- Composite: rename (SOURCE, DEST)
+     Ensure that DEST is undefined, then define it to the same stack of
+     definitions currently in SOURCE.  'copy' leaves SOURCE unchanged,
+     while 'rename' undefines SOURCE.  There are only a few macros, such
+     as 'copy' or 'defn', which cannot be copied via this macro.
+
+   The implementation is relatively straightforward (although since it
+uses 'curry', it is unable to copy builtin macros, such as the second
+definition of 'a' as a synonym for 'divnum'.  See if you can design a
+version that works around this limitation, or *note Answers: Improved
+copy.).
+
+     $ m4 -I examples
+     include(`curry.m4')include(`stack.m4')
+     =>
+     define(`rename', `copy($@)undefine(`$1')')dnl
+     define(`copy', `ifdef(`$2', `errprint(`$2 already defined
+     ')m4exit(`1')',
+        `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl
+     pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2')
+     =>
+     copy(`a', `b')
+     =>
+     rename(`b', `c')
+     =>
+     a b c
+     =>2 b 2
+     popdef(`a', `c')c a
+     => 0
+     popdef(`a', `c')a c
+     =>1 1
+
+
+File: m4.info,  Node: Debugging,  Next: Input Control,  Prev: Conditionals,  Up: Top
+
+7 How to debug macros and input
+*******************************
+
+When writing macros for 'm4', they often do not work as intended on the
+first try (as is the case with most programming languages).
+Fortunately, there is support for macro debugging in 'm4'.
+
+* Menu:
+
+* Dumpdef::                     Displaying macro definitions
+* Trace::                       Tracing macro calls
+* Debug Levels::                Controlling debugging output
+* Debug Output::                Saving debugging output
+
+
+File: m4.info,  Node: Dumpdef,  Next: Trace,  Up: Debugging
+
+7.1 Displaying macro definitions
+================================
+
+If you want to see what a name expands into, you can use the builtin
+'dumpdef':
+
+ -- Builtin: dumpdef ([NAMES...]
+     Accepts any number of arguments.  If called without any arguments,
+     it displays the definitions of all known names, otherwise it
+     displays the definitions of the NAMES given.  The output is printed
+     to the current debug file (usually standard error), and is sorted
+     by name.  If an unknown name is encountered, a warning is printed.
+
+     The expansion of 'dumpdef' is void.
+
+     $ m4 -d
+     define(`foo', `Hello world.')
+     =>
+     dumpdef(`foo')
+     error->foo: =>
+     dumpdef(`define')
+     error->define: =>
+
+   The last example shows how builtin macros definitions are displayed.
+The definition that is dumped corresponds to what would occur if the
+macro were to be called at that point, even if other definitions are
+still live due to redefining a macro during argument collection.
+
+     $ m4 -d
+     pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
+     =>
+     f(popdef(`f')dumpdef(`f'))
+     error->f: =>f2
+     f(popdef(`f')dumpdef(`f'))
+     error->m4:stdin:3: undefined macro `f'
+     =>f1
+
+   *Note Debug Levels::, for information on controlling the details of
+the display.
+
+
+File: m4.info,  Node: Trace,  Next: Debug Levels,  Prev: Dumpdef,  Up: Debugging
+
+7.2 Tracing macro calls
+=======================
+
+It is possible to trace macro calls and expansions through the builtins
+'traceon' and 'traceoff':
+
+ -- Builtin: traceon ([NAMES...]
+ -- Builtin: traceoff ([NAMES...]
+     When called without any arguments, 'traceon' and 'traceoff' will
+     turn tracing on and off, respectively, for all currently defined
+     macros.
+
+     When called with arguments, only the macros listed in NAMES are
+     affected, whether or not they are currently defined.
+
+     The expansion of 'traceon' and 'traceoff' is void.
+
+   Whenever a traced macro is called and the arguments have been
+collected, the call is displayed.  If the expansion of the macro call is
+not void, the expansion can be displayed after the call.  The output is
+printed to the current debug file (defaulting to standard error, *note
+Debug Output::).
+
+     $ m4 -d
+     define(`foo', `Hello World.')
+     =>
+     define(`echo', `$@')
+     =>
+     traceon(`foo', `echo')
+     =>
+     foo
+     error->m4trace: -1- foo -> `Hello World.'
+     =>Hello World.
+     echo(`gnus', `and gnats')
+     error->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
+     =>gnus,and gnats
+
+   The number between dashes is the depth of the expansion.  It is one
+most of the time, signifying an expansion at the outermost level, but it
+increases when macro arguments contain unquoted macro calls.  The
+maximum number that will appear between dashes is controlled by the
+option '--nesting-limit' (or '-L', *note Invoking m4: Limits control.).
+Additionally, the option '--trace' (or '-t') can be used to invoke
+'traceon(NAME)' before parsing input.
+
+     $ m4 -L 3 -t ifelse
+     ifelse(`one level')
+     error->m4trace: -1- ifelse
+     =>
+     ifelse(ifelse(ifelse(`three levels')))
+     error->m4trace: -3- ifelse
+     error->m4trace: -2- ifelse
+     error->m4trace: -1- ifelse
+     =>
+     ifelse(ifelse(ifelse(ifelse(`four levels'))))
+     error->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
+
+   Tracing by name is an attribute that is preserved whether the macro
+is defined or not.  This allows the selection of macros to trace before
+those macros are defined.
+
+     $ m4 -d
+     traceoff(`foo')
+     =>
+     traceon(`foo')
+     =>
+     foo
+     =>foo
+     defn(`foo')
+     =>
+     define(`foo', `bar')
+     =>
+     foo
+     error->m4trace: -1- foo -> `bar'
+     =>bar
+     undefine(`foo')
+     =>
+     ifdef(`foo', `yes', `no')
+     =>no
+     indir(`foo')
+     error->m4:stdin:9: undefined macro `foo'
+     =>
+     define(`foo', `blah')
+     =>
+     foo
+     error->m4trace: -1- foo -> `blah'
+     =>blah
+     traceoff
+     =>
+     foo
+     =>blah
+
+   Tracing even works on builtins.  However, 'defn' (*note Defn::) does
+not transfer tracing status.
+
+     $ m4 -d
+     traceon(`traceon')
+     =>
+     traceon(`traceoff')
+     error->m4trace: -1- traceon(`traceoff')
+     =>
+     traceoff(`traceoff')
+     error->m4trace: -1- traceoff(`traceoff')
+     =>
+     traceoff(`traceon')
+     =>
+     traceon(`eval', `m4_divnum')
+     =>
+     define(`m4_eval', defn(`eval'))
+     =>
+     define(`m4_divnum', defn(`divnum'))
+     =>
+     eval(divnum)
+     error->m4trace: -1- eval(`0') -> `0'
+     =>0
+     m4_eval(m4_divnum)
+     error->m4trace: -2- m4_divnum -> `0'
+     =>0
+
+   *Note Debug Levels::, for information on controlling the details of
+the display.  The format of the trace output is not specified by POSIX,
+and varies between implementations of 'm4'.
+
+
+File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging
+
+7.3 Controlling debugging output
+================================
+
+The '-d' option to 'm4' (or '--debug', *note Invoking m4: Debugging
+options.) controls the amount of details presented in three categories
+of output.  Trace output is requested by 'traceon' (*note Trace::), and
+each line is prefixed by 'm4trace:' in relation to a macro invocation.
+Debug output tracks useful events not associated with a macro
+invocation, and each line is prefixed by 'm4debug:'.  Finally, 'dumpdef'
+(*note Dumpdef::) output is affected, with no prefix added to the output
+lines.
+
+   The FLAGS following the option can be one or more of the following:
+
+'a'
+     In trace output, show the actual arguments that were collected
+     before invoking the macro.  This applies to all macro calls if the
+     't' flag is used, otherwise only the macros covered by calls of
+     'traceon'.  Arguments are subject to length truncation specified by
+     the command line option '--arglength' (or '-l').
+
+'c'
+     In trace output, show several trace lines for each macro call.  A
+     line is shown when the macro is seen, but before the arguments are
+     collected; a second line when the arguments have been collected and
+     a third line after the call has completed.
+
+'e'
+     In trace output, show the expansion of each macro call, if it is
+     not void.  This applies to all macro calls if the 't' flag is used,
+     otherwise only the macros covered by calls of 'traceon'.  The
+     expansion is subject to length truncation specified by the command
+     line option '--arglength' (or '-l').
+
+'f'
+     In debug and trace output, include the name of the current input
+     file in the output line.
+
+'i'
+     In debug output, print a message each time the current input file
+     is changed.
+
+'l'
+     In debug and trace output, include the current input line number in
+     the output line.
+
+'p'
+     In debug output, print a message when a named file is found through
+     the path search mechanism (*note Search Path::), giving the actual
+     file name used.
+
+'q'
+     In trace and dumpdef output, quote actual arguments and macro
+     expansions in the display with the current quotes.  This is useful
+     in connection with the 'a' and 'e' flags above.
+
+'t'
+     In trace output, trace all macro calls made in this invocation of
+     'm4', regardless of the settings of 'traceon'.
+
+'x'
+     In trace output, add a unique 'macro call id' to each line of the
+     trace output.  This is useful in connection with the 'c' flag
+     above.
+
+'V'
+     A shorthand for all of the above flags.
+
+   If no flags are specified with the '-d' option, the default is 'aeq'.
+The examples throughout this manual assume the default flags.
+
+   There is a builtin macro 'debugmode', which allows on-the-fly control
+of the debugging output format:
+
+ -- Builtin: debugmode ([FLAGS]
+     The argument FLAGS should be a subset of the letters listed above.
+     As special cases, if the argument starts with a '+', the flags are
+     added to the current debug flags, and if it starts with a '-', they
+     are removed.  If no argument is present, all debugging flags are
+     cleared (as if no '-d' was given), and with an empty argument the
+     flags are reset to the default of 'aeq'.
+
+     The expansion of 'debugmode' is void.
+
+     $ m4
+     define(`foo', `FOO')
+     =>
+     traceon(`foo')
+     =>
+     debugmode()
+     =>
+     foo
+     error->m4trace: -1- foo -> `FOO'
+     =>FOO
+     debugmode
+     =>
+     foo
+     error->m4trace: -1- foo
+     =>FOO
+     debugmode(`+l')
+     =>
+     foo
+     error->m4trace:8: -1- foo
+     =>FOO
+
+   The following example demonstrates the behavior of length truncation,
+when specified on the command line.  Note that each argument and the
+final result are individually truncated.  Also, the special tokens for
+builtin functions are not truncated.
+
+     $ m4 -d -l 6
+     define(`echo', `$@')debugmode(`+t')
+     =>
+     echo(`1', `long string')
+     error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
+     =>1,long string
+     indir(`echo', defn(`changequote'))
+     error->m4trace: -2- defn(`change...')
+     error->m4trace: -1- indir(`echo', <changequote>) -> ``''
+     =>
+
+   This example shows the effects of the debug flags that are not
+related to macro tracing.
+
+     $ m4 -dip -I examples
+     error->m4debug: input read from stdin
+     include(`foo')dnl
+     error->m4debug: path search for `foo' found `examples/foo'
+     error->m4debug: input read from examples/foo
+     =>bar
+     error->m4debug: input reverted to stdin, line 1
+     ^D
+     error->m4debug: input exhausted
+
+
+File: m4.info,  Node: Debug Output,  Prev: Debug Levels,  Up: Debugging
+
+7.4 Saving debugging output
+===========================
+
+Debug and tracing output can be redirected to files using either the
+'--debugfile' option to 'm4' (*note Invoking m4: Debugging options.), or
+with the builtin macro 'debugfile':
+
+ -- Builtin: debugfile ([FILE]
+     Sends all further debug and trace output to FILE, opened in append
+     mode.  If FILE is the empty string, debug and trace output are
+     discarded.  If 'debugfile' is called without any arguments, debug
+     and trace output are sent to standard error.  This does not affect
+     warnings, error messages, or 'errprint' output, which are always
+     sent to standard error.  If FILE cannot be opened, the current
+     debug file is unchanged, and an error is issued.
+
+     The expansion of 'debugfile' is void.
+
+     $ m4 -d
+     traceon(`divnum')
+     =>
+     divnum(`extra')
+     error->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
+     error->m4trace: -1- divnum(`extra') -> `0'
+     =>0
+     debugfile()
+     =>
+     divnum(`extra')
+     error->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
+     =>0
+     debugfile
+     =>
+     divnum
+     error->m4trace: -1- divnum -> `0'
+     =>0
+
+
+File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top
+
+8 Input control
+***************
+
+This chapter describes various builtin macros for controlling the input
+to 'm4'.
+
+* Menu:
+
+* Dnl::                         Deleting whitespace in input
+* Changequote::                 Changing the quote characters
+* Changecom::                   Changing the comment delimiters
+* Changeword::                  Changing the lexical structure of words
+* M4wrap::                      Saving text until end of input
+
+
+File: m4.info,  Node: Dnl,  Next: Changequote,  Up: Input Control
+
+8.1 Deleting whitespace in input
+================================
+
+The builtin 'dnl' stands for "Discard to Next Line":
+
+ -- Builtin: dnl
+     All characters, up to and including the next newline, are discarded
+     without performing any macro expansion.  A warning is issued if the
+     end of the file is encountered without a newline.
+
+     The expansion of 'dnl' is void.
+
+   It is often used in connection with 'define', to remove the newline
+that follows the call to 'define'.  Thus
+
+     define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
+     foo
+     =>Macro foo.
+
+   The input up to and including the next newline is discarded, as
+opposed to the way comments are treated (*note Comments::).
+
+   Usually, 'dnl' is immediately followed by an end of line or some
+other whitespace.  GNU 'm4' will produce a warning diagnostic if 'dnl'
+is followed by an open parenthesis.  In this case, 'dnl' will collect
+and process all arguments, looking for a matching close parenthesis.
+All predictable side effects resulting from this collection will take
+place.  'dnl' will return no output.  The input following the matching
+close parenthesis up to and including the next newline, on whatever line
+containing it, will still be discarded.
+
+     dnl(`args are ignored, but side effects occur',
+     define(`foo', `like this')) while this text is ignored: undefine(`foo')
+     error->m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored
+     See how `foo' was defined, foo?
+     =>See how foo was defined, like this?
+
+   If the end of file is encountered without a newline character, a
+warning is issued and dnl stops consuming input.
+
+     m4wrap(`m4wrap(`2 hi
+     ')0 hi dnl 1 hi')
+     =>
+     define(`hi', `HI')
+     =>
+     ^D
+     error->m4:stdin:1: Warning: end of file treated as newline
+     =>0 HI 2 HI
+
+
+File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control
+
+8.2 Changing the quote characters
+=================================
+
+The default quote delimiters can be changed with the builtin
+'changequote':
+
+ -- Builtin: changequote ([START = '`']
+     This sets START as the new begin-quote delimiter and END as the new
+     end-quote delimiter.  If both arguments are missing, the default
+     quotes ('`' and ''') are used.  If START is void, then quoting is
+     disabled.  Otherwise, if END is missing or void, the default
+     end-quote delimiter (''') is used.  The quote delimiters can be of
+     any length.
+
+     The expansion of 'changequote' is void.
+
+     changequote(`[', `]')
+     =>
+     define([foo], [Macro [foo].])
+     =>
+     foo
+     =>Macro foo.
+
+   The quotation strings can safely contain eight-bit characters.  If no
+single character is appropriate, START and END can be of any length.
+Other implementations cap the delimiter length to five characters, but
+GNU has no inherent limit.
+
+     changequote(`[[[', `]]]')
+     =>
+     define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
+     =>
+     foo
+     =>Macro [[foo]].
+
+   Calling 'changequote' with START as the empty string will effectively
+disable the quoting mechanism, leaving no way to quote text.  However,
+using an empty string is not portable, as some other implementations of
+'m4' revert to the default quoting, while others preserve the prior
+non-empty delimiter.  If START is not empty, then an empty END will use
+the default end-quote delimiter of ''', as otherwise, it would be
+impossible to end a quoted string.  Again, this is not portable, as some
+other 'm4' implementations reuse START as the end-quote delimiter, while
+others preserve the previous non-empty value.  Omitting both arguments
+restores the default begin-quote and end-quote delimiters; fortunately
+this behavior is portable to all implementations of 'm4'.
+
+     define(`foo', `Macro `FOO'.')
+     =>
+     changequote(`', `')
+     =>
+     foo
+     =>Macro `FOO'.
+     `foo'
+     =>`Macro `FOO'.'
+     changequote(`,)
+     =>
+     foo
+     =>Macro FOO.
+
+   There is no way in 'm4' to quote a string containing an unmatched
+begin-quote, except using 'changequote' to change the current quotes.
+
+   If the quotes should be changed from, say, '[' to '[[', temporary
+quote characters have to be defined.  To achieve this, two calls of
+'changequote' must be made, one for the temporary quotes and one for the
+new quotes.
+
+   Macros are recognized in preference to the begin-quote string, so if
+a prefix of START can be recognized as part of a potential macro name,
+the quoting mechanism is effectively disabled.  Unless you use
+'changeword' (*note Changeword::), this means that START should not
+begin with a letter, digit, or '_' (underscore).  However, even though
+quoted strings are not recognized, the quote characters can still be
+discerned in macro expansion and in trace output.
+
+     define(`echo', `$@')
+     =>
+     define(`hi', `HI')
+     =>
+     changequote(`q', `Q')
+     =>
+     q hi Q hi
+     =>q HI Q HI
+     echo(hi)
+     =>qHIQ
+     changequote
+     =>
+     changequote(`-', `EOF')
+     =>
+     - hi EOF hi
+     => hi  HI
+     changequote
+     =>
+     changequote(`1', `2')
+     =>
+     hi1hi2
+     =>hi1hi2
+     hi 1hi2
+     =>HI hi
+
+   Quotes are recognized in preference to argument collection.  In
+particular, if START is a single '(', then argument collection is
+effectively disabled.  For portability with other implementations, it is
+a good idea to avoid '(', ',', and ')' as the first character in START.
+
+     define(`echo', `$#:$@:')
+     =>
+     define(`hi', `HI')
+     =>
+     changequote(`(',`)')
+     =>
+     echo(hi)
+     =>0::hi
+     changequote
+     =>
+     changequote(`((', `))')
+     =>
+     echo(hi)
+     =>1:HI:
+     echo((hi))
+     =>0::hi
+     changequote
+     =>
+     changequote(`,', `)')
+     =>
+     echo(hi,hi)bye)
+     =>1:HIhibye:
+
+   However, if you are not worried about portability, using '(' and ')'
+as quoting characters has an interesting property--you can use it to
+compute a quoted string containing the expansion of any quoted text, as
+long as the expansion results in both balanced quotes and balanced
+parentheses.  The trick is realizing 'expand' uses '$1' unquoted, to
+trigger its expansion using the normal quoting characters, but uses
+extra parentheses to group unquoted commas that occur in the expansion
+without consuming whitespace following those commas.  Then '_expand'
+uses 'changequote' to convert the extra parentheses back into quoting
+characters.  Note that it takes two more 'changequote' invocations to
+restore the original quotes.  Contrast the behavior on whitespace when
+using '$*', via 'quote', to attempt the same task.
+
+     changequote(`[', `]')dnl
+     define([a], [1, (b)])dnl
+     define([b], [2])dnl
+     define([quote], [[$*]])dnl
+     define([expand], [_$0(($1))])dnl
+     define([_expand],
+       [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
+     expand([a, a, [a, a], [[a, a]]])
+     =>1, (2), 1, (2), a, a, [a, a]
+     quote(a, a, [a, a], [[a, a]])
+     =>1,(2),1,(2),a, a,[a, a]
+
+   If END is a prefix of START, the end-quote will be recognized in
+preference to a nested begin-quote.  In particular, changing the quotes
+to have the same string for START and END disables nesting of quotes.
+When quote nesting is disabled, it is impossible to double-quote strings
+across macro expansions, so using the same string is not done very
+often.
+
+     define(`hi', `HI')
+     =>
+     changequote(`""', `"')
+     =>
+     ""hi"""hi"
+     =>hihi
+     ""hi" ""hi"
+     =>hi hi
+     ""hi"" "hi"
+     =>hi" "HI"
+     changequote
+     =>
+     `hi`hi'hi'
+     =>hi`hi'hi
+     changequote(`"', `"')
+     =>
+     "hi"hi"hi"
+     =>hiHIhi
+
+   It is an error if the end of file occurs within a quoted string.
+
+     `hello world'
+     =>hello world
+     `dangling quote
+     ^D
+     error->m4:stdin:2: ERROR: end of file in string
+
+     ifelse(`dangling quote
+     ^D
+     error->m4:stdin:1: ERROR: end of file in string
+
+
+File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control
+
+8.3 Changing the comment delimiters
+===================================
+
+The default comment delimiters can be changed with the builtin macro
+'changecom':
+
+ -- Builtin: changecom ([START]
+     This sets START as the new begin-comment delimiter and END as the
+     new end-comment delimiter.  If both arguments are missing, or START
+     is void, then comments are disabled.  Otherwise, if END is missing
+     or void, the default end-comment delimiter of newline is used.  The
+     comment delimiters can be of any length.
+
+     The expansion of 'changecom' is void.
+
+     define(`comment', `COMMENT')
+     =>
+     # A normal comment
+     =># A normal comment
+     changecom(`/*', `*/')
+     =>
+     # Not a comment anymore
+     =># Not a COMMENT anymore
+     But: /* this is a comment now */ while this is not a comment
+     =>But: /* this is a comment now */ while this is not a COMMENT
+
+   Note how comments are copied to the output, much as if they were
+quoted strings.  If you want the text inside a comment expanded, quote
+the begin-comment delimiter.
+
+   Calling 'changecom' without any arguments, or with START as the empty
+string, will effectively disable the commenting mechanism.  To restore
+the original comment start of '#', you must explicitly ask for it.  If
+START is not empty, then an empty END will use the default end-comment
+delimiter of newline, as otherwise, it would be impossible to end a
+comment.  However, this is not portable, as some other 'm4'
+implementations preserve the previous non-empty delimiters instead.
+
+     define(`comment', `COMMENT')
+     =>
+     changecom
+     =>
+     # Not a comment anymore
+     =># Not a COMMENT anymore
+     changecom(`#', `')
+     =>
+     # comment again
+     =># comment again
+
+   The comment strings can safely contain eight-bit characters.  If no
+single character is appropriate, START and END can be of any length.
+Other implementations cap the delimiter length to five characters, but
+GNU has no inherent limit.
+
+   Comments are recognized in preference to macros.  However, this is
+not compatible with other implementations, where macros and even quoting
+takes precedence over comments, so it may change in a future release.
+For portability, this means that START should not begin with a letter,
+digit, or '_' (underscore), and that neither the start-quote nor the
+start-comment string should be a prefix of the other.
+
+     define(`hi', `HI')
+     =>
+     define(`hi1hi2', `hello')
+     =>
+     changecom(`q', `Q')
+     =>
+     q hi Q hi
+     =>q hi Q HI
+     changecom(`1', `2')
+     =>
+     hi1hi2
+     =>hello
+     hi 1hi2
+     =>HI 1hi2
+
+   Comments are recognized in preference to argument collection.  In
+particular, if START is a single '(', then argument collection is
+effectively disabled.  For portability with other implementations, it is
+a good idea to avoid '(', ',', and ')' as the first character in START.
+
+     define(`echo', `$#:$*:$@:')
+     =>
+     define(`hi', `HI')
+     =>
+     changecom(`(',`)')
+     =>
+     echo(hi)
+     =>0:::(hi)
+     changecom
+     =>
+     changecom(`((', `))')
+     =>
+     echo(hi)
+     =>1:HI:HI:
+     echo((hi))
+     =>0:::((hi))
+     changecom(`,', `)')
+     =>
+     echo(hi,hi)bye)
+     =>1:HI,hi)bye:HI,hi)bye:
+     changecom
+     =>
+     echo(hi,`,`'hi',hi)
+     =>3:HI,,HI,HI:HI,,`'hi,HI:
+     echo(hi,`,`'hi',hi`'changecom(`,,', `hi'))
+     =>3:HI,,`'hi,HI:HI,,`'hi,HI:
+
+   It is an error if the end of file occurs within a comment.
+
+     changecom(`/*', `*/')
+     =>
+     /*dangling comment
+     ^D
+     error->m4:stdin:2: ERROR: end of file in comment
+
+
+File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control
+
+8.4 Changing the lexical structure of words
+===========================================
+
+     The macro 'changeword' and all associated functionality is
+     experimental.  It is only available if the '--enable-changeword'
+     option was given to 'configure', at GNU 'm4' installation time.
+     The functionality will go away in the future, to be replaced by
+     other new features that are more efficient at providing the same
+     capabilities.  _Do not rely on it_.  Please direct your comments
+     about it the same way you would do for bugs.
+
+   A file being processed by 'm4' is split into quoted strings, words
+(potential macro names) and simple tokens (any other single character).
+Initially a word is defined by the following regular expression:
+
+     [_a-zA-Z][_a-zA-Z0-9]*
+
+   Using 'changeword', you can change this regular expression:
+
+ -- Optional builtin: changeword (REGEX)
+     Changes the regular expression for recognizing macro names to be
+     REGEX.  If REGEX is empty, use '[_a-zA-Z][_a-zA-Z0-9]*'.  REGEX
+     must obey the constraint that every prefix of the desired final
+     pattern is also accepted by the regular expression.  If REGEX
+     contains grouping parentheses, the macro invoked is the portion
+     that matched the first group, rather than the entire matching
+     string.
+
+     The expansion of 'changeword' is void.  The macro 'changeword' is
+     recognized only with parameters.
+
+   Relaxing the lexical rules of 'm4' might be useful (for example) if
+you wanted to apply translations to a file of numbers:
+
+     ifdef(`changeword', `', `errprint(` skipping: no changeword support
+     ')m4exit(`77')')dnl
+     changeword(`[_a-zA-Z0-9]+')
+     =>
+     define(`1', `0')1
+     =>0
+
+   Tightening the lexical rules is less useful, because it will
+generally make some of the builtins unavailable.  You could use it to
+prevent accidental call of builtins, for example:
+
+     ifdef(`changeword', `', `errprint(` skipping: no changeword support
+     ')m4exit(`77')')dnl
+     define(`_indir', defn(`indir'))
+     =>
+     changeword(`_[_a-zA-Z0-9]*')
+     =>
+     esyscmd(`foo')
+     =>esyscmd(foo)
+     _indir(`esyscmd', `echo hi')
+     =>hi
+     =>
+
+   Because 'm4' constructs its words a character at a time, there is a
+restriction on the regular expressions that may be passed to
+'changeword'.  This is that if your regular expression accepts 'foo', it
+must also accept 'f' and 'fo'.
+
+     ifdef(`changeword', `', `errprint(` skipping: no changeword support
+     ')m4exit(`77')')dnl
+     define(`foo
+     ', `bar
+     ')
+     =>
+     dnl This example wants to recognize changeword, dnl, and `foo\n'.
+     dnl First, we check that our regexp will match.
+     regexp(`changeword', `[cd][a-z]*\|foo[
+     ]')
+     =>0
+     regexp(`foo
+     ', `[cd][a-z]*\|foo[
+     ]')
+     =>0
+     regexp(`f', `[cd][a-z]*\|foo[
+     ]')
+     =>-1
+     foo
+     =>foo
+     changeword(`[cd][a-z]*\|foo[
+     ]')
+     =>
+     dnl Even though `foo\n' matches, we forgot to allow `f'.
+     foo
+     =>foo
+     changeword(`[cd][a-z]*\|fo*[
+     ]?')
+     =>
+     dnl Now we can call `foo\n'.
+     foo
+     =>bar
+
+   'changeword' has another function.  If the regular expression
+supplied contains any grouped subexpressions, then text outside the
+first of these is discarded before symbol lookup.  So:
+
+     ifdef(`changeword', `', `errprint(` skipping: no changeword support
+     ')m4exit(`77')')dnl
+     ifdef(`__unix__', ,
+           `errprint(` skipping: syscmd does not have unix semantics
+     ')m4exit(`77')')dnl
+     changecom(`/*', `*/')dnl
+     define(`foo', `bar')dnl
+     changeword(`#\([_a-zA-Z0-9]*\)')
+     =>
+     #esyscmd(`echo foo \#foo')
+     =>foo bar
+     =>
+
+   'm4' now requires a '#' mark at the beginning of every macro
+invocation, so one can use 'm4' to preprocess plain text without losing
+various words like 'divert'.
+
+   In 'm4', macro substitution is based on text, while in TeX, it is
+based on tokens.  'changeword' can throw this difference into relief.
+For example, here is the same idea represented in TeX and 'm4'.  First,
+the TeX version:
+
+     \def\a{\message{Hello}}
+     \catcode`\@=0
+     \catcode`\\=12
+     @a
+     @bye
+     =>Hello
+
+Then, the 'm4' version:
+
+     ifdef(`changeword', `', `errprint(` skipping: no changeword support
+     ')m4exit(`77')')dnl
+     define(`a', `errprint(`Hello')')dnl
+     changeword(`@\([_a-zA-Z0-9]*\)')
+     =>
+     @a
+     =>errprint(Hello)
+
+   In the TeX example, the first line defines a macro 'a' to print the
+message 'Hello'.  The second line defines <@> to be usable instead of
+<\> as an escape character.  The third line defines <\> to be a normal
+printing character, not an escape.  The fourth line invokes the macro
+'a'.  So, when TeX is run on this file, it displays the message 'Hello'.
+
+   When the 'm4' example is passed through 'm4', it outputs
+'errprint(Hello)'.  The reason for this is that TeX does lexical
+analysis of macro definition when the macro is _defined_.  'm4' just
+stores the text, postponing the lexical analysis until the macro is
+_used_.
+
+   You should note that using 'changeword' will slow 'm4' down by a
+factor of about seven, once it is changed to something other than the
+default regular expression.  You can invoke 'changeword' with the empty
+string to restore the default word definition, and regain the parsing
+speed.
+
+
+File: m4.info,  Node: M4wrap,  Prev: Changeword,  Up: Input Control
+
+8.5 Saving text until end of input
+==================================
+
+It is possible to 'save' some text until the end of the normal input has
+been seen.  Text can be saved, to be read again by 'm4' when the normal
+input has been exhausted.  This feature is normally used to initiate
+cleanup actions before normal exit, e.g., deleting temporary files.
+
+   To save input text, use the builtin 'm4wrap':
+
+ -- Builtin: m4wrap (STRING, ...)
+     Stores STRING in a safe place, to be reread when end of input is
+     reached.  As a GNU extension, additional arguments are concatenated
+     with a space to the STRING.
+
+     The expansion of 'm4wrap' is void.  The macro 'm4wrap' is
+     recognized only with parameters.
+
+     define(`cleanup', `This is the `cleanup' action.
+     ')
+     =>
+     m4wrap(`cleanup')
+     =>
+     This is the first and last normal input line.
+     =>This is the first and last normal input line.
+     ^D
+     =>This is the cleanup action.
+
+   The saved input is only reread when the end of normal input is seen,
+and not if 'm4exit' is used to exit 'm4'.
+
+   It is safe to call 'm4wrap' from saved text, but then the order in
+which the saved text is reread is undefined.  If 'm4wrap' is not used
+recursively, the saved pieces of text are reread in the opposite order
+in which they were saved (LIFO--last in, first out).  However, this
+behavior is likely to change in a future release, to match POSIX, so you
+should not depend on this order.
+
+   It is possible to emulate POSIX behavior even with older versions of
+GNU M4 by including the file 'm4-1.4.17/examples/wrapfifo.m4' from the
+distribution:
+
+     $ m4 -I examples
+     undivert(`wrapfifo.m4')dnl
+     =>dnl Redefine m4wrap to have FIFO semantics.
+     =>define(`_m4wrap_level', `0')dnl
+     =>define(`m4wrap',
+     =>`ifdef(`m4wrap'_m4wrap_level,
+     =>       `define(`m4wrap'_m4wrap_level,
+     =>               defn(`m4wrap'_m4wrap_level)`$1')',
+     =>       `builtin(`m4wrap', `define(`_m4wrap_level',
+     =>                                  incr(_m4wrap_level))dnl
+     =>m4wrap'_m4wrap_level)dnl
+     =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
+     include(`wrapfifo.m4')
+     =>
+     m4wrap(`a`'m4wrap(`c
+     ', `d')')m4wrap(`b')
+     =>
+     ^D
+     =>abc
+
+   It is likewise possible to emulate LIFO behavior without resorting to
+the GNU M4 extension of 'builtin', by including the file
+'m4-1.4.17/examples/wraplifo.m4' from the distribution.  (Unfortunately,
+both examples shown here share some subtle bugs.  See if you can find
+and correct them; or *note Answers: Improved m4wrap.).
+
+     $ m4 -I examples
+     undivert(`wraplifo.m4')dnl
+     =>dnl Redefine m4wrap to have LIFO semantics.
+     =>define(`_m4wrap_level', `0')dnl
+     =>define(`_m4wrap', defn(`m4wrap'))dnl
+     =>define(`m4wrap',
+     =>`ifdef(`m4wrap'_m4wrap_level,
+     =>       `define(`m4wrap'_m4wrap_level,
+     =>               `$1'defn(`m4wrap'_m4wrap_level))',
+     =>       `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl
+     =>m4wrap'_m4wrap_level)dnl
+     =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
+     include(`wraplifo.m4')
+     =>
+     m4wrap(`a`'m4wrap(`c
+     ', `d')')m4wrap(`b')
+     =>
+     ^D
+     =>bac
+
+   Here is an example of implementing a factorial function using
+'m4wrap':
+
+     define(`f', `ifelse(`$1', `0', `Answer: 0!=1
+     ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
+     ', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
+     =>
+     f(`10')
+     =>
+     ^D
+     =>Answer: 10*9*8*7*6*5*4*3*2*1=3628800
+
+   Invocations of 'm4wrap' at the same recursion level are concatenated
+and rescanned as usual:
+
+     define(`aa', `AA
+     ')
+     =>
+     m4wrap(`a')m4wrap(`a')
+     =>
+     ^D
+     =>AA
+
+however, the transition between recursion levels behaves like an end of
+file condition between two input files.
+
+     m4wrap(`m4wrap(`)')len(abc')
+     =>
+     ^D
+     error->m4:stdin:1: ERROR: end of file in argument list
+
+
+File: m4.info,  Node: File Inclusion,  Next: Diversions,  Prev: Input Control,  Up: Top
+
+9 File inclusion
+****************
+
+'m4' allows you to include named files at any point in the input.
+
+* Menu:
+
+* Include::                     Including named files
+* Search Path::                 Searching for include files
+
+
+File: m4.info,  Node: Include,  Next: Search Path,  Up: File Inclusion
+
+9.1 Including named files
+=========================
+
+There are two builtin macros in 'm4' for including files:
+
+ -- Builtin: include (FILE)
+ -- Builtin: sinclude (FILE)
+     Both macros cause the file named FILE to be read by 'm4'.  When the
+     end of the file is reached, input is resumed from the previous
+     input file.
+
+     The expansion of 'include' and 'sinclude' is therefore the contents
+     of FILE.
+
+     If FILE does not exist, is a directory, or cannot otherwise be
+     read, the expansion is void, and 'include' will fail with an error
+     while 'sinclude' is silent.  The empty string counts as a file that
+     does not exist.
+
+     The macros 'include' and 'sinclude' are recognized only with
+     parameters.
+
+     include(`none')
+     error->m4:stdin:1: cannot open `none': No such file or directory
+     =>
+     include()
+     error->m4:stdin:2: cannot open `': No such file or directory
+     =>
+     sinclude(`none')
+     =>
+     sinclude()
+     =>
+
+   The rest of this section assumes that 'm4' is invoked with the '-I'
+option (*note Invoking m4: Preprocessor features.) pointing to the
+'m4-1.4.17/examples' directory shipped as part of the GNU 'm4' package.
+The file 'm4-1.4.17/examples/incl.m4' in the distribution contains the
+lines:
+
+     $ cat examples/incl.m4
+     =>Include file start
+     =>foo
+     =>Include file end
+
+   Normally file inclusion is used to insert the contents of a file into
+the input stream.  The contents of the file will be read by 'm4' and
+macro calls in the file will be expanded:
+
+     $ m4 -I examples
+     define(`foo', `FOO')
+     =>
+     include(`incl.m4')
+     =>Include file start
+     =>FOO
+     =>Include file end
+     =>
+
+   The fact that 'include' and 'sinclude' expand to the contents of the
+file can be used to define macros that operate on entire files.  Here is
+an example, which defines 'bar' to expand to the contents of 'incl.m4':
+
+     $ m4 -I examples
+     define(`bar', include(`incl.m4'))
+     =>
+     This is `bar':  >>bar<<
+     =>This is bar:  >>Include file start
+     =>foo
+     =>Include file end
+     =><<
+
+   This use of 'include' is not trivial, though, as files can contain
+quotes, commas, and parentheses, which can interfere with the way the
+'m4' parser works.  GNU 'm4' seamlessly concatenates the file contents
+with the next character, even if the included file ended in the middle
+of a comment, string, or macro call.  These conditions are only treated
+as end of file errors if specified as input files on the command line.
+
+   In GNU 'm4', an alternative method of reading files is using
+'undivert' (*note Undivert::) on a named file.
+
+
+File: m4.info,  Node: Search Path,  Prev: Include,  Up: File Inclusion
+
+9.2 Searching for include files
+===============================
+
+GNU 'm4' allows included files to be found in other directories than the
+current working directory.
+
+   If the '--prepend-include' or '-B' command-line option was provided
+(*note Invoking m4: Preprocessor features.), those directories are
+searched first, in reverse order that those options were listed on the
+command line.  Then 'm4' looks in the current working directory.  Next
+comes the directories specified with the '--include' or '-I' option, in
+the order found on the command line.  Finally, if the 'M4PATH'
+environment variable is set, it is expected to contain a colon-separated
+list of directories, which will be searched in order.
+
+   If the automatic search for include-files causes trouble, the 'p'
+debug flag (*note Debug Levels::) can help isolate the problem.
+
+
+File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top
+
+10 Diverting and undiverting output
+***********************************
+
+Diversions are a way of temporarily saving output.  The output of 'm4'
+can at any time be diverted to a temporary file, and be reinserted into
+the output stream, "undiverted", again at a later time.
+
+   Numbered diversions are counted from 0 upwards, diversion number 0
+being the normal output stream.  GNU 'm4' tries to keep diversions in
+memory.  However, there is a limit to the overall memory usable by all
+diversions taken together (512K, currently).  When this maximum is about
+to be exceeded, a temporary file is opened to receive the contents of
+the biggest diversion still in memory, freeing this memory for other
+diversions.  When creating the temporary file, 'm4' honors the value of
+the environment variable 'TMPDIR', and falls back to '/tmp'.  Thus, the
+amount of available disk space provides the only real limit on the
+number and aggregate size of diversions.
+
+   Diversions make it possible to generate output in a different order
+than the input was read.  It is possible to implement topological
+sorting dependencies.  For example, GNU Autoconf makes use of diversions
+under the hood to ensure that the expansion of a prerequisite macro
+appears in the output prior to the expansion of a dependent macro,
+regardless of which order the two macros were invoked in the user's
+input file.
+
+* Menu:
+
+* Divert::                      Diverting output
+* Undivert::                    Undiverting output
+* Divnum::                      Diversion numbers
+* Cleardivert::                 Discarding diverted text
+
+
+File: m4.info,  Node: Divert,  Next: Undivert,  Up: Diversions
+
+10.1 Diverting output
+=====================
+
+Output is diverted using 'divert':
+
+ -- Builtin: divert ([NUMBER = '0']
+     The current diversion is changed to NUMBER.  If NUMBER is left out
+     or empty, it is assumed to be zero.  If NUMBER cannot be parsed,
+     the diversion is unchanged.
+
+     The expansion of 'divert' is void.
+
+   When all the 'm4' input will have been processed, all existing
+diversions are automatically undiverted, in numerical order.
+
+     divert(`1')
+     This text is diverted.
+     divert
+     =>
+     This text is not diverted.
+     =>This text is not diverted.
+     ^D
+     =>
+     =>This text is diverted.
+
+   Several calls of 'divert' with the same argument do not overwrite the
+previous diverted text, but append to it.  Diversions are printed after
+any wrapped text is expanded.
+
+     define(`text', `TEXT')
+     =>
+     divert(`1')`diverted text.'
+     divert
+     =>
+     m4wrap(`Wrapped text precedes ')
+     =>
+     ^D
+     =>Wrapped TEXT precedes diverted text.
+
+   If output is diverted to a negative diversion, it is simply
+discarded.  This can be used to suppress unwanted output.  A common
+example of unwanted output is the trailing newlines after macro
+definitions.  Here is a common programming idiom in 'm4' for avoiding
+them.
+
+     divert(`-1')
+     define(`foo', `Macro `foo'.')
+     define(`bar', `Macro `bar'.')
+     divert
+     =>
+
+   Traditional implementations only supported ten diversions.  But as a
+GNU extension, diversion numbers can be as large as positive integers
+will allow, rather than treating a multi-digit diversion number as a
+request to discard text.
+
+     divert(eval(`1<<28'))world
+     divert(`2')hello
+     ^D
+     =>hello
+     =>world
+
+   Note that 'divert' is an English word, but also an active macro
+without arguments.  When processing plain text, the word might appear in
+normal text and be unintentionally swallowed as a macro invocation.  One
+way to avoid this is to use the '-P' option to rename all builtins
+(*note Invoking m4: Operation modes.).  Another is to write a wrapper
+that requires a parameter to be recognized.
+
+     We decided to divert the stream for irrigation.
+     =>We decided to  the stream for irrigation.
+     define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')')
+     =>
+     divert(`-1')
+     Ignored text.
+     divert(`0')
+     =>
+     We decided to divert the stream for irrigation.
+     =>We decided to divert the stream for irrigation.
+
+
+File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions
+
+10.2 Undiverting output
+=======================
+
+Diverted text can be undiverted explicitly using the builtin 'undivert':
+
+ -- Builtin: undivert ([DIVERSIONS...]
+     Undiverts the numeric DIVERSIONS given by the arguments, in the
+     order given.  If no arguments are supplied, all diversions are
+     undiverted, in numerical order.
+
+     As a GNU extension, DIVERSIONS may contain non-numeric strings,
+     which are treated as the names of files to copy into the output
+     without expansion.  A warning is issued if a file could not be
+     opened.
+
+     The expansion of 'undivert' is void.
+
+     divert(`1')
+     This text is diverted.
+     divert
+     =>
+     This text is not diverted.
+     =>This text is not diverted.
+     undivert(`1')
+     =>
+     =>This text is diverted.
+     =>
+
+   Notice the last two blank lines.  One of them comes from the newline
+following 'undivert', the other from the newline that followed the
+'divert'!  A diversion often starts with a blank line like this.
+
+   When diverted text is undiverted, it is _not_ reread by 'm4', but
+rather copied directly to the current output, and it is therefore not an
+error to undivert into a diversion.  Undiverting the empty string is the
+same as specifying diversion 0; in either case nothing happens since the
+output has already been flushed.
+
+     divert(`1')diverted text
+     divert
+     =>
+     undivert()
+     =>
+     undivert(`0')
+     =>
+     undivert
+     =>diverted text
+     =>
+     divert(`1')more
+     divert(`2')undivert(`1')diverted text`'divert
+     =>
+     undivert(`1')
+     =>
+     undivert(`2')
+     =>more
+     =>diverted text
+
+   When a diversion has been undiverted, the diverted text is discarded,
+and it is not possible to bring back diverted text more than once.
+
+     divert(`1')
+     This text is diverted first.
+     divert(`0')undivert(`1')dnl
+     =>
+     =>This text is diverted first.
+     undivert(`1')
+     =>
+     divert(`1')
+     This text is also diverted but not appended.
+     divert(`0')undivert(`1')dnl
+     =>
+     =>This text is also diverted but not appended.
+
+   Attempts to undivert the current diversion are silently ignored.
+Thus, when the current diversion is not 0, the current diversion does
+not get rearranged among the other diversions.
+
+     divert(`1')one
+     divert(`2')two
+     divert(`3')three
+     divert(`2')undivert`'dnl
+     divert`'undivert`'dnl
+     =>two
+     =>one
+     =>three
+
+   GNU 'm4' allows named files to be undiverted.  Given a non-numeric
+argument, the contents of the file named will be copied, uninterpreted,
+to the current output.  This complements the builtin 'include' (*note
+Include::).  To illustrate the difference, assume the file 'foo'
+contains:
+
+     $ cat foo
+     bar
+
+then
+
+     define(`bar', `BAR')
+     =>
+     undivert(`foo')
+     =>bar
+     =>
+     include(`foo')
+     =>BAR
+     =>
+
+   If the file is not found (or cannot be read), an error message is
+issued, and the expansion is void.  It is possible to intermix files and
+diversion numbers.
+
+     divert(`1')diversion one
+     divert(`2')undivert(`foo')dnl
+     divert(`3')diversion three
+     divert`'dnl
+     undivert(`1', `2', `foo', `3')dnl
+     =>diversion one
+     =>bar
+     =>bar
+     =>diversion three
+
+
+File: m4.info,  Node: Divnum,  Next: Cleardivert,  Prev: Undivert,  Up: Diversions
+
+10.3 Diversion numbers
+======================
+
+The current diversion is tracked by the builtin 'divnum':
+
+ -- Builtin: divnum
+     Expands to the number of the current diversion.
+
+     Initial divnum
+     =>Initial 0
+     divert(`1')
+     Diversion one: divnum
+     divert(`2')
+     Diversion two: divnum
+     ^D
+     =>
+     =>Diversion one: 1
+     =>
+     =>Diversion two: 2
+
+
+File: m4.info,  Node: Cleardivert,  Prev: Divnum,  Up: Diversions
+
+10.4 Discarding diverted text
+=============================
+
+Often it is not known, when output is diverted, whether the diverted
+text is actually needed.  Since all non-empty diversion are brought back
+on the main output stream when the end of input is seen, a method of
+discarding a diversion is needed.  If all diversions should be
+discarded, the easiest is to end the input to 'm4' with 'divert(`-1')'
+followed by an explicit 'undivert':
+
+     divert(`1')
+     Diversion one: divnum
+     divert(`2')
+     Diversion two: divnum
+     divert(`-1')
+     undivert
+     ^D
+
+No output is produced at all.
+
+   Clearing selected diversions can be done with the following macro:
+
+ -- Composite: cleardivert ([DIVERSIONS...]
+     Discard the contents of each of the listed numeric DIVERSIONS.
+
+     define(`cleardivert',
+     `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
+     =>
+
+   It is called just like 'undivert', but the effect is to clear the
+diversions, given by the arguments.  (This macro has a nasty bug!  You
+should try to see if you can find it and correct it; or *note Answers:
+Improved cleardivert.).
+
+
+File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top
+
+11 Macros for text handling
+***************************
+
+There are a number of builtins in 'm4' for manipulating text in various
+ways, extracting substrings, searching, substituting, and so on.
+
+* Menu:
+
+* Len::                         Calculating length of strings
+* Index macro::                 Searching for substrings
+* Regexp::                      Searching for regular expressions
+* Substr::                      Extracting substrings
+* Translit::                    Translating characters
+* Patsubst::                    Substituting text by regular expression
+* Format::                      Formatting strings (printf-like)
+
+
+File: m4.info,  Node: Len,  Next: Index macro,  Up: Text handling
+
+11.1 Calculating length of strings
+==================================
+
+The length of a string can be calculated by 'len':
+
+ -- Builtin: len (STRING)
+     Expands to the length of STRING, as a decimal number.
+
+     The macro 'len' is recognized only with parameters.
+
+     len()
+     =>0
+     len(`abcdef')
+     =>6
+
+
+File: m4.info,  Node: Index macro,  Next: Regexp,  Prev: Len,  Up: Text handling
+
+11.2 Searching for substrings
+=============================
+
+Searching for substrings is done with 'index':
+
+ -- Builtin: index (STRING, SUBSTRING)
+     Expands to the index of the first occurrence of SUBSTRING in
+     STRING.  The first character in STRING has index 0.  If SUBSTRING
+     does not occur in STRING, 'index' expands to '-1'.
+
+     The macro 'index' is recognized only with parameters.
+
+     index(`gnus, gnats, and armadillos', `nat')
+     =>7
+     index(`gnus, gnats, and armadillos', `dag')
+     =>-1
+
+   Omitting SUBSTRING evokes a warning, but still produces output;
+contrast this with an empty SUBSTRING.
+
+     index(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `index'
+     =>0
+     index(`abc', `')
+     =>0
+     index(`abc', `b')
+     =>1
+
+
+File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index macro,  Up: Text handling
+
+11.3 Searching for regular expressions
+======================================
+
+Searching for regular expressions is done with the builtin 'regexp':
+
+ -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT]
+     Searches for REGEXP in STRING.  The syntax for regular expressions
+     is the same as in GNU Emacs, which is similar to BRE, Basic Regular
+     Expressions in POSIX. *Note Syntax of Regular Expressions:
+     (emacs)Regexps.  Support for ERE, Extended Regular Expressions is
+     not available, but will be added in GNU M4 2.0.
+
+     If REPLACEMENT is omitted, 'regexp' expands to the index of the
+     first match of REGEXP in STRING.  If REGEXP does not match anywhere
+     in STRING, it expands to -1.
+
+     If REPLACEMENT is supplied, and there was a match, 'regexp' changes
+     the expansion to this argument, with '\N' substituted by the text
+     matched by the Nth parenthesized sub-expression of REGEXP, up to
+     nine sub-expressions.  The escape '\&' is replaced by the text of
+     the entire regular expression matched.  For all other characters,
+     '\' treats the next character literally.  A warning is issued if
+     there were fewer sub-expressions than the '\N' requested, or if
+     there is a trailing '\'.  If there was no match, 'regexp' expands
+     to the empty string.
+
+     The macro 'regexp' is recognized only with parameters.
+
+     regexp(`GNUs not Unix', `\<[a-z]\w+')
+     =>5
+     regexp(`GNUs not Unix', `\<Q\w*')
+     =>-1
+     regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
+     =>*** Unix *** nix ***
+     regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
+     =>
+
+   Here are some more examples on the handling of backslash:
+
+     regexp(`abc', `\(b\)', `\\\10\a')
+     =>\b0a
+     regexp(`abc', `b', `\1\')
+     error->m4:stdin:2: Warning: sub-expression 1 not present
+     error->m4:stdin:2: Warning: trailing \ ignored in replacement
+     =>
+     regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
+     error->m4:stdin:3: Warning: sub-expression 4 not present
+     error->m4:stdin:3: Warning: sub-expression 5 not present
+     error->m4:stdin:3: Warning: sub-expression 6 not present
+     =>c
+
+   Omitting REGEXP evokes a warning, but still produces output; contrast
+this with an empty REGEXP argument.
+
+     regexp(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `regexp'
+     =>0
+     regexp(`abc', `')
+     =>0
+     regexp(`abc', `', `\\def')
+     =>\def
+
+
+File: m4.info,  Node: Substr,  Next: Translit,  Prev: Regexp,  Up: Text handling
+
+11.4 Extracting substrings
+==========================
+
+Substrings are extracted with 'substr':
+
+ -- Builtin: substr (STRING, FROM, [LENGTH]
+     Expands to the substring of STRING, which starts at index FROM, and
+     extends for LENGTH characters, or to the end of STRING, if LENGTH
+     is omitted.  The starting index of a string is always 0.  The
+     expansion is empty if there is an error parsing FROM or LENGTH, if
+     FROM is beyond the end of STRING, or if LENGTH is negative.
+
+     The macro 'substr' is recognized only with parameters.
+
+     substr(`gnus, gnats, and armadillos', `6')
+     =>gnats, and armadillos
+     substr(`gnus, gnats, and armadillos', `6', `5')
+     =>gnats
+
+   Omitting FROM evokes a warning, but still produces output.
+
+     substr(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `substr'
+     =>abc
+     substr(`abc',)
+     error->m4:stdin:2: empty string treated as 0 in builtin `substr'
+     =>abc
+
+
+File: m4.info,  Node: Translit,  Next: Patsubst,  Prev: Substr,  Up: Text handling
+
+11.5 Translating characters
+===========================
+
+Character translation is done with 'translit':
+
+ -- Builtin: translit (STRING, CHARS, [REPLACEMENT]
+     Expands to STRING, with each character that occurs in CHARS
+     translated into the character from REPLACEMENT with the same index.
+
+     If REPLACEMENT is shorter than CHARS, the excess characters of
+     CHARS are deleted from the expansion; if CHARS is shorter, the
+     excess characters in REPLACEMENT are silently ignored.  If
+     REPLACEMENT is omitted, all characters in STRING that are present
+     in CHARS are deleted from the expansion.  If a character appears
+     more than once in CHARS, only the first instance is used in making
+     the translation.  Only a single translation pass is made, even if
+     characters in REPLACEMENT also appear in CHARS.
+
+     As a GNU extension, both CHARS and REPLACEMENT can contain
+     character-ranges, e.g., 'a-z' (meaning all lowercase letters) or
+     '0-9' (meaning all digits).  To include a dash '-' in CHARS or
+     REPLACEMENT, place it first or last in the entire string, or as the
+     last character of a range.  Back-to-back ranges can share a common
+     endpoint.  It is not an error for the last character in the range
+     to be 'larger' than the first.  In that case, the range runs
+     backwards, i.e., '9-0' means the string '9876543210'.  The
+     expansion of a range is dependent on the underlying encoding of
+     characters, so using ranges is not always portable between
+     machines.
+
+     The macro 'translit' is recognized only with parameters.
+
+     translit(`GNUs not Unix', `A-Z')
+     =>s not nix
+     translit(`GNUs not Unix', `a-z', `A-Z')
+     =>GNUS NOT UNIX
+     translit(`GNUs not Unix', `A-Z', `z-a')
+     =>tmfs not fnix
+     translit(`+,-12345', `+--1-5', `<;>a-c-a')
+     =><;>abcba
+     translit(`abcdef', `aabdef', `bcged')
+     =>bgced
+
+   In the ASCII encoding, the first example deletes all uppercase
+letters, the second converts lowercase to uppercase, and the third
+'mirrors' all uppercase letters, while converting them to lowercase.
+The two first cases are by far the most common, even though they are not
+portable to EBCDIC or other encodings.  The fourth example shows a range
+ending in '-', as well as back-to-back ranges.  The final example shows
+that 'a' is mapped to 'b', not 'c'; the resulting 'b' is not further
+remapped to 'g'; the 'd' and 'e' are swapped, and the 'f' is discarded.
+
+   Omitting CHARS evokes a warning, but still produces output.
+
+     translit(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `translit'
+     =>abc
+
+
+File: m4.info,  Node: Patsubst,  Next: Format,  Prev: Translit,  Up: Text handling
+
+11.6 Substituting text by regular expression
+============================================
+
+Global substitution in a string is done by 'patsubst':
+
+ -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT]
+     Searches STRING for matches of REGEXP, and substitutes REPLACEMENT
+     for each match.  The syntax for regular expressions is the same as
+     in GNU Emacs (*note Regexp::).
+
+     The parts of STRING that are not covered by any match of REGEXP are
+     copied to the expansion.  Whenever a match is found, the search
+     proceeds from the end of the match, so a character from STRING will
+     never be substituted twice.  If REGEXP matches a string of zero
+     length, the start position for the search is incremented, to avoid
+     infinite loops.
+
+     When a replacement is to be made, REPLACEMENT is inserted into the
+     expansion, with '\N' substituted by the text matched by the Nth
+     parenthesized sub-expression of PATSUBST, for up to nine
+     sub-expressions.  The escape '\&' is replaced by the text of the
+     entire regular expression matched.  For all other characters, '\'
+     treats the next character literally.  A warning is issued if there
+     were fewer sub-expressions than the '\N' requested, or if there is
+     a trailing '\'.
+
+     The REPLACEMENT argument can be omitted, in which case the text
+     matched by REGEXP is deleted.
+
+     The macro 'patsubst' is recognized only with parameters.
+
+     patsubst(`GNUs not Unix', `^', `OBS: ')
+     =>OBS: GNUs not Unix
+     patsubst(`GNUs not Unix', `\<', `OBS: ')
+     =>OBS: GNUs OBS: not OBS: Unix
+     patsubst(`GNUs not Unix', `\w*', `(\&)')
+     =>(GNUs)() (not)() (Unix)()
+     patsubst(`GNUs not Unix', `\w+', `(\&)')
+     =>(GNUs) (not) (Unix)
+     patsubst(`GNUs not Unix', `[A-Z][a-z]+')
+     =>GN not 
+     patsubst(`GNUs not Unix', `not', `NOT\')
+     error->m4:stdin:6: Warning: trailing \ ignored in replacement
+     =>GNUs NOT Unix
+
+   Here is a slightly more realistic example, which capitalizes
+individual words or whole sentences, by substituting calls of the macros
+'upcase' and 'downcase' into the strings.
+
+ -- Composite: upcase (TEXT)
+ -- Composite: downcase (TEXT)
+ -- Composite: capitalize (TEXT)
+     Expand to TEXT, but with capitalization changed: 'upcase' changes
+     all letters to upper case, 'downcase' changes all letters to lower
+     case, and 'capitalize' changes the first character of each word to
+     upper case and the remaining characters to lower case.
+
+   First, an example of their usage, using implementations distributed
+in 'm4-1.4.17/examples/capitalize.m4'.
+
+     $ m4 -I examples
+     include(`capitalize.m4')
+     =>
+     upcase(`GNUs not Unix')
+     =>GNUS NOT UNIX
+     downcase(`GNUs not Unix')
+     =>gnus not unix
+     capitalize(`GNUs not Unix')
+     =>Gnus Not Unix
+
+   Now for the implementation.  There is a helper macro '_capitalize'
+which puts only its first word in mixed case.  Then 'capitalize' merely
+parses out the words, and replaces them with an invocation of
+'_capitalize'.  (As presented here, the 'capitalize' macro has some
+subtle flaws.  You should try to see if you can find and correct them;
+or *note Answers: Improved capitalize.).
+
+     $ m4 -I examples
+     undivert(`capitalize.m4')dnl
+     =>divert(`-1')
+     =># upcase(text)
+     =># downcase(text)
+     =># capitalize(text)
+     =>#   change case of text, simple version
+     =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
+     =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
+     =>define(`_capitalize',
+     =>       `regexp(`$1', `^\(\w\)\(\w*\)',
+     =>               `upcase(`\1')`'downcase(`\2')')')
+     =>define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')')
+     =>divert`'dnl
+
+   While 'regexp' replaces the whole input with the replacement as soon
+as there is a match, 'patsubst' replaces each _occurrence_ of a match
+and preserves non-matching pieces:
+
+     define(`patreg',
+     `patsubst($@)
+     regexp($@)')dnl
+     patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
+     =>bar FOO baz FOO
+     =>FOO
+     patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
+     =>bab abb 212
+     =>bab
+
+   Omitting REGEXP evokes a warning, but still produces output; contrast
+this with an empty REGEXP argument.
+
+     patsubst(`abc')
+     error->m4:stdin:1: Warning: too few arguments to builtin `patsubst'
+     =>abc
+     patsubst(`abc', `')
+     =>abc
+     patsubst(`abc', `', `\\-')
+     =>\-a\-b\-c\-
+
+
+File: m4.info,  Node: Format,  Prev: Patsubst,  Up: Text handling
+
+11.7 Formatting strings (printf-like)
+=====================================
+
+Formatted output can be made with 'format':
+
+ -- Builtin: format (FORMAT-STRING, ...)
+     Works much like the C function 'printf'.  The first argument
+     FORMAT-STRING can contain '%' specifications which are satisfied by
+     additional arguments, and the expansion of 'format' is the
+     formatted string.
+
+     The macro 'format' is recognized only with parameters.
+
+   Its use is best described by a few examples:
+
+     define(`foo', `The brown fox jumped over the lazy dog')
+     =>
+     format(`The string "%s" uses %d characters', foo, len(foo))
+     =>The string "The brown fox jumped over the lazy dog" uses 38 characters
+     format(`%*.*d', `-1', `-1', `1')
+     =>1
+     format(`%.0f', `56789.9876')
+     =>56790
+     len(format(`%-*X', `5000', `1'))
+     =>5000
+     ifelse(format(`%010F', `infinity'), `       INF', `success',
+            format(`%010F', `infinity'), `  INFINITY', `success',
+            format(`%010F', `infinity'))
+     =>success
+     ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
+            format(`%.1A', `1.999'), `0X2.0P+0', `success',
+            format(`%.1A', `1.999'))
+     =>success
+     format(`%g', `0xa.P+1')
+     =>20
+
+   Using the 'forloop' macro defined earlier (*note Forloop::), this
+example shows how 'format' can be used to produce tabular output.
+
+     $ m4 -I examples
+     include(`forloop.m4')
+     =>
+     forloop(`i', `1', `10', `format(`%6d squared is %10d
+     ', i, eval(i**2))')
+     =>     1 squared is          1
+     =>     2 squared is          4
+     =>     3 squared is          9
+     =>     4 squared is         16
+     =>     5 squared is         25
+     =>     6 squared is         36
+     =>     7 squared is         49
+     =>     8 squared is         64
+     =>     9 squared is         81
+     =>    10 squared is        100
+     =>
+
+   The builtin 'format' is modeled after the ANSI C 'printf' function,
+and supports these '%' specifiers: 'c', 's', 'd', 'o', 'x', 'X', 'u',
+'a', 'A', 'e', 'E', 'f', 'F', 'g', 'G', and '%'; it supports field
+widths and precisions, and the flags '+', '-', ' ', '0', '#', and '''.
+For integer specifiers, the width modifiers 'hh', 'h', and 'l' are
+recognized, and for floating point specifiers, the width modifier 'l' is
+recognized.  Items not yet supported include positional arguments, the
+'n', 'p', 'S', and 'C' specifiers, the 'z', 't', 'j', 'L' and 'll'
+modifiers, and any platform extensions available in the native 'printf'.
+For more details on the functioning of 'printf', see the C Library
+Manual, or the POSIX specification (for example, '%a' is supported even
+on platforms that haven't yet implemented C99 hexadecimal floating point
+output natively).
+
+   Unrecognized specifiers result in a warning.  It is anticipated that
+a future release of GNU 'm4' will support more specifiers, and give
+better warnings when various problems such as overflow are encountered.
+Likewise, escape sequences are not yet recognized.
+
+     format(`%p', `0')
+     error->m4:stdin:1: Warning: unrecognized specifier in `%p'
+     =>
+
+
+File: m4.info,  Node: Arithmetic,  Next: Shell commands,  Prev: Text handling,  Up: Top
+
+12 Macros for doing arithmetic
+******************************
+
+Integer arithmetic is included in 'm4', with a C-like syntax.  As
+convenient shorthands, there are builtins for simple increment and
+decrement operations.
+
+* Menu:
+
+* Incr::                        Decrement and increment operators
+* Eval::                        Evaluating integer expressions
+
+
+File: m4.info,  Node: Incr,  Next: Eval,  Up: Arithmetic
+
+12.1 Decrement and increment operators
+======================================
+
+Increment and decrement of integers are supported using the builtins
+'incr' and 'decr':
+
+ -- Builtin: incr (NUMBER)
+ -- Builtin: decr (NUMBER)
+     Expand to the numerical value of NUMBER, incremented or
+     decremented, respectively, by one.  Except for the empty string,
+     the expansion is empty if NUMBER could not be parsed.
+
+     The macros 'incr' and 'decr' are recognized only with parameters.
+
+     incr(`4')
+     =>5
+     decr(`7')
+     =>6
+     incr()
+     error->m4:stdin:3: empty string treated as 0 in builtin `incr'
+     =>1
+     decr()
+     error->m4:stdin:4: empty string treated as 0 in builtin `decr'
+     =>-1
+
+
+File: m4.info,  Node: Eval,  Prev: Incr,  Up: Arithmetic
+
+12.2 Evaluating integer expressions
+===================================
+
+Integer expressions are evaluated with 'eval':
+
+ -- Builtin: eval (EXPRESSION, [RADIX = '10']
+     Expands to the value of EXPRESSION.  The expansion is empty if a
+     problem is encountered while parsing the arguments.  If specified,
+     RADIX and WIDTH control the format of the output.
+
+     Calculations are done with 32-bit signed numbers.  Overflow
+     silently results in wraparound.  A warning is issued if division by
+     zero is attempted, or if EXPRESSION could not be parsed.
+
+     Expressions can contain the following operators, listed in order of
+     decreasing precedence.
+
+     '()'
+          Parentheses
+     '+ - ~ !'
+          Unary plus and minus, and bitwise and logical negation
+     '**'
+          Exponentiation
+     '* / %'
+          Multiplication, division, and modulo
+     '+ -'
+          Addition and subtraction
+     '<< >>'
+          Shift left or right
+     '> >= < <='
+          Relational operators
+     '== !='
+          Equality operators
+     '&'
+          Bitwise and
+     '^'
+          Bitwise exclusive-or
+     '|'
+          Bitwise or
+     '&&'
+          Logical and
+     '||'
+          Logical or
+
+     The macro 'eval' is recognized only with parameters.
+
+   All binary operators, except exponentiation, are left associative.  C
+operators that perform variable assignment, such as '+=' or '--', are
+not implemented, since 'eval' only operates on constants, not variables.
+Attempting to use them results in an error.  However, since traditional
+implementations treated '=' as an undocumented alias for '==' as opposed
+to an assignment operator, this usage is supported as a special case.
+Be aware that a future version of GNU M4 may support assignment
+semantics as an extension when POSIX mode is not requested, and that
+using '=' to check equality is not portable.
+
+     eval(`2 = 2')
+     error->m4:stdin:1: Warning: recommend ==, not =, for equality operator
+     =>1
+     eval(`++0')
+     error->m4:stdin:2: invalid operator in eval: ++0
+     =>
+     eval(`0 |= 1')
+     error->m4:stdin:3: invalid operator in eval: 0 |= 1
+     =>
+
+   Note that some older 'm4' implementations use '^' as an alternate
+operator for the exponentiation, although POSIX requires the C behavior
+of bitwise exclusive-or.  The precedence of the negation operators, '~'
+and '!', was traditionally lower than equality.  The unary operators
+could not be used reliably more than once on the same term without
+intervening parentheses.  The traditional precedence of the equality
+operators '==' and '!=' was identical instead of lower than the
+relational operators such as '<', even through GNU M4 1.4.8.  Starting
+with version 1.4.9, GNU M4 correctly follows POSIX precedence rules.  M4
+scripts designed to be portable between releases must be aware that
+parentheses may be required to enforce C precedence rules.  Likewise,
+division by zero, even in the unused branch of a short-circuiting
+operator, is not always well-defined in other implementations.
+
+   Following are some examples where the current version of M4 follows C
+precedence rules, but where older versions and some other
+implementations of 'm4' require explicit parentheses to get the correct
+result:
+
+     eval(`1 == 2 > 0')
+     =>1
+     eval(`(1 == 2) > 0')
+     =>0
+     eval(`! 0 * 2')
+     =>2
+     eval(`! (0 * 2)')
+     =>1
+     eval(`1 | 1 ^ 1')
+     =>1
+     eval(`(1 | 1) ^ 1')
+     =>0
+     eval(`+ + - ~ ! ~ 0')
+     =>1
+     eval(`2 || 1 / 0')
+     =>1
+     eval(`0 || 1 / 0')
+     error->m4:stdin:9: divide by zero in eval: 0 || 1 / 0
+     =>
+     eval(`0 && 1 % 0')
+     =>0
+     eval(`2 && 1 % 0')
+     error->m4:stdin:11: modulo by zero in eval: 2 && 1 % 0
+     =>
+
+   As a GNU extension, the operator '**' performs integral
+exponentiation.  The operator is right-associative, and if evaluated,
+the exponent must be non-negative, and at least one of the arguments
+must be non-zero, or a warning is issued.
+
+     eval(`2 ** 3 ** 2')
+     =>512
+     eval(`(2 ** 3) ** 2')
+     =>64
+     eval(`0 ** 1')
+     =>0
+     eval(`2 ** 0')
+     =>1
+     eval(`0 ** 0')
+     =>
+     error->m4:stdin:5: divide by zero in eval: 0 ** 0
+     eval(`4 ** -2')
+     error->m4:stdin:6: negative exponent in eval: 4 ** -2
+     =>
+
+   Within EXPRESSION, (but not RADIX or WIDTH), numbers without a
+special prefix are decimal.  A simple '0' prefix introduces an octal
+number.  '0x' introduces a hexadecimal number.  As GNU extensions, '0b'
+introduces a binary number.  '0r' introduces a number expressed in any
+radix between 1 and 36: the prefix should be immediately followed by the
+decimal expression of the radix, a colon, then the digits making the
+number.  For radix 1, leading zeros are ignored, and all remaining
+digits must be '1'; for all other radices, the digits are '0', '1', '2',
+....  Beyond '9', the digits are 'a', 'b' ... up to 'z'.  Lower and
+upper case letters can be used interchangeably in numbers prefixes and
+as number digits.
+
+   Parentheses may be used to group subexpressions whenever needed.  For
+the relational operators, a true relation returns '1', and a false
+relation return '0'.
+
+   Here are a few examples of use of 'eval'.
+
+     eval(`-3 * 5')
+     =>-15
+     eval(`-99 / 10')
+     =>-9
+     eval(`-99 % 10')
+     =>-9
+     eval(`99 % -10')
+     =>9
+     eval(index(`Hello world', `llo') >= 0)
+     =>1
+     eval(`0r1:0111 + 0b100 + 0r3:12')
+     =>12
+     define(`square', `eval(`($1) ** 2')')
+     =>
+     square(`9')
+     =>81
+     square(square(`5')` + 1')
+     =>676
+     define(`foo', `666')
+     =>
+     eval(`foo / 6')
+     error->m4:stdin:11: bad expression in eval: foo / 6
+     =>
+     eval(foo / 6)
+     =>111
+
+   As the last two lines show, 'eval' does not handle macro names, even
+if they expand to a valid expression (or part of a valid expression).
+Therefore all macros must be expanded before they are passed to 'eval'.
+
+   Some calculations are not portable to other implementations, since
+they have undefined semantics in C, but GNU 'm4' has well-defined
+behavior on overflow.  When shifting, an out-of-range shift amount is
+implicitly brought into the range of 32-bit signed integers using an
+implicit bit-wise and with 0x1f).
+
+     define(`max_int', eval(`0x7fffffff'))
+     =>
+     define(`min_int', incr(max_int))
+     =>
+     eval(min_int` < 0')
+     =>1
+     eval(max_int` > 0')
+     =>1
+     ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
+     =>overflow occurred
+     min_int
+     =>-2147483648
+     eval(`0x80000000 % -1')
+     =>0
+     eval(`-4 >> 1')
+     =>-2
+     eval(`-4 >> 33')
+     =>-2
+
+   If RADIX is specified, it specifies the radix to be used in the
+expansion.  The default radix is 10; this is also the case if RADIX is
+the empty string.  A warning results if the radix is outside the range
+of 1 through 36, inclusive.  The result of 'eval' is always taken to be
+signed.  No radix prefix is output, and for radices greater than 10, the
+digits are lower case.  The WIDTH argument specifies the minimum output
+width, excluding any negative sign.  The result is zero-padded to extend
+the expansion to the requested width.  A warning results if the width is
+negative.  If RADIX or WIDTH is out of bounds, the expansion of 'eval'
+is empty.
+
+     eval(`666', `10')
+     =>666
+     eval(`666', `11')
+     =>556
+     eval(`666', `6')
+     =>3030
+     eval(`666', `6', `10')
+     =>0000003030
+     eval(`-666', `6', `10')
+     =>-0000003030
+     eval(`10', `', `0')
+     =>10
+     `0r1:'eval(`10', `1', `11')
+     =>0r1:01111111111
+     eval(`10', `16')
+     =>a
+     eval(`1', `37')
+     error->m4:stdin:9: radix 37 in builtin `eval' out of range
+     =>
+     eval(`1', , `-1')
+     error->m4:stdin:10: negative width to builtin `eval'
+     =>
+     eval()
+     error->m4:stdin:11: empty string treated as 0 in builtin `eval'
+     =>0
+
+
+File: m4.info,  Node: Shell commands,  Next: Miscellaneous,  Prev: Arithmetic,  Up: Top
+
+13 Macros for running shell commands
+************************************
+
+There are a few builtin macros in 'm4' that allow you to run shell
+commands from within 'm4'.
+
+   Note that the definition of a valid shell command is system
+dependent.  On UNIX systems, this is the typical '/bin/sh'.  But on
+other systems, such as native Windows, the shell has a different syntax
+of commands that it understands.  Some examples in this chapter assume
+'/bin/sh', and also demonstrate how to quit early with a known exit
+value if this is not the case.
+
+* Menu:
+
+* Platform macros::             Determining the platform
+* Syscmd::                      Executing simple commands
+* Esyscmd::                     Reading the output of commands
+* Sysval::                      Exit status
+* Mkstemp::                     Making temporary files
+
+
+File: m4.info,  Node: Platform macros,  Next: Syscmd,  Up: Shell commands
+
+13.1 Determining the platform
+=============================
+
+Sometimes it is desirable for an input file to know which platform 'm4'
+is running on.  GNU 'm4' provides several macros that are predefined to
+expand to the empty string; checking for their existence will confirm
+platform details.
+
+ -- Optional builtin: __gnu__
+ -- Optional builtin: __os2__
+ -- Optional builtin: os2
+ -- Optional builtin: __unix__
+ -- Optional builtin: unix
+ -- Optional builtin: __windows__
+ -- Optional builtin: windows
+     Each of these macros is conditionally defined as needed to describe
+     the environment of 'm4'.  If defined, each macro expands to the
+     empty string.  For now, these macros silently ignore all arguments,
+     but in a future release of M4, they might warn if arguments are
+     present.
+
+   When GNU extensions are in effect (that is, when you did not use the
+'-G' option, *note Invoking m4: Limits control.), GNU 'm4' will define
+the macro '__gnu__' to expand to the empty string.
+
+     $ m4
+     __gnu__
+     =>
+     __gnu__(`ignored')
+     =>
+     Extensions are ifdef(`__gnu__', `active', `inactive')
+     =>Extensions are active
+
+     $ m4 -G
+     __gnu__
+     =>__gnu__
+     __gnu__(`ignored')
+     =>__gnu__(ignored)
+     Extensions are ifdef(`__gnu__', `active', `inactive')
+     =>Extensions are inactive
+
+   On UNIX systems, GNU 'm4' will define '__unix__' by default, or
+'unix' when the '-G' option is specified.
+
+   On native Windows systems, GNU 'm4' will define '__windows__' by
+default, or 'windows' when the '-G' option is specified.
+
+   On OS/2 systems, GNU 'm4' will define '__os2__' by default, or 'os2'
+when the '-G' option is specified.
+
+   If GNU 'm4' does not provide a platform macro for your system, please
+report that as a bug.
+
+     define(`provided', `0')
+     =>
+     ifdef(`__unix__', `define(`provided', incr(provided))')
+     =>
+     ifdef(`__windows__', `define(`provided', incr(provided))')
+     =>
+     ifdef(`__os2__', `define(`provided', incr(provided))')
+     =>
+     provided
+     =>1
+
+
+File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: Platform macros,  Up: Shell commands
+
+13.2 Executing simple commands
+==============================
+
+Any shell command can be executed, using 'syscmd':
+
+ -- Builtin: syscmd (SHELL-COMMAND)
+     Executes SHELL-COMMAND as a shell command.
+
+     The expansion of 'syscmd' is void, _not_ the output from
+     SHELL-COMMAND!  Output or error messages from SHELL-COMMAND are not
+     read by 'm4'.  *Note Esyscmd::, if you need to process the command
+     output.
+
+     Prior to executing the command, 'm4' flushes its buffers.  The
+     default standard input, output and error of SHELL-COMMAND are the
+     same as those of 'm4'.
+
+     By default, the SHELL-COMMAND will be used as the argument to the
+     '-c' option of the '/bin/sh' shell (or the version of 'sh'
+     specified by 'command -p getconf PATH', if your system supports
+     that).  If you prefer a different shell, the 'configure' script can
+     be given the option '--with-syscmd-shell=LOCATION' to set the
+     location of an alternative shell at GNU 'm4' installation; the
+     alternative shell must still support '-c'.
+
+     The macro 'syscmd' is recognized only with parameters.
+
+     define(`foo', `FOO')
+     =>
+     syscmd(`echo foo')
+     =>foo
+     =>
+
+   Note how the expansion of 'syscmd' keeps the trailing newline of the
+command, as well as using the newline that appeared after the macro.
+
+   The following is an example of SHELL-COMMAND using the same standard
+input as 'm4':
+
+     $ echo "m4wrap(\`syscmd(\`cat')')" | m4
+     =>
+
+   It tells 'm4' to read all of its input before executing the wrapped
+text, then hand a valid (albeit emptied) pipe as standard input for the
+'cat' subcommand.  Therefore, you should be careful when using standard
+input (either by specifying no files, or by passing '-' as a file name
+on the command line, *note Invoking m4: Command line files.), and also
+invoking subcommands via 'syscmd' or 'esyscmd' that consume data from
+standard input.  When standard input is a seekable file, the subprocess
+will pick up with the next character not yet processed by 'm4'; when it
+is a pipe or other non-seekable file, there is no guarantee how much
+data will already be buffered by 'm4' and thus unavailable to the child.
+
+
+File: m4.info,  Node: Esyscmd,  Next: Sysval,  Prev: Syscmd,  Up: Shell commands
+
+13.3 Reading the output of commands
+===================================
+
+If you want 'm4' to read the output of a shell command, use 'esyscmd':
+
+ -- Builtin: esyscmd (SHELL-COMMAND)
+     Expands to the standard output of the shell command SHELL-COMMAND.
+
+     Prior to executing the command, 'm4' flushes its buffers.  The
+     default standard input and standard error of SHELL-COMMAND are the
+     same as those of 'm4'.  The error output of SHELL-COMMAND is not a
+     part of the expansion: it will appear along with the error output
+     of 'm4'.
+
+     By default, the SHELL-COMMAND will be used as the argument to the
+     '-c' option of the '/bin/sh' shell (or the version of 'sh'
+     specified by 'command -p getconf PATH', if your system supports
+     that).  If you prefer a different shell, the 'configure' script can
+     be given the option '--with-syscmd-shell=LOCATION' to set the
+     location of an alternative shell at GNU 'm4' installation; the
+     alternative shell must still support '-c'.
+
+     The macro 'esyscmd' is recognized only with parameters.
+
+     define(`foo', `FOO')
+     =>
+     esyscmd(`echo foo')
+     =>FOO
+     =>
+
+   Note how the expansion of 'esyscmd' keeps the trailing newline of the
+command, as well as using the newline that appeared after the macro.
+
+   Just as with 'syscmd', care must be exercised when sharing standard
+input between 'm4' and the child process of 'esyscmd'.
+
+
+File: m4.info,  Node: Sysval,  Next: Mkstemp,  Prev: Esyscmd,  Up: Shell commands
+
+13.4 Exit status
+================
+
+To see whether a shell command succeeded, use 'sysval':
+
+ -- Builtin: sysval
+     Expands to the exit status of the last shell command run with
+     'syscmd' or 'esyscmd'.  Expands to 0 if no command has been run
+     yet.
+
+     sysval
+     =>0
+     syscmd(`false')
+     =>
+     ifelse(sysval, `0', `zero', `non-zero')
+     =>non-zero
+     syscmd(`exit 2')
+     =>
+     sysval
+     =>2
+     syscmd(`true')
+     =>
+     sysval
+     =>0
+     esyscmd(`false')
+     =>
+     ifelse(sysval, `0', `zero', `non-zero')
+     =>non-zero
+     esyscmd(`echo dnl && exit 127')
+     =>
+     sysval
+     =>127
+     esyscmd(`true')
+     =>
+     sysval
+     =>0
+
+   'sysval' results in 127 if there was a problem executing the command,
+for example, if the system-imposed argument length is exceeded, or if
+there were not enough resources to fork.  It is not possible to
+distinguish between failed execution and successful execution that had
+an exit status of 127, unless there was output from the child process.
+
+   On UNIX platforms, where it is possible to detect when command
+execution is terminated by a signal, rather than a normal exit, the
+result is the signal number shifted left by eight bits.
+
+     dnl This test assumes kill is a shell builtin, and that signals are
+     dnl recognizable.
+     ifdef(`__unix__', ,
+           `errprint(` skipping: syscmd does not have unix semantics
+     ')m4exit(`77')')dnl
+     syscmd(`kill -9 $$')
+     =>
+     sysval
+     =>2304
+     syscmd()
+     =>
+     sysval
+     =>0
+     esyscmd(`kill -9 $$')
+     =>
+     sysval
+     =>2304
+
+
+File: m4.info,  Node: Mkstemp,  Prev: Sysval,  Up: Shell commands
+
+13.5 Making temporary files
+===========================
+
+Commands specified to 'syscmd' or 'esyscmd' might need a temporary file,
+for output or for some other purpose.  There is a builtin macro,
+'mkstemp', for making a temporary file:
+
+ -- Builtin: mkstemp (TEMPLATE)
+ -- Builtin: maketemp (TEMPLATE)
+     Expands to the quoted name of a new, empty file, made from the
+     string TEMPLATE, which should end with the string 'XXXXXX'.  The
+     six 'X' characters are then replaced with random characters
+     matching the regular expression '[a-zA-Z0-9._-]', in order to make
+     the file name unique.  If fewer than six 'X' characters are found
+     at the end of 'template', the result will be longer than the
+     template.  The created file will have access permissions as if by
+     'chmod =rw,go=', meaning that the current umask of the 'm4' process
+     is taken into account, and at most only the current user can read
+     and write the file.
+
+     The traditional behavior, standardized by POSIX, is that 'maketemp'
+     merely replaces the trailing 'X' with the process id, without
+     creating a file or quoting the expansion, and without ensuring that
+     the resulting string is a unique file name.  In part, this means
+     that using the same TEMPLATE twice in the same input file will
+     result in the same expansion.  This behavior is a security hole, as
+     it is very easy for another process to guess the name that will be
+     generated, and thus interfere with a subsequent use of 'syscmd'
+     trying to manipulate that file name.  Hence, POSIX has recommended
+     that all new implementations of 'm4' provide the secure 'mkstemp'
+     builtin, and that users of 'm4' check for its existence.
+
+     The expansion is void and an error issued if a temporary file could
+     not be created.
+
+     The macros 'mkstemp' and 'maketemp' are recognized only with
+     parameters.
+
+   If you try this next example, you will most likely get different
+output for the two file names, since the replacement characters are
+randomly chosen:
+
+     $ m4
+     define(`tmp', `oops')
+     =>
+     maketemp(`/tmp/fooXXXXXX')
+     =>/tmp/fooa07346
+     ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
+           `define(`mkstemp', defn(`maketemp'))dnl
+     errprint(`warning: potentially insecure maketemp implementation
+     ')')
+     =>
+     mkstemp(`doc')
+     =>docQv83Uw
+
+   Unless you use the '--traditional' command line option (or '-G',
+*note Invoking m4: Limits control.), the GNU version of 'maketemp' is
+secure.  This means that using the same template to multiple calls will
+generate multiple files.  However, we recommend that you use the new
+'mkstemp' macro, introduced in GNU M4 1.4.8, which is secure even in
+traditional mode.  Also, as of M4 1.4.11, the secure implementation
+quotes the resulting file name, so that you are guaranteed to know what
+file was created even if the random file name happens to match an
+existing macro.  Notice that this example is careful to use 'defn' to
+avoid unintended expansion of 'foo'.
+
+     $ m4
+     define(`foo', `errprint(`oops')')
+     =>
+     syscmd(`rm -f foo-??????')sysval
+     =>0
+     define(`file1', maketemp(`foo-XXXXXX'))dnl
+     ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ',
+            `no file', `created')
+     =>created
+     define(`file2', maketemp(`foo-XX'))dnl
+     define(`file3', mkstemp(`foo-XXXXXX'))dnl
+     ifelse(len(defn(`file1')), len(defn(`file2')),
+            `same length', `different')
+     =>same length
+     ifelse(defn(`file1'), defn(`file2'), `same', `different file')
+     =>different file
+     ifelse(defn(`file2'), defn(`file3'), `same', `different file')
+     =>different file
+     ifelse(defn(`file1'), defn(`file3'), `same', `different file')
+     =>different file
+     syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3'))
+     =>
+     sysval
+     =>0
+
+
+File: m4.info,  Node: Miscellaneous,  Next: Frozen files,  Prev: Shell commands,  Up: Top
+
+14 Miscellaneous builtin macros
+*******************************
+
+This chapter describes various builtins, that do not really belong in
+any of the previous chapters.
+
+* Menu:
+
+* Errprint::                    Printing error messages
+* Location::                    Printing current location
+* M4exit::                      Exiting from 'm4'
+
+
+File: m4.info,  Node: Errprint,  Next: Location,  Up: Miscellaneous
+
+14.1 Printing error messages
+============================
+
+You can print error messages using 'errprint':
+
+ -- Builtin: errprint (MESSAGE, ...)
+     Prints MESSAGE and the rest of the arguments to standard error,
+     separated by spaces.  Standard error is used, regardless of the
+     '--debugfile' option (*note Invoking m4: Debugging options.).
+
+     The expansion of 'errprint' is void.  The macro 'errprint' is
+     recognized only with parameters.
+
+     errprint(`Invalid arguments to forloop
+     ')
+     error->Invalid arguments to forloop
+     =>
+     errprint(`1')errprint(`2',`3
+     ')
+     error->12 3
+     =>
+
+   A trailing newline is _not_ printed automatically, so it should be
+supplied as part of the argument, as in the example.  Unfortunately, the
+exact output of 'errprint' is not very portable to other 'm4'
+implementations: POSIX requires that all arguments be printed, but some
+implementations of 'm4' only print the first.  Furthermore, some BSD
+implementations always append a newline for each 'errprint' call,
+regardless of whether the last argument already had one, and POSIX is
+silent on whether this is acceptable.
+
+
+File: m4.info,  Node: Location,  Next: M4exit,  Prev: Errprint,  Up: Miscellaneous
+
+14.2 Printing current location
+==============================
+
+To make it possible to specify the location of an error, three utility
+builtins exist:
+
+ -- Builtin: __file__
+ -- Builtin: __line__
+ -- Builtin: __program__
+     Expand to the quoted name of the current input file, the current
+     input line number in that file, and the quoted name of the current
+     invocation of 'm4'.
+
+     errprint(__program__:__file__:__line__: `input error
+     ')
+     error->m4:stdin:1: input error
+     =>
+
+   Line numbers start at 1 for each file.  If the file was found due to
+the '-I' option or 'M4PATH' environment variable, that is reflected in
+the file name.  The syncline option ('-s', *note Invoking m4:
+Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (*note
+Debug Levels::), also use this notion of current file and line.
+Redefining the three location macros has no effect on syncline, debug,
+warning, or error message output.
+
+   This example reuses the file 'incl.m4' mentioned earlier (*note
+Include::):
+
+     $ m4 -I examples
+     define(`foo', ``$0' called at __file__:__line__')
+     =>
+     foo
+     =>foo called at stdin:2
+     include(`incl.m4')
+     =>Include file start
+     =>foo called at examples/incl.m4:2
+     =>Include file end
+     =>
+
+   The location of macros invoked during the rescanning of macro
+expansion text corresponds to the location in the file where the
+expansion was triggered, regardless of how many newline characters the
+expansion text contains.  As of GNU M4 1.4.8, the location of text
+wrapped with 'm4wrap' (*note M4wrap::) is the point at which the
+'m4wrap' was invoked.  Previous versions, however, behaved as though
+wrapped text came from line 0 of the file "".
+
+     define(`echo', `$@')
+     =>
+     define(`foo', `echo(__line__
+     __line__)')
+     =>
+     echo(__line__
+     __line__)
+     =>4
+     =>5
+     m4wrap(`foo
+     ')
+     =>
+     foo(errprint(__line__
+     __line__
+     ))
+     error->8
+     error->9
+     =>8
+     =>8
+     __line__
+     =>11
+     m4wrap(`__line__
+     ')
+     =>
+     ^D
+     =>12
+     =>6
+     =>6
+
+   The '__program__' macro behaves like '$0' in shell terminology.  If
+you invoke 'm4' through an absolute path or a link with a different
+spelling, rather than by relying on a 'PATH' search for plain 'm4', it
+will affect how '__program__' expands.  The intent is that you can use
+it to produce error messages with the same formatting that 'm4' produces
+internally.  It can also be used within 'syscmd' (*note Syscmd::) to
+pick the same version of 'm4' that is currently running, rather than
+whatever version of 'm4' happens to be first in 'PATH'.  It was first
+introduced in GNU M4 1.4.6.
+
+
+File: m4.info,  Node: M4exit,  Prev: Location,  Up: Miscellaneous
+
+14.3 Exiting from 'm4'
+======================
+
+If you need to exit from 'm4' before the entire input has been read, you
+can use 'm4exit':
+
+ -- Builtin: m4exit ([CODE = '0']
+     Causes 'm4' to exit, with exit status CODE.  If CODE is left out,
+     the exit status is zero.  If CODE cannot be parsed, or is outside
+     the range of 0 to 255, the exit status is one.  No further input is
+     read, and all wrapped and diverted text is discarded.
+
+     m4wrap(`This text is lost due to `m4exit'.')
+     =>
+     divert(`1') So is this.
+     divert
+     =>
+     m4exit And this is never read.
+
+   A common use of this is to abort processing:
+
+ -- Composite: fatal_error (MESSAGE)
+     Abort processing with an error message and non-zero status.  Prefix
+     MESSAGE with details about where the error occurred, and print the
+     resulting string to standard error.
+
+     define(`fatal_error',
+            `errprint(__program__:__file__:__line__`: fatal error: $*
+     ')m4exit(`1')')
+     =>
+     fatal_error(`this is a BAD one, buster')
+     error->m4:stdin:4: fatal error: this is a BAD one, buster
+
+   After this macro call, 'm4' will exit with exit status 1.  This macro
+is only intended for error exits, since the normal exit procedures are
+not followed, i.e., diverted text is not undiverted, and saved text
+(*note M4wrap::) is not reread.  (This macro could be made more robust
+to earlier versions of 'm4'.  You should try to see if you can find
+weaknesses and correct them; or *note Answers: Improved fatal_error.).
+
+   Note that it is still possible for the exit status to be different
+than what was requested by 'm4exit'.  If 'm4' detects some other error,
+such as a write error on standard output, the exit status will be
+non-zero even if 'm4exit' requested zero.
+
+   If standard input is seekable, then the file will be positioned at
+the next unread character.  If it is a pipe or other non-seekable file,
+then there are no guarantees how much data 'm4' might have read into
+buffers, and thus discarded.
+
+
+File: m4.info,  Node: Frozen files,  Next: Compatibility,  Prev: Miscellaneous,  Up: Top
+
+15 Fast loading of frozen state
+*******************************
+
+Some bigger 'm4' applications may be built over a common base containing
+hundreds of definitions and other costly initializations.  Usually, the
+common base is kept in one or more declarative files, which files are
+listed on each 'm4' invocation prior to the user's input file, or else
+each input file uses 'include'.
+
+   Reading the common base of a big application, over and over again,
+may be time consuming.  GNU 'm4' offers some machinery to speed up the
+start of an application using lengthy common bases.
+
+* Menu:
+
+* Using frozen files::          Using frozen files
+* Frozen file format::          Frozen file format
+
+
+File: m4.info,  Node: Using frozen files,  Next: Frozen file format,  Up: Frozen files
+
+15.1 Using frozen files
+=======================
+
+Suppose a user has a library of 'm4' initializations in 'base.m4', which
+is then used with multiple input files:
+
+     $ m4 base.m4 input1.m4
+     $ m4 base.m4 input2.m4
+     $ m4 base.m4 input3.m4
+
+   Rather than spending time parsing the fixed contents of 'base.m4'
+every time, the user might rather execute:
+
+     $ m4 -F base.m4f base.m4
+
+once, and further execute, as often as needed:
+
+     $ m4 -R base.m4f input1.m4
+     $ m4 -R base.m4f input2.m4
+     $ m4 -R base.m4f input3.m4
+
+with the varying input.  The first call, containing the '-F' option,
+only reads and executes file 'base.m4', defining various application
+macros and computing other initializations.  Once the input file
+'base.m4' has been completely processed, GNU 'm4' produces in 'base.m4f'
+a "frozen" file, that is, a file which contains a kind of snapshot of
+the 'm4' internal state.
+
+   Later calls, containing the '-R' option, are able to reload the
+internal state of 'm4', from 'base.m4f', _prior_ to reading any other
+input files.  This means instead of starting with a virgin copy of 'm4',
+input will be read after having effectively recovered the effect of a
+prior run.  In our example, the effect is the same as if file 'base.m4'
+has been read anew.  However, this effect is achieved a lot faster.
+
+   Only one frozen file may be created or read in any one 'm4'
+invocation.  It is not possible to recover two frozen files at once.
+However, frozen files may be updated incrementally, through using '-R'
+and '-F' options simultaneously.  For example, if some care is taken,
+the command:
+
+     $ m4 file1.m4 file2.m4 file3.m4 file4.m4
+
+could be broken down in the following sequence, accumulating the same
+output:
+
+     $ m4 -F file1.m4f file1.m4
+     $ m4 -R file1.m4f -F file2.m4f file2.m4
+     $ m4 -R file2.m4f -F file3.m4f file3.m4
+     $ m4 -R file3.m4f file4.m4
+
+   Some care is necessary because not every effort has been made for
+this to work in all cases.  In particular, the trace attribute of macros
+is not handled, nor the current setting of 'changeword'.  Currently,
+'m4wrap' and 'sysval' also have problems.  Also, interactions for some
+options of 'm4', being used in one call and not in the next, have not
+been fully analyzed yet.  On the other end, you may be confident that
+stacks of 'pushdef' definitions are handled correctly, as well as
+undefined or renamed builtins, and changed strings for quotes or
+comments.  And future releases of GNU M4 will improve on the utility of
+frozen files.
+
+   When an 'm4' run is to be frozen, the automatic undiversion which
+takes place at end of execution is inhibited.  Instead, all positively
+numbered diversions are saved into the frozen file.  The active
+diversion number is also transmitted.
+
+   A frozen file to be reloaded need not reside in the current
+directory.  It is looked up the same way as an 'include' file (*note
+Search Path::).
+
+   If the frozen file was generated with a newer version of 'm4', and
+contains directives that an older 'm4' cannot parse, attempting to load
+the frozen file with option '-R' will cause 'm4' to exit with status 63
+to indicate version mismatch.
+
+
+File: m4.info,  Node: Frozen file format,  Prev: Using frozen files,  Up: Frozen files
+
+15.2 Frozen file format
+=======================
+
+Frozen files are sharable across architectures.  It is safe to write a
+frozen file on one machine and read it on another, given that the second
+machine uses the same or newer version of GNU 'm4'.  It is conventional,
+but not required, to give a frozen file the suffix of '.m4f'.
+
+   These are simple (editable) text files, made up of directives, each
+starting with a capital letter and ending with a newline (<NL>).
+Wherever a directive is expected, the character '#' introduces a comment
+line; empty lines are also ignored if they are not part of an embedded
+string.  In the following descriptions, each LEN refers to the length of
+the corresponding strings STR in the next line of input.  Numbers are
+always expressed in decimal.  There are no escape characters.  The
+directives are:
+
+'C LEN1 , LEN2 <NL> STR1 STR2 <NL>'
+     Uses STR1 and STR2 as the begin-comment and end-comment strings.
+     If omitted, then '#' and <NL> are the comment delimiters.
+
+'D NUMBER, LEN <NL> STR <NL>'
+     Selects diversion NUMBER, making it current, then copy STR in the
+     current diversion.  NUMBER may be a negative number for a
+     non-existing diversion.  To merely specify an active selection, use
+     this command with an empty STR.  With 0 as the diversion NUMBER,
+     STR will be issued on standard output at reload time.  GNU 'm4'
+     will not produce the 'D' directive with non-zero length for
+     diversion 0, but this can be done with manual edits.  This
+     directive may appear more than once for the same diversion, in
+     which case the diversion is the concatenation of the various uses.
+     If omitted, then diversion 0 is current.
+
+'F LEN1 , LEN2 <NL> STR1 STR2 <NL>'
+     Defines, through 'pushdef', a definition for STR1 expanding to the
+     function whose builtin name is STR2.  If the builtin does not exist
+     (for example, if the frozen file was produced by a copy of 'm4'
+     compiled with changeword support, but the version of 'm4' reloading
+     was compiled without it), the reload is silent, but any subsequent
+     use of the definition of STR1 will result in a warning.  This
+     directive may appear more than once for the same name, and its
+     order, along with 'T', is important.  If omitted, you will have no
+     access to any builtins.
+
+'Q LEN1 , LEN2 <NL> STR1 STR2 <NL>'
+     Uses STR1 and STR2 as the begin-quote and end-quote strings.  If
+     omitted, then '`' and ''' are the quote delimiters.
+
+'T LEN1 , LEN2 <NL> STR1 STR2 <NL>'
+     Defines, though 'pushdef', a definition for STR1 expanding to the
+     text given by STR2.  This directive may appear more than once for
+     the same name, and its order, along with 'F', is important.
+
+'V NUMBER <NL>'
+     Confirms the format of the file.  'm4' 1.4.17 only creates and
+     understands frozen files where NUMBER is 1.  This directive must be
+     the first non-comment in the file, and may not appear more than
+     once.
+
+
+File: m4.info,  Node: Compatibility,  Next: Answers,  Prev: Frozen files,  Up: Top
+
+16 Compatibility with other versions of 'm4'
+********************************************
+
+This chapter describes the many of the differences between this
+implementation of 'm4', and of other implementations found under UNIX,
+such as System V Release 4, Solaris, and BSD flavors.  In particular, it
+lists the known differences and extensions to POSIX. However, the list
+is not necessarily comprehensive.
+
+   At the time of this writing, POSIX 2001 (also known as IEEE Std
+1003.1-2001) is the latest standard, although a new version of POSIX is
+under development and includes several proposals for modifying what 'm4'
+is required to do.  The requirements for 'm4' are shared between SUSv3
+and POSIX, and can be viewed at
+<http://www.opengroup.org/onlinepubs/000095399/utilities/m4.html>.
+
+* Menu:
+
+* Extensions::                  Extensions in GNU M4
+* Incompatibilities::           Facilities in System V m4 not in GNU M4
+* Other Incompatibilities::     Other incompatibilities
+
+
+File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Up: Compatibility
+
+16.1 Extensions in GNU M4
+=========================
+
+This version of 'm4' contains a few facilities that do not exist in
+System V 'm4'.  These extra facilities are all suppressed by using the
+'-G' command line option (*note Invoking m4: Limits control.), unless
+overridden by other command line options.
+
+   * In the '$N' notation for macro arguments, N can contain several
+     digits, while the System V 'm4' only accepts one digit.  This
+     allows macros in GNU 'm4' to take any number of arguments, and not
+     only nine (*note Arguments::).
+
+     This means that 'define(`foo', `$11')' is ambiguous between
+     implementations.  To portably choose between grabbing the first
+     parameter and appending 1 to the expansion, or grabbing the
+     eleventh parameter, you can do the following:
+
+          define(`a1', `A1')
+          =>
+          dnl First argument, concatenated with 1
+          define(`_1', `$1')define(`first1', `_1($@)1')
+          =>
+          dnl Eleventh argument, portable
+          define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))')
+          =>
+          dnl Eleventh argument, GNU style
+          define(`Eleventh', `$11')
+          =>
+          first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+          =>A1
+          eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+          =>k
+          Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+          =>k
+
+     Also see the 'argn' macro (*note Shift::).
+
+   * The 'divert' (*note Divert::) macro can manage more than 9
+     diversions.  GNU 'm4' treats all positive numbers as valid
+     diversions, rather than discarding diversions greater than 9.
+
+   * Files included with 'include' and 'sinclude' are sought in a user
+     specified search path, if they are not found in the working
+     directory.  The search path is specified by the '-I' option and the
+     'M4PATH' environment variable (*note Search Path::).
+
+   * Arguments to 'undivert' can be non-numeric, in which case the named
+     file will be included uninterpreted in the output (*note
+     Undivert::).
+
+   * Formatted output is supported through the 'format' builtin, which
+     is modeled after the C library function 'printf' (*note Format::).
+
+   * Searches and text substitution through basic regular expressions
+     are supported by the 'regexp' (*note Regexp::) and 'patsubst'
+     (*note Patsubst::) builtins.  Some BSD implementations use extended
+     regular expressions instead.
+
+   * The output of shell commands can be read into 'm4' with 'esyscmd'
+     (*note Esyscmd::).
+
+   * There is indirect access to any builtin macro with 'builtin' (*note
+     Builtin::).
+
+   * Macros can be called indirectly through 'indir' (*note Indir::).
+
+   * The name of the program, the current input file, and the current
+     input line number are accessible through the builtins
+     '__program__', '__file__', and '__line__' (*note Location::).
+
+   * The format of the output from 'dumpdef' and macro tracing can be
+     controlled with 'debugmode' (*note Debug Levels::).
+
+   * The destination of trace and debug output can be controlled with
+     'debugfile' (*note Debug Output::).
+
+   * The 'maketemp' (*note Mkstemp::) macro behaves like 'mkstemp',
+     creating a new file with a unique name on every invocation, rather
+     than following the insecure behavior of replacing the trailing 'X'
+     characters with the 'm4' process id.
+
+   * POSIX only requires support for the command line options '-s',
+     '-D', and '-U', so all other options accepted by GNU M4 are
+     extensions.  *Note Invoking m4::, for a description of these
+     options.
+
+     The debugging and tracing facilities in GNU 'm4' are much more
+     extensive than in most other versions of 'm4'.
+
+
+File: m4.info,  Node: Incompatibilities,  Next: Other Incompatibilities,  Prev: Extensions,  Up: Compatibility
+
+16.2 Facilities in System V 'm4' not in GNU 'm4'
+================================================
+
+The version of 'm4' from System V contains a few facilities that have
+not been implemented in GNU 'm4' yet.  Additionally, POSIX requires some
+behaviors that GNU 'm4' has not implemented yet.  Relying on these
+behaviors is non-portable, as a future release of GNU 'm4' may change.
+
+   * POSIX requires support for multiple arguments to 'defn', without
+     any clarification on how 'defn' behaves when one of the multiple
+     arguments names a builtin.  System V 'm4' and some other
+     implementations allow mixing builtins and text macros into a single
+     macro.  GNU 'm4' only supports joining multiple text arguments,
+     although a future implementation may lift this restriction to
+     behave more like System V.  The only portable way to join text
+     macros with builtins is via helper macros and implicit
+     concatenation of macro results.
+
+   * POSIX requires an application to exit with non-zero status if it
+     wrote an error message to stderr.  This has not yet been
+     consistently implemented for the various builtins that are required
+     to issue an error (such as 'eval' (*note Eval::) when an argument
+     cannot be parsed).
+
+   * Some traditional implementations only allow reading standard input
+     once, but GNU 'm4' correctly handles multiple instances of '-' on
+     the command line.
+
+   * POSIX requires 'm4wrap' (*note M4wrap::) to act in FIFO (first-in,
+     first-out) order, but GNU 'm4' currently uses LIFO order.
+     Furthermore, POSIX states that only the first argument to 'm4wrap'
+     is saved for later evaluation, but GNU 'm4' saves and processes all
+     arguments, with output separated by spaces.
+
+   * POSIX states that builtins that require arguments, but are called
+     without arguments, have undefined behavior.  Traditional
+     implementations simply behave as though empty strings had been
+     passed.  For example, 'a`'define`'b' would expand to 'ab'.  But GNU
+     'm4' ignores certain builtins if they have missing arguments,
+     giving 'adefineb' for the above example.
+
+   * Traditional implementations handle 'define(`f',`1')' (*note
+     Define::) by undefining the entire stack of previous definitions,
+     and if doing 'undefine(`f')' first.  GNU 'm4' replaces just the top
+     definition on the stack, as if doing 'popdef(`f')' followed by
+     'pushdef(`f',`1')'.  POSIX allows either behavior.
+
+   * POSIX 2001 requires 'syscmd' (*note Syscmd::) to evaluate command
+     output for macro expansion, but this was a mistake that is
+     anticipated to be corrected in the next version of POSIX. GNU 'm4'
+     follows traditional behavior in 'syscmd' where output is not
+     rescanned, and provides the extension 'esyscmd' that does scan the
+     output.
+
+   * At one point, POSIX required 'changequote(ARG)' (*note
+     Changequote::) to use newline as the close quote, but this was a
+     bug, and the next version of POSIX is anticipated to state that
+     using empty strings or just one argument is unspecified.
+     Meanwhile, the GNU 'm4' behavior of treating an empty end-quote
+     delimiter as ''' is not portable, as Solaris treats it as repeating
+     the start-quote delimiter, and BSD treats it as leaving the
+     previous end-quote delimiter unchanged.  For predictable results,
+     never call changequote with just one argument, or with empty
+     strings for arguments.
+
+   * At one point, POSIX required 'changecom(ARG,)' (*note Changecom::)
+     to make it impossible to end a comment, but this is a bug, and the
+     next version of POSIX is anticipated to state that using empty
+     strings is unspecified.  Meanwhile, the GNU 'm4' behavior of
+     treating an empty end-comment delimiter as newline is not portable,
+     as BSD treats it as leaving the previous end-comment delimiter
+     unchanged.  It is also impossible in BSD implementations to disable
+     comments, even though that is required by POSIX. For predictable
+     results, never call changecom with empty strings for arguments.
+
+   * Most implementations of 'm4' give macros a higher precedence than
+     comments when parsing, meaning that if the start delimiter given to
+     'changecom' (*note Changecom::) starts with a macro name, comments
+     are effectively disabled.  POSIX does not specify what the
+     precedence is, so this version of GNU 'm4' parser recognizes
+     comments, then macros, then quoted strings.
+
+   * Traditional implementations allow argument collection, but not
+     string and comment processing, to span file boundaries.  Thus, if
+     'a.m4' contains 'len(', and 'b.m4' contains 'abc)', 'm4 a.m4 b.m4'
+     outputs '3' with traditional 'm4', but gives an error message that
+     the end of file was encountered inside a macro with GNU 'm4'.  On
+     the other hand, traditional implementations do end of file
+     processing for files included with 'include' or 'sinclude' (*note
+     Include::), while GNU 'm4' seamlessly integrates the content of
+     those files.  Thus 'include(`a.m4')include(`b.m4')' will output '3'
+     instead of giving an error.
+
+   * Traditional 'm4' treats 'traceon' (*note Trace::) without arguments
+     as a global variable, independent of named macro tracing.  Also,
+     once a macro is undefined, named tracing of that macro is lost.  On
+     the other hand, when GNU 'm4' encounters 'traceon' without
+     arguments, it turns tracing on for all existing definitions at the
+     time, but does not trace future definitions; 'traceoff' without
+     arguments turns tracing off for all definitions regardless of
+     whether they were also traced by name; and tracing by name, such as
+     with '-tfoo' at the command line or 'traceon(`foo')' in the input,
+     is an attribute that is preserved even if the macro is currently
+     undefined.
+
+     Additionally, while POSIX requires trace output, it makes no
+     demands on the formatting of that output.  Parsing trace output is
+     not guaranteed to be reliable, even between different releases of
+     GNU M4; however, the intent is that any future changes in trace
+     output will only occur under the direction of additional
+     'debugmode' flags (*note Debug Levels::).
+
+   * POSIX requires 'eval' (*note Eval::) to treat all operators with
+     the same precedence as C.  However, earlier versions of GNU 'm4'
+     followed the traditional behavior of other 'm4' implementations,
+     where bitwise and logical negation ('~' and '!') have lower
+     precedence than equality operators; and where equality operators
+     ('==' and '!=') had the same precedence as relational operators
+     (such as '<').  Use explicit parentheses to ensure proper
+     precedence.  As extensions to POSIX, GNU 'm4' gives well-defined
+     semantics to operations that C leaves undefined, such as when
+     overflow occurs, when shifting negative numbers, or when performing
+     division by zero.  POSIX also requires '=' to cause an error, but
+     many traditional implementations allowed it as an alias for '=='.
+
+   * POSIX 2001 requires 'translit' (*note Translit::) to treat each
+     character of the second and third arguments literally.  However, it
+     is anticipated that the next version of POSIX will allow the GNU
+     'm4' behavior of treating '-' as a range operator.
+
+   * POSIX requires 'm4' to honor the locale environment variables of
+     'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', and 'NLSPATH', but
+     this has not yet been implemented in GNU 'm4'.
+
+   * POSIX states that only unquoted leading newlines and blanks (that
+     is, space and tab) are ignored when collecting macro arguments.
+     However, this appears to be a bug in POSIX, since most traditional
+     implementations also ignore all whitespace (formfeed, carriage
+     return, and vertical tab).  GNU 'm4' follows tradition and ignores
+     all leading unquoted whitespace.
+
+   * A strictly-compliant POSIX client is not allowed to use
+     command-line arguments not specified by POSIX. However, since this
+     version of M4 ignores 'POSIXLY_CORRECT' and enables the option
+     '--gnu' by default (*note Invoking m4: Limits control.), a client
+     desiring to be strictly compliant has no way to disable GNU
+     extensions that conflict with POSIX when directly invoking the
+     compiled 'm4'.  A future version of 'GNU' M4 will honor the
+     environment variable 'POSIXLY_CORRECT', implicitly enabling
+     '--traditional' if it is set, in order to allow a
+     strictly-compliant client.  In the meantime, a client needing
+     strict POSIX compliance can use the workaround of invoking a shell
+     script wrapper, where the wrapper then adds '--traditional' to the
+     arguments passed to the compiled 'm4'.
+
+
+File: m4.info,  Node: Other Incompatibilities,  Prev: Incompatibilities,  Up: Compatibility
+
+16.3 Other incompatibilities
+============================
+
+There are a few other incompatibilities between this implementation of
+'m4', and the System V version.
+
+   * GNU 'm4' implements sync lines differently from System V 'm4', when
+     text is being diverted.  GNU 'm4' outputs the sync lines when the
+     text is being diverted, and System V 'm4' when the diverted text is
+     being brought back.
+
+     The problem is which lines and file names should be attached to
+     text that is being, or has been, diverted.  System V 'm4' regards
+     all the diverted text as being generated by the source line
+     containing the 'undivert' call, whereas GNU 'm4' regards the
+     diverted text as being generated at the time it is diverted.
+
+     The sync line option is used mostly when using 'm4' as a front end
+     to a compiler.  If a diverted line causes a compiler error, the
+     error messages should most probably refer to the place where the
+     diversion was made, and not where it was inserted again.
+
+          divert(2)2
+          divert(1)1
+          divert`'0
+          =>#line 3 "stdin"
+          =>0
+          ^D
+          =>#line 2 "stdin"
+          =>1
+          =>#line 1 "stdin"
+          =>2
+
+     The current 'm4' implementation has a limitation that the syncline
+     output at the start of each diversion occurs no matter what, even
+     if the previous diversion did not end with a newline.  This goes
+     contrary to the claim that synclines appear on a line by
+     themselves, so this limitation may be corrected in a future version
+     of 'm4'.  In the meantime, when using '-s', it is wisest to make
+     sure all diversions end with newline.
+
+   * GNU 'm4' makes no attempt at prohibiting self-referential
+     definitions like:
+
+          define(`x', `x')
+          =>
+          define(`x', `x ')
+          =>
+
+     There is nothing inherently wrong with defining 'x' to return 'x'.
+     The wrong thing is to expand 'x' unquoted, because that would cause
+     an infinite rescan loop.  In 'm4', one might use macros to hold
+     strings, as we do for variables in other programming languages,
+     further checking them with:
+
+          ifelse(defn(`HOLDER'), `VALUE', ...)
+
+     In cases like this one, an interdiction for a macro to hold its own
+     name would be a useless limitation.  Of course, this leaves more
+     rope for the GNU 'm4' user to hang himself!  Rescanning hangs may
+     be avoided through careful programming, a little like for endless
+     loops in traditional programming languages.
+
+
+File: m4.info,  Node: Answers,  Next: Copying This Package,  Prev: Compatibility,  Up: Top
+
+17 Correct version of some examples
+***********************************
+
+Some of the examples in this manuals are buggy or not very robust, for
+demonstration purposes.  Improved versions of these composite macros are
+presented here.
+
+* Menu:
+
+* Improved exch::               Solution for 'exch'
+* Improved forloop::            Solution for 'forloop'
+* Improved foreach::            Solution for 'foreach'
+* Improved copy::               Solution for 'copy'
+* Improved m4wrap::             Solution for 'm4wrap'
+* Improved cleardivert::        Solution for 'cleardivert'
+* Improved capitalize::         Solution for 'capitalize'
+* Improved fatal_error::        Solution for 'fatal_error'
+
+
+File: m4.info,  Node: Improved exch,  Next: Improved forloop,  Up: Answers
+
+17.1 Solution for 'exch'
+========================
+
+The 'exch' macro (*note Arguments::) as presented requires clients to
+double quote their arguments.  A nicer definition, which lets clients
+follow the rule of thumb of one level of quoting per level of
+parentheses, involves adding quotes in the definition of 'exch', as
+follows:
+
+     define(`exch', ``$2', `$1'')
+     =>
+     define(exch(`expansion text', `macro'))
+     =>
+     macro
+     =>expansion text
+
+
+File: m4.info,  Node: Improved forloop,  Next: Improved foreach,  Prev: Improved exch,  Up: Answers
+
+17.2 Solution for 'forloop'
+===========================
+
+The 'forloop' macro (*note Forloop::) as presented earlier can go into
+an infinite loop if given an iterator that is not parsed as a macro
+name.  It does not do any sanity checking on its numeric bounds, and
+only permits decimal numbers for bounds.  Here is an improved version,
+shipped as 'm4-1.4.17/examples/forloop2.m4'; this version also optimizes
+overhead by calling four macros instead of six per iteration (excluding
+those in TEXT), by not dereferencing the ITERATOR in the helper
+'_forloop'.
+
+     $ m4 -d -I examples
+     undivert(`forloop2.m4')dnl
+     =>divert(`-1')
+     =># forloop(var, from, to, stmt) - improved version:
+     =>#   works even if VAR is not a strict macro name
+     =>#   performs sanity check that FROM is larger than TO
+     =>#   allows complex numerical expressions in TO and FROM
+     =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
+     =>  `pushdef(`$1')_$0(`$1', eval(`$2'),
+     =>    eval(`$3'), `$4')popdef(`$1')')')
+     =>define(`_forloop',
+     =>  `define(`$1', `$2')$4`'ifelse(`$2', `$3', `',
+     =>    `$0(`$1', incr(`$2'), `$3', `$4')')')
+     =>divert`'dnl
+     include(`forloop2.m4')
+     =>
+     forloop(`i', `2', `1', `no iteration occurs')
+     =>
+     forloop(`', `1', `2', ` odd iterator name')
+     => odd iterator name odd iterator name
+     forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')')
+     => 0xa 0xb 0xc
+     forloop(`i', `a', `b', `non-numeric bounds')
+     error->m4:stdin:6: bad expression in eval (bad input): (a) <= (b)
+     =>
+
+   One other change to notice is that the improved version used '_$0'
+rather than '_foreach' to invoke the helper routine.  In general, this
+is a good practice to follow, because then the set of macros can be
+uniformly transformed.  The following example shows a transformation
+that doubles the current quoting and appends a suffix '2' to each
+transformed macro.  If 'foreach' refers to the literal '_foreach', then
+'foreach2' invokes '_foreach' instead of the intended '_foreach2', and
+the mixing of quoting paradigms leads to an infinite recursion loop in
+this example.
+
+     $ m4 -d -L 9 -I examples
+     define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4')
+     =>
+     define(`double', `define(`$1'`2',
+       arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))')
+     =>
+     double(`forloop')double(`_forloop')defn(`forloop2')
+     =>ifelse(eval(``($2) <= ($3)''), ``1'',
+     =>  ``pushdef(``$1'')_$0(``$1'', eval(``$2''),
+     =>    eval(``$3''), ``$4'')popdef(``$1'')'')
+     forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
+     =>
+     changequote(`[', `]')changequote([``], [''])
+     =>
+     forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
+     =>
+     changequote`'include(`forloop.m4')
+     =>
+     double(`forloop')double(`_forloop')defn(`forloop2')
+     =>pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'')
+     forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
+     =>
+     changequote(`[', `]')changequote([``], [''])
+     =>
+     forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
+     error->m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it
+
+   One more optimization is still possible.  Instead of repeatedly
+assigning a variable then invoking or dereferencing it, it is possible
+to pass the current iterator value as a single argument.  Coupled with
+'curry' if other arguments are needed (*note Composition::), or with
+helper macros if the argument is needed in more than one place in the
+expansion, the output can be generated with three, rather than four,
+macros of overhead per iteration.  Notice how the file
+'m4-1.4.17/examples/forloop3.m4' rearranges the arguments of the helper
+'_forloop' to take two arguments that are placed around the current
+value.  By splitting a balanced set of parantheses across multiple
+arguments, the helper macro can now be shared by 'forloop' and the new
+'forloop_arg'.
+
+     $ m4 -I examples
+     include(`forloop3.m4')
+     =>
+     undivert(`forloop3.m4')dnl
+     =>divert(`-1')
+     =># forloop_arg(from, to, macro) - invoke MACRO(value) for
+     =>#   each value between FROM and TO, without define overhead
+     =>define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1',
+     =>  `_forloop(`$1', eval(`$2'), `$3(', `)')')')
+     =># forloop(var, from, to, stmt) - refactored to share code
+     =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
+     =>  `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'),
+     =>    `define(`$1',', `)$4')popdef(`$1')')')
+     =>define(`_forloop',
+     =>  `$3`$1'$4`'ifelse(`$1', `$2', `',
+     =>    `$0(incr(`$1'), `$2', `$3', `$4')')')
+     =>divert`'dnl
+     forloop(`i', `1', `3', ` i')
+     => 1 2 3
+     define(`echo', `$@')
+     =>
+     forloop_arg(`1', `3', ` echo')
+     => 1 2 3
+     include(`curry.m4')
+     =>
+     forloop_arg(`1', `3', `curry(`pushdef', `a')')
+     =>
+     a
+     =>3
+     popdef(`a')a
+     =>2
+     popdef(`a')a
+     =>1
+     popdef(`a')a
+     =>a
+
+   Of course, it is possible to make even more improvements, such as
+adding an optional step argument, or allowing iteration through
+descending sequences.  GNU Autoconf provides some of these additional
+bells and whistles in its 'm4_for' macro.
+
+
+File: m4.info,  Node: Improved foreach,  Next: Improved copy,  Prev: Improved forloop,  Up: Answers
+
+17.3 Solution for 'foreach'
+===========================
+
+The 'foreach' and 'foreachq' macros (*note Foreach::) as presented
+earlier each have flaws.  First, we will examine and fix the quadratic
+behavior of 'foreachq':
+
+     $ m4 -I examples
+     include(`foreachq.m4')
+     =>
+     traceon(`shift')debugmode(`aq')
+     =>
+     foreachq(`x', ``1', `2', `3', `4'', `x
+     ')dnl
+     =>1
+     error->m4trace: -3- shift(`1', `2', `3', `4')
+     error->m4trace: -2- shift(`1', `2', `3', `4')
+     =>2
+     error->m4trace: -4- shift(`1', `2', `3', `4')
+     error->m4trace: -3- shift(`2', `3', `4')
+     error->m4trace: -3- shift(`1', `2', `3', `4')
+     error->m4trace: -2- shift(`2', `3', `4')
+     =>3
+     error->m4trace: -5- shift(`1', `2', `3', `4')
+     error->m4trace: -4- shift(`2', `3', `4')
+     error->m4trace: -3- shift(`3', `4')
+     error->m4trace: -4- shift(`1', `2', `3', `4')
+     error->m4trace: -3- shift(`2', `3', `4')
+     error->m4trace: -2- shift(`3', `4')
+     =>4
+     error->m4trace: -6- shift(`1', `2', `3', `4')
+     error->m4trace: -5- shift(`2', `3', `4')
+     error->m4trace: -4- shift(`3', `4')
+     error->m4trace: -3- shift(`4')
+
+   Each successive iteration was adding more quoted 'shift' invocations,
+and the entire list contents were passing through every iteration.  In
+general, when recursing, it is a good idea to make the recursion use
+fewer arguments, rather than adding additional quoted uses of 'shift'.
+By doing so, 'm4' uses less memory, invokes fewer macros, is less likely
+to run into machine limits, and most importantly, performs faster.  The
+fixed version of 'foreachq' can be found in
+'m4-1.4.17/examples/foreachq2.m4':
+
+     $ m4 -I examples
+     include(`foreachq2.m4')
+     =>
+     undivert(`foreachq2.m4')dnl
+     =>include(`quote.m4')dnl
+     =>divert(`-1')
+     =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
+     =>#   quoted list, improved version
+     =>define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')')
+     =>define(`_arg1q', ``$1'')
+     =>define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')')
+     =>define(`_foreachq', `ifelse(`$2', `', `',
+     =>  `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')')
+     =>divert`'dnl
+     traceon(`shift')debugmode(`aq')
+     =>
+     foreachq(`x', ``1', `2', `3', `4'', `x
+     ')dnl
+     =>1
+     error->m4trace: -3- shift(`1', `2', `3', `4')
+     =>2
+     error->m4trace: -3- shift(`2', `3', `4')
+     =>3
+     error->m4trace: -3- shift(`3', `4')
+     =>4
+
+   Note that the fixed version calls unquoted helper macros in
+'_foreachq' to trim elements immediately; those helper macros in turn
+must re-supply the layer of quotes lost in the macro invocation.
+Contrast the use of '_arg1q', which quotes the first list element, with
+'_arg1' of the earlier implementation that returned the first list
+element directly.  Additionally, by calling the helper method
+immediately, the 'defn(`ITERATOR')' no longer contains unexpanded
+macros.
+
+   The astute m4 programmer might notice that the solution above still
+uses more memory and macro invocations, and thus more time, than
+strictly necessary.  Note that '$2', which contains an arbitrarily long
+quoted list, is expanded and rescanned three times per iteration of
+'_foreachq'.  Furthermore, every iteration of the algorithm effectively
+unboxes then reboxes the list, which costs a couple of macro
+invocations.  It is possible to rewrite the algorithm for a bit more
+speed by swapping the order of the arguments to '_foreachq' in order to
+operate on an unboxed list in the first place, and by using the
+fixed-length '$#' instead of an arbitrary length list as the key to end
+recursion.  The result is an overhead of six macro invocations per loop
+(excluding any macros in TEXT), instead of eight.  This alternative
+approach is available as 'm4-1.4.17/examples/foreach3.m4':
+
+     $ m4 -I examples
+     include(`foreachq3.m4')
+     =>
+     undivert(`foreachq3.m4')dnl
+     =>divert(`-1')
+     =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
+     =>#   quoted list, alternate improved version
+     =>define(`foreachq', `ifelse(`$2', `', `',
+     =>  `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')')
+     =>define(`_foreachq', `ifelse(`$#', `3', `',
+     =>  `define(`$1', `$4')$2`'$0(`$1', `$2',
+     =>    shift(shift(shift($@))))')')
+     =>divert`'dnl
+     traceon(`shift')debugmode(`aq')
+     =>
+     foreachq(`x', ``1', `2', `3', `4'', `x
+     ')dnl
+     =>1
+     error->m4trace: -4- shift(`x', `x
+     error->', `', `1', `2', `3', `4')
+     error->m4trace: -3- shift(`x
+     error->', `', `1', `2', `3', `4')
+     error->m4trace: -2- shift(`', `1', `2', `3', `4')
+     =>2
+     error->m4trace: -4- shift(`x', `x
+     error->', `1', `2', `3', `4')
+     error->m4trace: -3- shift(`x
+     error->', `1', `2', `3', `4')
+     error->m4trace: -2- shift(`1', `2', `3', `4')
+     =>3
+     error->m4trace: -4- shift(`x', `x
+     error->', `2', `3', `4')
+     error->m4trace: -3- shift(`x
+     error->', `2', `3', `4')
+     error->m4trace: -2- shift(`2', `3', `4')
+     =>4
+     error->m4trace: -4- shift(`x', `x
+     error->', `3', `4')
+     error->m4trace: -3- shift(`x
+     error->', `3', `4')
+     error->m4trace: -2- shift(`3', `4')
+
+   In the current version of M4, every instance of '$@' is rescanned as
+it is encountered.  Thus, the 'foreachq3.m4' alternative uses much less
+memory than 'foreachq2.m4', and executes as much as 10% faster, since
+each iteration encounters fewer '$@'.  However, the implementation of
+rescanning every byte in '$@' is quadratic in the number of bytes
+scanned (for example, making the broken version in 'foreachq.m4' cubic,
+rather than quadratic, in behavior).  A future release of M4 will
+improve the underlying implementation by reusing results of previous
+scans, so that both styles of 'foreachq' can become linear in the number
+of bytes scanned.  Notice how the implementation injects an empty
+argument prior to expanding '$2' within 'foreachq'; the helper macro
+'_foreachq' then ignores the third argument altogether, and ends
+recursion when there are three arguments left because there was nothing
+left to pass through 'shift'.  Thus, each iteration only needs one
+'ifelse', rather than the two conditionals used in the version from
+'foreachq2.m4'.
+
+   So far, all of the implementations of 'foreachq' presented have been
+quadratic with M4 1.4.x.  But 'forloop' is linear, because each
+iteration parses a constant amount of arguments.  So, it is possible to
+design a variant that uses 'forloop' to do the iteration, then uses '$@'
+only once at the end, giving a linear result even with older M4
+implementations.  This implementation relies on the GNU extension that
+'$10' expands to the tenth argument rather than the first argument
+concatenated with '0'.  The trick is to define an intermediate macro
+that repeats the text 'm4_define(`$1', `$N')$2`'', with 'n' set to
+successive integers corresponding to each argument.  The helper macro
+'_foreachq_' is needed in order to generate the literal sequences such
+as '$1' into the intermediate macro, rather than expanding them as the
+arguments of '_foreachq'.  With this approach, no 'shift' calls are even
+needed!  Even though there are seven macros of overhead per iteration
+instead of six in 'foreachq3.m4', the linear scaling is apparent at
+relatively small list sizes.  However, this approach will need
+adjustment when a future version of M4 follows POSIX by no longer
+treating '$10' as the tenth argument; the anticipation is that '${10}'
+can be used instead, although that alternative syntax is not yet
+supported.
+
+     $ m4 -I examples
+     include(`foreachq4.m4')
+     =>
+     undivert(`foreachq4.m4')dnl
+     =>include(`forloop2.m4')dnl
+     =>divert(`-1')
+     =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
+     =>#   quoted list, version based on forloop
+     =>define(`foreachq',
+     =>`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')')
+     =>define(`_foreachq',
+     =>`pushdef(`$1', forloop(`$1', `3', `$#',
+     =>  `$0_(`1', `2', indir(`$1'))')`popdef(
+     =>    `$1')')indir(`$1', $@)')
+     =>define(`_foreachq_',
+     =>``define(`$$1', `$$3')$$2`''')
+     =>divert`'dnl
+     traceon(`shift')debugmode(`aq')
+     =>
+     foreachq(`x', ``1', `2', `3', `4'', `x
+     ')dnl
+     =>1
+     =>2
+     =>3
+     =>4
+
+   For yet another approach, the improved version of 'foreach',
+available in 'm4-1.4.17/examples/foreach2.m4', simply overquotes the
+arguments to '_foreach' to begin with, using 'dquote_elt'.  Then
+'_foreach' can just use '_arg1' to remove the extra layer of quoting
+that was added up front:
+
+     $ m4 -I examples
+     include(`foreach2.m4')
+     =>
+     undivert(`foreach2.m4')dnl
+     =>include(`quote.m4')dnl
+     =>divert(`-1')
+     =># foreach(x, (item_1, item_2, ..., item_n), stmt)
+     =>#   parenthesized list, improved version
+     =>define(`foreach', `pushdef(`$1')_$0(`$1',
+     =>  (dquote(dquote_elt$2)), `$3')popdef(`$1')')
+     =>define(`_arg1', `$1')
+     =>define(`_foreach', `ifelse(`$2', `(`')', `',
+     =>  `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')')
+     =>divert`'dnl
+     traceon(`shift')debugmode(`aq')
+     =>
+     foreach(`x', `(`1', `2', `3', `4')', `x
+     ')dnl
+     error->m4trace: -4- shift(`1', `2', `3', `4')
+     error->m4trace: -4- shift(`2', `3', `4')
+     error->m4trace: -4- shift(`3', `4')
+     =>1
+     error->m4trace: -3- shift(``1'', ``2'', ``3'', ``4'')
+     =>2
+     error->m4trace: -3- shift(``2'', ``3'', ``4'')
+     =>3
+     error->m4trace: -3- shift(``3'', ``4'')
+     =>4
+     error->m4trace: -3- shift(``4'')
+
+   It is likewise possible to write a variant of 'foreach' that performs
+in linear time on M4 1.4.x; the easiest method is probably writing a
+version of 'foreach' that unboxes its list, then invokes '_foreachq' as
+previously defined in 'foreachq4.m4'.
+
+   In summary, recursion over list elements is trickier than it appeared
+at first glance, but provides a powerful idiom within 'm4' processing.
+As a final demonstration, both list styles are now able to handle
+several scenarios that would wreak havoc on one or both of the original
+implementations.  This points out one other difference between the list
+styles.  'foreach' evaluates unquoted list elements only once, in
+preparation for calling '_foreach', similary for 'foreachq' as provided
+by 'foreachq3.m4' or 'foreachq4.m4'.  But 'foreachq', as provided by
+'foreachq2.m4', evaluates unquoted list elements twice while visiting
+the first list element, once in '_arg1q' and once in '_rest'.  When
+deciding which list style to use, one must take into account whether
+repeating the side effects of unquoted list elements will have any
+detrimental effects.
+
+     $ m4 -I examples
+     include(`foreach2.m4')
+     =>
+     include(`foreachq2.m4')
+     =>
+     dnl 0-element list:
+     foreach(`x', `', `<x>') / foreachq(`x', `', `<x>')
+     => / 
+     dnl 1-element list of empty element
+     foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>')
+     =><> / <>
+     dnl 2-element list of empty elements
+     foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>')
+     =><><> / <><>
+     dnl 1-element list of a comma
+     foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>')
+     =><,> / <,>
+     dnl 2-element list of unbalanced parentheses
+     foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
+     =><(><)> / <(><)>
+     define(`ab', `oops')dnl using defn(`iterator')
+     foreach(`x', `(`a', `b')', `defn(`x')') /dnl
+      foreachq(`x', ``a', `b'', `defn(`x')')
+     =>ab / ab
+     define(`active', `ACT, IVE')
+     =>
+     traceon(`active')
+     =>
+     dnl list of unquoted macros; expansion occurs before recursion
+     foreach(`x', `(active, active)', `<x>
+     ')dnl
+     error->m4trace: -4- active -> `ACT, IVE'
+     error->m4trace: -4- active -> `ACT, IVE'
+     =><ACT>
+     =><IVE>
+     =><ACT>
+     =><IVE>
+     foreachq(`x', `active, active', `<x>
+     ')dnl
+     error->m4trace: -3- active -> `ACT, IVE'
+     error->m4trace: -3- active -> `ACT, IVE'
+     =><ACT>
+     error->m4trace: -3- active -> `ACT, IVE'
+     error->m4trace: -3- active -> `ACT, IVE'
+     =><IVE>
+     =><ACT>
+     =><IVE>
+     dnl list of quoted macros; expansion occurs during recursion
+     foreach(`x', `(`active', `active')', `<x>
+     ')dnl
+     error->m4trace: -1- active -> `ACT, IVE'
+     =><ACT, IVE>
+     error->m4trace: -1- active -> `ACT, IVE'
+     =><ACT, IVE>
+     foreachq(`x', ``active', `active'', `<x>
+     ')dnl
+     error->m4trace: -1- active -> `ACT, IVE'
+     =><ACT, IVE>
+     error->m4trace: -1- active -> `ACT, IVE'
+     =><ACT, IVE>
+     dnl list of double-quoted macro names; no expansion
+     foreach(`x', `(``active'', ``active'')', `<x>
+     ')dnl
+     =><active>
+     =><active>
+     foreachq(`x', ```active'', ``active''', `<x>
+     ')dnl
+     =><active>
+     =><active>
+
+
+File: m4.info,  Node: Improved copy,  Next: Improved m4wrap,  Prev: Improved foreach,  Up: Answers
+
+17.4 Solution for 'copy'
+========================
+
+The macro 'copy' presented above is unable to handle builtin tokens with
+M4 1.4.x, because it tries to pass the builtin token through the macro
+'curry', where it is silently flattened to an empty string (*note
+Composition::).  Rather than using the problematic 'curry' to work
+around the limitation that 'stack_foreach' expects to invoke a macro
+that takes exactly one argument, we can write a new macro that lets us
+form the exact two-argument 'pushdef' call sequence needed, so that we
+are no longer passing a builtin token through a text macro.
+
+ -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP)
+ -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP)
+     For each of the 'pushdef' definitions associated with MACRO, expand
+     the sequence 'PRE`'definition`'POST'.  Additionally, expand SEP
+     between definitions.  'stack_foreach_sep' visits the oldest
+     definition first, while 'stack_foreach_sep_lifo' visits the current
+     definition first.  The expansion may dereference MACRO, but should
+     not modify it.  There are a few special macros, such as 'defn',
+     which cannot be used as the MACRO parameter.
+
+   Note that 'stack_foreach(`MACRO', `ACTION')' is equivalent to
+'stack_foreach_sep(`MACRO', `ACTION(', `)')'.  By supplying explicit
+parentheses, split among the PRE and POST arguments to
+'stack_foreach_sep', it is now possible to construct macro calls with
+more than one argument, without passing builtin tokens through a macro
+call.  It is likewise possible to directly reference the stack
+definitions without a macro call, by leaving PRE and POST empty.  Thus,
+in addition to fixing 'copy' on builtin tokens, it also executes with
+fewer macro invocations.
+
+   The new macro also adds a separator that is only output after the
+first iteration of the helper '_stack_reverse_sep', implemented by
+prepending the original SEP to PRE and omitting a SEP argument in
+subsequent iterations.  Note that the empty string that separates SEP
+from PRE is provided as part of the fourth argument when originally
+calling '_stack_reverse_sep', and not by writing '$4`'$3' as the third
+argument in the recursive call; while the other approach would give the
+same output, it does so at the expense of increasing the argument size
+on each iteration of '_stack_reverse_sep', which results in quadratic
+instead of linear execution time.  The improved stack walking macros are
+available in 'm4-1.4.17/examples/stack_sep.m4':
+
+     $ m4 -I examples
+     include(`stack_sep.m4')
+     =>
+     define(`copy', `ifdef(`$2', `errprint(`$2 already defined
+     ')m4exit(`1')',
+        `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl
+     pushdef(`a', `1')pushdef(`a', defn(`divnum'))
+     =>
+     copy(`a', `b')
+     =>
+     b
+     =>0
+     popdef(`b')
+     =>
+     b
+     =>1
+     pushdef(`c', `1')pushdef(`c', `2')
+     =>
+     stack_foreach_sep_lifo(`c', `', `', `, ')
+     =>2, 1
+     undivert(`stack_sep.m4')dnl
+     =>divert(`-1')
+     =># stack_foreach_sep(macro, pre, post, sep)
+     =># Invoke PRE`'defn`'POST with a single argument of each definition
+     =># from the definition stack of MACRO, starting with the oldest, and
+     =># separated by SEP between definitions.
+     =>define(`stack_foreach_sep',
+     =>`_stack_reverse_sep(`$1', `tmp-$1')'dnl
+     =>`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')')
+     =># stack_foreach_sep_lifo(macro, pre, post, sep)
+     =># Like stack_foreach_sep, but starting with the newest definition.
+     =>define(`stack_foreach_sep_lifo',
+     =>`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl
+     =>`_stack_reverse_sep(`tmp-$1', `$1')')
+     =>define(`_stack_reverse_sep',
+     =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0(
+     =>  `$1', `$2', `$4$3')')')
+     =>divert`'dnl
+
+
+File: m4.info,  Node: Improved m4wrap,  Next: Improved cleardivert,  Prev: Improved copy,  Up: Answers
+
+17.5 Solution for 'm4wrap'
+==========================
+
+The replacement 'm4wrap' versions presented above, designed to guarantee
+FIFO or LIFO order regardless of the underlying M4 implementation, share
+a bug when dealing with wrapped text that looks like parameter
+expansion.  Note how the invocation of 'm4wrapN' interprets these
+parameters, while using the builtin preserves them for their intended
+use.
+
+     $ m4 -I examples
+     include(`wraplifo.m4')
+     =>
+     m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
+     ')
+     =>
+     builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b')
+     ')
+     =>
+     ^D
+     =>bar:-a-a,b-2-
+     =>m4wrap0:---0-
+
+   Additionally, the computation of '_m4wrap_level' and creation of
+multiple 'm4wrapN' placeholders in the original examples is more
+expensive in time and memory than strictly necessary.  Notice how the
+improved version grabs the wrapped text via 'defn' to avoid parameter
+expansion, then undefines '_m4wrap_text', before stripping a level of
+quotes with '_arg1' to expand the text.  That way, each level of
+wrapping reuses the single placeholder, which starts each nesting level
+in an undefined state.
+
+   Finally, it is worth emulating the GNU M4 extension of saving all
+arguments to 'm4wrap', separated by a space, rather than saving just the
+first argument.  This is done with the 'join' macro documented
+previously (*note Shift::).  The improved LIFO example is shipped as
+'m4-1.4.17/examples/wraplifo2.m4', and can easily be converted to a FIFO
+solution by swapping the adjacent invocations of 'joinall' and 'defn'.
+
+     $ m4 -I examples
+     include(`wraplifo2.m4')
+     =>
+     undivert(`wraplifo2.m4')dnl
+     =>dnl Redefine m4wrap to have LIFO semantics, improved example.
+     =>include(`join.m4')dnl
+     =>define(`_m4wrap', defn(`m4wrap'))dnl
+     =>define(`_arg1', `$1')dnl
+     =>define(`m4wrap',
+     =>`ifdef(`_$0_text',
+     =>       `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))',
+     =>       `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl
+     =>define(`_$0_text', joinall(` ', $@))')')dnl
+     m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
+     ')
+     =>
+     m4wrap(`lifo text
+     m4wrap(`nested', `', `$@
+     ')')
+     =>
+     ^D
+     =>lifo text
+     =>foo:-a-a,b-2-
+     =>nested  $@
+
+
+File: m4.info,  Node: Improved cleardivert,  Next: Improved capitalize,  Prev: Improved m4wrap,  Up: Answers
+
+17.6 Solution for 'cleardivert'
+===============================
+
+The 'cleardivert' macro (*note Cleardivert::) cannot, as it stands, be
+called without arguments to clear all pending diversions.  That is
+because using undivert with an empty string for an argument is different
+than using it with no arguments at all.  Compare the earlier definition
+with one that takes the number of arguments into account:
+
+     define(`cleardivert',
+       `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
+     =>
+     divert(`1')one
+     divert
+     =>
+     cleardivert
+     =>
+     undivert
+     =>one
+     =>
+     define(`cleardivert',
+       `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
+         `undivert`'', `undivert($@)')divert(_num)popdef(`_num')')
+     =>
+     divert(`2')two
+     divert
+     =>
+     cleardivert
+     =>
+     undivert
+     =>
+
+
+File: m4.info,  Node: Improved capitalize,  Next: Improved fatal_error,  Prev: Improved cleardivert,  Up: Answers
+
+17.7 Solution for 'capitalize'
+==============================
+
+The 'capitalize' macro (*note Patsubst::) as presented earlier does not
+allow clients to follow the quoting rule of thumb.  Consider the three
+macros 'active', 'Active', and 'ACTIVE', and the difference between
+calling 'capitalize' with the expansion of a macro, expanding the result
+of a case change, and changing the case of a double-quoted string:
+
+     $ m4 -I examples
+     include(`capitalize.m4')dnl
+     define(`active', `act1, ive')dnl
+     define(`Active', `Act2, Ive')dnl
+     define(`ACTIVE', `ACT3, IVE')dnl
+     upcase(active)
+     =>ACT1,IVE
+     upcase(`active')
+     =>ACT3, IVE
+     upcase(``active'')
+     =>ACTIVE
+     downcase(ACTIVE)
+     =>act3,ive
+     downcase(`ACTIVE')
+     =>act1, ive
+     downcase(``ACTIVE'')
+     =>active
+     capitalize(active)
+     =>Act1
+     capitalize(`active')
+     =>Active
+     capitalize(``active'')
+     =>_capitalize(`active')
+     define(`A', `OOPS')
+     =>
+     capitalize(active)
+     =>OOPSct1
+     capitalize(`active')
+     =>OOPSctive
+
+   First, when 'capitalize' is called with more than one argument, it
+was throwing away later arguments, whereas 'upcase' and 'downcase' used
+'$*' to collect them all.  The fix is simple: use '$*' consistently.
+
+   Next, with single-quoting, 'capitalize' outputs a single character, a
+set of quotes, then the rest of the characters, making it impossible to
+invoke 'Active' after the fact, and allowing the alternate macro 'A' to
+interfere.  Here, the solution is to use additional quoting in the
+helper macros, then pass the final over-quoted output string through
+'_arg1' to remove the extra quoting and finally invoke the concatenated
+portions as a single string.
+
+   Finally, when passed a double-quoted string, the nested macro
+'_capitalize' is never invoked because it ended up nested inside quotes.
+This one is the toughest to fix.  In short, we have no idea how many
+levels of quotes are in effect on the substring being altered by
+'patsubst'.  If the replacement string cannot be expressed entirely in
+terms of literal text and backslash substitutions, then we need a
+mechanism to guarantee that the helper macros are invoked outside of
+quotes.  In other words, this sounds like a job for 'changequote' (*note
+Changequote::).  By changing the active quoting characters, we can
+guarantee that replacement text injected by 'patsubst' always occurs in
+the middle of a string that has exactly one level of over-quoting using
+alternate quotes; so the replacement text closes the quoted string,
+invokes the helper macros, then reopens the quoted string.  In turn,
+that means the replacement text has unbalanced quotes, necessitating
+another round of 'changequote'.
+
+   In the fixed version below, (also shipped as
+'m4-1.4.17/examples/capitalize2.m4'), 'capitalize' uses the alternate
+quotes of '<<[' and ']>>' (the longer strings are chosen so as to be
+less likely to appear in the text being converted).  The helpers
+'_to_alt' and '_from_alt' merely reduce the number of characters
+required to perform a 'changequote', since the definition changes twice.
+The outermost pair means that 'patsubst' and '_capitalize_alt' are
+invoked with alternate quoting; the innermost pair is used so that the
+third argument to 'patsubst' can contain an unbalanced ']>>'/'<<[' pair.
+Note that 'upcase' and 'downcase' must be redefined as '_upcase_alt' and
+'_downcase_alt', since they contain nested quotes but are invoked with
+the alternate quoting scheme in effect.
+
+     $ m4 -I examples
+     include(`capitalize2.m4')dnl
+     define(`active', `act1, ive')dnl
+     define(`Active', `Act2, Ive')dnl
+     define(`ACTIVE', `ACT3, IVE')dnl
+     define(`A', `OOPS')dnl
+     capitalize(active; `active'; ``active''; ```actIVE''')
+     =>Act1,Ive; Act2, Ive; Active; `Active'
+     undivert(`capitalize2.m4')dnl
+     =>divert(`-1')
+     =># upcase(text)
+     =># downcase(text)
+     =># capitalize(text)
+     =>#   change case of text, improved version
+     =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
+     =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
+     =>define(`_arg1', `$1')
+     =>define(`_to_alt', `changequote(`<<[', `]>>')')
+     =>define(`_from_alt', `changequote(<<[`]>>, <<[']>>)')
+     =>define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)')
+     =>define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)')
+     =>define(`_capitalize_alt',
+     =>  `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>,
+     =>    <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)')
+     =>define(`capitalize',
+     =>  `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>,
+     =>    _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())')
+     =>divert`'dnl
+
+
+File: m4.info,  Node: Improved fatal_error,  Prev: Improved capitalize,  Up: Answers
+
+17.8 Solution for 'fatal_error'
+===============================
+
+The 'fatal_error' macro (*note M4exit::) is not robust to versions of
+GNU M4 earlier than 1.4.8, where invoking '__file__' (*note Location::)
+inside 'm4wrap' would result in an empty string, and '__line__' resulted
+in '0' even though all files start at line 1.  Furthermore, versions
+earlier than 1.4.6 did not support the '__program__' macro.  If you want
+'fatal_error' to work across the entire 1.4.x release series, a better
+implementation would be:
+
+     define(`fatal_error',
+       `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
+     `:ifelse(__line__, `0', `',
+         `__file__:__line__:')` fatal error: $*
+     ')m4exit(`1')')
+     =>
+     m4wrap(`divnum(`demo of internal message')
+     fatal_error(`inside wrapped text')')
+     =>
+     ^D
+     error->m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored
+     =>0
+     error->m4:stdin:6: fatal error: inside wrapped text
+
+
+File: m4.info,  Node: Copying This Package,  Next: Copying This Manual,  Prev: Answers,  Up: Top
+
+Appendix A How to make copies of the overall M4 package
+*******************************************************
+
+This appendix covers the license for copying the source code of the
+overall M4 package.  This manual is under a different set of
+restrictions, covered later (*note Copying This Manual::).
+
+* Menu:
+
+* GNU General Public License::  License for copying the M4 package
+
+
+File: m4.info,  Node: GNU General Public License,  Up: Copying This Package
+
+A.1 License for copying the M4 package
+======================================
+
+                        Version 3, 29 June 2007
+
+     Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+
+     Everyone is permitted to copy and distribute verbatim copies of this
+     license document, but changing it is not allowed.
+
+Preamble
+========
+
+The GNU General Public License is a free, copyleft license for software
+and other kinds of works.
+
+   The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+   When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+   To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+   For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+   Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+   For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+   Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+   Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+   The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+====================
+
+  0. Definitions.
+
+     "This License" refers to version 3 of the GNU General Public
+     License.
+
+     "Copyright" also means copyright-like laws that apply to other
+     kinds of works, such as semiconductor masks.
+
+     "The Program" refers to any copyrightable work licensed under this
+     License.  Each licensee is addressed as "you".  "Licensees" and
+     "recipients" may be individuals or organizations.
+
+     To "modify" a work means to copy from or adapt all or part of the
+     work in a fashion requiring copyright permission, other than the
+     making of an exact copy.  The resulting work is called a "modified
+     version" of the earlier work or a work "based on" the earlier work.
+
+     A "covered work" means either the unmodified Program or a work
+     based on the Program.
+
+     To "propagate" a work means to do anything with it that, without
+     permission, would make you directly or secondarily liable for
+     infringement under applicable copyright law, except executing it on
+     a computer or modifying a private copy.  Propagation includes
+     copying, distribution (with or without modification), making
+     available to the public, and in some countries other activities as
+     well.
+
+     To "convey" a work means any kind of propagation that enables other
+     parties to make or receive copies.  Mere interaction with a user
+     through a computer network, with no transfer of a copy, is not
+     conveying.
+
+     An interactive user interface displays "Appropriate Legal Notices"
+     to the extent that it includes a convenient and prominently visible
+     feature that (1) displays an appropriate copyright notice, and (2)
+     tells the user that there is no warranty for the work (except to
+     the extent that warranties are provided), that licensees may convey
+     the work under this License, and how to view a copy of this
+     License.  If the interface presents a list of user commands or
+     options, such as a menu, a prominent item in the list meets this
+     criterion.
+
+  1. Source Code.
+
+     The "source code" for a work means the preferred form of the work
+     for making modifications to it.  "Object code" means any non-source
+     form of a work.
+
+     A "Standard Interface" means an interface that either is an
+     official standard defined by a recognized standards body, or, in
+     the case of interfaces specified for a particular programming
+     language, one that is widely used among developers working in that
+     language.
+
+     The "System Libraries" of an executable work include anything,
+     other than the work as a whole, that (a) is included in the normal
+     form of packaging a Major Component, but which is not part of that
+     Major Component, and (b) serves only to enable use of the work with
+     that Major Component, or to implement a Standard Interface for
+     which an implementation is available to the public in source code
+     form.  A "Major Component", in this context, means a major
+     essential component (kernel, window system, and so on) of the
+     specific operating system (if any) on which the executable work
+     runs, or a compiler used to produce the work, or an object code
+     interpreter used to run it.
+
+     The "Corresponding Source" for a work in object code form means all
+     the source code needed to generate, install, and (for an executable
+     work) run the object code and to modify the work, including scripts
+     to control those activities.  However, it does not include the
+     work's System Libraries, or general-purpose tools or generally
+     available free programs which are used unmodified in performing
+     those activities but which are not part of the work.  For example,
+     Corresponding Source includes interface definition files associated
+     with source files for the work, and the source code for shared
+     libraries and dynamically linked subprograms that the work is
+     specifically designed to require, such as by intimate data
+     communication or control flow between those subprograms and other
+     parts of the work.
+
+     The Corresponding Source need not include anything that users can
+     regenerate automatically from other parts of the Corresponding
+     Source.
+
+     The Corresponding Source for a work in source code form is that
+     same work.
+
+  2. Basic Permissions.
+
+     All rights granted under this License are granted for the term of
+     copyright on the Program, and are irrevocable provided the stated
+     conditions are met.  This License explicitly affirms your unlimited
+     permission to run the unmodified Program.  The output from running
+     a covered work is covered by this License only if the output, given
+     its content, constitutes a covered work.  This License acknowledges
+     your rights of fair use or other equivalent, as provided by
+     copyright law.
+
+     You may make, run and propagate covered works that you do not
+     convey, without conditions so long as your license otherwise
+     remains in force.  You may convey covered works to others for the
+     sole purpose of having them make modifications exclusively for you,
+     or provide you with facilities for running those works, provided
+     that you comply with the terms of this License in conveying all
+     material for which you do not control copyright.  Those thus making
+     or running the covered works for you must do so exclusively on your
+     behalf, under your direction and control, on terms that prohibit
+     them from making any copies of your copyrighted material outside
+     their relationship with you.
+
+     Conveying under any other circumstances is permitted solely under
+     the conditions stated below.  Sublicensing is not allowed; section
+     10 makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+     No covered work shall be deemed part of an effective technological
+     measure under any applicable law fulfilling obligations under
+     article 11 of the WIPO copyright treaty adopted on 20 December
+     1996, or similar laws prohibiting or restricting circumvention of
+     such measures.
+
+     When you convey a covered work, you waive any legal power to forbid
+     circumvention of technological measures to the extent such
+     circumvention is effected by exercising rights under this License
+     with respect to the covered work, and you disclaim any intention to
+     limit operation or modification of the work as a means of
+     enforcing, against the work's users, your or third parties' legal
+     rights to forbid circumvention of technological measures.
+
+  4. Conveying Verbatim Copies.
+
+     You may convey verbatim copies of the Program's source code as you
+     receive it, in any medium, provided that you conspicuously and
+     appropriately publish on each copy an appropriate copyright notice;
+     keep intact all notices stating that this License and any
+     non-permissive terms added in accord with section 7 apply to the
+     code; keep intact all notices of the absence of any warranty; and
+     give all recipients a copy of this License along with the Program.
+
+     You may charge any price or no price for each copy that you convey,
+     and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+     You may convey a work based on the Program, or the modifications to
+     produce it from the Program, in the form of source code under the
+     terms of section 4, provided that you also meet all of these
+     conditions:
+
+       a. The work must carry prominent notices stating that you
+          modified it, and giving a relevant date.
+
+       b. The work must carry prominent notices stating that it is
+          released under this License and any conditions added under
+          section 7.  This requirement modifies the requirement in
+          section 4 to "keep intact all notices".
+
+       c. You must license the entire work, as a whole, under this
+          License to anyone who comes into possession of a copy.  This
+          License will therefore apply, along with any applicable
+          section 7 additional terms, to the whole of the work, and all
+          its parts, regardless of how they are packaged.  This License
+          gives no permission to license the work in any other way, but
+          it does not invalidate such permission if you have separately
+          received it.
+
+       d. If the work has interactive user interfaces, each must display
+          Appropriate Legal Notices; however, if the Program has
+          interactive interfaces that do not display Appropriate Legal
+          Notices, your work need not make them do so.
+
+     A compilation of a covered work with other separate and independent
+     works, which are not by their nature extensions of the covered
+     work, and which are not combined with it such as to form a larger
+     program, in or on a volume of a storage or distribution medium, is
+     called an "aggregate" if the compilation and its resulting
+     copyright are not used to limit the access or legal rights of the
+     compilation's users beyond what the individual works permit.
+     Inclusion of a covered work in an aggregate does not cause this
+     License to apply to the other parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+     You may convey a covered work in object code form under the terms
+     of sections 4 and 5, provided that you also convey the
+     machine-readable Corresponding Source under the terms of this
+     License, in one of these ways:
+
+       a. Convey the object code in, or embodied in, a physical product
+          (including a physical distribution medium), accompanied by the
+          Corresponding Source fixed on a durable physical medium
+          customarily used for software interchange.
+
+       b. Convey the object code in, or embodied in, a physical product
+          (including a physical distribution medium), accompanied by a
+          written offer, valid for at least three years and valid for as
+          long as you offer spare parts or customer support for that
+          product model, to give anyone who possesses the object code
+          either (1) a copy of the Corresponding Source for all the
+          software in the product that is covered by this License, on a
+          durable physical medium customarily used for software
+          interchange, for a price no more than your reasonable cost of
+          physically performing this conveying of source, or (2) access
+          to copy the Corresponding Source from a network server at no
+          charge.
+
+       c. Convey individual copies of the object code with a copy of the
+          written offer to provide the Corresponding Source.  This
+          alternative is allowed only occasionally and noncommercially,
+          and only if you received the object code with such an offer,
+          in accord with subsection 6b.
+
+       d. Convey the object code by offering access from a designated
+          place (gratis or for a charge), and offer equivalent access to
+          the Corresponding Source in the same way through the same
+          place at no further charge.  You need not require recipients
+          to copy the Corresponding Source along with the object code.
+          If the place to copy the object code is a network server, the
+          Corresponding Source may be on a different server (operated by
+          you or a third party) that supports equivalent copying
+          facilities, provided you maintain clear directions next to the
+          object code saying where to find the Corresponding Source.
+          Regardless of what server hosts the Corresponding Source, you
+          remain obligated to ensure that it is available for as long as
+          needed to satisfy these requirements.
+
+       e. Convey the object code using peer-to-peer transmission,
+          provided you inform other peers where the object code and
+          Corresponding Source of the work are being offered to the
+          general public at no charge under subsection 6d.
+
+     A separable portion of the object code, whose source code is
+     excluded from the Corresponding Source as a System Library, need
+     not be included in conveying the object code work.
+
+     A "User Product" is either (1) a "consumer product", which means
+     any tangible personal property which is normally used for personal,
+     family, or household purposes, or (2) anything designed or sold for
+     incorporation into a dwelling.  In determining whether a product is
+     a consumer product, doubtful cases shall be resolved in favor of
+     coverage.  For a particular product received by a particular user,
+     "normally used" refers to a typical or common use of that class of
+     product, regardless of the status of the particular user or of the
+     way in which the particular user actually uses, or expects or is
+     expected to use, the product.  A product is a consumer product
+     regardless of whether the product has substantial commercial,
+     industrial or non-consumer uses, unless such uses represent the
+     only significant mode of use of the product.
+
+     "Installation Information" for a User Product means any methods,
+     procedures, authorization keys, or other information required to
+     install and execute modified versions of a covered work in that
+     User Product from a modified version of its Corresponding Source.
+     The information must suffice to ensure that the continued
+     functioning of the modified object code is in no case prevented or
+     interfered with solely because modification has been made.
+
+     If you convey an object code work under this section in, or with,
+     or specifically for use in, a User Product, and the conveying
+     occurs as part of a transaction in which the right of possession
+     and use of the User Product is transferred to the recipient in
+     perpetuity or for a fixed term (regardless of how the transaction
+     is characterized), the Corresponding Source conveyed under this
+     section must be accompanied by the Installation Information.  But
+     this requirement does not apply if neither you nor any third party
+     retains the ability to install modified object code on the User
+     Product (for example, the work has been installed in ROM).
+
+     The requirement to provide Installation Information does not
+     include a requirement to continue to provide support service,
+     warranty, or updates for a work that has been modified or installed
+     by the recipient, or for the User Product in which it has been
+     modified or installed.  Access to a network may be denied when the
+     modification itself materially and adversely affects the operation
+     of the network or violates the rules and protocols for
+     communication across the network.
+
+     Corresponding Source conveyed, and Installation Information
+     provided, in accord with this section must be in a format that is
+     publicly documented (and with an implementation available to the
+     public in source code form), and must require no special password
+     or key for unpacking, reading or copying.
+
+  7. Additional Terms.
+
+     "Additional permissions" are terms that supplement the terms of
+     this License by making exceptions from one or more of its
+     conditions.  Additional permissions that are applicable to the
+     entire Program shall be treated as though they were included in
+     this License, to the extent that they are valid under applicable
+     law.  If additional permissions apply only to part of the Program,
+     that part may be used separately under those permissions, but the
+     entire Program remains governed by this License without regard to
+     the additional permissions.
+
+     When you convey a copy of a covered work, you may at your option
+     remove any additional permissions from that copy, or from any part
+     of it.  (Additional permissions may be written to require their own
+     removal in certain cases when you modify the work.)  You may place
+     additional permissions on material, added by you to a covered work,
+     for which you have or can give appropriate copyright permission.
+
+     Notwithstanding any other provision of this License, for material
+     you add to a covered work, you may (if authorized by the copyright
+     holders of that material) supplement the terms of this License with
+     terms:
+
+       a. Disclaiming warranty or limiting liability differently from
+          the terms of sections 15 and 16 of this License; or
+
+       b. Requiring preservation of specified reasonable legal notices
+          or author attributions in that material or in the Appropriate
+          Legal Notices displayed by works containing it; or
+
+       c. Prohibiting misrepresentation of the origin of that material,
+          or requiring that modified versions of such material be marked
+          in reasonable ways as different from the original version; or
+
+       d. Limiting the use for publicity purposes of names of licensors
+          or authors of the material; or
+
+       e. Declining to grant rights under trademark law for use of some
+          trade names, trademarks, or service marks; or
+
+       f. Requiring indemnification of licensors and authors of that
+          material by anyone who conveys the material (or modified
+          versions of it) with contractual assumptions of liability to
+          the recipient, for any liability that these contractual
+          assumptions directly impose on those licensors and authors.
+
+     All other non-permissive additional terms are considered "further
+     restrictions" within the meaning of section 10.  If the Program as
+     you received it, or any part of it, contains a notice stating that
+     it is governed by this License along with a term that is a further
+     restriction, you may remove that term.  If a license document
+     contains a further restriction but permits relicensing or conveying
+     under this License, you may add to a covered work material governed
+     by the terms of that license document, provided that the further
+     restriction does not survive such relicensing or conveying.
+
+     If you add terms to a covered work in accord with this section, you
+     must place, in the relevant source files, a statement of the
+     additional terms that apply to those files, or a notice indicating
+     where to find the applicable terms.
+
+     Additional terms, permissive or non-permissive, may be stated in
+     the form of a separately written license, or stated as exceptions;
+     the above requirements apply either way.
+
+  8. Termination.
+
+     You may not propagate or modify a covered work except as expressly
+     provided under this License.  Any attempt otherwise to propagate or
+     modify it is void, and will automatically terminate your rights
+     under this License (including any patent licenses granted under the
+     third paragraph of section 11).
+
+     However, if you cease all violation of this License, then your
+     license from a particular copyright holder is reinstated (a)
+     provisionally, unless and until the copyright holder explicitly and
+     finally terminates your license, and (b) permanently, if the
+     copyright holder fails to notify you of the violation by some
+     reasonable means prior to 60 days after the cessation.
+
+     Moreover, your license from a particular copyright holder is
+     reinstated permanently if the copyright holder notifies you of the
+     violation by some reasonable means, this is the first time you have
+     received notice of violation of this License (for any work) from
+     that copyright holder, and you cure the violation prior to 30 days
+     after your receipt of the notice.
+
+     Termination of your rights under this section does not terminate
+     the licenses of parties who have received copies or rights from you
+     under this License.  If your rights have been terminated and not
+     permanently reinstated, you do not qualify to receive new licenses
+     for the same material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+     You are not required to accept this License in order to receive or
+     run a copy of the Program.  Ancillary propagation of a covered work
+     occurring solely as a consequence of using peer-to-peer
+     transmission to receive a copy likewise does not require
+     acceptance.  However, nothing other than this License grants you
+     permission to propagate or modify any covered work.  These actions
+     infringe copyright if you do not accept this License.  Therefore,
+     by modifying or propagating a covered work, you indicate your
+     acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+     Each time you convey a covered work, the recipient automatically
+     receives a license from the original licensors, to run, modify and
+     propagate that work, subject to this License.  You are not
+     responsible for enforcing compliance by third parties with this
+     License.
+
+     An "entity transaction" is a transaction transferring control of an
+     organization, or substantially all assets of one, or subdividing an
+     organization, or merging organizations.  If propagation of a
+     covered work results from an entity transaction, each party to that
+     transaction who receives a copy of the work also receives whatever
+     licenses to the work the party's predecessor in interest had or
+     could give under the previous paragraph, plus a right to possession
+     of the Corresponding Source of the work from the predecessor in
+     interest, if the predecessor has it or can get it with reasonable
+     efforts.
+
+     You may not impose any further restrictions on the exercise of the
+     rights granted or affirmed under this License.  For example, you
+     may not impose a license fee, royalty, or other charge for exercise
+     of rights granted under this License, and you may not initiate
+     litigation (including a cross-claim or counterclaim in a lawsuit)
+     alleging that any patent claim is infringed by making, using,
+     selling, offering for sale, or importing the Program or any portion
+     of it.
+
+  11. Patents.
+
+     A "contributor" is a copyright holder who authorizes use under this
+     License of the Program or a work on which the Program is based.
+     The work thus licensed is called the contributor's "contributor
+     version".
+
+     A contributor's "essential patent claims" are all patent claims
+     owned or controlled by the contributor, whether already acquired or
+     hereafter acquired, that would be infringed by some manner,
+     permitted by this License, of making, using, or selling its
+     contributor version, but do not include claims that would be
+     infringed only as a consequence of further modification of the
+     contributor version.  For purposes of this definition, "control"
+     includes the right to grant patent sublicenses in a manner
+     consistent with the requirements of this License.
+
+     Each contributor grants you a non-exclusive, worldwide,
+     royalty-free patent license under the contributor's essential
+     patent claims, to make, use, sell, offer for sale, import and
+     otherwise run, modify and propagate the contents of its contributor
+     version.
+
+     In the following three paragraphs, a "patent license" is any
+     express agreement or commitment, however denominated, not to
+     enforce a patent (such as an express permission to practice a
+     patent or covenant not to sue for patent infringement).  To "grant"
+     such a patent license to a party means to make such an agreement or
+     commitment not to enforce a patent against the party.
+
+     If you convey a covered work, knowingly relying on a patent
+     license, and the Corresponding Source of the work is not available
+     for anyone to copy, free of charge and under the terms of this
+     License, through a publicly available network server or other
+     readily accessible means, then you must either (1) cause the
+     Corresponding Source to be so available, or (2) arrange to deprive
+     yourself of the benefit of the patent license for this particular
+     work, or (3) arrange, in a manner consistent with the requirements
+     of this License, to extend the patent license to downstream
+     recipients.  "Knowingly relying" means you have actual knowledge
+     that, but for the patent license, your conveying the covered work
+     in a country, or your recipient's use of the covered work in a
+     country, would infringe one or more identifiable patents in that
+     country that you have reason to believe are valid.
+
+     If, pursuant to or in connection with a single transaction or
+     arrangement, you convey, or propagate by procuring conveyance of, a
+     covered work, and grant a patent license to some of the parties
+     receiving the covered work authorizing them to use, propagate,
+     modify or convey a specific copy of the covered work, then the
+     patent license you grant is automatically extended to all
+     recipients of the covered work and works based on it.
+
+     A patent license is "discriminatory" if it does not include within
+     the scope of its coverage, prohibits the exercise of, or is
+     conditioned on the non-exercise of one or more of the rights that
+     are specifically granted under this License.  You may not convey a
+     covered work if you are a party to an arrangement with a third
+     party that is in the business of distributing software, under which
+     you make payment to the third party based on the extent of your
+     activity of conveying the work, and under which the third party
+     grants, to any of the parties who would receive the covered work
+     from you, a discriminatory patent license (a) in connection with
+     copies of the covered work conveyed by you (or copies made from
+     those copies), or (b) primarily for and in connection with specific
+     products or compilations that contain the covered work, unless you
+     entered into that arrangement, or that patent license was granted,
+     prior to 28 March 2007.
+
+     Nothing in this License shall be construed as excluding or limiting
+     any implied license or other defenses to infringement that may
+     otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+     If conditions are imposed on you (whether by court order, agreement
+     or otherwise) that contradict the conditions of this License, they
+     do not excuse you from the conditions of this License.  If you
+     cannot convey a covered work so as to satisfy simultaneously your
+     obligations under this License and any other pertinent obligations,
+     then as a consequence you may not convey it at all.  For example,
+     if you agree to terms that obligate you to collect a royalty for
+     further conveying from those to whom you convey the Program, the
+     only way you could satisfy both those terms and this License would
+     be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+     Notwithstanding any other provision of this License, you have
+     permission to link or combine any covered work with a work licensed
+     under version 3 of the GNU Affero General Public License into a
+     single combined work, and to convey the resulting work.  The terms
+     of this License will continue to apply to the part which is the
+     covered work, but the special requirements of the GNU Affero
+     General Public License, section 13, concerning interaction through
+     a network will apply to the combination as such.
+
+  14. Revised Versions of this License.
+
+     The Free Software Foundation may publish revised and/or new
+     versions of the GNU General Public License from time to time.  Such
+     new versions will be similar in spirit to the present version, but
+     may differ in detail to address new problems or concerns.
+
+     Each version is given a distinguishing version number.  If the
+     Program specifies that a certain numbered version of the GNU
+     General Public License "or any later version" applies to it, you
+     have the option of following the terms and conditions either of
+     that numbered version or of any later version published by the Free
+     Software Foundation.  If the Program does not specify a version
+     number of the GNU General Public License, you may choose any
+     version ever published by the Free Software Foundation.
+
+     If the Program specifies that a proxy can decide which future
+     versions of the GNU General Public License can be used, that
+     proxy's public statement of acceptance of a version permanently
+     authorizes you to choose that version for the Program.
+
+     Later license versions may give you additional or different
+     permissions.  However, no additional obligations are imposed on any
+     author or copyright holder as a result of your choosing to follow a
+     later version.
+
+  15. Disclaimer of Warranty.
+
+     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+     APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
+     COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
+     WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
+     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
+     RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
+     SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+     NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
+     AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
+     DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
+     THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
+     BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+     PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+     PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
+     THE POSSIBILITY OF SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+     If the disclaimer of warranty and limitation of liability provided
+     above cannot be given local legal effect according to their terms,
+     reviewing courts shall apply local law that most closely
+     approximates an absolute waiver of all civil liability in
+     connection with the Program, unless a warranty or assumption of
+     liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+===========================
+
+How to Apply These Terms to Your New Programs
+=============================================
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+   To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
+     Copyright (C) YEAR NAME OF AUTHOR
+
+     This program is free software: you can redistribute it and/or modify
+     it under the terms of the GNU General Public License as published by
+     the Free Software Foundation, either version 3 of the License, or (at
+     your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+   Also add information on how to contact you by electronic and paper
+mail.
+
+   If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+     PROGRAM Copyright (C) YEAR NAME OF AUTHOR
+     This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
+     This is free software, and you are welcome to redistribute it
+     under certain conditions; type 'show c' for details.
+
+   The hypothetical commands 'show w' and 'show c' should show the
+appropriate parts of the General Public License.  Of course, your
+program's commands might be different; for a GUI interface, you would
+use an "about box".
+
+   You should also get your employer (if you work as a programmer) or
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  For more information on this, and how to apply and follow
+the GNU GPL, see <http://www.gnu.org/licenses/>.
+
+   The GNU General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may 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.  But first,
+please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.
+
diff --git a/doc/m4.info-2 b/doc/m4.info-2
new file mode 100644
index 0000000..84921f0
--- /dev/null
+++ b/doc/m4.info-2
@@ -0,0 +1,923 @@
+This is m4.info, produced by makeinfo version 5.1 from m4.texi.
+
+This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
+package containing an implementation of the m4 macro language.
+
+   Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; 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."
+INFO-DIR-SECTION Text creation and manipulation
+START-INFO-DIR-ENTRY
+* M4: (m4).                     A powerful macro processor.
+END-INFO-DIR-ENTRY
+
+
+File: m4.info,  Node: Copying This Manual,  Next: Indices,  Prev: Copying This Package,  Up: Top
+
+Appendix B How to make copies of this manual
+********************************************
+
+This appendix covers the license for copying this manual.  Note that
+some of the longer examples in this manual are also distributed in the
+directory 'm4-1.4.17/examples/', where a more permissive license is in
+effect when copying just the examples.
+
+* Menu:
+
+* GNU Free Documentation License::  License for copying this manual
+
+
+File: m4.info,  Node: GNU Free Documentation License,  Up: Copying This Manual
+
+B.1 License for copying this manual
+===================================
+
+                     Version 1.3, 3 November 2008
+
+     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+     <http://fsf.org/>
+
+     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
+     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.
+     It complements the GNU General Public License, which is a copyleft
+     license designed for free software.
+
+     We have designed this License in order to use it for manuals for
+     free software, because free software needs free documentation: a
+     free program should come with manuals providing the same freedoms
+     that the software does.  But this License is not limited to
+     software manuals; 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.
+
+  1. APPLICABILITY AND DEFINITIONS
+
+     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.  (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.
+     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.  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, 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, 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, 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
+     material 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.
+
+     The "publisher" means any person or entity that distributes copies
+     of the Document to the public.
+
+     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
+     commercially or noncommercially, provided that this License, the
+     copyright notices, and the license notice saying this License
+     applies to the Document are reproduced in all copies, and that you
+     add no other conditions whatsoever to those of this License.  You
+     may not use technical measures to obstruct or control the reading
+     or further copying of the copies you make or distribute.  However,
+     you may accept compensation in exchange for copies.  If you
+     distribute a large enough 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.
+
+  3. COPYING IN QUANTITY
+
+     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 title
+     equally prominent and visible.  You may add other material on the
+     covers in addition.  Copying with changes limited to the covers, as
+     long as they preserve the title of the Document and satisfy these
+     conditions, can be treated as verbatim copying in other respects.
+
+     If the required texts for either cover are too voluminous to fit
+     legibly, you should put the first ones listed (as many as fit
+     reasonably) on the actual cover, and continue the rest onto
+     adjacent 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 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.
+
+  4. MODIFICATIONS
+
+     You may copy and distribute a Modified Version of the Document
+     under the conditions of sections 2 and 3 above, provided that you
+     release the Modified Version under precisely this License, with the
+     Modified Version filling the role of the Document, thus licensing
+     distribution and modification of the Modified Version to whoever
+     possesses a copy of it.  In addition, you must do these things in
+     the Modified Version:
+
+       A. Use in the Title Page (and on the covers, if any) a title
+          distinct from that of the Document, and from those of previous
+          versions (which should, if there were any, be listed in the
+          History section of the Document).  You may use the same title
+          as a previous version if the original publisher of that
+          version gives permission.
+
+       B. 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 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.
+
+       D. Preserve all the copyright notices of the Document.
+
+       E. Add an appropriate copyright notice for your modifications
+          adjacent to the other copyright notices.
+
+       F. Include, immediately after the copyright notices, a license
+          notice giving the public permission to use the Modified
+          Version under the terms of this License, in the form shown in
+          the Addendum below.
+
+       G. Preserve in that license notice the full lists of Invariant
+          Sections and required Cover Texts given in the Document's
+          license notice.
+
+       H. Include an unaltered copy of this License.
+
+       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
+          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.
+
+       J. Preserve the network location, if any, given in the Document
+          for public access to a Transparent copy of the Document, and
+          likewise the network locations given in the Document for
+          previous versions it was based on.  These may be placed in the
+          "History" section.  You may omit a network location for a work
+          that was published at least four years before the Document
+          itself, or if the original publisher of the version it refers
+          to gives permission.
+
+       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, unaltered
+          in their text and in their titles.  Section numbers or the
+          equivalent are not considered part of the section titles.
+
+       M. Delete any section Entitled "Endorsements".  Such a section
+          may not be included in the Modified Version.
+
+       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
+     material copied from the Document, you may at your option designate
+     some or all 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
+     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.
+
+     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 of
+     the list of Cover Texts in the Modified Version.  Only one passage
+     of Front-Cover Text and one of Back-Cover Text may be added by (or
+     through arrangements made by) any one entity.  If the Document
+     already includes a cover text for the same cover, previously added
+     by you or by arrangement made by the same entity you are acting on
+     behalf of, you may not add another; but you may replace the old
+     one, on explicit 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.
+
+  5. COMBINING DOCUMENTS
+
+     You may combine the Document with other documents released under
+     this 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, 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
+     copy.  If there are multiple Invariant Sections with the same name
+     but different contents, make the title of each such section unique
+     by adding at the end of it, in parentheses, the name of the
+     original 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."
+
+  6. COLLECTIONS OF DOCUMENTS
+
+     You may make a collection consisting of the Document and other
+     documents released under this License, and replace the individual
+     copies of this License in the various documents with a single copy
+     that is included in the collection, provided that you follow the
+     rules of this License for verbatim copying of each of the documents
+     in all other respects.
+
+     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.
+
+  7. 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, 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 in 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 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
+
+     Translation is considered a kind of modification, so you may
+     distribute translations of the Document under the terms of section
+     4.  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, and all the license notices in the
+     Document, and any Warranty 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
+
+     You may not copy, modify, sublicense, or distribute the Document
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense, or distribute it is void,
+     and will automatically terminate your rights under this License.
+
+     However, if you cease all violation of this License, then your
+     license from a particular copyright holder is reinstated (a)
+     provisionally, unless and until the copyright holder explicitly and
+     finally terminates your license, and (b) permanently, if the
+     copyright holder fails to notify you of the violation by some
+     reasonable means prior to 60 days after the cessation.
+
+     Moreover, your license from a particular copyright holder is
+     reinstated permanently if the copyright holder notifies you of the
+     violation by some reasonable means, this is the first time you have
+     received notice of violation of this License (for any work) from
+     that copyright holder, and you cure the violation prior to 30 days
+     after your receipt of the notice.
+
+     Termination of your rights under this section does not terminate
+     the licenses of parties who have received copies or rights from you
+     under this License.  If your rights have been terminated and not
+     permanently reinstated, receipt of a copy of some or all of the
+     same material does not give you any rights to use it.
+
+  10. FUTURE REVISIONS OF THIS LICENSE
+
+     The Free Software Foundation may publish new, revised versions of
+     the GNU Free Documentation License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.  See
+     <http://www.gnu.org/copyleft/>.
+
+     Each version of the License is given a distinguishing version
+     number.  If the Document specifies that a particular numbered
+     version of this License "or any later version" applies to it, you
+     have the option of following the terms and conditions either of
+     that specified version or 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.  If the Document specifies that a proxy can
+     decide which future versions of this License can be used, that
+     proxy's public statement of acceptance of a version permanently
+     authorizes you to choose that version for the Document.
+
+  11. RELICENSING
+
+     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+     World Wide Web server that publishes copyrightable works and also
+     provides prominent facilities for anybody to edit those works.  A
+     public wiki that anybody can edit is an example of such a server.
+     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+     site means any set of copyrightable works thus published on the MMC
+     site.
+
+     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+     license published by Creative Commons Corporation, a not-for-profit
+     corporation with a principal place of business in San Francisco,
+     California, as well as future copyleft versions of that license
+     published by that same organization.
+
+     "Incorporate" means to publish or republish a Document, in whole or
+     in part, as part of another Document.
+
+     An MMC is "eligible for relicensing" if it is licensed under this
+     License, and if all works that were first published under this
+     License somewhere other than this MMC, and subsequently
+     incorporated in whole or in part into the MMC, (1) had no cover
+     texts or invariant sections, and (2) were thus incorporated prior
+     to November 1, 2008.
+
+     The operator of an MMC Site may republish an MMC contained in the
+     site under CC-BY-SA on the same site at any time before August 1,
+     2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+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.3
+       or any later version published by the Free Software Foundation;
+       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 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 free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+File: m4.info,  Node: Indices,  Prev: Copying This Manual,  Up: Top
+
+Appendix C Indices of concepts and macros
+*****************************************
+
+* Menu:
+
+* Macro index::                 Index for all 'm4' macros
+* Concept index::               Index for many concepts
+
+
+File: m4.info,  Node: Macro index,  Next: Concept index,  Up: Indices
+
+C.1 Index for all 'm4' macros
+=============================
+
+This index covers all 'm4' builtins, as well as several useful composite
+macros.  References are exclusively to the places where a macro is
+introduced the first time.
+
+
+* Menu:
+
+* __file__:                              Location.            (line   9)
+* __gnu__:                               Platform macros.     (line  11)
+* __line__:                              Location.            (line  10)
+* __os2__:                               Platform macros.     (line  12)
+* __program__:                           Location.            (line  11)
+* __unix__:                              Platform macros.     (line  14)
+* __windows__:                           Platform macros.     (line  16)
+* argn:                                  Shift.               (line 255)
+* array:                                 Define.              (line  55)
+* array_set:                             Define.              (line  56)
+* builtin:                               Builtin.             (line   8)
+* capitalize:                            Patsubst.            (line  54)
+* changecom:                             Changecom.           (line   9)
+* changequote:                           Changequote.         (line   9)
+* changeword:                            Changeword.          (line  22)
+* cleardivert:                           Cleardivert.         (line  25)
+* cond:                                  Shift.               (line  51)
+* copy:                                  Composition.         (line 119)
+* curry:                                 Composition.         (line  67)
+* debugfile:                             Debug Output.        (line  10)
+* debugmode:                             Debug Levels.        (line  77)
+* decr:                                  Incr.                (line  10)
+* define:                                Define.              (line   9)
+* define_blind:                          Composition.         (line  10)
+* defn:                                  Defn.                (line   9)
+* divert:                                Divert.              (line   8)
+* divnum:                                Divnum.              (line   8)
+* dnl:                                   Dnl.                 (line   8)
+* downcase:                              Patsubst.            (line  53)
+* dquote:                                Shift.               (line 193)
+* dquote_elt:                            Shift.               (line 194)
+* dumpdef:                               Dumpdef.             (line   9)
+* errprint:                              Errprint.            (line   8)
+* esyscmd:                               Esyscmd.             (line   8)
+* eval:                                  Eval.                (line   8)
+* example:                               Manual.              (line  39)
+* exch:                                  Arguments.           (line  12)
+* fatal_error:                           M4exit.              (line  24)
+* foreach:                               Foreach.             (line   8)
+* foreachq:                              Foreach.             (line   9)
+* forloop:                               Forloop.             (line   8)
+* format:                                Format.              (line   8)
+* ifdef:                                 Ifdef.               (line   9)
+* ifelse:                                Ifelse.              (line  10)
+* ifelse <1>:                            Ifelse.              (line  11)
+* ifelse <2>:                            Ifelse.              (line  12)
+* include:                               Include.             (line   8)
+* incr:                                  Incr.                (line   9)
+* index:                                 Index macro.         (line   8)
+* indir:                                 Indir.               (line   8)
+* join:                                  Shift.               (line 101)
+* joinall:                               Shift.               (line 102)
+* len:                                   Len.                 (line   8)
+* m4exit:                                M4exit.              (line   9)
+* m4wrap:                                M4wrap.              (line  13)
+* maketemp:                              Mkstemp.             (line  11)
+* mkstemp:                               Mkstemp.             (line  10)
+* nargs:                                 Pseudo Arguments.    (line  12)
+* os2:                                   Platform macros.     (line  13)
+* patsubst:                              Patsubst.            (line   8)
+* popdef:                                Pushdef.             (line  11)
+* pushdef:                               Pushdef.             (line  10)
+* quote:                                 Shift.               (line 192)
+* regexp:                                Regexp.              (line   8)
+* rename:                                Composition.         (line 120)
+* reverse:                               Shift.               (line  31)
+* shift:                                 Shift.               (line  16)
+* sinclude:                              Include.             (line   9)
+* stack_foreach:                         Stacks.              (line  11)
+* stack_foreach_lifo:                    Stacks.              (line  12)
+* stack_foreach_sep:                     Improved copy.       (line  15)
+* stack_foreach_sep_lifo:                Improved copy.       (line  16)
+* substr:                                Substr.              (line   8)
+* syscmd:                                Syscmd.              (line   8)
+* sysval:                                Sysval.              (line   8)
+* traceoff:                              Trace.               (line  10)
+* traceon:                               Trace.               (line   9)
+* translit:                              Translit.            (line   8)
+* undefine:                              Undefine.            (line   8)
+* undivert:                              Undivert.            (line   8)
+* unix:                                  Platform macros.     (line  15)
+* upcase:                                Patsubst.            (line  52)
+* windows:                               Platform macros.     (line  17)
+
+
+File: m4.info,  Node: Concept index,  Prev: Macro index,  Up: Indices
+
+C.2 Index for many concepts
+===========================
+
+
+* Menu:
+
+* argument currying:                     Composition.         (line  63)
+* arguments to macros:                   Macro Arguments.     (line   6)
+* arguments to macros <1>:               Arguments.           (line   6)
+* arguments to macros, special:          Pseudo Arguments.    (line   6)
+* arguments, joining:                    Shift.               (line  98)
+* arguments, more than nine:             Arguments.           (line  54)
+* arguments, more than nine <1>:         Shift.               (line 250)
+* arguments, more than nine <2>:         Improved foreach.    (line 156)
+* arguments, quoted macro:               Quoting Arguments.   (line   6)
+* arguments, reversing:                  Shift.               (line  31)
+* arithmetic:                            Arithmetic.          (line   6)
+* arrays:                                Define.              (line  52)
+* avoiding quadratic behavior:           Improved foreach.    (line  38)
+* basic regular expressions:             Regexp.              (line   6)
+* basic regular expressions <1>:         Patsubst.            (line   6)
+* blind macro:                           Inhibiting Invocation.
+                                                              (line  13)
+* blind macro <1>:                       Ifelse.              (line  52)
+* blind macro <2>:                       Composition.         (line  10)
+* bug reports:                           Bugs.                (line   6)
+* builtins, indirect call of:            Builtin.             (line   6)
+* builtins, special tokens:              Defn.                (line 101)
+* call of builtins, indirect:            Builtin.             (line   6)
+* call of macros, indirect:              Indir.               (line   6)
+* case statement:                        Ifelse.              (line  69)
+* changing comment delimiters:           Changecom.           (line   6)
+* changing quote delimiters:             Changequote.         (line   6)
+* changing syntax:                       Changeword.          (line   6)
+* characters, translating:               Translit.            (line   6)
+* command line:                          Invoking m4.         (line   6)
+* command line, file names on the:       Command line files.  (line   6)
+* command line, macro definitions on the: Preprocessor features.
+                                                              (line   6)
+* command line, options:                 Invoking m4.         (line  10)
+* commands, exit status from shell:      Sysval.              (line   6)
+* commands, running shell:               Shell commands.      (line   6)
+* comment delimiters, changing:          Changecom.           (line   6)
+* comments:                              Comments.            (line   6)
+* comments, copied to output:            Changecom.           (line  29)
+* comparing strings:                     Ifelse.              (line   6)
+* compatibility:                         Compatibility.       (line   6)
+* composing macros:                      Composition.         (line   6)
+* concatenating arguments:               Shift.               (line  98)
+* conditional, short-circuiting:         Shift.               (line  51)
+* conditionals:                          Ifdef.               (line   6)
+* controlling debugging output:          Debug Levels.        (line   6)
+* copying macros:                        Composition.         (line 116)
+* counting loops:                        Forloop.             (line   6)
+* currying arguments:                    Composition.         (line  63)
+* debugging macros:                      Debugging.           (line   6)
+* debugging output, controlling:         Debug Levels.        (line   6)
+* debugging output, saving:              Debug Output.        (line   6)
+* decrement operator:                    Incr.                (line   6)
+* deferring expansion:                   M4wrap.              (line   6)
+* deferring output:                      Diversions.          (line   6)
+* defining new macros:                   Definitions.         (line   6)
+* definition stack:                      Pushdef.             (line   6)
+* definition stack <1>:                  Stacks.              (line   6)
+* definitions, displaying macro:         Defn.                (line   6)
+* definitions, displaying macro <1>:     Dumpdef.             (line   6)
+* deleting macros:                       Undefine.            (line   6)
+* deleting whitespace in input:          Dnl.                 (line   6)
+* delimiters, changing:                  Changequote.         (line   6)
+* delimiters, changing <1>:              Changecom.           (line   6)
+* discarding diverted text:              Cleardivert.         (line   6)
+* discarding input:                      Ifelse.              (line   6)
+* discarding input <1>:                  Dnl.                 (line   6)
+* discarding input <2>:                  Divert.              (line  42)
+* displaying macro definitions:          Dumpdef.             (line   6)
+* diversion numbers:                     Divnum.              (line   6)
+* diverted text, discarding:             Cleardivert.         (line   6)
+* diverting output to files:             Divert.              (line   6)
+* dumping into frozen file:              Using frozen files.  (line   6)
+* error messages, printing:              Errprint.            (line   6)
+* errors, fatal:                         Operation modes.     (line  19)
+* evaluation, of integer expressions:    Eval.                (line   6)
+* examples, understanding:               Manual.              (line   6)
+* executing shell commands:              Shell commands.      (line   6)
+* exit status from shell commands:       Sysval.              (line   6)
+* exiting from 'm4':                     M4exit.              (line   6)
+* expansion of macros:                   Macro expansion.     (line   6)
+* expansion, deferring:                  M4wrap.              (line   6)
+* expansion, tracing macro:              Trace.               (line   6)
+* expressions, evaluation of integer:    Eval.                (line   6)
+* expressions, regular:                  Regexp.              (line   6)
+* expressions, regular <1>:              Patsubst.            (line   6)
+* extracting substrings:                 Substr.              (line   6)
+* fast loading of frozen files:          Using frozen files.  (line   6)
+* fatal errors:                          Operation modes.     (line  19)
+* FDL, GNU Free Documentation License:   GNU Free Documentation License.
+                                                              (line   6)
+* file format, frozen file:              Frozen file format.  (line   6)
+* file inclusion:                        File Inclusion.      (line   6)
+* file inclusion <1>:                    Undivert.            (line  13)
+* file inclusion <2>:                    Undivert.            (line  89)
+* file names, on the command line:       Command line files.  (line   6)
+* files, diverting output to:            Divert.              (line   6)
+* files, names of temporary:             Mkstemp.             (line   6)
+* for each loops:                        Foreach.             (line   6)
+* for loops:                             Forloop.             (line   6)
+* formatted output:                      Format.              (line   6)
+* Free Documentation License (FDL), GNU: GNU Free Documentation License.
+                                                              (line   6)
+* frozen file format:                    Frozen file format.  (line   6)
+* frozen files for fast loading:         Using frozen files.  (line   6)
+* General Public License (GPL), GNU:     GNU General Public License.
+                                                              (line   6)
+* GNU extensions:                        Inhibiting Invocation.
+                                                              (line  13)
+* GNU extensions <1>:                    Define.              (line  41)
+* GNU extensions <2>:                    Arguments.           (line  54)
+* GNU extensions <3>:                    Indir.               (line   6)
+* GNU extensions <4>:                    Builtin.             (line   6)
+* GNU extensions <5>:                    Debug Levels.        (line  74)
+* GNU extensions <6>:                    Debug Output.        (line   6)
+* GNU extensions <7>:                    Search Path.         (line   6)
+* GNU extensions <8>:                    Divert.              (line  54)
+* GNU extensions <9>:                    Undivert.            (line  13)
+* GNU extensions <10>:                   Undivert.            (line  89)
+* GNU extensions <11>:                   Regexp.              (line   6)
+* GNU extensions <12>:                   Patsubst.            (line   6)
+* GNU extensions <13>:                   Format.              (line   6)
+* GNU extensions <14>:                   Eval.                (line 113)
+* GNU extensions <15>:                   Esyscmd.             (line   6)
+* GNU extensions <16>:                   Mkstemp.             (line  58)
+* GNU extensions <17>:                   Using frozen files.  (line   6)
+* GNU extensions <18>:                   Extensions.          (line   6)
+* GNU Free Documentation License:        GNU Free Documentation License.
+                                                              (line   6)
+* GNU General Public License:            GNU General Public License.
+                                                              (line   6)
+* GNU M4, history of:                    History.             (line   6)
+* GPL, GNU General Public License:       GNU General Public License.
+                                                              (line   6)
+* history of 'm4':                       History.             (line   6)
+* included files, search path for:       Search Path.         (line   6)
+* inclusion, of files:                   File Inclusion.      (line   6)
+* inclusion, of files <1>:               Undivert.            (line  13)
+* inclusion, of files <2>:               Undivert.            (line  89)
+* increment operator:                    Incr.                (line   6)
+* indirect call of builtins:             Builtin.             (line   6)
+* indirect call of macros:               Indir.               (line   6)
+* initialization, frozen state:          Using frozen files.  (line   6)
+* input location:                        Preprocessor features.
+                                                              (line  28)
+* input location <1>:                    Location.            (line   6)
+* input tokens:                          Syntax.              (line   6)
+* input, discarding:                     Ifelse.              (line   6)
+* input, discarding <1>:                 Dnl.                 (line   6)
+* input, discarding <2>:                 Divert.              (line  42)
+* input, saving:                         M4wrap.              (line   6)
+* integer arithmetic:                    Arithmetic.          (line   6)
+* integer expression evaluation:         Eval.                (line   6)
+* invoking 'm4':                         Invoking m4.         (line   6)
+* invoking macros:                       Invocation.          (line   6)
+* iterating over lists:                  Foreach.             (line   6)
+* joining arguments:                     Shift.               (line  98)
+* length of strings:                     Len.                 (line   6)
+* lexical structure of words:            Changeword.          (line   6)
+* License, code:                         Copying This Package.
+                                                              (line   6)
+* License, manual:                       Copying This Manual. (line   6)
+* limit, nesting:                        Limits control.      (line  43)
+* literal output:                        Pseudo Arguments.    (line 106)
+* local variables:                       Pushdef.             (line  79)
+* location, input:                       Preprocessor features.
+                                                              (line  28)
+* location, input <1>:                   Location.            (line   6)
+* loops:                                 Shift.               (line  10)
+* loops, counting:                       Forloop.             (line   6)
+* loops, list iteration:                 Foreach.             (line   6)
+* 'M4PATH':                              Search Path.         (line   9)
+* macro composition:                     Composition.         (line   6)
+* macro definitions, on the command line: Preprocessor features.
+                                                              (line   6)
+* macro expansion, tracing:              Trace.               (line   6)
+* macro invocation:                      Invocation.          (line   6)
+* macro, blind:                          Inhibiting Invocation.
+                                                              (line  13)
+* macro, blind <1>:                      Ifelse.              (line  52)
+* macro, blind <2>:                      Composition.         (line  10)
+* macros, arguments to:                  Macro Arguments.     (line   6)
+* macros, arguments to <1>:              Arguments.           (line   6)
+* macros, copying:                       Composition.         (line 116)
+* macros, debugging:                     Debugging.           (line   6)
+* macros, displaying definitions:        Defn.                (line   6)
+* macros, displaying definitions <1>:    Dumpdef.             (line   6)
+* macros, expansion of:                  Macro expansion.     (line   6)
+* macros, how to define new:             Definitions.         (line   6)
+* macros, how to delete:                 Undefine.            (line   6)
+* macros, how to rename:                 Defn.                (line   6)
+* macros, indirect call of:              Indir.               (line   6)
+* macros, quoted arguments to:           Quoting Arguments.   (line   6)
+* macros, recursive:                     Shift.               (line   6)
+* macros, special arguments to:          Pseudo Arguments.    (line   6)
+* macros, temporary redefinition of:     Pushdef.             (line   6)
+* manipulating quotes:                   Shift.               (line 189)
+* messages, printing error:              Errprint.            (line   6)
+* more than nine arguments:              Arguments.           (line  54)
+* more than nine arguments <1>:          Shift.               (line 250)
+* more than nine arguments <2>:          Improved foreach.    (line 156)
+* multibranches:                         Ifelse.              (line  69)
+* names:                                 Names.               (line   6)
+* nesting limit:                         Limits control.      (line  43)
+* nine arguments, more than:             Arguments.           (line  54)
+* nine arguments, more than <1>:         Shift.               (line 250)
+* nine arguments, more than <2>:         Improved foreach.    (line 156)
+* numbers:                               Manual.              (line  57)
+* options, command line:                 Invoking m4.         (line  10)
+* output, diverting to files:            Divert.              (line   6)
+* output, formatted:                     Format.              (line   6)
+* output, literal:                       Pseudo Arguments.    (line 106)
+* output, saving debugging:              Debug Output.        (line   6)
+* overview of 'm4':                      Intro.               (line   6)
+* pattern substitution:                  Patsubst.            (line   6)
+* platform macros:                       Platform macros.     (line   6)
+* positional parameters, more than nine: Arguments.           (line  54)
+* POSIX:                                 Extensions.          (line   6)
+* 'POSIXLY_CORRECT':                     Invoking m4.         (line  10)
+* 'POSIXLY_CORRECT' <1>:                 Incompatibilities.   (line 144)
+* preprocessor features:                 Preprocessor features.
+                                                              (line   6)
+* printing error messages:               Errprint.            (line   6)
+* pushdef stack:                         Pushdef.             (line   6)
+* pushdef stack <1>:                     Stacks.              (line   6)
+* quadratic behavior, avoiding:          Improved foreach.    (line  38)
+* quote delimiters, changing:            Changequote.         (line   6)
+* quote manipulation:                    Shift.               (line 189)
+* quoted macro arguments:                Quoting Arguments.   (line   6)
+* quoted string:                         Quoted strings.      (line   6)
+* quoting rule of thumb:                 Quoting Arguments.   (line  22)
+* recursive macros:                      Shift.               (line   6)
+* redefinition of macros, temporary:     Pushdef.             (line   6)
+* regular expressions:                   Changeword.          (line   6)
+* regular expressions <1>:               Regexp.              (line   6)
+* regular expressions <2>:               Patsubst.            (line   6)
+* reloading a frozen file:               Using frozen files.  (line   6)
+* renaming macros:                       Defn.                (line   6)
+* renaming macros <1>:                   Composition.         (line 116)
+* reporting bugs:                        Bugs.                (line   6)
+* rescanning:                            Limits control.      (line  56)
+* rescanning <1>:                        Inhibiting Invocation.
+                                                              (line  86)
+* rescanning <2>:                        Pseudo Arguments.    (line 106)
+* rescanning <3>:                        Defn.                (line  61)
+* rescanning <4>:                        Other Incompatibilities.
+                                                              (line  52)
+* reversing arguments:                   Shift.               (line  31)
+* rule of thumb, quoting:                Quoting Arguments.   (line  22)
+* running shell commands:                Shell commands.      (line   6)
+* saving debugging output:               Debug Output.        (line   6)
+* saving input:                          M4wrap.              (line   6)
+* search path for included files:        Search Path.         (line   6)
+* shell commands, exit status from:      Sysval.              (line   6)
+* shell commands, running:               Shell commands.      (line   6)
+* short-circuiting conditional:          Shift.               (line  51)
+* special arguments to macros:           Pseudo Arguments.    (line   6)
+* stack, macro definition:               Pushdef.             (line   6)
+* stack, macro definition <1>:           Stacks.              (line   6)
+* standard error, output to:             Dumpdef.             (line   6)
+* standard error, output to <1>:         Trace.               (line   6)
+* standard error, output to <2>:         Errprint.            (line   6)
+* status of shell commands:              Sysval.              (line   6)
+* status, setting 'm4' exit:             M4exit.              (line   6)
+* string, quoted:                        Quoted strings.      (line   6)
+* strings, length of:                    Len.                 (line   6)
+* substitution by regular expression:    Patsubst.            (line   6)
+* substrings, extracting:                Substr.              (line   6)
+* substrings, locating:                  Index macro.         (line   6)
+* suggestions, reporting:                Bugs.                (line   6)
+* suppressing warnings:                  Macro Arguments.     (line  38)
+* switch statement:                      Ifelse.              (line  69)
+* synchronization lines:                 Preprocessor features.
+                                                              (line  28)
+* syntax, changing:                      Changeword.          (line   6)
+* temporary file names:                  Mkstemp.             (line   6)
+* temporary redefinition of macros:      Pushdef.             (line   6)
+* 'TMPDIR':                              Diversions.          (line  10)
+* tokens:                                Syntax.              (line   6)
+* tokens, builtin macro:                 Defn.                (line 101)
+* tokens, special:                       Other tokens.        (line   6)
+* tracing macro expansion:               Trace.               (line   6)
+* translating characters:                Translit.            (line   6)
+* undefining macros:                     Undefine.            (line   6)
+* UNIX commands, exit status from:       Sysval.              (line   6)
+* UNIX commands, running:                Shell commands.      (line   6)
+* variables, local:                      Pushdef.             (line  79)
+* warnings, suppressing:                 Macro Arguments.     (line  38)
+* words:                                 Names.               (line   6)
+* words, lexical structure of:           Changeword.          (line   6)
+
diff --git a/doc/m4.texi b/doc/m4.texi
new file mode 100644
index 0000000..81dd255
--- /dev/null
+++ b/doc/m4.texi
@@ -0,0 +1,8758 @@
+\input texinfo @c -*- texinfo -*-
+@comment ========================================================
+@comment %**start of header
+@setfilename m4.info
+@include version.texi
+@settitle GNU M4 @value{VERSION} macro processor
+@setchapternewpage odd
+@ifnothtml
+@setcontentsaftertitlepage
+@end ifnothtml
+@finalout
+
+@c @tabchar{}
+@c ----------
+@c The testsuite expects literal tab output in some examples, but
+@c literal tabs in texinfo lead to formatting issues.
+@macro tabchar
+@	@c
+@end macro
+
+@c @ovar{ARG}
+@c -------------------
+@c The ARG is an optional argument.  To be used for macro arguments in
+@c their documentation (@defmac).
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}@c
+@end macro
+
+@c @dvar{ARG, DEFAULT}
+@c -------------------
+@c The ARG is an optional argument, defaulting to DEFAULT.  To be used
+@c for macro arguments in their documentation (@defmac).
+@macro dvar{varname, default}
+@r{[}@var{\varname\} = @samp{\default\}@r{]}@c
+@end macro
+
+@comment %**end of header
+@comment ========================================================
+
+@copying
+
+This manual (@value{UPDATED}) is for GNU M4 (version
+@value{VERSION}), a package containing an implementation of the m4 macro
+language.
+
+Copyright @copyright{} 1989-1994, 2004-2013 Free Software Foundation,
+Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License,
+Version 1.3 or any later version published by the Free Software
+Foundation; 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 quotation
+@end copying
+
+@dircategory Text creation and manipulation
+@direntry
+* M4: (m4).                     A powerful macro processor.
+@end direntry
+
+@titlepage
+@title GNU M4, version @value{VERSION}
+@subtitle A powerful macro processor
+@subtitle Edition @value{EDITION}, @value{UPDATED}
+@author by Ren@'e Seindal, Fran@,{c}ois Pinard,
+@author Gary V. Vaughan, and Eric Blake
+@author (@email{bug-m4@@gnu.org})
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top GNU M4
+@insertcopying
+@end ifnottex
+
+GNU @code{m4} is an implementation of the traditional UNIX macro
+processor.  It is mostly SVR4 compatible, although it has some
+extensions (for example, handling more than 9 positional parameters
+to macros).  @code{m4} also has builtin functions for including
+files, running shell commands, doing arithmetic, etc.  Autoconf needs
+GNU @code{m4} for generating @file{configure} scripts, but not for
+running them.
+
+GNU @code{m4} was originally written by Ren@'e Seindal, with
+subsequent changes by Fran@,{c}ois Pinard and other volunteers
+on the Internet.  All names and email addresses can be found in the
+files @file{m4-@value{VERSION}/@/AUTHORS} and
+@file{m4-@value{VERSION}/@/THANKS} from the GNU M4
+distribution.
+
+This is release @value{VERSION}.  It is now considered stable:  future
+releases in the 1.4.x series are only meant to fix bugs, increase speed,
+or improve documentation.  However@dots{}
+
+An experimental feature, which would improve @code{m4} usefulness,
+allows for changing the syntax for what is a @dfn{word} in @code{m4}.
+You should use:
+@comment ignore
+@example
+./configure --enable-changeword
+@end example
+@noindent
+if you want this feature compiled in.  The current implementation
+slows down @code{m4} considerably and is hardly acceptable.  In the
+future, @code{m4} 2.0 will come with a different set of new features
+that provide similar capabilities, but without the inefficiencies, so
+changeword will go away and @emph{you should not count on it}.
+
+@menu
+* Preliminaries::               Introduction and preliminaries
+* Invoking m4::                 Invoking @code{m4}
+* Syntax::                      Lexical and syntactic conventions
+
+* Macros::                      How to invoke macros
+* Definitions::                 How to define new macros
+* Conditionals::                Conditionals, loops, and recursion
+
+* Debugging::                   How to debug macros and input
+
+* Input Control::               Input control
+* File Inclusion::              File inclusion
+* Diversions::                  Diverting and undiverting output
+
+* Text handling::               Macros for text handling
+* Arithmetic::                  Macros for doing arithmetic
+* Shell commands::              Macros for running shell commands
+* Miscellaneous::               Miscellaneous builtin macros
+* Frozen files::                Fast loading of frozen state
+
+* Compatibility::               Compatibility with other versions of @code{m4}
+* Answers::                     Correct version of some examples
+
+* Copying This Package::        How to make copies of the overall M4 package
+* Copying This Manual::         How to make copies of this manual
+* Indices::                     Indices of concepts and macros
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction and preliminaries
+
+* Intro::                       Introduction to @code{m4}
+* History::                     Historical references
+* Bugs::                        Problems and bugs
+* Manual::                      Using this manual
+
+Invoking @code{m4}
+
+* Operation modes::             Command line options for operation modes
+* Preprocessor features::       Command line options for preprocessor features
+* Limits control::              Command line options for limits control
+* Frozen state::                Command line options for frozen state
+* Debugging options::           Command line options for debugging
+* Command line files::          Specifying input files on the command line
+
+Lexical and syntactic conventions
+
+* Names::                       Macro names
+* Quoted strings::              Quoting input to @code{m4}
+* Comments::                    Comments in @code{m4} input
+* Other tokens::                Other kinds of input tokens
+* Input processing::            How @code{m4} copies input to output
+
+How to invoke macros
+
+* Invocation::                  Macro invocation
+* Inhibiting Invocation::       Preventing macro invocation
+* Macro Arguments::             Macro arguments
+* Quoting Arguments::           On Quoting Arguments to macros
+* Macro expansion::             Expanding macros
+
+How to define new macros
+
+* Define::                      Defining a new macro
+* Arguments::                   Arguments to macros
+* Pseudo Arguments::            Special arguments to macros
+* Undefine::                    Deleting a macro
+* Defn::                        Renaming macros
+* Pushdef::                     Temporarily redefining macros
+
+* Indir::                       Indirect call of macros
+* Builtin::                     Indirect call of builtins
+
+Conditionals, loops, and recursion
+
+* Ifdef::                       Testing if a macro is defined
+* Ifelse::                      If-else construct, or multibranch
+* Shift::                       Recursion in @code{m4}
+* Forloop::                     Iteration by counting
+* Foreach::                     Iteration by list contents
+* Stacks::                      Working with definition stacks
+* Composition::                 Building macros with macros
+
+How to debug macros and input
+
+* Dumpdef::                     Displaying macro definitions
+* Trace::                       Tracing macro calls
+* Debug Levels::                Controlling debugging output
+* Debug Output::                Saving debugging output
+
+Input control
+
+* Dnl::                         Deleting whitespace in input
+* Changequote::                 Changing the quote characters
+* Changecom::                   Changing the comment delimiters
+* Changeword::                  Changing the lexical structure of words
+* M4wrap::                      Saving text until end of input
+
+File inclusion
+
+* Include::                     Including named files
+* Search Path::                 Searching for include files
+
+Diverting and undiverting output
+
+* Divert::                      Diverting output
+* Undivert::                    Undiverting output
+* Divnum::                      Diversion numbers
+* Cleardivert::                 Discarding diverted text
+
+Macros for text handling
+
+* Len::                         Calculating length of strings
+* Index macro::                 Searching for substrings
+* Regexp::                      Searching for regular expressions
+* Substr::                      Extracting substrings
+* Translit::                    Translating characters
+* Patsubst::                    Substituting text by regular expression
+* Format::                      Formatting strings (printf-like)
+
+Macros for doing arithmetic
+
+* Incr::                        Decrement and increment operators
+* Eval::                        Evaluating integer expressions
+
+Macros for running shell commands
+
+* Platform macros::             Determining the platform
+* Syscmd::                      Executing simple commands
+* Esyscmd::                     Reading the output of commands
+* Sysval::                      Exit status
+* Mkstemp::                     Making temporary files
+
+Miscellaneous builtin macros
+
+* Errprint::                    Printing error messages
+* Location::                    Printing current location
+* M4exit::                      Exiting from @code{m4}
+
+Fast loading of frozen state
+
+* Using frozen files::          Using frozen files
+* Frozen file format::          Frozen file format
+
+Compatibility with other versions of @code{m4}
+
+* Extensions::                  Extensions in GNU M4
+* Incompatibilities::           Facilities in System V m4 not in GNU M4
+* Other Incompatibilities::     Other incompatibilities
+
+Correct version of some examples
+
+* Improved exch::               Solution for @code{exch}
+* Improved forloop::            Solution for @code{forloop}
+* Improved foreach::            Solution for @code{foreach}
+* Improved copy::               Solution for @code{copy}
+* Improved m4wrap::             Solution for @code{m4wrap}
+* Improved cleardivert::        Solution for @code{cleardivert}
+* Improved capitalize::         Solution for @code{capitalize}
+* Improved fatal_error::        Solution for @code{fatal_error}
+
+How to make copies of the overall M4 package
+
+* GNU General Public License::  License for copying the M4 package
+
+How to make copies of this manual
+
+* GNU Free Documentation License::  License for copying this manual
+
+Indices of concepts and macros
+
+* Macro index::                 Index for all @code{m4} macros
+* Concept index::               Index for many concepts
+
+@end detailmenu
+@end menu
+
+@node Preliminaries
+@chapter Introduction and preliminaries
+
+This first chapter explains what GNU @code{m4} is, where @code{m4}
+comes from, how to read and use this documentation, how to call the
+@code{m4} program, and how to report bugs about it.  It concludes by
+giving tips for reading the remainder of the manual.
+
+The following chapters then detail all the features of the @code{m4}
+language.
+
+@menu
+* Intro::                       Introduction to @code{m4}
+* History::                     Historical references
+* Bugs::                        Problems and bugs
+* Manual::                      Using this manual
+@end menu
+
+@node Intro
+@section Introduction to @code{m4}
+
+@cindex overview of @code{m4}
+@code{m4} is a macro processor, in the sense that it copies its
+input to the output, expanding macros as it goes.  Macros are either
+builtin or user-defined, and can take any number of arguments.
+Besides just doing macro expansion, @code{m4} has builtin functions
+for including named files, running shell commands, doing integer
+arithmetic, manipulating text in various ways, performing recursion,
+etc.@dots{}  @code{m4} can be used either as a front-end to a compiler,
+or as a macro processor in its own right.
+
+The @code{m4} macro processor is widely available on all UNIXes, and has
+been standardized by POSIX.
+Usually, only a small percentage of users are aware of its existence.
+However, those who find it often become committed users.  The
+popularity of GNU Autoconf, which requires GNU
+@code{m4} for @emph{generating} @file{configure} scripts, is an incentive
+for many to install it, while these people will not themselves
+program in @code{m4}.  GNU @code{m4} is mostly compatible with the
+System V, Release 4 version, except for some minor differences.
+@xref{Compatibility}, for more details.
+
+Some people find @code{m4} to be fairly addictive.  They first use
+@code{m4} for simple problems, then take bigger and bigger challenges,
+learning how to write complex sets of @code{m4} macros along the way.
+Once really addicted, users pursue writing of sophisticated @code{m4}
+applications even to solve simple problems, devoting more time
+debugging their @code{m4} scripts than doing real work.  Beware that
+@code{m4} may be dangerous for the health of compulsive programmers.
+
+@node History
+@section Historical references
+
+@cindex history of @code{m4}
+@cindex GNU M4, history of
+Macro languages were invented early in the history of computing.  In the
+1950s Alan Perlis suggested that the macro language be independent of the
+language being processed.  Techniques such as conditional and recursive
+macros, and using macros to define other macros, were described by Doug
+McIlroy of Bell Labs in ``Macro Instruction Extensions of Compiler
+Languages'', @emph{Communications of the ACM} 3, 4 (1960), 214--20,
+@url{http://dx.doi.org/10.1145/367177.367223}.
+
+An important precursor of @code{m4} was GPM; see C. Strachey,
+@c The title uses lower case and has no space between "macro" and "generator".
+``A general purpose macrogenerator'', @emph{Computer Journal} 8, 3
+(1965), 225--41, @url{http://dx.doi.org/10.1093/comjnl/8.3.225}.  GPM is
+also succinctly described in David Gries's book @emph{Compiler
+Construction for Digital Computers}, Wiley (1971).  Strachey was a
+brilliant programmer: GPM fit into 250 machine instructions!
+
+Inspired by GPM while visiting Strachey's Lab in 1968, McIlroy wrote a
+model preprocessor in that fit into a page of Snobol 3 code, and McIlroy
+and Robert Morris developed a series of further models at Bell Labs.
+Andrew D. Hall followed up with M6, a general purpose macro processor
+used to port the Fortran source code of the Altran computer algebra
+system; see Hall's ``The M6 Macro Processor'', Computing Science
+Technical Report #2, Bell Labs (1972),
+@url{http://cm.bell-labs.com/cm/cs/cstr/2.pdf}.  M6's source code
+consisted of about 600 Fortran statements.  Its name was the first of
+the @code{m4} line.
+
+The Brian Kernighan and P.J. Plauger book @emph{Software Tools},
+Addison-Wesley (1976), describes and implements a Unix
+macro-processor language, which inspired Dennis Ritchie to write
+@code{m3}, a macro processor for the AP-3 minicomputer.
+
+Kernighan and Ritchie then joined forces to develop the original
+@code{m4}, described in ``The M4 Macro Processor'', Bell Laboratories
+(1977), @url{http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf}.
+It had only 21 builtin macros.
+
+While @code{GPM} was more @emph{pure}, @code{m4} is meant to deal with
+the true intricacies of real life: macros can be recognized without
+being pre-announced, skipping whitespace or end-of-lines is easier,
+more constructs are builtin instead of derived, etc.
+
+Originally, the Kernighan and Plauger macro-processor, and then
+@code{m3}, formed the engine for the Rational FORTRAN preprocessor,
+that is, the @code{Ratfor} equivalent of @code{cpp}.  Later, @code{m4}
+was used as a front-end for @code{Ratfor}, @code{C} and @code{Cobol}.
+
+Ren@'e Seindal released his implementation of @code{m4}, GNU
+@code{m4},
+in 1990, with the aim of removing the artificial limitations in many
+of the traditional @code{m4} implementations, such as maximum line
+length, macro size, or number of macros.
+
+The late Professor A. Dain Samples described and implemented a further
+evolution in the form of @code{M5}: ``User's Guide to the M5 Macro
+Language: 2nd edition'', Electronic Announcement on comp.compilers
+newsgroup (1992).
+
+Fran@,{c}ois Pinard took over maintenance of GNU @code{m4} in
+1992, until 1994 when he released GNU @code{m4} 1.4, which was
+the stable release for 10 years.  It was at this time that GNU
+Autoconf decided to require GNU @code{m4} as its underlying
+engine, since all other implementations of @code{m4} had too many
+limitations.
+
+More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
+addressed some long standing bugs in the venerable 1.4 release.  Then in
+2005, Gary V. Vaughan collected together the many patches to
+GNU @code{m4} 1.4 that were floating around the net and
+released 1.4.3 and 1.4.4.  And in 2006, Eric Blake joined the team and
+prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.
+More bug fixes were incorporated in 2007, with releases 1.4.9 and
+1.4.10.  Eric continued with some portability fixes for 1.4.11 and
+1.4.12 in 2008, 1.4.13 in 2009, 1.4.14 and 1.4.15 in 2010, and 1.4.16 in
+2011.
+
+Meanwhile, development has continued on new features for @code{m4}, such
+as dynamic module loading and additional builtins.  When complete,
+GNU @code{m4} 2.0 will start a new series of releases.
+
+@node Bugs
+@section Problems and bugs
+
+@cindex reporting bugs
+@cindex bug reports
+@cindex suggestions, reporting
+If you have problems with GNU M4 or think you've found a bug,
+please report it.  Before reporting a bug, make sure you've actually
+found a real bug.  Carefully reread the documentation and see if it
+really says you can do what you're trying to do.  If it's not clear
+whether you should be able to do something or not, report that too; it's
+a bug in the documentation!
+
+Before reporting a bug or trying to fix it yourself, try to isolate it
+to the smallest possible input file that reproduces the problem.  Then
+send us the input file and the exact results @code{m4} gave you.  Also
+say what you expected to occur; this will help us decide whether the
+problem was really in the documentation.
+
+Once you've got a precise problem, send e-mail to
+@email{bug-m4@@gnu.org}.  Please include the version number of @code{m4}
+you are using.  You can get this information with the command
+@kbd{m4 --version}.  Also provide details about the platform you are
+executing on.
+
+Non-bug suggestions are always welcome as well.  If you have questions
+about things that are unclear in the documentation or are just obscure
+features, please report them too.
+
+@node Manual
+@section Using this manual
+
+@cindex examples, understanding
+This manual contains a number of examples of @code{m4} input and output,
+and a simple notation is used to distinguish input, output and error
+messages from @code{m4}.  Examples are set out from the normal text, and
+shown in a fixed width font, like this
+
+@comment ignore
+@example
+This is an example of an example!
+@end example
+
+To distinguish input from output, all output from @code{m4} is prefixed
+by the string @samp{@result{}}, and all error messages by the string
+@samp{@error{}}.  When showing how command line options affect matters,
+the command line is shown with a prompt @samp{$ @kbd{like this}},
+otherwise, you can assume that a simple @kbd{m4} invocation will work.
+Thus:
+
+@comment ignore
+@example
+$ @kbd{command line to invoke m4}
+Example of input line
+@result{}Output line from m4
+@error{}and an error message
+@end example
+
+The sequence @samp{^D} in an example indicates the end of the input
+file.  The sequence @samp{@key{NL}} refers to the newline character.
+The majority of these examples are self-contained, and you can run them
+with similar results by invoking @kbd{m4 -d}.  In fact, the testsuite
+that is bundled in the GNU M4 package consists of the examples
+in this document!  Some of the examples assume that your current
+directory is located where you unpacked the installation, so if you plan
+on following along, you may find it helpful to do this now:
+
+@comment ignore
+@example
+$ @kbd{cd m4-@value{VERSION}}
+@end example
+
+As each of the predefined macros in @code{m4} is described, a prototype
+call of the macro will be shown, giving descriptive names to the
+arguments, e.g.,
+
+@deffn Composite example (@var{string}, @dvar{count, 1}, @
+  @ovar{argument}@dots{})
+This is a sample prototype.  There is not really a macro named
+@code{example}, but this documents that if there were, it would be a
+Composite macro, rather than a Builtin.  It requires at least one
+argument, @var{string}.  Remember that in @code{m4}, there must not be a
+space between the macro name and the opening parenthesis, unless it was
+intended to call the macro without any arguments.  The brackets around
+@var{count} and @var{argument} show that these arguments are optional.
+If @var{count} is omitted, the macro behaves as if count were @samp{1},
+whereas if @var{argument} is omitted, the macro behaves as if it were
+the empty string.  A blank argument is not the same as an omitted
+argument.  For example, @samp{example(`a')}, @samp{example(`a',`1')},
+and @samp{example(`a',`1',)} would behave identically with @var{count}
+set to @samp{1}; while @samp{example(`a',)} and @samp{example(`a',`')}
+would explicitly pass the empty string for @var{count}.  The ellipses
+(@samp{@dots{}}) show that the macro processes additional arguments
+after @var{argument}, rather than ignoring them.
+@end deffn
+
+@cindex numbers
+All macro arguments in @code{m4} are strings, but some are given
+special interpretation, e.g., as numbers, file names, regular
+expressions, etc.  The documentation for each macro will state how the
+parameters are interpreted, and what happens if the argument cannot be
+parsed according to the desired interpretation.  Unless specified
+otherwise, a parameter specified to be a number is parsed as a decimal,
+even if the argument has leading zeros; and parsing the empty string as
+a number results in 0 rather than an error, although a warning will be
+issued.
+
+This document consistently writes and uses @dfn{builtin}, without a
+hyphen, as if it were an English word.  This is how the @code{builtin}
+primitive is spelled within @code{m4}.
+
+@node Invoking m4
+@chapter Invoking @code{m4}
+
+@cindex command line
+@cindex invoking @code{m4}
+The format of the @code{m4} command is:
+
+@comment ignore
+@example
+@code{m4} @r{[}@var{option}@dots{}@r{]} @r{[}@var{file}@dots{}@r{]}
+@end example
+
+@cindex command line, options
+@cindex options, command line
+@cindex @env{POSIXLY_CORRECT}
+All options begin with @samp{-}, or if long option names are used, with
+@samp{--}.  A long option name need not be written completely, any
+unambiguous prefix is sufficient.  POSIX requires @code{m4} to
+recognize arguments intermixed with files, even when
+@env{POSIXLY_CORRECT} is set in the environment.  Most options take
+effect at startup regardless of their position, but some are documented
+below as taking effect after any files that occurred earlier in the
+command line.  The argument @option{--} is a marker to denote the end of
+options.
+
+With short options, options that do not take arguments may be combined
+into a single command line argument with subsequent options, options
+with mandatory arguments may be provided either as a single command line
+argument or as two arguments, and options with optional arguments must
+be provided as a single argument.  In other words,
+@kbd{m4 -QPDfoo -d a -df} is equivalent to
+@kbd{m4 -Q -P -D foo -d -df -- ./a}, although the latter form is
+considered canonical.
+
+With long options, options with mandatory arguments may be provided with
+an equal sign (@samp{=}) in a single argument, or as two arguments, and
+options with optional arguments must be provided as a single argument.
+In other words, @kbd{m4 --def foo --debug a} is equivalent to
+@kbd{m4 --define=foo --debug= -- ./a}, although the latter form is
+considered canonical (not to mention more robust, in case a future
+version of @code{m4} introduces an option named @option{--default}).
+
+@code{m4} understands the following options, grouped by functionality.
+
+@menu
+* Operation modes::             Command line options for operation modes
+* Preprocessor features::       Command line options for preprocessor features
+* Limits control::              Command line options for limits control
+* Frozen state::                Command line options for frozen state
+* Debugging options::           Command line options for debugging
+* Command line files::          Specifying input files on the command line
+@end menu
+
+@node Operation modes
+@section Command line options for operation modes
+
+Several options control the overall operation of @code{m4}:
+
+@table @code
+@item --help
+Print a help summary on standard output, then immediately exit
+@code{m4} without reading any input files or performing any other
+actions.
+
+@item --version
+Print the version number of the program on standard output, then
+immediately exit @code{m4} without reading any input files or
+performing any other actions.
+
+@item -E
+@itemx --fatal-warnings
+@cindex errors, fatal
+@cindex fatal errors
+Controls the effect of warnings.  If unspecified, then execution
+continues and exit status is unaffected when a warning is printed.  If
+specified exactly once, warnings become fatal; when one is issued,
+execution continues, but the exit status will be non-zero.  If specified
+multiple times, then execution halts with non-zero status the first time
+a warning is issued.  The introduction of behavior levels is new to M4
+1.4.9; for behavior consistent with earlier versions, you should specify
+@option{-E} twice.
+
+@item -i
+@itemx --interactive
+@itemx -e
+Makes this invocation of @code{m4} interactive.  This means that all
+output will be unbuffered, and interrupts will be ignored.  The
+spelling @option{-e} exists for compatibility with other @code{m4}
+implementations, and issues a warning because it may be withdrawn in a
+future version of GNU M4.
+
+@item -P
+@itemx --prefix-builtins
+Internally modify @emph{all} builtin macro names so they all start with
+the prefix @samp{m4_}.  For example, using this option, one should write
+@samp{m4_define} instead of @samp{define}, and @samp{m4___file__}
+instead of @samp{__file__}.  This option has no effect if @option{-R}
+is also specified.
+
+@item -Q
+@itemx --quiet
+@itemx --silent
+Suppress warnings, such as missing or superfluous arguments in macro
+calls, or treating the empty string as zero.
+
+@item --warn-macro-sequence@r{[}=@var{regexp}@r{]}
+Issue a warning if the regular expression @var{regexp} has a non-empty
+match in any macro definition (either by @code{define} or
+@code{pushdef}).  Empty matches are ignored; therefore, supplying the
+empty string as @var{regexp} disables any warning.  If the optional
+@var{regexp} is not supplied, then the default regular expression is
+@samp{\$\(@{[^@}]*@}\|[0-9][0-9]+\)} (a literal @samp{$} followed by
+multiple digits or by an open brace), since these sequences will
+change semantics in the default operation of GNU M4 2.0 (due
+to a change in how more than 9 arguments in a macro definition will be
+handled, @pxref{Arguments}).  Providing an alternate regular
+expression can provide a useful reverse lookup feature of finding
+where a macro is defined to have a given definition.
+
+@item -W @var{regexp}
+@itemx --word-regexp=@var{regexp}
+Use @var{regexp} as an alternative syntax for macro names.  This
+experimental option will not be present in all GNU @code{m4}
+implementations (@pxref{Changeword}).
+@end table
+
+@node Preprocessor features
+@section Command line options for preprocessor features
+
+@cindex macro definitions, on the command line
+@cindex command line, macro definitions on the
+@cindex preprocessor features
+Several options allow @code{m4} to behave more like a preprocessor.
+Macro definitions and deletions can be made on the command line, the
+search path can be altered, and the output file can track where the
+input came from.  These features occur with the following options:
+
+@table @code
+@item -D @var{name}@r{[}=@var{value}@r{]}
+@itemx --define=@var{name}@r{[}=@var{value}@r{]}
+This enters @var{name} into the symbol table.  If @samp{=@var{value}} is
+missing, the value is taken to be the empty string.  The @var{value} can
+be any string, and the macro can be defined to take arguments, just as
+if it was defined from within the input.  This option may be given more
+than once; order with respect to file names is significant, and
+redefining the same @var{name} loses the previous value.
+
+@item -I @var{directory}
+@itemx --include=@var{directory}
+Make @code{m4} search @var{directory} for included files that are not
+found in the current working directory.  @xref{Search Path}, for more
+details.  This option may be given more than once.
+
+@item -s
+@itemx --synclines
+@cindex synchronization lines
+@cindex location, input
+@cindex input location
+Generate synchronization lines, for use by the C preprocessor or other
+similar tools.  Order is significant with respect to file names.  This
+option is useful, for example, when @code{m4} is used as a
+front end to a compiler.  Source file name and line number information
+is conveyed by directives of the form @samp{#line @var{linenum}
+"@var{file}"}, which are inserted as needed into the middle of the
+output.  Such directives mean that the following line originated or was
+expanded from the contents of input file @var{file} at line
+@var{linenum}.  The @samp{"@var{file}"} part is often omitted when
+the file name did not change from the previous directive.
+
+Synchronization directives are always given on complete lines by
+themselves.  When a synchronization discrepancy occurs in the middle of
+an output line, the associated synchronization directive is delayed
+until the next newline that does not occur in the middle of a quoted
+string or comment.
+
+@comment options: -s
+@example
+define(`twoline', `1
+2')
+@result{}#line 2 "stdin"
+@result{}
+changecom(`/*', `*/')
+@result{}
+define(`comment', `/*1
+2*/')
+@result{}#line 5
+@result{}
+dnl no line
+hello
+@result{}#line 7
+@result{}hello
+twoline
+@result{}1
+@result{}#line 8
+@result{}2
+comment
+@result{}/*1
+@result{}2*/
+one comment `two
+three'
+@result{}#line 10
+@result{}one /*1
+@result{}2*/ two
+@result{}three
+goodbye
+@result{}#line 12
+@result{}goodbye
+@end example
+
+@item -U @var{name}
+@itemx --undefine=@var{name}
+This deletes any predefined meaning @var{name} might have.  Obviously,
+only predefined macros can be deleted in this way.  This option may be
+given more than once; undefining a @var{name} that does not have a
+definition is silently ignored.  Order is significant with respect to
+file names.
+@end table
+
+@node Limits control
+@section Command line options for limits control
+
+There are some limits within @code{m4} that can be tuned.  For
+compatibility, @code{m4} also accepts some options that control limits
+in other implementations, but which are automatically unbounded (limited
+only by your hardware and operating system constraints) in GNU
+@code{m4}.
+
+@table @code
+@item -g
+@itemx --gnu
+Enable all the extensions in this implementation.  In this release of
+M4, this option is always on by default; it is currently only useful
+when overriding a prior use of @option{--traditional}.  However, having
+GNU behavior as default makes it impossible to write a
+strictly POSIX-compliant client that avoids all incompatible
+GNU M4 extensions, since such a client would have to use the
+non-POSIX command-line option to force full POSIX
+behavior.  Thus, a future version of M4 will be changed to implicitly
+use the option @option{--traditional} if the environment variable
+@env{POSIXLY_CORRECT} is set.  Projects that intentionally use
+GNU extensions should consider using @option{--gnu} to state
+their intentions, so that the project will not mysteriously break if the
+user upgrades to a newer M4 and has @env{POSIXLY_CORRECT} set in their
+environment.
+
+@item -G
+@itemx --traditional
+Suppress all the extensions made in this implementation, compared to the
+System V version.  @xref{Compatibility}, for a list of these.
+
+@item -H @var{num}
+@itemx --hashsize=@var{num}
+Make the internal hash table for symbol lookup be @var{num} entries big.
+For better performance, the number should be prime, but this is not
+checked.  The default is 509 entries.  It should not be necessary to
+increase this value, unless you define an excessive number of macros.
+
+@item -L @var{num}
+@itemx --nesting-limit=@var{num}
+@cindex nesting limit
+@cindex limit, nesting
+Artificially limit the nesting of macro calls to @var{num} levels,
+stopping program execution if this limit is ever exceeded.  When not
+specified, nesting defaults to unlimited on platforms that can detect
+stack overflow, and to 1024 levels otherwise.  A value of zero means
+unlimited; but then heavily nested code could potentially cause a stack
+overflow.
+
+The precise effect of this option is more correctly associated
+with textual nesting than dynamic recursion.  It has been useful
+when some complex @code{m4} input was generated by mechanical means, and
+also in diagnosing recursive algorithms that do not scale well.
+Most users never need to change this option from its default.
+
+@cindex rescanning
+This option does @emph{not} have the ability to break endless
+rescanning loops, since these do not necessarily consume much memory
+or stack space.  Through clever usage of rescanning loops, one can
+request complex, time-consuming computations from @code{m4} with useful
+results.  Putting limitations in this area would break @code{m4} power.
+There are many pathological cases: @w{@samp{define(`a', `a')a}} is
+only the simplest example (but @pxref{Compatibility}).  Expecting GNU
+@code{m4} to detect these would be a little like expecting a compiler
+system to detect and diagnose endless loops: it is a quite @emph{hard}
+problem in general, if not undecidable!
+
+@item -B @var{num}
+@itemx -S @var{num}
+@itemx -T @var{num}
+These options are present for compatibility with System V @code{m4}, but
+do nothing in this implementation.  They may disappear in future
+releases, and issue a warning to that effect.
+
+@item -N @var{num}
+@itemx --diversions=@var{num}
+These options are present only for compatibility with previous
+versions of GNU @code{m4}, and were controlling the number of
+possible diversions which could be used at the same time.  They do nothing,
+because there is no fixed limit anymore.  They may disappear in future
+releases, and issue a warning to that effect.
+@end table
+
+@node Frozen state
+@section Command line options for frozen state
+
+GNU @code{m4} comes with a feature of freezing internal state
+(@pxref{Frozen files}).  This can be used to speed up @code{m4}
+execution when reusing a common initialization script.
+
+@table @code
+@item -F @var{file}
+@itemx --freeze-state=@var{file}
+Once execution is finished, write out the frozen state on the specified
+@var{file}.  It is conventional, but not required, for @var{file} to end
+in @samp{.m4f}.
+
+@item -R @var{file}
+@itemx --reload-state=@var{file}
+Before execution starts, recover the internal state from the specified
+frozen @var{file}.  The options @option{-D}, @option{-U}, and
+@option{-t} take effect after state is reloaded, but before the input
+files are read.
+@end table
+
+@node Debugging options
+@section Command line options for debugging
+
+Finally, there are several options for aiding in debugging @code{m4}
+scripts.
+
+@table @code
+@item -d@r{[}@var{flags}@r{]}
+@itemx --debug@r{[}=@var{flags}@r{]}
+Set the debug-level according to the flags @var{flags}.  The debug-level
+controls the format and amount of information presented by the debugging
+functions.  @xref{Debug Levels}, for more details on the format and
+meaning of @var{flags}.  If omitted, @var{flags} defaults to @samp{aeq}.
+
+@item --debugfile@r{[}=@var{file}@r{]}
+@itemx -o @var{file}
+@itemx --error-output=@var{file}
+Redirect @code{dumpdef} output, debug messages, and trace output to the
+named @var{file}.  Warnings, error messages, and @code{errprint} output
+are still printed to standard error.  If these options are not used, or
+if @var{file} is unspecified (only possible for @option{--debugfile}),
+debug output goes to standard error; if @var{file} is the empty string,
+debug output is discarded.  @xref{Debug Output}, for more details.  The
+option @option{--debugfile} may be given more than once, and order is
+significant with respect to file names.  The spellings @option{-o} and
+@option{--error-output} are misleading and inconsistent with other
+GNU tools; for now they are silently accepted as synonyms of
+@option{--debugfile} and only recognized once, but in a future version
+of M4, using them will cause a warning to be issued.
+
+@ignore
+@comment not worth including in the manual, but provides a good test
+
+@comment examples
+@comment options: -Dbar=hello -tbar --debugfile= foo --debugfile -
+@example
+$ @kbd{m4 -d -Iexamples -Dbar=hello -tbar --debugfile= foo --debugfile -
+@result{}hello
+errprint(`hi
+')dnl
+@error{}hi
+bar
+@error{}m4trace: -1- bar -> `hello'
+@result{}hello
+@end example
+@end ignore
+
+@item -l @var{num}
+@itemx --arglength=@var{num}
+Restrict the size of the output generated by macro tracing to @var{num}
+characters per trace line.  If unspecified or zero, output is
+unlimited.  @xref{Debug Levels}, for more details.
+
+@item -t @var{name}
+@itemx --trace=@var{name}
+This enables tracing for the macro @var{name}, at any point where it is
+defined.  @var{name} need not be defined when this option is given.
+This option may be given more than once, and order is significant with
+respect to file names.  @xref{Trace}, for more details.
+@end table
+
+@node Command line files
+@section Specifying input files on the command line
+
+@cindex command line, file names on the
+@cindex file names, on the command line
+The remaining arguments on the command line are taken to be input file
+names.  If no names are present, standard input is read.  A file
+name of @file{-} is taken to mean standard input.  It is
+conventional, but not required, for input files to end in @samp{.m4}.
+
+The input files are read in the sequence given.  Standard input can be
+read more than once, so the file name @file{-} may appear multiple times
+on the command line; this makes a difference when input is from a
+terminal or other special file type.  It is an error if an input file
+ends in the middle of argument collection, a comment, or a quoted
+string.
+
+The options @option{--define} (@option{-D}), @option{--undefine}
+(@option{-U}), @option{--synclines} (@option{-s}), and @option{--trace}
+(@option{-t}) only take effect after processing input from any file
+names that occur earlier on the command line.  For example, assume the
+file @file{foo} contains:
+
+@comment ignore
+@example
+$ @kbd{cat foo}
+bar
+@end example
+
+The text @samp{bar} can then be redefined over multiple uses of
+@file{foo}:
+
+@comment options: -Dbar=hello foo -Dbar=world foo
+@example
+$ @kbd{m4 -Dbar=hello foo -Dbar=world foo}
+@result{}hello
+@result{}world
+@end example
+
+If none of the input files invoked @code{m4exit} (@pxref{M4exit}), the
+exit status of @code{m4} will be 0 for success, 1 for general failure
+(such as problems with reading an input file), and 63 for version
+mismatch (@pxref{Using frozen files}).
+
+If you need to read a file whose name starts with a @file{-}, you can
+specify it as @samp{./-file}, or use @option{--} to mark the end of
+options.
+
+@ignore
+@comment Test that 'm4 file/' detects that file is not a directory; we
+@comment can assume that the current directory contains a Makefile.
+@comment mingw fails with EINVAL rather than ENOTDIR.
+
+@comment status: 1
+@comment xerr: ignore
+@comment options: Makefile/
+@example
+@error{}m4: cannot open `Makefile/': Not a directory
+@end example
+
+@comment Test that closed stderr does not cause a crash.  Not all
+@comment systems have the same message for EBADF.
+
+@comment xerr: ignore
+@example
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+syscmd(`echo | cat >&- 2>/dev/null')ifelse(sysval, `0',
+       `errprint(` skipping: system does not allow closing stdout
+')m4exit(`77')')dnl
+changequote(`[', `]')dnl
+syscmd([echo | ']__program__[' >&-])dnl
+@error{}m4: write error: Bad file descriptor
+sysval
+@result{}1
+@end example
+
+@example
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+syscmd(`echo | cat >&- 2>/dev/null')ifelse(sysval, `0',
+       `errprint(` skipping: system does not allow closing stdout
+')m4exit(`77')')dnl
+changequote(`[', `]')dnl
+syscmd([echo 'esyscmd(echo hi >&2 && echo err"print(bye
+)d"nl)dnl' > tmp.m4 \
+  && ']__program__[' tmp.m4 <&- >&- \
+  && rm tmp.m4])sysval
+@error{}hi
+@error{}bye
+@result{}0
+@end example
+
+@comment Test that we obey POSIX semantics with -D interspersed with
+@comment files, even with POSIXLY_CORRECT (BSD getopt gets it wrong).
+
+$ @kbd{m4 }
+@example
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+changequote(`[', `]')dnl
+syscmd([POSIXLY_CORRECT=1 ']__program__[' -Dbar=hello foo -Dbar=world foo])dnl
+@result{}hello
+@result{}world
+sysval
+@result{}0
+@end example
+@end ignore
+
+@node Syntax
+@chapter Lexical and syntactic conventions
+
+@cindex input tokens
+@cindex tokens
+As @code{m4} reads its input, it separates it into @dfn{tokens}.  A
+token is either a name, a quoted string, or any single character, that
+is not a part of either a name or a string.  Input to @code{m4} can also
+contain comments.  GNU @code{m4} does not yet understand
+multibyte locales; all operations are byte-oriented rather than
+character-oriented (although if your locale uses a single byte
+encoding, such as @sc{ISO-8859-1}, you will not notice a difference).
+However, @code{m4} is eight-bit clean, so you can
+use non-@sc{ascii} characters in quoted strings (@pxref{Changequote}),
+comments (@pxref{Changecom}), and macro names (@pxref{Indir}), with the
+exception of the @sc{nul} character (the zero byte @samp{'\0'}).
+
+@menu
+* Names::                       Macro names
+* Quoted strings::              Quoting input to @code{m4}
+* Comments::                    Comments in @code{m4} input
+* Other tokens::                Other kinds of input tokens
+* Input processing::            How @code{m4} copies input to output
+@end menu
+
+@node Names
+@section Macro names
+
+@cindex names
+@cindex words
+A name is any sequence of letters, digits, and the character @samp{_}
+(underscore), where the first character is not a digit.  @code{m4} will
+use the longest such sequence found in the input.  If a name has a
+macro definition, it will be subject to macro expansion
+(@pxref{Macros}).  Names are case-sensitive.
+
+Examples of legal names are: @samp{foo}, @samp{_tmp}, and @samp{name01}.
+
+@node Quoted strings
+@section Quoting input to @code{m4}
+
+@cindex quoted string
+@cindex string, quoted
+A quoted string is a sequence of characters surrounded by quote
+strings, defaulting to
+@samp{`} and @samp{'}, where the nested begin and end quotes within the
+string are balanced.  The value of a string token is the text, with one
+level of quotes stripped off.  Thus
+
+@comment ignore
+@example
+`'
+@result{}
+@end example
+
+@noindent
+is the empty string, and double-quoting turns into single-quoting.
+
+@comment ignore
+@example
+``quoted''
+@result{}`quoted'
+@end example
+
+The quote characters can be changed at any time, using the builtin macro
+@code{changequote}.  @xref{Changequote}, for more information.
+
+@node Comments
+@section Comments in @code{m4} input
+
+@cindex comments
+Comments in @code{m4} are normally delimited by the characters @samp{#}
+and newline.  All characters between the comment delimiters are ignored,
+but the entire comment (including the delimiters) is passed through to
+the output---comments are @emph{not} discarded by @code{m4}.
+
+Comments cannot be nested, so the first newline after a @samp{#} ends
+the comment.  The commenting effect of the begin-comment string
+can be inhibited by quoting it.
+
+@example
+$ @kbd{m4}
+`quoted text' # `commented text'
+@result{}quoted text # `commented text'
+`quoting inhibits' `#' `comments'
+@result{}quoting inhibits # comments
+@end example
+
+The comment delimiters can be changed to any string at any time, using
+the builtin macro @code{changecom}.  @xref{Changecom}, for more
+information.
+
+@ignore
+@comment Detect regression in 1.4.10b in regards to reparsing comments.
+@comment Not worth including in the manual.
+@example
+define(`e', `$@@')define(`q', ``$@@'')define(`foo', `bar')
+@result{}
+q(e(`one
+',#two ' foo
+))
+@result{}`one
+@result{}',`#two  bar
+@result{}''
+changecom(`<', `>')define(`n', `$#')
+@result{}
+n(e(<`>, <'>))
+@result{}1
+len(e(<`>, ,<'>))
+@result{}12
+@end example
+@end ignore
+
+@node Other tokens
+@section Other kinds of input tokens
+
+@cindex tokens, special
+Any character, that is neither a part of a name, nor of a quoted string,
+nor a comment, is a token by itself.  When not in the context of macro
+expansion, all of these tokens are just copied to output.  However,
+during macro expansion, whitespace characters (space, tab, newline,
+formfeed, carriage return, vertical tab), parentheses (@samp{(} and
+@samp{)}), comma (@samp{,}), and dollar (@samp{$}) have additional
+roles, explained later.
+
+@node Input processing
+@section How @code{m4} copies input to output
+
+As @code{m4} reads the input token by token, it will copy each token
+directly to the output immediately.
+
+The exception is when it finds a word with a macro definition.  In that
+case @code{m4} will calculate the macro's expansion, possibly reading
+more input to get the arguments.  It then inserts the expansion in front
+of the remaining input.  In other words, the resulting text from a macro
+call will be read and parsed into tokens again.
+
+@code{m4} expands a macro as soon as possible.  If it finds a macro call
+when collecting the arguments to another, it will expand the second call
+first.  This process continues until there are no more macro calls to
+expand and all the input has been consumed.
+
+For a running example, examine how @code{m4} handles this input:
+
+@comment ignore
+@example
+format(`Result is %d', eval(`2**15'))
+@end example
+
+@noindent
+First, @code{m4} sees that the token @samp{format} is a macro name, so
+it collects the tokens @samp{(}, @samp{`Result is %d'}, @samp{,},
+and @samp{@w{ }}, before encountering another potential macro.  Sure
+enough, @samp{eval} is a macro name, so the nested argument collection
+picks up @samp{(}, @samp{`2**15'}, and @samp{)}, invoking the eval macro
+with the lone argument of @samp{2**15}.  The expansion of
+@samp{eval(2**15)} is @samp{32768}, which is then rescanned as the five
+tokens @samp{3}, @samp{2}, @samp{7}, @samp{6}, and @samp{8}; and
+combined with the next @samp{)}, the format macro now has all its
+arguments, as if the user had typed:
+
+@comment ignore
+@example
+format(`Result is %d', 32768)
+@end example
+
+@noindent
+The format macro expands to @samp{Result is 32768}, and we have another
+round of scanning for the tokens @samp{Result}, @samp{@w{ }},
+@samp{is}, @samp{@w{ }}, @samp{3}, @samp{2}, @samp{7}, @samp{6}, and
+@samp{8}.  None of these are macros, so the final output is
+
+@comment ignore
+@example
+@result{}Result is 32768
+@end example
+
+As a more complicated example, we will contrast an actual code
+example from the Gnulib project@footnote{Derived from a patch in
+@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-01/@/msg00389.html},
+and a followup patch in
+@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-02/@/msg00000.html}},
+showing both a buggy approach and the desired results.  The user desires
+to output a shell assignment statement that takes its argument and turns
+it into a shell variable by converting it to uppercase and prepending a
+prefix.  The original attempt looks like this:
+
+@example
+changequote([,])dnl
+define([gl_STRING_MODULE_INDICATOR],
+  [
+    dnl comment
+    GNULIB_]translit([$1],[a-z],[A-Z])[=1
+  ])dnl
+  gl_STRING_MODULE_INDICATOR([strcase])
+@result{} @w{ }
+@result{}        GNULIB_strcase=1
+@result{} @w{ }
+@end example
+
+Oops -- the argument did not get capitalized.  And although the manual
+is not able to easily show it, both lines that appear empty actually
+contain two trailing spaces.  By stepping through the parse, it is easy
+to see what happened.  First, @code{m4} sees the token
+@samp{changequote}, which it recognizes as a macro, followed by
+@samp{(}, @samp{[}, @samp{,}, @samp{]}, and @samp{)} to form the
+argument list.  The macro expands to the empty string, but changes the
+quoting characters to something more useful for generating shell code
+(unbalanced @samp{`} and @samp{'} appear all the time in shell scripts,
+but unbalanced @samp{[]} tend to be rare).  Also in the first line,
+@code{m4} sees the token @samp{dnl}, which it recognizes as a builtin
+macro that consumes the rest of the line, resulting in no output for
+that line.
+
+The second line starts a macro definition.  @code{m4} sees the token
+@samp{define}, which it recognizes as a macro, followed by a @samp{(},
+@samp{[gl_STRING_MODULE_INDICATOR]}, and @samp{,}.  Because an unquoted
+comma was encountered, the first argument is known to be the expansion
+of the single-quoted string token, or @samp{gl_STRING_MODULE_INDICATOR}.
+Next, @code{m4} sees @samp{@key{NL}}, @samp{ }, and @samp{ }, but this
+whitespace is discarded as part of argument collection.  Then comes a
+rather lengthy single-quoted string token, @samp{[@key{NL}@ @ @ @ dnl
+comment@key{NL}@ @ @ @ GNULIB_]}.  This is followed by the token
+@samp{translit}, which @code{m4} recognizes as a macro name, so a nested
+macro expansion has started.
+
+The arguments to the @code{translit} are found by the tokens @samp{(},
+@samp{[$1]}, @samp{,}, @samp{[a-z]}, @samp{,}, @samp{[A-Z]}, and finally
+@samp{)}.  All three string arguments are expanded (or in other words,
+the quotes are stripped), and since neither @samp{$} nor @samp{1} need
+capitalization, the result of the macro is @samp{$1}.  This expansion is
+rescanned, resulting in the two literal characters @samp{$} and
+@samp{1}.
+
+Scanning of the outer macro resumes, and picks up with
+@samp{[=1@key{NL}@ @ ]}, and finally @samp{)}.  The collected pieces of
+expanded text are concatenated, with the end result that the macro
+@samp{gl_STRING_MODULE_INDICATOR} is now defined to be the sequence
+@samp{@key{NL}@ @ @ @ dnl comment@key{NL}@ @ @ @ GNULIB_$1=1@key{NL}@ @ }.
+Once again, @samp{dnl} is recognized and avoids a newline in the output.
+
+The final line is then parsed, beginning with @samp{ } and @samp{ }
+that are output literally.  Then @samp{gl_STRING_MODULE_INDICATOR} is
+recognized as a macro name, with an argument list of @samp{(},
+@samp{[strcase]}, and @samp{)}.  Since the definition of the macro
+contains the sequence @samp{$1}, that sequence is replaced with the
+argument @samp{strcase} prior to starting the rescan.  The rescan sees
+@samp{@key{NL}} and four spaces, which are output literally, then
+@samp{dnl}, which discards the text @samp{ comment@key{NL}}.  Next
+comes four more spaces, also output literally, and the token
+@samp{GNULIB_strcase}, which resulted from the earlier parameter
+substitution.  Since that is not a macro name, it is output literally,
+followed by the literal tokens @samp{=}, @samp{1}, @samp{@key{NL}}, and
+two more spaces.  Finally, the original @samp{@key{NL}} seen after the
+macro invocation is scanned and output literally.
+
+Now for a corrected approach.  This rearranges the use of newlines and
+whitespace so that less whitespace is output (which, although harmless
+to shell scripts, can be visually unappealing), and fixes the quoting
+issues so that the capitalization occurs when the macro
+@samp{gl_STRING_MODULE_INDICATOR} is invoked, rather then when it is
+defined.  It also adds another layer of quoting to the first argument of
+@code{translit}, to ensure that the output will be rescanned as a string
+rather than a potential uppercase macro name needing further expansion.
+
+@example
+changequote([,])dnl
+define([gl_STRING_MODULE_INDICATOR],
+  [dnl comment
+  GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl
+])dnl
+  gl_STRING_MODULE_INDICATOR([strcase])
+@result{}    GNULIB_STRCASE=1
+@end example
+
+The parsing of the first line is unchanged.  The second line sees the
+name of the macro to define, then sees the discarded @samp{@key{NL}}
+and two spaces, as before.  But this time, the next token is
+@samp{[dnl comment@key{NL}@ @ GNULIB_[]translit([[$1]], [a-z],
+[A-Z])=1dnl@key{NL}]}, which includes nested quotes, followed by
+@samp{)} to end the macro definition and @samp{dnl} to skip the
+newline.  No early expansion of @code{translit} occurs, so the entire
+string becomes the definition of the macro.
+
+The final line is then parsed, beginning with two spaces that are
+output literally, and an invocation of
+@code{gl_STRING_MODULE_INDICATOR} with the argument @samp{strcase}.
+Again, the @samp{$1} in the macro definition is substituted prior to
+rescanning.  Rescanning first encounters @samp{dnl}, and discards
+@samp{ comment@key{NL}}.  Then two spaces are output literally.  Next
+comes the token @samp{GNULIB_}, but that is not a macro, so it is
+output literally.  The token @samp{[]} is an empty string, so it does
+not affect output.  Then the token @samp{translit} is encountered.
+
+This time, the arguments to @code{translit} are parsed as @samp{(},
+@samp{[[strcase]]}, @samp{,}, @samp{ }, @samp{[a-z]}, @samp{,}, @samp{ },
+@samp{[A-Z]}, and @samp{)}.  The two spaces are discarded, and the
+translit results in the desired result @samp{[STRCASE]}.  This is
+rescanned, but since it is a string, the quotes are stripped and the
+only output is a literal @samp{STRCASE}.
+Then the scanner sees @samp{=} and @samp{1}, which are output
+literally, followed by @samp{dnl} which discards the rest of the
+definition of @code{gl_STRING_MODULE_INDICATOR}.  The newline at the
+end of output is the literal @samp{@key{NL}} that appeared after the
+invocation of the macro.
+
+The order in which @code{m4} expands the macros can be further explored
+using the trace facilities of GNU @code{m4} (@pxref{Trace}).
+
+@node Macros
+@chapter How to invoke macros
+
+This chapter covers macro invocation, macro arguments and how macro
+expansion is treated.
+
+@menu
+* Invocation::                  Macro invocation
+* Inhibiting Invocation::       Preventing macro invocation
+* Macro Arguments::             Macro arguments
+* Quoting Arguments::           On Quoting Arguments to macros
+* Macro expansion::             Expanding macros
+@end menu
+
+@node Invocation
+@section Macro invocation
+
+@cindex macro invocation
+@cindex invoking macros
+Macro invocations has one of the forms
+
+@comment ignore
+@example
+name
+@end example
+
+@noindent
+which is a macro invocation without any arguments, or
+
+@comment ignore
+@example
+name(arg1, arg2, @dots{}, arg@var{n})
+@end example
+
+@noindent
+which is a macro invocation with @var{n} arguments.  Macros can have any
+number of arguments.  All arguments are strings, but different macros
+might interpret the arguments in different ways.
+
+The opening parenthesis @emph{must} follow the @var{name} directly, with
+no spaces in between.  If it does not, the macro is called with no
+arguments at all.
+
+For a macro call to have no arguments, the parentheses @emph{must} be
+left out.  The macro call
+
+@comment ignore
+@example
+name()
+@end example
+
+@noindent
+is a macro call with one argument, which is the empty string, not a call
+with no arguments.
+
+@node Inhibiting Invocation
+@section Preventing macro invocation
+
+An innovation of the @code{m4} language, compared to some of its
+predecessors (like Strachey's @code{GPM}, for example), is the ability
+to recognize macro calls without resorting to any special, prefixed
+invocation character.  While generally useful, this feature might
+sometimes be the source of spurious, unwanted macro calls.  So, GNU
+@code{m4} offers several mechanisms or techniques for inhibiting the
+recognition of names as macro calls.
+
+@cindex GNU extensions
+@cindex blind macro
+@cindex macro, blind
+First of all, many builtin macros cannot meaningfully be called without
+arguments.  As a GNU extension, for any of these macros,
+whenever an opening parenthesis does not immediately follow their name,
+the builtin macro call is not triggered.  This solves the most usual
+cases, like for @samp{include} or @samp{eval}.  Later in this document,
+the sentence ``This macro is recognized only with parameters'' refers to
+this specific provision of GNU M4, also known as a blind
+builtin macro.  For the builtins defined by POSIX that bear
+this disclaimer, POSIX specifically states that invoking those
+builtins without arguments is unspecified, because many other
+implementations simply invoke the builtin as though it were given one
+empty argument instead.
+
+@example
+$ @kbd{m4}
+eval
+@result{}eval
+eval(`1')
+@result{}1
+@end example
+
+There is also a command line option (@option{--prefix-builtins}, or
+@option{-P}, @pxref{Operation modes, , Invoking m4}) that renames all
+builtin macros with a prefix of @samp{m4_} at startup.  The option has
+no effect whatsoever on user defined macros.  For example, with this option,
+one has to write @code{m4_dnl} and even @code{m4_m4exit}.  It also has
+no effect on whether a macro requires parameters.
+
+@comment options: -P
+@example
+$ @kbd{m4 -P}
+eval
+@result{}eval
+eval(`1')
+@result{}eval(1)
+m4_eval
+@result{}m4_eval
+m4_eval(`1')
+@result{}1
+@end example
+
+Another alternative is to redefine problematic macros to a name less
+likely to cause conflicts, using @ref{Definitions}.
+
+If your version of GNU @code{m4} has the @code{changeword} feature
+compiled in, it offers far more flexibility in specifying the
+syntax of macro names, both builtin or user-defined.  @xref{Changeword},
+for more information on this experimental feature.
+
+Of course, the simplest way to prevent a name from being interpreted
+as a call to an existing macro is to quote it.  The remainder of
+this section studies a little more deeply how quoting affects macro
+invocation, and how quoting can be used to inhibit macro invocation.
+
+Even if quoting is usually done over the whole macro name, it can also
+be done over only a few characters of this name (provided, of course,
+that the unquoted portions are not also a macro).  It is also possible
+to quote the empty string, but this works only @emph{inside} the name.
+For example:
+
+@example
+`divert'
+@result{}divert
+`d'ivert
+@result{}divert
+di`ver't
+@result{}divert
+div`'ert
+@result{}divert
+@end example
+
+@noindent
+all yield the string @samp{divert}.  While in both:
+
+@example
+`'divert
+@result{}
+divert`'
+@result{}
+@end example
+
+@noindent
+the @code{divert} builtin macro will be called, which expands to the
+empty string.
+
+@cindex rescanning
+The output of macro evaluations is always rescanned.  In the following
+example, the input @samp{x`'y} yields the string @samp{bCD}, exactly as
+if @code{m4}
+has been given @w{@samp{substr(ab`'cde, `1', `3')}} as input:
+
+@example
+define(`cde', `CDE')
+@result{}
+define(`x', `substr(ab')
+@result{}
+define(`y', `cde, `1', `3')')
+@result{}
+x`'y
+@result{}bCD
+@end example
+
+@ignore
+@comment Similar, but with argument references, to ensure good test
+@comment coverage.
+@example
+define(`x1', `len(`$1'')
+@result{}
+define(`y1', ``$1')')
+@result{}
+x1(`01234567890123456789')y1(`98765432109876543210')
+@result{}40
+@end example
+@end ignore
+
+Unquoted strings on either side of a quoted string are subject to
+being recognized as macro names.  In the following example, quoting the
+empty string allows for the second @code{macro} to be recognized as such:
+
+@example
+define(`macro', `m')
+@result{}
+macro(`m')macro
+@result{}mmacro
+macro(`m')`'macro
+@result{}mm
+@end example
+
+Quoting may prevent recognizing as a macro name the concatenation of a
+macro expansion with the surrounding characters.  In this example:
+
+@example
+define(`macro', `di$1')
+@result{}
+macro(`v')`ert'
+@result{}divert
+macro(`v')ert
+@result{}
+@end example
+
+@noindent
+the input will produce the string @samp{divert}.  When the quotes were
+removed, the @code{divert} builtin was called instead.
+
+@node Macro Arguments
+@section Macro arguments
+
+@cindex macros, arguments to
+@cindex arguments to macros
+When a name is seen, and it has a macro definition, it will be expanded
+as a macro.
+
+If the name is followed by an opening parenthesis, the arguments will be
+collected before the macro is called.  If too few arguments are
+supplied, the missing arguments are taken to be the empty string.
+However, some builtins are documented to behave differently for a
+missing optional argument than for an explicit empty string.  If there
+are too many arguments, the excess arguments are ignored.  Unquoted
+leading whitespace is stripped off all arguments, but whitespace
+generated by a macro expansion or occurring after a macro that expanded
+to an empty string remains intact.  Whitespace includes space, tab,
+newline, carriage return, vertical tab, and formfeed.
+
+@example
+define(`macro', `$1')
+@result{}
+macro( unquoted leading space lost)
+@result{}unquoted leading space lost
+macro(` quoted leading space kept')
+@result{} quoted leading space kept
+macro(
+ divert `unquoted space kept after expansion')
+@result{} unquoted space kept after expansion
+macro(macro(`
+')`whitespace from expansion kept')
+@result{}
+@result{}whitespace from expansion kept
+macro(`unquoted trailing whitespace kept'
+)
+@result{}unquoted trailing whitespace kept
+@result{}
+@end example
+
+@cindex warnings, suppressing
+@cindex suppressing warnings
+Normally @code{m4} will issue warnings if a builtin macro is called
+with an inappropriate number of arguments, but it can be suppressed with
+the @option{--quiet} command line option (or @option{--silent}, or
+@option{-Q}, @pxref{Operation modes, , Invoking m4}).  For user
+defined macros, there is no check of the number of arguments given.
+
+@example
+$ @kbd{m4}
+index(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `index'
+@result{}0
+index(`abc',)
+@result{}0
+index(`abc', `b', `ignored')
+@error{}m4:stdin:3: Warning: excess arguments to builtin `index' ignored
+@result{}1
+@end example
+
+@comment options: -Q
+@example
+$ @kbd{m4 -Q}
+index(`abc')
+@result{}0
+index(`abc',)
+@result{}0
+index(`abc', `b', `ignored')
+@result{}1
+@end example
+
+Macros are expanded normally during argument collection, and whatever
+commas, quotes and parentheses that might show up in the resulting
+expanded text will serve to define the arguments as well.  Thus, if
+@var{foo} expands to @samp{, b, c}, the macro call
+
+@comment ignore
+@example
+bar(a foo, d)
+@end example
+
+@noindent
+is a macro call with four arguments, which are @samp{a }, @samp{b},
+@samp{c} and @samp{d}.  To understand why the first argument contains
+whitespace, remember that unquoted leading whitespace is never part
+of an argument, but trailing whitespace always is.
+
+It is possible for a macro's definition to change during argument
+collection, in which case the expansion uses the definition that was in
+effect at the time the opening @samp{(} was seen.
+
+@example
+define(`f', `1')
+@result{}
+f(define(`f', `2'))
+@result{}1
+f
+@result{}2
+@end example
+
+It is an error if the end of file occurs while collecting arguments.
+
+@comment status: 1
+@example
+hello world
+@result{}hello world
+define(
+^D
+@error{}m4:stdin:2: ERROR: end of file in argument list
+@end example
+
+@node Quoting Arguments
+@section On Quoting Arguments to macros
+
+@cindex quoted macro arguments
+@cindex macros, quoted arguments to
+@cindex arguments, quoted macro
+Each argument has unquoted leading whitespace removed.  Within each
+argument, all unquoted parentheses must match.  For example, if
+@var{foo} is a macro,
+
+@comment ignore
+@example
+foo(() (`(') `(')
+@end example
+
+@noindent
+is a macro call, with one argument, whose value is @samp{() (() (}.
+Commas separate arguments, except when they occur inside quotes,
+comments, or unquoted parentheses.  @xref{Pseudo Arguments}, for
+examples.
+
+It is common practice to quote all arguments to macros, unless you are
+sure you want the arguments expanded.  Thus, in the above
+example with the parentheses, the `right' way to do it is like this:
+
+@comment ignore
+@example
+foo(`() (() (')
+@end example
+
+@cindex quoting rule of thumb
+@cindex rule of thumb, quoting
+It is, however, in certain cases necessary (because nested expansion
+must occur to create the arguments for the outer macro) or convenient
+(because it uses fewer characters) to leave out quotes for some
+arguments, and there is nothing wrong in doing it.  It just makes life a
+bit harder, if you are not careful to follow a consistent quoting style.
+For consistency, this manual follows the rule of thumb that each layer
+of parentheses introduces another layer of single quoting, except when
+showing the consequences of quoting rules.  This is done even when the
+quoted string cannot be a macro, such as with integers when you have not
+changed the syntax via @code{changeword} (@pxref{Changeword}).
+
+The quoting rule of thumb of one level of quoting per parentheses has a
+nice property: when a macro name appears inside parentheses, you can
+determine when it will be expanded.  If it is not quoted, it will be
+expanded prior to the outer macro, so that its expansion becomes the
+argument.  If it is single-quoted, it will be expanded after the outer
+macro.  And if it is double-quoted, it will be used as literal text
+instead of a macro name.
+
+@example
+define(`active', `ACT, IVE')
+@result{}
+define(`show', `$1 $1')
+@result{}
+show(active)
+@result{}ACT ACT
+show(`active')
+@result{}ACT, IVE ACT, IVE
+show(``active'')
+@result{}active active
+@end example
+
+@node Macro expansion
+@section Macro expansion
+
+@cindex macros, expansion of
+@cindex expansion of macros
+When the arguments, if any, to a macro call have been collected, the
+macro is expanded, and the expansion text is pushed back onto the input
+(unquoted), and reread.  The expansion text from one macro call might
+therefore result in more macros being called, if the calls are included,
+completely or partially, in the first macro calls' expansion.
+
+Taking a very simple example, if @var{foo} expands to @samp{bar}, and
+@var{bar} expands to @samp{Hello}, the input
+
+@comment options: -Dbar=Hello -Dfoo=bar
+@example
+$ @kbd{m4 -Dbar=Hello -Dfoo=bar}
+foo
+@result{}Hello
+@end example
+
+@noindent
+will expand first to @samp{bar}, and when this is reread and
+expanded, into @samp{Hello}.
+
+@ignore
+@comment not worth documenting, but test that the command line can
+@comment define macros that take parameters
+
+@comment options: -Dfoo -Decho=$@
+@example
+$ @kbd{m4 -Dfoo -Decho='$@'}
+foo
+@result{}
+foo(`silently ignored')
+@result{}
+echo(`1', `2')
+@result{}1,2
+@end example
+@end ignore
+
+@node Definitions
+@chapter How to define new macros
+
+@cindex macros, how to define new
+@cindex defining new macros
+Macros can be defined, redefined and deleted in several different ways.
+Also, it is possible to redefine a macro without losing a previous
+value, and bring back the original value at a later time.
+
+@menu
+* Define::                      Defining a new macro
+* Arguments::                   Arguments to macros
+* Pseudo Arguments::            Special arguments to macros
+* Undefine::                    Deleting a macro
+* Defn::                        Renaming macros
+* Pushdef::                     Temporarily redefining macros
+
+* Indir::                       Indirect call of macros
+* Builtin::                     Indirect call of builtins
+@end menu
+
+@node Define
+@section Defining a macro
+
+The normal way to define or redefine macros is to use the builtin
+@code{define}:
+
+@deffn Builtin define (@var{name}, @ovar{expansion})
+Defines @var{name} to expand to @var{expansion}.  If
+@var{expansion} is not given, it is taken to be empty.
+
+The expansion of @code{define} is void.
+The macro @code{define} is recognized only with parameters.
+@end deffn
+
+The following example defines the macro @var{foo} to expand to the text
+@samp{Hello World.}.
+
+@example
+define(`foo', `Hello world.')
+@result{}
+foo
+@result{}Hello world.
+@end example
+
+The empty line in the output is there because the newline is not
+a part of the macro definition, and it is consequently copied to
+the output.  This can be avoided by use of the macro @code{dnl}.
+@xref{Dnl}, for details.
+
+The first argument to @code{define} should be quoted; otherwise, if the
+macro is already defined, you will be defining a different macro.  This
+example shows the problems with underquoting, since we did not want to
+redefine @code{one}:
+
+@example
+define(foo, one)
+@result{}
+define(foo, two)
+@result{}
+one
+@result{}two
+@end example
+
+@cindex GNU extensions
+GNU @code{m4} normally replaces only the @emph{topmost}
+definition of a macro if it has several definitions from @code{pushdef}
+(@pxref{Pushdef}).  Some other implementations of @code{m4} replace all
+definitions of a macro with @code{define}.  @xref{Incompatibilities},
+for more details.
+
+As a GNU extension, the first argument to @code{define} does
+not have to be a simple word.
+It can be any text string, even the empty string.  A macro with a
+non-standard name cannot be invoked in the normal way, as the name is
+not recognized.  It can only be referenced by the builtins @code{indir}
+(@pxref{Indir}) and @code{defn} (@pxref{Defn}).
+
+@cindex arrays
+Arrays and associative arrays can be simulated by using non-standard
+macro names.
+
+@deffn Composite array (@var{index})
+@deffnx Composite array_set (@var{index}, @ovar{value})
+Provide access to entries within an array.  @code{array} reads the entry
+at location @var{index}, and @code{array_set} assigns @var{value} to
+location @var{index}.
+@end deffn
+
+@example
+define(`array', `defn(format(``array[%d]'', `$1'))')
+@result{}
+define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
+@result{}
+array_set(`4', `array element no. 4')
+@result{}
+array_set(`17', `array element no. 17')
+@result{}
+array(`4')
+@result{}array element no. 4
+array(eval(`10 + 7'))
+@result{}array element no. 17
+@end example
+
+Change the @samp{%d} to @samp{%s} and it is an associative array.
+
+@node Arguments
+@section Arguments to macros
+
+@cindex macros, arguments to
+@cindex arguments to macros
+Macros can have arguments.  The @var{n}th argument is denoted by
+@code{$n} in the expansion text, and is replaced by the @var{n}th actual
+argument, when the macro is expanded.  Replacement of arguments happens
+before rescanning, regardless of how many nesting levels of quoting
+appear in the expansion.  Here is an example of a macro with
+two arguments.
+
+@deffn Composite exch (@var{arg1}, @var{arg2})
+Expands to @var{arg2} followed by @var{arg1}, effectively exchanging
+their order.
+@end deffn
+
+@example
+define(`exch', `$2, $1')
+@result{}
+exch(`arg1', `arg2')
+@result{}arg2, arg1
+@end example
+
+This can be used, for example, if you like the arguments to
+@code{define} to be reversed.
+
+@example
+define(`exch', `$2, $1')
+@result{}
+define(exch(``expansion text'', ``macro''))
+@result{}
+macro
+@result{}expansion text
+@end example
+
+@xref{Quoting Arguments}, for an explanation of the double quotes.
+(You should try and improve this example so that clients of @code{exch}
+do not have to double quote; or @pxref{Improved exch, , Answers}).
+
+As a special case, the zeroth argument, @code{$0}, is always the name
+of the macro being expanded.
+
+@example
+define(`test', ``Macro name: $0'')
+@result{}
+test
+@result{}Macro name: test
+@end example
+
+If you want quoted text to appear as part of the expansion text,
+remember that quotes can be nested in quoted strings.  Thus, in
+
+@example
+define(`foo', `This is macro `foo'.')
+@result{}
+foo
+@result{}This is macro foo.
+@end example
+
+@noindent
+The @samp{foo} in the expansion text is @emph{not} expanded, since it is
+a quoted string, and not a name.
+
+@cindex GNU extensions
+@cindex nine arguments, more than
+@cindex more than nine arguments
+@cindex arguments, more than nine
+@cindex positional parameters, more than nine
+GNU @code{m4} allows the number following the @samp{$} to
+consist of one or more digits, allowing macros to have any number of
+arguments.  The extension of accepting multiple digits is incompatible
+with POSIX, and is different than traditional implementations
+of @code{m4}, which only recognize one digit.  Therefore, future
+versions of GNU M4 will phase out this feature.  To portably
+access beyond the ninth argument, you can use the @code{argn} macro
+documented later (@pxref{Shift}).
+
+POSIX also states that @samp{$} followed immediately by
+@samp{@{} in a macro definition is implementation-defined.  This version
+of M4 passes the literal characters @samp{$@{} through unchanged, but M4
+2.0 will implement an optional feature similar to @command{sh}, where
+@samp{$@{11@}} expands to the eleventh argument, to replace the current
+recognition of @samp{$11}.  Meanwhile, if you want to guarantee that you
+will get a literal @samp{$@{} in output when expanding a macro, even
+when you upgrade to M4 2.0, you can use nested quoting to your
+advantage:
+
+@example
+define(`foo', `single quoted $`'@{1@} output')
+@result{}
+define(`bar', ``double quoted $'`@{2@} output'')
+@result{}
+foo(`a', `b')
+@result{}single quoted $@{1@} output
+bar(`a', `b')
+@result{}double quoted $@{2@} output
+@end example
+
+To help you detect places in your M4 input files that might change in
+behavior due to the changed behavior of M4 2.0, you can use the
+@option{--warn-macro-sequence} command-line option (@pxref{Operation
+modes, , Invoking m4}) with the default regular expression.  This will
+add a warning any time a macro definition includes @samp{$} followed by
+multiple digits, or by @samp{@{}.  The warning is not enabled by
+default, because it triggers a number of warnings in Autoconf 2.61 (and
+Autoconf uses @option{-E} to treat warnings as errors), and because it
+will still be possible to restore older behavior in M4 2.0.
+
+@comment options: --warn-macro-sequence
+@example
+$ @kbd{m4 --warn-macro-sequence}
+define(`foo', `$001 $@{1@} $1')
+@error{}m4:stdin:1: Warning: definition of `foo' contains sequence `$001'
+@error{}m4:stdin:1: Warning: definition of `foo' contains sequence `$@{1@}'
+@result{}
+foo(`bar')
+@result{}bar $@{1@} bar
+@end example
+
+@node Pseudo Arguments
+@section Special arguments to macros
+
+@cindex special arguments to macros
+@cindex macros, special arguments to
+@cindex arguments to macros, special
+There is a special notation for the number of actual arguments supplied,
+and for all the actual arguments.
+
+The number of actual arguments in a macro call is denoted by @code{$#}
+in the expansion text.
+
+@deffn Composite nargs (@dots{})
+Expands to a count of the number of arguments supplied.
+@end deffn
+
+@example
+define(`nargs', `$#')
+@result{}
+nargs
+@result{}0
+nargs()
+@result{}1
+nargs(`arg1', `arg2', `arg3')
+@result{}3
+nargs(`commas can be quoted, like this')
+@result{}1
+nargs(arg1#inside comments, commas do not separate arguments
+still arg1)
+@result{}1
+nargs((unquoted parentheses, like this, group arguments))
+@result{}1
+@end example
+
+Remember that @samp{#} defaults to the comment character; if you forget
+quotes to inhibit the comment behavior, your macro definition may not
+end where you expected.
+
+@example
+dnl Attempt to define a macro to just `$#'
+define(underquoted, $#)
+oops)
+@result{}
+underquoted
+@result{}0)
+@result{}oops
+@end example
+
+The notation @code{$*} can be used in the expansion text to denote all
+the actual arguments, unquoted, with commas in between.  For example
+
+@example
+define(`echo', `$*')
+@result{}
+echo(arg1,    arg2, arg3 , arg4)
+@result{}arg1,arg2,arg3 ,arg4
+@end example
+
+Often each argument should be quoted, and the notation @code{$@@} handles
+that.  It is just like @code{$*}, except that it quotes each argument.
+A simple example of that is:
+
+@example
+define(`echo', `$@@')
+@result{}
+echo(arg1,    arg2, arg3 , arg4)
+@result{}arg1,arg2,arg3 ,arg4
+@end example
+
+Where did the quotes go?  Of course, they were eaten, when the expanded
+text were reread by @code{m4}.  To show the difference, try
+
+@example
+define(`echo1', `$*')
+@result{}
+define(`echo2', `$@@')
+@result{}
+define(`foo', `This is macro `foo'.')
+@result{}
+echo1(foo)
+@result{}This is macro This is macro foo..
+echo1(`foo')
+@result{}This is macro foo.
+echo2(foo)
+@result{}This is macro foo.
+echo2(`foo')
+@result{}foo
+@end example
+
+@noindent
+@xref{Trace}, if you do not understand this.  As another example of the
+difference, remember that comments encountered in arguments are passed
+untouched to the macro, and that quoting disables comments.
+
+@example
+define(`echo1', `$*')
+@result{}
+define(`echo2', `$@@')
+@result{}
+define(`foo', `bar')
+@result{}
+echo1(#foo'foo
+foo)
+@result{}#foo'foo
+@result{}bar
+echo2(#foo'foo
+foo)
+@result{}#foobar
+@result{}bar'
+@end example
+
+@ignore
+@comment Not worth putting in the manual, but this example is needed for
+@comment good test coverage of copying large strings across recursion
+@comment levels.
+
+@example
+define(`echo', `$@@')dnl
+echo(echo(`01234567890123456789', `01234567890123456789')
+echo(`98765432109876543210', `98765432109876543210'))
+@result{}01234567890123456789,01234567890123456789
+@result{}98765432109876543210,98765432109876543210
+len((echo(`01234567890123456789',
+          `01234567890123456789')echo(`98765432109876543210',
+                                      `98765432109876543210')))
+@result{}84
+indir(`echo', indir(`echo', `01234567890123456789',
+                            `01234567890123456789')
+indir(`echo', `98765432109876543210', `98765432109876543210'))
+@result{}01234567890123456789,01234567890123456789
+@result{}98765432109876543210,98765432109876543210
+define(`argn', `$#')dnl
+define(`echo1', `-$@@-')define(`echo2', `,$@@,')dnl
+echo1(`1', `2', `3') argn(echo1(`1', `2', `3'))
+@result{}-1,2,3- 3
+echo2(`1', `2', `3') argn(echo2(`1', `2', `3'))
+@result{},1,2,3, 5
+@end example
+@end ignore
+
+A @samp{$} sign in the expansion text, that is not followed by anything
+@code{m4} understands, is simply copied to the macro expansion, as any
+other text is.
+
+@example
+define(`foo', `$$$ hello $$$')
+@result{}
+foo
+@result{}$$$ hello $$$
+@end example
+
+@cindex rescanning
+@cindex literal output
+@cindex output, literal
+If you want a macro to expand to something like @samp{$12}, the
+judicious use of nested quoting can put a safe character between the
+@code{$} and the next character, relying on the rescanning to remove the
+nested quote.  This will prevent @code{m4} from interpreting the
+@code{$} sign as a reference to an argument.
+
+@example
+define(`foo', `no nested quote: $1')
+@result{}
+foo(`arg')
+@result{}no nested quote: arg
+define(`foo', `nested quote around $: `$'1')
+@result{}
+foo(`arg')
+@result{}nested quote around $: $1
+define(`foo', `nested empty quote after $: $`'1')
+@result{}
+foo(`arg')
+@result{}nested empty quote after $: $1
+define(`foo', `nested quote around next character: $`1'')
+@result{}
+foo(`arg')
+@result{}nested quote around next character: $1
+define(`foo', `nested quote around both: `$1'')
+@result{}
+foo(`arg')
+@result{}nested quote around both: arg
+@end example
+
+@node Undefine
+@section Deleting a macro
+
+@cindex macros, how to delete
+@cindex deleting macros
+@cindex undefining macros
+A macro definition can be removed with @code{undefine}:
+
+@deffn Builtin undefine (@var{name}@dots{})
+For each argument, remove the macro @var{name}.  The macro names must
+necessarily be quoted, since they will be expanded otherwise.
+
+The expansion of @code{undefine} is void.
+The macro @code{undefine} is recognized only with parameters.
+@end deffn
+
+@example
+foo bar blah
+@result{}foo bar blah
+define(`foo', `some')define(`bar', `other')define(`blah', `text')
+@result{}
+foo bar blah
+@result{}some other text
+undefine(`foo')
+@result{}
+foo bar blah
+@result{}foo other text
+undefine(`bar', `blah')
+@result{}
+foo bar blah
+@result{}foo bar blah
+@end example
+
+Undefining a macro inside that macro's expansion is safe; the macro
+still expands to the definition that was in effect at the @samp{(}.
+
+@example
+define(`f', ``$0':$1')
+@result{}
+f(f(f(undefine(`f')`hello world')))
+@result{}f:f:f:hello world
+f(`bye')
+@result{}f(bye)
+@end example
+
+It is not an error for @var{name} to have no macro definition.  In that
+case, @code{undefine} does nothing.
+
+@node Defn
+@section Renaming macros
+
+@cindex macros, how to rename
+@cindex renaming macros
+@cindex macros, displaying definitions
+@cindex definitions, displaying macro
+It is possible to rename an already defined macro.  To do this, you need
+the builtin @code{defn}:
+
+@deffn Builtin defn (@var{name}@dots{})
+Expands to the @emph{quoted definition} of each @var{name}.  If an
+argument is not a defined macro, the expansion for that argument is
+empty.
+
+If @var{name} is a user-defined macro, the quoted definition is simply
+the quoted expansion text.  If, instead, there is only one @var{name}
+and it is a builtin, the
+expansion is a special token, which points to the builtin's internal
+definition.  This token is only meaningful as the second argument to
+@code{define} (and @code{pushdef}), and is silently converted to an
+empty string in most other contexts.  Combining a builtin with anything
+else is not supported; a warning is issued and the builtin is omitted
+from the final expansion.
+
+The macro @code{defn} is recognized only with parameters.
+@end deffn
+
+Its normal use is best understood through an example, which shows how to
+rename @code{undefine} to @code{zap}:
+
+@example
+define(`zap', defn(`undefine'))
+@result{}
+zap(`undefine')
+@result{}
+undefine(`zap')
+@result{}undefine(zap)
+@end example
+
+In this way, @code{defn} can be used to copy macro definitions, and also
+definitions of builtin macros.  Even if the original macro is removed,
+the other name can still be used to access the definition.
+
+The fact that macro definitions can be transferred also explains why you
+should use @code{$0}, rather than retyping a macro's name in its
+definition:
+
+@example
+define(`foo', `This is `$0'')
+@result{}
+define(`bar', defn(`foo'))
+@result{}
+bar
+@result{}This is bar
+@end example
+
+Macros used as string variables should be referred through @code{defn},
+to avoid unwanted expansion of the text:
+
+@example
+define(`string', `The macro dnl is very useful
+')
+@result{}
+string
+@result{}The macro@w{ }
+defn(`string')
+@result{}The macro dnl is very useful
+@result{}
+@end example
+
+@cindex rescanning
+However, it is important to remember that @code{m4} rescanning is purely
+textual.  If an unbalanced end-quote string occurs in a macro
+definition, the rescan will see that embedded quote as the termination
+of the quoted string, and the remainder of the macro's definition will
+be rescanned unquoted.  Thus it is a good idea to avoid unbalanced
+end-quotes in macro definitions or arguments to macros.
+
+@example
+define(`foo', a'a)
+@result{}
+define(`a', `A')
+@result{}
+define(`echo', `$@@')
+@result{}
+foo
+@result{}A'A
+defn(`foo')
+@result{}aA'
+echo(foo)
+@result{}AA'
+@end example
+
+On the other hand, it is possible to exploit the fact that @code{defn}
+can concatenate multiple macros prior to the rescanning phase, in order
+to join the definitions of macros that, in isolation, have unbalanced
+quotes.  This is particularly useful when one has used several macros to
+accumulate text that M4 should rescan as a whole.  In the example below,
+note how the use of @code{defn} on @code{l} in isolation opens a string,
+which is not closed until the next line; but used on @code{l} and
+@code{r} together results in nested quoting.
+
+@example
+define(`l', `<[>')define(`r', `<]>')
+@result{}
+changequote(`[', `]')
+@result{}
+defn([l])defn([r])
+])
+@result{}<[>]defn([r])
+@result{})
+defn([l], [r])
+@result{}<[>][<]>
+@end example
+
+@cindex builtins, special tokens
+@cindex tokens, builtin macro
+Using @code{defn} to generate special tokens for builtin macros outside
+of expected contexts can sometimes trigger warnings.  But most of the
+time, such tokens are silently converted to the empty string.
+
+@example
+$ @kbd{m4 -d}
+defn(`defn')
+@result{}
+define(defn(`divnum'), `cannot redefine a builtin token')
+@error{}m4:stdin:2: Warning: define: invalid macro name ignored
+@result{}
+divnum
+@result{}0
+len(defn(`divnum'))
+@result{}0
+@end example
+
+Also note that @code{defn} with multiple arguments can only join text
+macros, not builtins, although a future version of GNU M4 may
+lift this restriction.
+
+@example
+$ @kbd{m4 -d}
+define(`a', `A')define(`AA', `b')
+@result{}
+traceon(`defn', `define')
+@result{}
+defn(`a', `divnum', `a')
+@error{}m4:stdin:3: Warning: cannot concatenate builtin `divnum'
+@error{}m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A''
+@result{}AA
+define(`mydivnum', defn(`divnum', `divnum'))mydivnum
+@error{}m4:stdin:4: Warning: cannot concatenate builtin `divnum'
+@error{}m4:stdin:4: Warning: cannot concatenate builtin `divnum'
+@error{}m4trace: -2- defn(`divnum', `divnum')
+@error{}m4trace: -1- define(`mydivnum', `')
+@result{}
+traceoff(`defn', `define')
+@result{}
+@end example
+
+@node Pushdef
+@section Temporarily redefining macros
+
+@cindex macros, temporary redefinition of
+@cindex temporary redefinition of macros
+@cindex redefinition of macros, temporary
+@cindex definition stack
+@cindex pushdef stack
+@cindex stack, macro definition
+It is possible to redefine a macro temporarily, reverting to the
+previous definition at a later time.  This is done with the builtins
+@code{pushdef} and @code{popdef}:
+
+@deffn Builtin pushdef (@var{name}, @ovar{expansion})
+@deffnx Builtin popdef (@var{name}@dots{})
+Analogous to @code{define} and @code{undefine}.
+
+These macros work in a stack-like fashion.  A macro is temporarily
+redefined with @code{pushdef}, which replaces an existing definition of
+@var{name}, while saving the previous definition, before the new one is
+installed.  If there is no previous definition, @code{pushdef} behaves
+exactly like @code{define}.
+
+If a macro has several definitions (of which only one is accessible),
+the topmost definition can be removed with @code{popdef}.  If there is
+no previous definition, @code{popdef} behaves like @code{undefine}.
+
+The expansion of both @code{pushdef} and @code{popdef} is void.
+The macros @code{pushdef} and @code{popdef} are recognized only with
+parameters.
+@end deffn
+
+@example
+define(`foo', `Expansion one.')
+@result{}
+foo
+@result{}Expansion one.
+pushdef(`foo', `Expansion two.')
+@result{}
+foo
+@result{}Expansion two.
+pushdef(`foo', `Expansion three.')
+@result{}
+pushdef(`foo', `Expansion four.')
+@result{}
+popdef(`foo')
+@result{}
+foo
+@result{}Expansion three.
+popdef(`foo', `foo')
+@result{}
+foo
+@result{}Expansion one.
+popdef(`foo')
+@result{}
+foo
+@result{}foo
+@end example
+
+If a macro with several definitions is redefined with @code{define}, the
+topmost definition is @emph{replaced} with the new definition.  If it is
+removed with @code{undefine}, @emph{all} the definitions are removed,
+and not only the topmost one.  However, POSIX allows other
+implementations that treat @code{define} as replacing an entire stack
+of definitions with a single new definition, so to be portable to other
+implementations, it may be worth explicitly using @code{popdef} and
+@code{pushdef} rather than relying on the GNU behavior of
+@code{define}.
+
+@example
+define(`foo', `Expansion one.')
+@result{}
+foo
+@result{}Expansion one.
+pushdef(`foo', `Expansion two.')
+@result{}
+foo
+@result{}Expansion two.
+define(`foo', `Second expansion two.')
+@result{}
+foo
+@result{}Second expansion two.
+undefine(`foo')
+@result{}
+foo
+@result{}foo
+@end example
+
+@cindex local variables
+@cindex variables, local
+Local variables within macros are made with @code{pushdef} and
+@code{popdef}.  At the start of the macro a new definition is pushed,
+within the macro it is manipulated and at the end it is popped,
+revealing the former definition.
+
+It is possible to temporarily redefine a builtin with @code{pushdef}
+and @code{defn}.
+
+@node Indir
+@section Indirect call of macros
+
+@cindex indirect call of macros
+@cindex call of macros, indirect
+@cindex macros, indirect call of
+@cindex GNU extensions
+Any macro can be called indirectly with @code{indir}:
+
+@deffn Builtin indir (@var{name}, @ovar{args@dots{}})
+Results in a call to the macro @var{name}, which is passed the
+rest of the arguments @var{args}.  If @var{name} is not defined, an
+error message is printed, and the expansion is void.
+
+The macro @code{indir} is recognized only with parameters.
+@end deffn
+
+This can be used to call macros with computed or ``invalid''
+names (@code{define} allows such names to be defined):
+
+@example
+define(`$$internal$macro', `Internal macro (name `$0')')
+@result{}
+$$internal$macro
+@result{}$$internal$macro
+indir(`$$internal$macro')
+@result{}Internal macro (name $$internal$macro)
+@end example
+
+The point is, here, that larger macro packages can have private macros
+defined, that will not be called by accident.  They can @emph{only} be
+called through the builtin @code{indir}.
+
+One other point to observe is that argument collection occurs before
+@code{indir} invokes @var{name}, so if argument collection changes the
+value of @var{name}, that will be reflected in the final expansion.
+This is different than the behavior when invoking macros directly,
+where the definition that was in effect before argument collection is
+used.
+
+@example
+$ @kbd{m4 -d}
+define(`f', `1')
+@result{}
+f(define(`f', `2'))
+@result{}1
+indir(`f', define(`f', `3'))
+@result{}3
+indir(`f', undefine(`f'))
+@error{}m4:stdin:4: undefined macro `f'
+@result{}
+@end example
+
+When handed the result of @code{defn} (@pxref{Defn}) as one of its
+arguments, @code{indir} defers to the invoked @var{name} for whether a
+token representing a builtin is recognized or flattened to the empty
+string.
+
+@example
+$ @kbd{m4 -d}
+indir(defn(`defn'), `divnum')
+@error{}m4:stdin:1: Warning: indir: invalid macro name ignored
+@result{}
+indir(`define', defn(`defn'), `divnum')
+@error{}m4:stdin:2: Warning: define: invalid macro name ignored
+@result{}
+indir(`define', `foo', defn(`divnum'))
+@result{}
+foo
+@result{}0
+indir(`divert', defn(`foo'))
+@error{}m4:stdin:5: empty string treated as 0 in builtin `divert'
+@result{}
+@end example
+
+@node Builtin
+@section Indirect call of builtins
+
+@cindex indirect call of builtins
+@cindex call of builtins, indirect
+@cindex builtins, indirect call of
+@cindex GNU extensions
+Builtin macros can be called indirectly with @code{builtin}:
+
+@deffn Builtin builtin (@var{name}, @ovar{args@dots{}})
+Results in a call to the builtin @var{name}, which is passed the
+rest of the arguments @var{args}.  If @var{name} does not name a
+builtin, an error message is printed, and the expansion is void.
+
+The macro @code{builtin} is recognized only with parameters.
+@end deffn
+
+This can be used even if @var{name} has been given another definition
+that has covered the original, or been undefined so that no macro
+maps to the builtin.
+
+@example
+pushdef(`define', `hidden')
+@result{}
+undefine(`undefine')
+@result{}
+define(`foo', `bar')
+@result{}hidden
+foo
+@result{}foo
+builtin(`define', `foo', defn(`divnum'))
+@result{}
+foo
+@result{}0
+builtin(`define', `foo', `BAR')
+@result{}
+foo
+@result{}BAR
+undefine(`foo')
+@result{}undefine(foo)
+foo
+@result{}BAR
+builtin(`undefine', `foo')
+@result{}
+foo
+@result{}foo
+@end example
+
+The @var{name} argument only matches the original name of the builtin,
+even when the @option{--prefix-builtins} option (or @option{-P},
+@pxref{Operation modes, , Invoking m4}) is in effect.  This is different
+from @code{indir}, which only tracks current macro names.
+
+@comment options: -P
+@example
+$ @kbd{m4 -P}
+m4_builtin(`divnum')
+@result{}0
+m4_builtin(`m4_divnum')
+@error{}m4:stdin:2: undefined builtin `m4_divnum'
+@result{}
+m4_indir(`divnum')
+@error{}m4:stdin:3: undefined macro `divnum'
+@result{}
+m4_indir(`m4_divnum')
+@result{}0
+@end example
+
+Note that @code{indir} and @code{builtin} can be used to invoke builtins
+without arguments, even when they normally require parameters to be
+recognized; but it will provoke a warning, and result in a void expansion.
+
+@example
+builtin
+@result{}builtin
+builtin()
+@error{}m4:stdin:2: undefined builtin `'
+@result{}
+builtin(`builtin')
+@error{}m4:stdin:3: Warning: too few arguments to builtin `builtin'
+@result{}
+builtin(`builtin',)
+@error{}m4:stdin:4: undefined builtin `'
+@result{}
+builtin(`builtin', ``'
+')
+@error{}m4:stdin:5: undefined builtin ``'
+@error{}'
+@result{}
+indir(`index')
+@error{}m4:stdin:7: Warning: too few arguments to builtin `index'
+@result{}
+@end example
+
+@ignore
+@comment This example is not worth putting in the manual, but it is
+@comment needed for full coverage.  Autoconf's m4_include relies heavily
+@comment on this feature.
+
+@example
+builtin(`include', `foo')dnl
+@result{}bar
+@end example
+
+@comment And this example triggers a regression present in 1.4.10b.
+
+@example
+define(`s', `builtin(`shift', $@@)')dnl
+define(`loop', `ifelse(`$2', `', `-', `$1$2: $0(`$1', s(s($@@)))')')dnl
+loop(`1')
+@result{}-
+loop(`1', `2')
+@result{}12: -
+loop(`1', `2', `3')
+@result{}12: 13: -
+loop(`1', `2', `3', `4')
+@result{}12: 13: 14: -
+loop(`1', `2', `3', `4', `5')
+@result{}12: 13: 14: 15: -
+@end example
+@end ignore
+
+@node Conditionals
+@chapter Conditionals, loops, and recursion
+
+Macros, expanding to plain text, perhaps with arguments, are not quite
+enough.  We would like to have macros expand to different things, based
+on decisions taken at run-time.  For that, we need some kind of conditionals.
+Also, we would like to have some kind of loop construct, so we could do
+something a number of times, or while some condition is true.
+
+@menu
+* Ifdef::                       Testing if a macro is defined
+* Ifelse::                      If-else construct, or multibranch
+* Shift::                       Recursion in @code{m4}
+* Forloop::                     Iteration by counting
+* Foreach::                     Iteration by list contents
+* Stacks::                      Working with definition stacks
+* Composition::                 Building macros with macros
+@end menu
+
+@node Ifdef
+@section Testing if a macro is defined
+
+@cindex conditionals
+There are two different builtin conditionals in @code{m4}.  The first is
+@code{ifdef}:
+
+@deffn Builtin ifdef (@var{name}, @var{string-1}, @ovar{string-2})
+If @var{name} is defined as a macro, @code{ifdef} expands to
+@var{string-1}, otherwise to @var{string-2}.  If @var{string-2} is
+omitted, it is taken to be the empty string (according to the normal
+rules).
+
+The macro @code{ifdef} is recognized only with parameters.
+@end deffn
+
+@example
+ifdef(`foo', ``foo' is defined', ``foo' is not defined')
+@result{}foo is not defined
+define(`foo', `')
+@result{}
+ifdef(`foo', ``foo' is defined', ``foo' is not defined')
+@result{}foo is defined
+ifdef(`no_such_macro', `yes', `no', `extra argument')
+@error{}m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored
+@result{}no
+@end example
+
+@node Ifelse
+@section If-else construct, or multibranch
+
+@cindex comparing strings
+@cindex discarding input
+@cindex input, discarding
+The other conditional, @code{ifelse}, is much more powerful.  It can be
+used as a way to introduce a long comment, as an if-else construct, or
+as a multibranch, depending on the number of arguments supplied:
+
+@deffn Builtin ifelse (@var{comment})
+@deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal}, @
+  @ovar{not-equal})
+@deffnx Builtin ifelse (@var{string-1}, @var{string-2}, @var{equal-1}, @
+  @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal})
+Used with only one argument, the @code{ifelse} simply discards it and
+produces no output.
+
+If called with three or four arguments, @code{ifelse} expands into
+@var{equal}, if @var{string-1} and @var{string-2} are equal (character
+for character), otherwise it expands to @var{not-equal}.  A final fifth
+argument is ignored, after triggering a warning.
+
+If called with six or more arguments, and @var{string-1} and
+@var{string-2} are equal, @code{ifelse} expands into @var{equal-1},
+otherwise the first three arguments are discarded and the processing
+starts again.
+
+The macro @code{ifelse} is recognized only with parameters.
+@end deffn
+
+Using only one argument is a common @code{m4} idiom for introducing a
+block comment, as an alternative to repeatedly using @code{dnl}.  This
+special usage is recognized by GNU @code{m4}, so that in this
+case, the warning about missing arguments is never triggered.
+
+@example
+ifelse(`some comments')
+@result{}
+ifelse(`foo', `bar')
+@error{}m4:stdin:2: Warning: too few arguments to builtin `ifelse'
+@result{}
+@end example
+
+Using three or four arguments provides decision points.
+
+@example
+ifelse(`foo', `bar', `true')
+@result{}
+ifelse(`foo', `foo', `true')
+@result{}true
+define(`foo', `bar')
+@result{}
+ifelse(foo, `bar', `true', `false')
+@result{}true
+ifelse(foo, `foo', `true', `false')
+@result{}false
+@end example
+
+@cindex macro, blind
+@cindex blind macro
+Notice how the first argument was used unquoted; it is common to compare
+the expansion of a macro with a string.  With this macro, you can now
+reproduce the behavior of blind builtins, where the macro is recognized
+only with arguments.
+
+@example
+define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')')
+@result{}
+foo
+@result{}foo
+foo()
+@result{}arguments:1
+foo(`a', `b', `c')
+@result{}arguments:3
+@end example
+
+For an example of a way to make defining blind macros easier, see
+@ref{Composition}.
+
+@cindex multibranches
+@cindex switch statement
+@cindex case statement
+The macro @code{ifelse} can take more than four arguments.  If given more
+than four arguments, @code{ifelse} works like a @code{case} or @code{switch}
+statement in traditional programming languages.  If @var{string-1} and
+@var{string-2} are equal, @code{ifelse} expands into @var{equal-1}, otherwise
+the procedure is repeated with the first three arguments discarded.  This
+calls for an example:
+
+@example
+ifelse(`foo', `bar', `third', `gnu', `gnats')
+@error{}m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored
+@result{}gnu
+ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth')
+@result{}
+ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh')
+@result{}seventh
+ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8')
+@error{}m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored
+@result{}7
+@end example
+
+@ignore
+@comment Stress tests, not worth documenting.
+
+@comment Ensure that references compared to strings work regardless of
+@comment similar prefixes.
+@example
+define(`e', `$@@')define(`long', `01234567890123456789')
+@result{}
+ifelse(long, `01234567890123456789', `yes', `no')
+@result{}yes
+ifelse(`01234567890123456789', long, `yes', `no')
+@result{}yes
+ifelse(long, `01234567890123456789-', `yes', `no')
+@result{}no
+ifelse(`01234567890123456789-', long, `yes', `no')
+@result{}no
+ifelse(e(long), `01234567890123456789', `yes', `no')
+@result{}yes
+ifelse(`01234567890123456789', e(long), `yes', `no')
+@result{}yes
+ifelse(e(long), `01234567890123456789-', `yes', `no')
+@result{}no
+ifelse(`01234567890123456789-', e(long), `yes', `no')
+@result{}no
+ifelse(-e(long), `-01234567890123456789', `yes', `no')
+@result{}yes
+ifelse(-`01234567890123456789', -e(long), `yes', `no')
+@result{}yes
+ifelse(-e(long), `-01234567890123456789-', `yes', `no')
+@result{}no
+ifelse(`-01234567890123456789-', -e(long), `yes', `no')
+@result{}no
+ifelse(-e(long)-, `-01234567890123456789-', `yes', `no')
+@result{}yes
+ifelse(-`01234567890123456789-', -e(long)-, `yes', `no')
+@result{}yes
+ifelse(-e(long)-, `-01234567890123456789', `yes', `no')
+@result{}no
+ifelse(`-01234567890123456789', -e(long)-, `yes', `no')
+@result{}no
+ifelse(`-'e(long), `-01234567890123456789', `yes', `no')
+@result{}yes
+ifelse(-`01234567890123456789', `-'e(long), `yes', `no')
+@result{}yes
+ifelse(`-'e(long), `-01234567890123456789-', `yes', `no')
+@result{}no
+ifelse(`-01234567890123456789-', `-'e(long), `yes', `no')
+@result{}no
+ifelse(`-'e(long)`-', `-01234567890123456789-', `yes', `no')
+@result{}yes
+ifelse(-`01234567890123456789-', `-'e(long)`-', `yes', `no')
+@result{}yes
+ifelse(`-'e(long)`-', `-01234567890123456789', `yes', `no')
+@result{}no
+ifelse(`-01234567890123456789', `-'e(long)`-', `yes', `no')
+@result{}no
+@end example
+@end ignore
+
+Naturally, the normal case will be slightly more advanced than these
+examples.  A common use of @code{ifelse} is in macros implementing loops
+of various kinds.
+
+@node Shift
+@section Recursion in @code{m4}
+
+@cindex recursive macros
+@cindex macros, recursive
+There is no direct support for loops in @code{m4}, but macros can be
+recursive.  There is no limit on the number of recursion levels, other
+than those enforced by your hardware and operating system.
+
+@cindex loops
+Loops can be programmed using recursion and the conditionals described
+previously.
+
+There is a builtin macro, @code{shift}, which can, among other things,
+be used for iterating through the actual arguments to a macro:
+
+@deffn Builtin shift (@var{arg1}, @dots{})
+Takes any number of arguments, and expands to all its arguments except
+@var{arg1}, separated by commas, with each argument quoted.
+
+The macro @code{shift} is recognized only with parameters.
+@end deffn
+
+@example
+shift
+@result{}shift
+shift(`bar')
+@result{}
+shift(`foo', `bar', `baz')
+@result{}bar,baz
+@end example
+
+An example of the use of @code{shift} is this macro:
+
+@cindex reversing arguments
+@cindex arguments, reversing
+@deffn Composite reverse (@dots{})
+Takes any number of arguments, and reverses their order.
+@end deffn
+
+It is implemented as:
+
+@example
+define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
+                          `reverse(shift($@@)), `$1'')')
+@result{}
+reverse
+@result{}
+reverse(`foo')
+@result{}foo
+reverse(`foo', `bar', `gnats', `and gnus')
+@result{}and gnus, gnats, bar, foo
+@end example
+
+While not a very interesting macro, it does show how simple loops can be
+made with @code{shift}, @code{ifelse} and recursion.  It also shows
+that @code{shift} is usually used with @samp{$@@}.  Another example of
+this is an implementation of a short-circuiting conditional operator.
+
+@cindex short-circuiting conditional
+@cindex conditional, short-circuiting
+@deffn Composite cond (@var{test-1}, @var{string-1}, @var{equal-1}, @
+  @ovar{test-2}, @ovar{string-2}, @ovar{equal-2}, @dots{}, @ovar{not-equal})
+Similar to @code{ifelse}, where an equal comparison between the first
+two strings results in the third, otherwise the first three arguments
+are discarded and the process repeats.  The difference is that each
+@var{test-<n>} is expanded only when it is encountered.  This means that
+every third argument to @code{cond} is normally given one more level of
+quoting than the corresponding argument to @code{ifelse}.
+@end deffn
+
+Here is the implementation of @code{cond}, along with a demonstration of
+how it can short-circuit the side effects in @code{side}.  Notice how
+all the unquoted side effects happen regardless of how many comparisons
+are made with @code{ifelse}, compared with only the relevant effects
+with @code{cond}.
+
+@example
+define(`cond',
+`ifelse(`$#', `1', `$1',
+        `ifelse($1, `$2', `$3',
+                `$0(shift(shift(shift($@@))))')')')dnl
+define(`side', `define(`counter', incr(counter))$1')dnl
+define(`example1',
+`define(`counter', `0')dnl
+ifelse(side(`$1'), `yes', `one comparison: ',
+       side(`$1'), `no', `two comparisons: ',
+       side(`$1'), `maybe', `three comparisons: ',
+       `side(`default answer: ')')counter')dnl
+define(`example2',
+`define(`counter', `0')dnl
+cond(`side(`$1')', `yes', `one comparison: ',
+     `side(`$1')', `no', `two comparisons: ',
+     `side(`$1')', `maybe', `three comparisons: ',
+     `side(`default answer: ')')counter')dnl
+example1(`yes')
+@result{}one comparison: 3
+example1(`no')
+@result{}two comparisons: 3
+example1(`maybe')
+@result{}three comparisons: 3
+example1(`feeling rather indecisive today')
+@result{}default answer: 4
+example2(`yes')
+@result{}one comparison: 1
+example2(`no')
+@result{}two comparisons: 2
+example2(`maybe')
+@result{}three comparisons: 3
+example2(`feeling rather indecisive today')
+@result{}default answer: 4
+@end example
+
+@cindex joining arguments
+@cindex arguments, joining
+@cindex concatenating arguments
+Another common task that requires iteration is joining a list of
+arguments into a single string.
+
+@deffn Composite join (@ovar{separator}, @ovar{args@dots{}})
+@deffnx Composite joinall (@ovar{separator}, @ovar{args@dots{}})
+Generate a single-quoted string, consisting of each @var{arg} separated
+by @var{separator}.  While @code{joinall} always outputs a
+@var{separator} between arguments, @code{join} avoids the
+@var{separator} for an empty @var{arg}.
+@end deffn
+
+Here are some examples of its usage, based on the implementation
+@file{m4-@value{VERSION}/@/examples/@/join.m4} distributed in this
+package:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`join.m4')
+@result{}
+join,join(`-'),join(`-', `'),join(`-', `', `')
+@result{},,,
+joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `')
+@result{},,,-
+join(`-', `1')
+@result{}1
+join(`-', `1', `2', `3')
+@result{}1-2-3
+join(`', `1', `2', `3')
+@result{}123
+join(`-', `', `1', `', `', `2', `')
+@result{}1-2
+joinall(`-', `', `1', `', `', `2', `')
+@result{}-1---2-
+join(`,', `1', `2', `3')
+@result{}1,2,3
+define(`nargs', `$#')dnl
+nargs(join(`,', `1', `2', `3'))
+@result{}1
+@end example
+
+Examining the implementation shows some interesting points about several
+m4 programming idioms.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`join.m4')dnl
+@result{}divert(`-1')
+@result{}# join(sep, args) - join each non-empty ARG into a single
+@result{}# string, with each element separated by SEP
+@result{}define(`join',
+@result{}`ifelse(`$#', `2', ``$2'',
+@result{}  `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@@)))')')
+@result{}define(`_join',
+@result{}`ifelse(`$#$2', `2', `',
+@result{}  `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@@)))')')
+@result{}# joinall(sep, args) - join each ARG, including empty ones,
+@result{}# into a single string, with each element separated by SEP
+@result{}define(`joinall', ``$2'_$0(`$1', shift($@@))')
+@result{}define(`_joinall',
+@result{}`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@@)))')')
+@result{}divert`'dnl
+@end example
+
+First, notice that this implementation creates helper macros
+@code{_join} and @code{_joinall}.  This division of labor makes it
+easier to output the correct number of @var{separator} instances:
+@code{join} and @code{joinall} are responsible for the first argument,
+without a separator, while @code{_join} and @code{_joinall} are
+responsible for all remaining arguments, always outputting a separator
+when outputting an argument.
+
+Next, observe how @code{join} decides to iterate to itself, because the
+first @var{arg} was empty, or to output the argument and swap over to
+@code{_join}.  If the argument is non-empty, then the nested
+@code{ifelse} results in an unquoted @samp{_}, which is concatenated
+with the @samp{$0} to form the next macro name to invoke.  The
+@code{joinall} implementation is simpler since it does not have to
+suppress empty @var{arg}; it always executes once then defers to
+@code{_joinall}.
+
+Another important idiom is the idea that @var{separator} is reused for
+each iteration.  Each iteration has one less argument, but rather than
+discarding @samp{$1} by iterating with @code{$0(shift($@@))}, the macro
+discards @samp{$2} by using @code{$0(`$1', shift(shift($@@)))}.
+
+Next, notice that it is possible to compare more than one condition in a
+single @code{ifelse} test.  The test of @samp{$#$2} against @samp{2}
+allows @code{_join} to iterate for two separate reasons---either there
+are still more than two arguments, or there are exactly two arguments
+but the last argument is not empty.
+
+Finally, notice that these macros require exactly two arguments to
+terminate recursion, but that they still correctly result in empty
+output when given no @var{args} (i.e., zero or one macro argument).  On
+the first pass when there are too few arguments, the @code{shift}
+results in no output, but leaves an empty string to serve as the
+required second argument for the second pass.  Put another way,
+@samp{`$1', shift($@@)} is not the same as @samp{$@@}, since only the
+former guarantees at least two arguments.
+
+@cindex quote manipulation
+@cindex manipulating quotes
+Sometimes, a recursive algorithm requires adding quotes to each element,
+or treating multiple arguments as a single element:
+
+@deffn Composite quote (@dots{})
+@deffnx Composite dquote (@dots{})
+@deffnx Composite dquote_elt (@dots{})
+Takes any number of arguments, and adds quoting.  With @code{quote},
+only one level of quoting is added, effectively removing whitespace
+after commas and turning multiple arguments into a single string.  With
+@code{dquote}, two levels of quoting are added, one around each element,
+and one around the list.  And with @code{dquote_elt}, two levels of
+quoting are added around each element.
+@end deffn
+
+An actual implementation of these three macros is distributed as
+@file{m4-@value{VERSION}/@/examples/@/quote.m4} in this package.  First,
+let's examine their usage:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`quote.m4')
+@result{}
+-quote-dquote-dquote_elt-
+@result{}----
+-quote()-dquote()-dquote_elt()-
+@result{}--`'-`'-
+-quote(`1')-dquote(`1')-dquote_elt(`1')-
+@result{}-1-`1'-`1'-
+-quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')-
+@result{}-1,2-`1',`2'-`1',`2'-
+define(`n', `$#')dnl
+-n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))-
+@result{}-1-1-2-
+dquote(dquote_elt(`1', `2'))
+@result{}``1'',``2''
+dquote_elt(dquote(`1', `2'))
+@result{}``1',`2''
+@end example
+
+The last two lines show that when given two arguments, @code{dquote}
+results in one string, while @code{dquote_elt} results in two.  Now,
+examine the implementation.  Note that @code{quote} and
+@code{dquote_elt} make decisions based on their number of arguments, so
+that when called without arguments, they result in nothing instead of a
+quoted empty string; this is so that it is possible to distinguish
+between no arguments and an empty first argument.  @code{dquote}, on the
+other hand, results in a string no matter what, since it is still
+possible to tell whether it was invoked without arguments based on the
+resulting string.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`quote.m4')dnl
+@result{}divert(`-1')
+@result{}# quote(args) - convert args to single-quoted string
+@result{}define(`quote', `ifelse(`$#', `0', `', ``$*'')')
+@result{}# dquote(args) - convert args to quoted list of quoted strings
+@result{}define(`dquote', ``$@@'')
+@result{}# dquote_elt(args) - convert args to list of double-quoted strings
+@result{}define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''',
+@result{}                             ```$1'',$0(shift($@@))')')
+@result{}divert`'dnl
+@end example
+
+It is worth pointing out that @samp{quote(@var{args})} is more efficient
+than @samp{joinall(`,', @var{args})} for producing the same output.
+
+@cindex nine arguments, more than
+@cindex more than nine arguments
+@cindex arguments, more than nine
+One more useful macro based on @code{shift} allows portably selecting
+an arbitrary argument (usually greater than the ninth argument), without
+relying on the GNU extension of multi-digit arguments
+(@pxref{Arguments}).
+
+@deffn Composite argn (@var{n}, @dots{})
+Expands to argument @var{n} out of the remaining arguments.  @var{n}
+must be a positive number.  Usually invoked as
+@samp{argn(`@var{n}',$@@)}.
+@end deffn
+
+It is implemented as:
+
+@example
+define(`argn', `ifelse(`$1', 1, ``$2'',
+  `argn(decr(`$1'), shift(shift($@@)))')')
+@result{}
+argn(`1', `a')
+@result{}a
+define(`foo', `argn(`11', $@@)')
+@result{}
+foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
+@result{}k
+@end example
+
+@node Forloop
+@section Iteration by counting
+
+@cindex for loops
+@cindex loops, counting
+@cindex counting loops
+Here is an example of a loop macro that implements a simple for loop.
+
+@deffn Composite forloop (@var{iterator}, @var{start}, @var{end}, @var{text})
+Takes the name in @var{iterator}, which must be a valid macro name, and
+successively assign it each integer value from @var{start} to @var{end},
+inclusive.  For each assignment to @var{iterator}, append @var{text} to
+the expansion of the @code{forloop}.  @var{text} may refer to
+@var{iterator}.  Any definition of @var{iterator} prior to this
+invocation is restored.
+@end deffn
+
+It can, for example, be used for simple counting:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`forloop.m4')
+@result{}
+forloop(`i', `1', `8', `i ')
+@result{}1 2 3 4 5 6 7 8@w{ }
+@end example
+
+For-loops can be nested, like:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`forloop.m4')
+@result{}
+forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
+')
+@result{} (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
+@result{} (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
+@result{} (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
+@result{} (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
+@result{}
+@end example
+
+The implementation of the @code{forloop} macro is fairly
+straightforward.  The @code{forloop} macro itself is simply a wrapper,
+which saves the previous definition of the first argument, calls the
+internal macro @code{@w{_forloop}}, and re-establishes the saved
+definition of the first argument.
+
+The macro @code{@w{_forloop}} expands the fourth argument once, and
+tests to see if the iterator has reached the final value.  If it has
+not finished, it increments the iterator (using the predefined macro
+@code{incr}, @pxref{Incr}), and recurses.
+
+Here is an actual implementation of @code{forloop}, distributed as
+@file{m4-@value{VERSION}/@/examples/@/forloop.m4} in this package:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`forloop.m4')dnl
+@result{}divert(`-1')
+@result{}# forloop(var, from, to, stmt) - simple version
+@result{}define(`forloop', `pushdef(`$1', `$2')_forloop($@@)popdef(`$1')')
+@result{}define(`_forloop',
+@result{}       `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@@)')')
+@result{}divert`'dnl
+@end example
+
+Notice the careful use of quotes.  Certain macro arguments are left
+unquoted, each for its own reason.  Try to find out @emph{why} these
+arguments are left unquoted, and see what happens if they are quoted.
+(As presented, these two macros are useful but not very robust for
+general use.  They lack even basic error handling for cases like
+@var{start} less than @var{end}, @var{end} not numeric, or
+@var{iterator} not being a macro name.  See if you can improve these
+macros; or @pxref{Improved forloop, , Answers}).
+
+@node Foreach
+@section Iteration by list contents
+
+@cindex for each loops
+@cindex loops, list iteration
+@cindex iterating over lists
+Here is an example of a loop macro that implements list iteration.
+
+@deffn Composite foreach (@var{iterator}, @var{paren-list}, @var{text})
+@deffnx Composite foreachq (@var{iterator}, @var{quote-list}, @var{text})
+Takes the name in @var{iterator}, which must be a valid macro name, and
+successively assign it each value from @var{paren-list} or
+@var{quote-list}.  In @code{foreach}, @var{paren-list} is a
+comma-separated list of elements contained in parentheses.  In
+@code{foreachq}, @var{quote-list} is a comma-separated list of elements
+contained in a quoted string.  For each assignment to @var{iterator},
+append @var{text} to the overall expansion.  @var{text} may refer to
+@var{iterator}.  Any definition of @var{iterator} prior to this
+invocation is restored.
+@end deffn
+
+As an example, this displays each word in a list inside of a sentence,
+using an implementation of @code{foreach} distributed as
+@file{m4-@value{VERSION}/@/examples/@/foreach.m4}, and @code{foreachq}
+in @file{m4-@value{VERSION}/@/examples/@/foreachq.m4}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreach.m4')
+@result{}
+foreach(`x', (foo, bar, foobar), `Word was: x
+')dnl
+@result{}Word was: foo
+@result{}Word was: bar
+@result{}Word was: foobar
+include(`foreachq.m4')
+@result{}
+foreachq(`x', `foo, bar, foobar', `Word was: x
+')dnl
+@result{}Word was: foo
+@result{}Word was: bar
+@result{}Word was: foobar
+@end example
+
+It is possible to be more complex; each element of the @var{paren-list}
+or @var{quote-list} can itself be a list, to pass as further arguments
+to a helper macro.  This example generates a shell case statement:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreach.m4')
+@result{}
+define(`_case', `  $1)
+    $2=" $1";;
+')dnl
+define(`_cat', `$1$2')dnl
+case $`'1 in
+@result{}case $1 in
+foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
+        `_cat(`_case', x)')dnl
+@result{}  a)
+@result{}    vara=" a";;
+@result{}  b)
+@result{}    varb=" b";;
+@result{}  c)
+@result{}    varc=" c";;
+esac
+@result{}esac
+@end example
+
+The implementation of the @code{foreach} macro is a bit more involved;
+it is a wrapper around two helper macros.  First, @code{@w{_arg1}} is
+needed to grab the first element of a list.  Second,
+@code{@w{_foreach}} implements the recursion, successively walking
+through the original list.  Here is a simple implementation of
+@code{foreach}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`foreach.m4')dnl
+@result{}divert(`-1')
+@result{}# foreach(x, (item_1, item_2, ..., item_n), stmt)
+@result{}#   parenthesized list, simple version
+@result{}define(`foreach', `pushdef(`$1')_foreach($@@)popdef(`$1')')
+@result{}define(`_arg1', `$1')
+@result{}define(`_foreach', `ifelse(`$2', `()', `',
+@result{}  `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')')
+@result{}divert`'dnl
+@end example
+
+Unfortunately, that implementation is not robust to macro names as list
+elements.  Each iteration of @code{@w{_foreach}} is stripping another
+layer of quotes, leading to erratic results if list elements are not
+already fully expanded.  The first cut at implementing @code{foreachq}
+takes this into account.  Also, when using quoted elements in a
+@var{paren-list}, the overall list must be quoted.  A @var{quote-list}
+has the nice property of requiring fewer characters to create a list
+containing the same quoted elements.  To see the difference between the
+two macros, we attempt to pass double-quoted macro names in a list,
+expecting the macro name on output after one layer of quotes is removed
+during list iteration and the final layer removed during the final
+rescan:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+define(`a', `1')define(`b', `2')define(`c', `3')
+@result{}
+include(`foreach.m4')
+@result{}
+include(`foreachq.m4')
+@result{}
+foreach(`x', `(``a'', ``(b'', ``c)'')', `x
+')
+@result{}1
+@result{}(2)1
+@result{}
+@result{}, x
+@result{})
+foreachq(`x', ```a'', ``(b'', ``c)''', `x
+')dnl
+@result{}a
+@result{}(b
+@result{}c)
+@end example
+
+Obviously, @code{foreachq} did a better job; here is its implementation:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`foreachq.m4')dnl
+@result{}include(`quote.m4')dnl
+@result{}divert(`-1')
+@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt)
+@result{}#   quoted list, simple version
+@result{}define(`foreachq', `pushdef(`$1')_foreachq($@@)popdef(`$1')')
+@result{}define(`_arg1', `$1')
+@result{}define(`_foreachq', `ifelse(quote($2), `', `',
+@result{}  `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')')
+@result{}divert`'dnl
+@end example
+
+Notice that @code{@w{_foreachq}} had to use the helper macro
+@code{quote} defined earlier (@pxref{Shift}), to ensure that the
+embedded @code{ifelse} call does not go haywire if a list element
+contains a comma.  Unfortunately, this implementation of @code{foreachq}
+has its own severe flaw.  Whereas the @code{foreach} implementation was
+linear, this macro is quadratic in the number of list elements, and is
+much more likely to trip up the limit set by the command line option
+@option{--nesting-limit} (or @option{-L}, @pxref{Limits control, ,
+Invoking m4}).  Additionally, this implementation does not expand
+@samp{defn(`@var{iterator}')} very well, when compared with
+@code{foreach}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreach.m4')include(`foreachq.m4')
+@result{}
+foreach(`name', `(`a', `b')', ` defn(`name')')
+@result{} a b
+foreachq(`name', ``a', `b'', ` defn(`name')')
+@result{} _arg1(`a', `b') _arg1(shift(`a', `b'))
+@end example
+
+It is possible to have robust iteration with linear behavior and sane
+@var{iterator} contents for either list style.  See if you can learn
+from the best elements of both of these implementations to create robust
+macros (or @pxref{Improved foreach, , Answers}).
+
+@node Stacks
+@section Working with definition stacks
+
+@cindex definition stack
+@cindex pushdef stack
+@cindex stack, macro definition
+Thanks to @code{pushdef}, manipulation of a stack is an intrinsic
+operation in @code{m4}.  Normally, only the topmost definition in a
+stack is important, but sometimes, it is desirable to manipulate the
+entire definition stack.
+
+@deffn Composite stack_foreach (@var{macro}, @var{action})
+@deffnx Composite stack_foreach_lifo (@var{macro}, @var{action})
+For each of the @code{pushdef} definitions associated with @var{macro},
+invoke the macro @var{action} with a single argument of that definition.
+@code{stack_foreach} visits the oldest definition first, while
+@code{stack_foreach_lifo} visits the current definition first.
+@var{action} should not modify or dereference @var{macro}.  There are a
+few special macros, such as @code{defn}, which cannot be used as the
+@var{macro} parameter.
+@end deffn
+
+A sample implementation of these macros is distributed in the file
+@file{m4-@value{VERSION}/@/examples/@/stack.m4}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`stack.m4')
+@result{}
+pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
+@result{}
+define(`show', ``$1'
+')
+@result{}
+stack_foreach(`a', `show')dnl
+@result{}1
+@result{}2
+@result{}3
+stack_foreach_lifo(`a', `show')dnl
+@result{}3
+@result{}2
+@result{}1
+@end example
+
+Now for the implementation.  Note the definition of a helper macro,
+@code{_stack_reverse}, which destructively swaps the contents of one
+stack of definitions into the reverse order in the temporary macro
+@samp{tmp-$1}.  By calling the helper twice, the original order is
+restored back into the macro @samp{$1}; since the operation is
+destructive, this explains why @samp{$1} must not be modified or
+dereferenced during the traversal.  The caller can then inject
+additional code to pass the definition currently being visited to
+@samp{$2}.  The choice of helper names is intentional; since @samp{-} is
+not valid as part of a macro name, there is no risk of conflict with a
+valid macro name, and the code is guaranteed to use @code{defn} where
+necessary.  Finally, note that any macro used in the traversal of a
+@code{pushdef} stack, such as @code{pushdef} or @code{defn}, cannot be
+handled by @code{stack_foreach}, since the macro would temporarily be
+undefined during the algorithm.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`stack.m4')dnl
+@result{}divert(`-1')
+@result{}# stack_foreach(macro, action)
+@result{}# Invoke ACTION with a single argument of each definition
+@result{}# from the definition stack of MACRO, starting with the oldest.
+@result{}define(`stack_foreach',
+@result{}`_stack_reverse(`$1', `tmp-$1')'dnl
+@result{}`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')')
+@result{}# stack_foreach_lifo(macro, action)
+@result{}# Invoke ACTION with a single argument of each definition
+@result{}# from the definition stack of MACRO, starting with the newest.
+@result{}define(`stack_foreach_lifo',
+@result{}`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl
+@result{}`_stack_reverse(`tmp-$1', `$1')')
+@result{}define(`_stack_reverse',
+@result{}`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@@)')')
+@result{}divert`'dnl
+@end example
+
+@node Composition
+@section Building macros with macros
+
+@cindex macro composition
+@cindex composing macros
+Since m4 is a macro language, it is possible to write macros that
+can build other macros.  First on the list is a way to automate the
+creation of blind macros.
+
+@cindex macro, blind
+@cindex blind macro
+@deffn Composite define_blind (@var{name}, @ovar{value})
+Defines @var{name} as a blind macro, such that @var{name} will expand to
+@var{value} only when given explicit arguments.  @var{value} should not
+be the result of @code{defn} (@pxref{Defn}).  This macro is only
+recognized with parameters, and results in an empty string.
+@end deffn
+
+Defining a macro to define another macro can be a bit tricky.  We want
+to use a literal @samp{$#} in the argument to the nested @code{define}.
+However, if @samp{$} and @samp{#} are adjacent in the definition of
+@code{define_blind}, then it would be expanded as the number of
+arguments to @code{define_blind} rather than the intended number of
+arguments to @var{name}.  The solution is to pass the difficult
+characters through extra arguments to a helper macro
+@code{_define_blind}.  When composing macros, it is a common idiom to
+need a helper macro to concatenate text that forms parameters in the
+composed macro, rather than interpreting the text as a parameter of the
+composing macro.
+
+As for the limitation against using @code{defn}, there are two reasons.
+If a macro was previously defined with @code{define_blind}, then it can
+safely be renamed to a new blind macro using plain @code{define}; using
+@code{define_blind} to rename it just adds another layer of
+@code{ifelse}, occupying memory and slowing down execution.  And if a
+macro is a builtin, then it would result in an attempt to define a macro
+consisting of both text and a builtin token; this is not supported, and
+the builtin token is flattened to an empty string.
+
+With that explanation, here's the definition, and some sample usage.
+Notice that @code{define_blind} is itself a blind macro.
+
+@example
+$ @kbd{m4 -d}
+define(`define_blind', `ifelse(`$#', `0', ``$0'',
+`_$0(`$1', `$2', `$'`#', `$'`0')')')
+@result{}
+define(`_define_blind', `define(`$1',
+`ifelse(`$3', `0', ``$4'', `$2')')')
+@result{}
+define_blind
+@result{}define_blind
+define_blind(`foo', `arguments were $*')
+@result{}
+foo
+@result{}foo
+foo(`bar')
+@result{}arguments were bar
+define(`blah', defn(`foo'))
+@result{}
+blah
+@result{}blah
+blah(`a', `b')
+@result{}arguments were a,b
+defn(`blah')
+@result{}ifelse(`$#', `0', ``$0'', `arguments were $*')
+@end example
+
+@cindex currying arguments
+@cindex argument currying
+Another interesting composition tactic is argument @dfn{currying}, or
+factoring a macro that takes multiple arguments for use in a context
+that provides exactly one argument.
+
+@deffn Composite curry (@var{macro}, @dots{})
+Expand to a macro call that takes exactly one argument, then appends
+that argument to the original arguments and invokes @var{macro} with the
+resulting list of arguments.
+@end deffn
+
+A demonstration of currying makes the intent of this macro a little more
+obvious.  The macro @code{stack_foreach} mentioned earlier is an example
+of a context that provides exactly one argument to a macro name.  But
+coupled with currying, we can invoke @code{reverse} with two arguments
+for each definition of a macro stack.  This example uses the file
+@file{m4-@value{VERSION}/@/examples/@/curry.m4} included in the
+distribution.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`curry.m4')include(`stack.m4')
+@result{}
+define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
+                          `reverse(shift($@@)), `$1'')')
+@result{}
+pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
+@result{}
+stack_foreach(`a', `:curry(`reverse', `4')')
+@result{}:1, 4:2, 4:3, 4
+curry(`curry', `reverse', `1')(`2')(`3')
+@result{}3, 2, 1
+@end example
+
+Now for the implementation.  Notice how @code{curry} leaves off with a
+macro name but no open parenthesis, while still in the middle of
+collecting arguments for @samp{$1}.  The macro @code{_curry} is the
+helper macro that takes one argument, then adds it to the list and
+finally supplies the closing parenthesis.  The use of a comma inside the
+@code{shift} call allows currying to also work for a macro that takes
+one argument, although it often makes more sense to invoke that macro
+directly rather than going through @code{curry}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`curry.m4')dnl
+@result{}divert(`-1')
+@result{}# curry(macro, args)
+@result{}# Expand to a macro call that takes one argument, then invoke
+@result{}# macro(args, extra).
+@result{}define(`curry', `$1(shift($@@,)_$0')
+@result{}define(`_curry', ``$1')')
+@result{}divert`'dnl
+@end example
+
+Unfortunately, with M4 1.4.x, @code{curry} is unable to handle builtin
+tokens, which are silently flattened to the empty string when passed
+through another text macro.  This limitation will be lifted in a future
+release of M4.
+
+@cindex renaming macros
+@cindex copying macros
+@cindex macros, copying
+Putting the last few concepts together, it is possible to copy or rename
+an entire stack of macro definitions.
+
+@deffn Composite copy (@var{source}, @var{dest})
+@deffnx Composite rename (@var{source}, @var{dest})
+Ensure that @var{dest} is undefined, then define it to the same stack of
+definitions currently in @var{source}.  @code{copy} leaves @var{source}
+unchanged, while @code{rename} undefines @var{source}.  There are only a
+few macros, such as @code{copy} or @code{defn}, which cannot be copied
+via this macro.
+@end deffn
+
+The implementation is relatively straightforward (although since it uses
+@code{curry}, it is unable to copy builtin macros, such as the second
+definition of @code{a} as a synonym for @code{divnum}.  See if you can
+design a version that works around this limitation, or @pxref{Improved
+copy, , Answers}).
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`curry.m4')include(`stack.m4')
+@result{}
+define(`rename', `copy($@@)undefine(`$1')')dnl
+define(`copy', `ifdef(`$2', `errprint(`$2 already defined
+')m4exit(`1')',
+   `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl
+pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2')
+@result{}
+copy(`a', `b')
+@result{}
+rename(`b', `c')
+@result{}
+a b c
+@result{}2 b 2
+popdef(`a', `c')c a
+@result{} 0
+popdef(`a', `c')a c
+@result{}1 1
+@end example
+
+@node Debugging
+@chapter How to debug macros and input
+
+@cindex debugging macros
+@cindex macros, debugging
+When writing macros for @code{m4}, they often do not work as intended on
+the first try (as is the case with most programming languages).
+Fortunately, there is support for macro debugging in @code{m4}.
+
+@menu
+* Dumpdef::                     Displaying macro definitions
+* Trace::                       Tracing macro calls
+* Debug Levels::                Controlling debugging output
+* Debug Output::                Saving debugging output
+@end menu
+
+@node Dumpdef
+@section Displaying macro definitions
+
+@cindex displaying macro definitions
+@cindex macros, displaying definitions
+@cindex definitions, displaying macro
+@cindex standard error, output to
+If you want to see what a name expands into, you can use the builtin
+@code{dumpdef}:
+
+@deffn Builtin dumpdef (@ovar{names@dots{}})
+Accepts any number of arguments.  If called without any arguments,
+it displays the definitions of all known names, otherwise it displays
+the definitions of the @var{names} given.  The output is printed to the
+current debug file (usually standard error), and is sorted by name.  If
+an unknown name is encountered, a warning is printed.
+
+The expansion of @code{dumpdef} is void.
+@end deffn
+
+@example
+$ @kbd{m4 -d}
+define(`foo', `Hello world.')
+@result{}
+dumpdef(`foo')
+@error{}foo:@tabchar{}`Hello world.'
+@result{}
+dumpdef(`define')
+@error{}define:@tabchar{}<define>
+@result{}
+@end example
+
+The last example shows how builtin macros definitions are displayed.
+The definition that is dumped corresponds to what would occur if the
+macro were to be called at that point, even if other definitions are
+still live due to redefining a macro during argument collection.
+
+@example
+$ @kbd{m4 -d}
+pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
+@result{}
+f(popdef(`f')dumpdef(`f'))
+@error{}f:@tabchar{}``$0'1'
+@result{}f2
+f(popdef(`f')dumpdef(`f'))
+@error{}m4:stdin:3: undefined macro `f'
+@result{}f1
+@end example
+
+@xref{Debug Levels}, for information on controlling the details of the
+display.
+
+@node Trace
+@section Tracing macro calls
+
+@cindex tracing macro expansion
+@cindex macro expansion, tracing
+@cindex expansion, tracing macro
+@cindex standard error, output to
+It is possible to trace macro calls and expansions through the builtins
+@code{traceon} and @code{traceoff}:
+
+@deffn Builtin traceon (@ovar{names@dots{}})
+@deffnx Builtin traceoff (@ovar{names@dots{}})
+When called without any arguments, @code{traceon} and @code{traceoff}
+will turn tracing on and off, respectively, for all currently defined
+macros.
+
+When called with arguments, only the macros listed in @var{names} are
+affected, whether or not they are currently defined.
+
+The expansion of @code{traceon} and @code{traceoff} is void.
+@end deffn
+
+Whenever a traced macro is called and the arguments have been collected,
+the call is displayed.  If the expansion of the macro call is not void,
+the expansion can be displayed after the call.  The output is printed
+to the current debug file (defaulting to standard error, @pxref{Debug
+Output}).
+
+@example
+$ @kbd{m4 -d}
+define(`foo', `Hello World.')
+@result{}
+define(`echo', `$@@')
+@result{}
+traceon(`foo', `echo')
+@result{}
+foo
+@error{}m4trace: -1- foo -> `Hello World.'
+@result{}Hello World.
+echo(`gnus', `and gnats')
+@error{}m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
+@result{}gnus,and gnats
+@end example
+
+The number between dashes is the depth of the expansion.  It is one most
+of the time, signifying an expansion at the outermost level, but it
+increases when macro arguments contain unquoted macro calls.  The
+maximum number that will appear between dashes is controlled by the
+option @option{--nesting-limit} (or @option{-L}, @pxref{Limits control,
+, Invoking m4}).  Additionally, the option @option{--trace} (or
+@option{-t}) can be used to invoke @code{traceon(@var{name})} before
+parsing input.
+
+@comment The explicit -dp neutralizes the testsuite default of -d.
+@comment options: -dp -L3 -tifelse
+@comment status: 1
+@example
+$ @kbd{m4 -L 3 -t ifelse}
+ifelse(`one level')
+@error{}m4trace: -1- ifelse
+@result{}
+ifelse(ifelse(ifelse(`three levels')))
+@error{}m4trace: -3- ifelse
+@error{}m4trace: -2- ifelse
+@error{}m4trace: -1- ifelse
+@result{}
+ifelse(ifelse(ifelse(ifelse(`four levels'))))
+@error{}m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
+@end example
+
+Tracing by name is an attribute that is preserved whether the macro is
+defined or not.  This allows the selection of macros to trace before
+those macros are defined.
+
+@example
+$ @kbd{m4 -d}
+traceoff(`foo')
+@result{}
+traceon(`foo')
+@result{}
+foo
+@result{}foo
+defn(`foo')
+@result{}
+define(`foo', `bar')
+@result{}
+foo
+@error{}m4trace: -1- foo -> `bar'
+@result{}bar
+undefine(`foo')
+@result{}
+ifdef(`foo', `yes', `no')
+@result{}no
+indir(`foo')
+@error{}m4:stdin:9: undefined macro `foo'
+@result{}
+define(`foo', `blah')
+@result{}
+foo
+@error{}m4trace: -1- foo -> `blah'
+@result{}blah
+traceoff
+@result{}
+foo
+@result{}blah
+@end example
+
+Tracing even works on builtins.  However, @code{defn} (@pxref{Defn})
+does not transfer tracing status.
+
+@example
+$ @kbd{m4 -d}
+traceon(`traceon')
+@result{}
+traceon(`traceoff')
+@error{}m4trace: -1- traceon(`traceoff')
+@result{}
+traceoff(`traceoff')
+@error{}m4trace: -1- traceoff(`traceoff')
+@result{}
+traceoff(`traceon')
+@result{}
+traceon(`eval', `m4_divnum')
+@result{}
+define(`m4_eval', defn(`eval'))
+@result{}
+define(`m4_divnum', defn(`divnum'))
+@result{}
+eval(divnum)
+@error{}m4trace: -1- eval(`0') -> `0'
+@result{}0
+m4_eval(m4_divnum)
+@error{}m4trace: -2- m4_divnum -> `0'
+@result{}0
+@end example
+
+@xref{Debug Levels}, for information on controlling the details of the
+display.  The format of the trace output is not specified by
+POSIX, and varies between implementations of @code{m4}.
+
+@ignore
+@comment not worth including in the manual, but this tests a trace code
+@comment path that was temporarily broken
+@comment options: -de --trace ifelse
+@example
+$ @kbd{m4 -de --trace ifelse}
+define(`e', `ifelse(`$1', `$2', `ifelse(`$1', `$2', `e(shift($@@))')')')
+@result{}
+e(`1', `1')
+@error{}m4trace: -1- ifelse -> ifelse(`1', `1', `e(shift(`1',`1'))')
+@error{}m4trace: -1- ifelse -> e(shift(`1',`1'))
+@error{}m4trace: -1- ifelse
+@result{}
+@end example
+@end ignore
+
+@node Debug Levels
+@section Controlling debugging output
+
+@cindex controlling debugging output
+@cindex debugging output, controlling
+The @option{-d} option to @code{m4} (or @option{--debug},
+@pxref{Debugging options, , Invoking m4}) controls the amount of details
+presented in three
+categories of output.  Trace output is requested by @code{traceon}
+(@pxref{Trace}), and each line is prefixed by @samp{m4trace:} in
+relation to a macro invocation.  Debug output tracks useful events not
+associated with a macro invocation, and each line is prefixed by
+@samp{m4debug:}.  Finally, @code{dumpdef} (@pxref{Dumpdef}) output is
+affected, with no prefix added to the output lines.
+
+The @var{flags} following the option can be one or more of the
+following:
+
+@table @code
+@item a
+In trace output, show the actual arguments that were collected before
+invoking the macro.  This applies to all macro calls if the @samp{t}
+flag is used, otherwise only the macros covered by calls of
+@code{traceon}.  Arguments are subject to length truncation specified by
+the command line option @option{--arglength} (or @option{-l}).
+
+@item c
+In trace output, show several trace lines for each macro call.  A line
+is shown when the macro is seen, but before the arguments are collected;
+a second line when the arguments have been collected and a third line
+after the call has completed.
+
+@item e
+In trace output, show the expansion of each macro call, if it is not
+void.  This applies to all macro calls if the @samp{t} flag is used,
+otherwise only the macros covered by calls of @code{traceon}.  The
+expansion is subject to length truncation specified by the command line
+option @option{--arglength} (or @option{-l}).
+
+@item f
+In debug and trace output, include the name of the current input file in
+the output line.
+
+@item i
+In debug output, print a message each time the current input file is
+changed.
+
+@item l
+In debug and trace output, include the current input line number in the
+output line.
+
+@item p
+In debug output, print a message when a named file is found through the
+path search mechanism (@pxref{Search Path}), giving the actual file name
+used.
+
+@item q
+In trace and dumpdef output, quote actual arguments and macro expansions
+in the display with the current quotes.  This is useful in connection
+with the @samp{a} and @samp{e} flags above.
+
+@item t
+In trace output, trace all macro calls made in this invocation of
+@code{m4}, regardless of the settings of @code{traceon}.
+
+@item x
+In trace output, add a unique `macro call id' to each line of the trace
+output.  This is useful in connection with the @samp{c} flag above.
+
+@item V
+A shorthand for all of the above flags.
+@end table
+
+If no flags are specified with the @option{-d} option, the default is
+@samp{aeq}.  The examples throughout this manual assume the default
+flags.
+
+@cindex GNU extensions
+There is a builtin macro @code{debugmode}, which allows on-the-fly control of
+the debugging output format:
+
+@deffn Builtin debugmode (@ovar{flags})
+The argument @var{flags} should be a subset of the letters listed above.
+As special cases, if the argument starts with a @samp{+}, the flags are
+added to the current debug flags, and if it starts with a @samp{-}, they
+are removed.  If no argument is present, all debugging flags are cleared
+(as if no @option{-d} was given), and with an empty argument the flags
+are reset to the default of @samp{aeq}.
+
+The expansion of @code{debugmode} is void.
+@end deffn
+
+@comment The explicit -dp neutralizes the testsuite default of -d.
+@comment options: -dp
+@example
+$ @kbd{m4}
+define(`foo', `FOO')
+@result{}
+traceon(`foo')
+@result{}
+debugmode()
+@result{}
+foo
+@error{}m4trace: -1- foo -> `FOO'
+@result{}FOO
+debugmode
+@result{}
+foo
+@error{}m4trace: -1- foo
+@result{}FOO
+debugmode(`+l')
+@result{}
+foo
+@error{}m4trace:8: -1- foo
+@result{}FOO
+@end example
+
+The following example demonstrates the behavior of length truncation,
+when specified on the command line.  Note that each argument and the
+final result are individually truncated.  Also, the special tokens for
+builtin functions are not truncated.
+
+@comment options: -l6
+@example
+$ @kbd{m4 -d -l 6}
+define(`echo', `$@@')debugmode(`+t')
+@result{}
+echo(`1', `long string')
+@error{}m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
+@result{}1,long string
+indir(`echo', defn(`changequote'))
+@error{}m4trace: -2- defn(`change...')
+@error{}m4trace: -1- indir(`echo', <changequote>) -> ``''
+@result{}
+@end example
+
+This example shows the effects of the debug flags that are not related
+to macro tracing.
+
+@comment examples
+@comment options: -dip
+@example
+$ @kbd{m4 -dip -I examples}
+@error{}m4debug: input read from stdin
+include(`foo')dnl
+@error{}m4debug: path search for `foo' found `examples/foo'
+@error{}m4debug: input read from examples/foo
+@result{}bar
+@error{}m4debug: input reverted to stdin, line 1
+^D
+@error{}m4debug: input exhausted
+@end example
+
+@node Debug Output
+@section Saving debugging output
+
+@cindex saving debugging output
+@cindex debugging output, saving
+@cindex output, saving debugging
+@cindex GNU extensions
+Debug and tracing output can be redirected to files using either the
+@option{--debugfile} option to @code{m4} (@pxref{Debugging options, ,
+Invoking m4}), or with the builtin macro @code{debugfile}:
+
+@deffn Builtin debugfile (@ovar{file})
+Sends all further debug and trace output to @var{file}, opened in append
+mode.  If @var{file} is the empty string, debug and trace output are
+discarded.  If @code{debugfile} is called without any arguments, debug
+and trace output are sent to standard error.  This does not affect
+warnings, error messages, or @code{errprint} output, which are
+always sent to standard error.  If @var{file} cannot be opened, the
+current debug file is unchanged, and an error is issued.
+
+The expansion of @code{debugfile} is void.
+@end deffn
+
+@example
+$ @kbd{m4 -d}
+traceon(`divnum')
+@result{}
+divnum(`extra')
+@error{}m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
+@error{}m4trace: -1- divnum(`extra') -> `0'
+@result{}0
+debugfile()
+@result{}
+divnum(`extra')
+@error{}m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
+@result{}0
+debugfile
+@result{}
+divnum
+@error{}m4trace: -1- divnum -> `0'
+@result{}0
+@end example
+
+@node Input Control
+@chapter Input control
+
+This chapter describes various builtin macros for controlling the input
+to @code{m4}.
+
+@menu
+* Dnl::                         Deleting whitespace in input
+* Changequote::                 Changing the quote characters
+* Changecom::                   Changing the comment delimiters
+* Changeword::                  Changing the lexical structure of words
+* M4wrap::                      Saving text until end of input
+@end menu
+
+@node Dnl
+@section Deleting whitespace in input
+
+@cindex deleting whitespace in input
+@cindex discarding input
+@cindex input, discarding
+The builtin @code{dnl} stands for ``Discard to Next Line'':
+
+@deffn Builtin dnl
+All characters, up to and including the next newline, are discarded
+without performing any macro expansion.  A warning is issued if the end
+of the file is encountered without a newline.
+
+The expansion of @code{dnl} is void.
+@end deffn
+
+It is often used in connection with @code{define}, to remove the
+newline that follows the call to @code{define}.  Thus
+
+@example
+define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
+foo
+@result{}Macro foo.
+@end example
+
+The input up to and including the next newline is discarded, as opposed
+to the way comments are treated (@pxref{Comments}).
+
+Usually, @code{dnl} is immediately followed by an end of line or some
+other whitespace.  GNU @code{m4} will produce a warning diagnostic if
+@code{dnl} is followed by an open parenthesis.  In this case, @code{dnl}
+will collect and process all arguments, looking for a matching close
+parenthesis.  All predictable side effects resulting from this
+collection will take place.  @code{dnl} will return no output.  The
+input following the matching close parenthesis up to and including the
+next newline, on whatever line containing it, will still be discarded.
+
+@example
+dnl(`args are ignored, but side effects occur',
+define(`foo', `like this')) while this text is ignored: undefine(`foo')
+@error{}m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored
+See how `foo' was defined, foo?
+@result{}See how foo was defined, like this?
+@end example
+
+If the end of file is encountered without a newline character, a
+warning is issued and dnl stops consuming input.
+
+@example
+m4wrap(`m4wrap(`2 hi
+')0 hi dnl 1 hi')
+@result{}
+define(`hi', `HI')
+@result{}
+^D
+@error{}m4:stdin:1: Warning: end of file treated as newline
+@result{}0 HI 2 HI
+@end example
+
+@node Changequote
+@section Changing the quote characters
+
+@cindex changing quote delimiters
+@cindex quote delimiters, changing
+@cindex delimiters, changing
+The default quote delimiters can be changed with the builtin
+@code{changequote}:
+
+@deffn Builtin changequote (@dvar{start, `}, @dvar{end, '})
+This sets @var{start} as the new begin-quote delimiter and @var{end} as
+the new end-quote delimiter.  If both arguments are missing, the default
+quotes (@code{`} and @code{'}) are used.  If @var{start} is void, then
+quoting is disabled.  Otherwise, if @var{end} is missing or void, the
+default end-quote delimiter (@code{'}) is used.  The quote delimiters
+can be of any length.
+
+The expansion of @code{changequote} is void.
+@end deffn
+
+@example
+changequote(`[', `]')
+@result{}
+define([foo], [Macro [foo].])
+@result{}
+foo
+@result{}Macro foo.
+@end example
+
+The quotation strings can safely contain eight-bit characters.
+@ignore
+@comment Yuck.  I know of no clean way to render an 8-bit character in
+@comment both info and dvi.  This example uses the `open-guillemot' and
+@comment `close-guillemot' characters of the Latin-1 character set.
+
+@example
+define(`a', `b')
+@result{}
+«a»
+@result{}«b»
+changequote(`«', `»')
+@result{}
+«a»
+@result{}a
+@end example
+@end ignore
+If no single character is appropriate, @var{start} and @var{end} can be
+of any length.  Other implementations cap the delimiter length to five
+characters, but GNU has no inherent limit.
+
+@example
+changequote(`[[[', `]]]')
+@result{}
+define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
+@result{}
+foo
+@result{}Macro [[foo]].
+@end example
+
+Calling @code{changequote} with @var{start} as the empty string will
+effectively disable the quoting mechanism, leaving no way to quote text.
+However, using an empty string is not portable, as some other
+implementations of @code{m4} revert to the default quoting, while others
+preserve the prior non-empty delimiter.  If @var{start} is not empty,
+then an empty @var{end} will use the default end-quote delimiter of
+@samp{'}, as otherwise, it would be impossible to end a quoted string.
+Again, this is not portable, as some other @code{m4} implementations
+reuse @var{start} as the end-quote delimiter, while others preserve the
+previous non-empty value.  Omitting both arguments restores the default
+begin-quote and end-quote delimiters; fortunately this behavior is
+portable to all implementations of @code{m4}.
+
+@example
+define(`foo', `Macro `FOO'.')
+@result{}
+changequote(`', `')
+@result{}
+foo
+@result{}Macro `FOO'.
+`foo'
+@result{}`Macro `FOO'.'
+changequote(`,)
+@result{}
+foo
+@result{}Macro FOO.
+@end example
+
+There is no way in @code{m4} to quote a string containing an unmatched
+begin-quote, except using @code{changequote} to change the current
+quotes.
+
+If the quotes should be changed from, say, @samp{[} to @samp{[[},
+temporary quote characters have to be defined.  To achieve this, two
+calls of @code{changequote} must be made, one for the temporary quotes
+and one for the new quotes.
+
+Macros are recognized in preference to the begin-quote string, so if a
+prefix of @var{start} can be recognized as part of a potential macro
+name, the quoting mechanism is effectively disabled.  Unless you use
+@code{changeword} (@pxref{Changeword}), this means that @var{start}
+should not begin with a letter, digit, or @samp{_} (underscore).
+However, even though quoted strings are not recognized, the quote
+characters can still be discerned in macro expansion and in trace
+output.
+
+@example
+define(`echo', `$@@')
+@result{}
+define(`hi', `HI')
+@result{}
+changequote(`q', `Q')
+@result{}
+q hi Q hi
+@result{}q HI Q HI
+echo(hi)
+@result{}qHIQ
+changequote
+@result{}
+changequote(`-', `EOF')
+@result{}
+- hi EOF hi
+@result{} hi  HI
+changequote
+@result{}
+changequote(`1', `2')
+@result{}
+hi1hi2
+@result{}hi1hi2
+hi 1hi2
+@result{}HI hi
+@end example
+
+Quotes are recognized in preference to argument collection.  In
+particular, if @var{start} is a single @samp{(}, then argument
+collection is effectively disabled.  For portability with other
+implementations, it is a good idea to avoid @samp{(}, @samp{,}, and
+@samp{)} as the first character in @var{start}.
+
+@example
+define(`echo', `$#:$@@:')
+@result{}
+define(`hi', `HI')
+@result{}
+changequote(`(',`)')
+@result{}
+echo(hi)
+@result{}0::hi
+changequote
+@result{}
+changequote(`((', `))')
+@result{}
+echo(hi)
+@result{}1:HI:
+echo((hi))
+@result{}0::hi
+changequote
+@result{}
+changequote(`,', `)')
+@result{}
+echo(hi,hi)bye)
+@result{}1:HIhibye:
+@end example
+
+However, if you are not worried about portability, using @samp{(} and
+@samp{)} as quoting characters has an interesting property---you can use
+it to compute a quoted string containing the expansion of any quoted
+text, as long as the expansion results in both balanced quotes and
+balanced parentheses.  The trick is realizing @code{expand} uses
+@samp{$1} unquoted, to trigger its expansion using the normal quoting
+characters, but uses extra parentheses to group unquoted commas that
+occur in the expansion without consuming whitespace following those
+commas.  Then @code{_expand} uses @code{changequote} to convert the
+extra parentheses back into quoting characters.  Note that it takes two
+more @code{changequote} invocations to restore the original quotes.
+Contrast the behavior on whitespace when using @samp{$*}, via
+@code{quote}, to attempt the same task.
+
+@example
+changequote(`[', `]')dnl
+define([a], [1, (b)])dnl
+define([b], [2])dnl
+define([quote], [[$*]])dnl
+define([expand], [_$0(($1))])dnl
+define([_expand],
+  [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
+expand([a, a, [a, a], [[a, a]]])
+@result{}1, (2), 1, (2), a, a, [a, a]
+quote(a, a, [a, a], [[a, a]])
+@result{}1,(2),1,(2),a, a,[a, a]
+@end example
+
+If @var{end} is a prefix of @var{start}, the end-quote will be
+recognized in preference to a nested begin-quote.  In particular,
+changing the quotes to have the same string for @var{start} and
+@var{end} disables nesting of quotes.  When quote nesting is disabled,
+it is impossible to double-quote strings across macro expansions, so
+using the same string is not done very often.
+
+@example
+define(`hi', `HI')
+@result{}
+changequote(`""', `"')
+@result{}
+""hi"""hi"
+@result{}hihi
+""hi" ""hi"
+@result{}hi hi
+""hi"" "hi"
+@result{}hi" "HI"
+changequote
+@result{}
+`hi`hi'hi'
+@result{}hi`hi'hi
+changequote(`"', `"')
+@result{}
+"hi"hi"hi"
+@result{}hiHIhi
+@end example
+
+@ignore
+@comment And another stress test, not worth documenting in the manual.
+@example
+define(`aaaaaaaaaaaaaaaaaaaa', `A')define(`q', `"$@@"')
+@result{}
+changequote(`"', `"')
+@result{}
+q(q("aaaaaaaaaaaaaaaaaaaa", "a"))
+@result{}A,a
+@end example
+@end ignore
+
+It is an error if the end of file occurs within a quoted string.
+
+@comment status: 1
+@example
+`hello world'
+@result{}hello world
+`dangling quote
+^D
+@error{}m4:stdin:2: ERROR: end of file in string
+@end example
+
+@comment status: 1
+@example
+ifelse(`dangling quote
+^D
+@error{}m4:stdin:1: ERROR: end of file in string
+@end example
+
+@node Changecom
+@section Changing the comment delimiters
+
+@cindex changing comment delimiters
+@cindex comment delimiters, changing
+@cindex delimiters, changing
+The default comment delimiters can be changed with the builtin
+macro @code{changecom}:
+
+@deffn Builtin changecom (@ovar{start}, @dvar{end, @key{NL}})
+This sets @var{start} as the new begin-comment delimiter and @var{end}
+as the new end-comment delimiter.  If both arguments are missing, or
+@var{start} is void, then comments are disabled.  Otherwise, if
+@var{end} is missing or void, the default end-comment delimiter of
+newline is used.  The comment delimiters can be of any length.
+
+The expansion of @code{changecom} is void.
+@end deffn
+
+@example
+define(`comment', `COMMENT')
+@result{}
+# A normal comment
+@result{}# A normal comment
+changecom(`/*', `*/')
+@result{}
+# Not a comment anymore
+@result{}# Not a COMMENT anymore
+But: /* this is a comment now */ while this is not a comment
+@result{}But: /* this is a comment now */ while this is not a COMMENT
+@end example
+
+@cindex comments, copied to output
+Note how comments are copied to the output, much as if they were quoted
+strings.  If you want the text inside a comment expanded, quote the
+begin-comment delimiter.
+
+Calling @code{changecom} without any arguments, or with @var{start} as
+the empty string, will effectively disable the commenting mechanism.  To
+restore the original comment start of @samp{#}, you must explicitly ask
+for it.  If @var{start} is not empty, then an empty @var{end} will use
+the default end-comment delimiter of newline, as otherwise, it would be
+impossible to end a comment.  However, this is not portable, as some
+other @code{m4} implementations preserve the previous non-empty
+delimiters instead.
+
+@example
+define(`comment', `COMMENT')
+@result{}
+changecom
+@result{}
+# Not a comment anymore
+@result{}# Not a COMMENT anymore
+changecom(`#', `')
+@result{}
+# comment again
+@result{}# comment again
+@end example
+
+The comment strings can safely contain eight-bit characters.
+@ignore
+@comment Yuck.  I know of no clean way to render an 8-bit character in
+@comment both info and dvi.  This example uses the `open-guillemot' and
+@comment `close-guillemot' characters of the Latin-1 character set.
+
+@example
+define(`a', `b')
+@result{}
+«a»
+@result{}«b»
+changecom(`«', `»')
+@result{}
+«a»
+@result{}«a»
+@end example
+@end ignore
+If no single character is appropriate, @var{start} and @var{end} can be
+of any length.  Other implementations cap the delimiter length to five
+characters, but GNU has no inherent limit.
+
+Comments are recognized in preference to macros.  However, this is not
+compatible with other implementations, where macros and even quoting
+takes precedence over comments, so it may change in a future release.
+For portability, this means that @var{start} should not begin with a
+letter, digit, or @samp{_} (underscore), and that neither the
+start-quote nor the start-comment string should be a prefix of the
+other.
+
+@example
+define(`hi', `HI')
+@result{}
+define(`hi1hi2', `hello')
+@result{}
+changecom(`q', `Q')
+@result{}
+q hi Q hi
+@result{}q hi Q HI
+changecom(`1', `2')
+@result{}
+hi1hi2
+@result{}hello
+hi 1hi2
+@result{}HI 1hi2
+@end example
+
+Comments are recognized in preference to argument collection.  In
+particular, if @var{start} is a single @samp{(}, then argument
+collection is effectively disabled.  For portability with other
+implementations, it is a good idea to avoid @samp{(}, @samp{,}, and
+@samp{)} as the first character in @var{start}.
+
+@example
+define(`echo', `$#:$*:$@@:')
+@result{}
+define(`hi', `HI')
+@result{}
+changecom(`(',`)')
+@result{}
+echo(hi)
+@result{}0:::(hi)
+changecom
+@result{}
+changecom(`((', `))')
+@result{}
+echo(hi)
+@result{}1:HI:HI:
+echo((hi))
+@result{}0:::((hi))
+changecom(`,', `)')
+@result{}
+echo(hi,hi)bye)
+@result{}1:HI,hi)bye:HI,hi)bye:
+changecom
+@result{}
+echo(hi,`,`'hi',hi)
+@result{}3:HI,,HI,HI:HI,,`'hi,HI:
+echo(hi,`,`'hi',hi`'changecom(`,,', `hi'))
+@result{}3:HI,,`'hi,HI:HI,,`'hi,HI:
+@end example
+
+It is an error if the end of file occurs within a comment.
+
+@comment status: 1
+@example
+changecom(`/*', `*/')
+@result{}
+/*dangling comment
+^D
+@error{}m4:stdin:2: ERROR: end of file in comment
+@end example
+
+@node Changeword
+@section Changing the lexical structure of words
+
+@cindex lexical structure of words
+@cindex words, lexical structure of
+@cindex syntax, changing
+@cindex changing syntax
+@cindex regular expressions
+@quotation
+The macro @code{changeword} and all associated functionality is
+experimental.  It is only available if the @option{--enable-changeword}
+option was given to @command{configure}, at GNU @code{m4}
+installation
+time.  The functionality will go away in the future, to be replaced by
+other new features that are more efficient at providing the same
+capabilities.  @emph{Do not rely on it}.  Please direct your comments
+about it the same way you would do for bugs.
+@end quotation
+
+A file being processed by @code{m4} is split into quoted strings, words
+(potential macro names) and simple tokens (any other single character).
+Initially a word is defined by the following regular expression:
+
+@comment ignore
+@example
+[_a-zA-Z][_a-zA-Z0-9]*
+@end example
+
+Using @code{changeword}, you can change this regular expression:
+
+@deffn {Optional builtin} changeword (@var{regex})
+Changes the regular expression for recognizing macro names to be
+@var{regex}.  If @var{regex} is empty, use
+@samp{[_a-zA-Z][_a-zA-Z0-9]*}.  @var{regex} must obey the constraint
+that every prefix of the desired final pattern is also accepted by the
+regular expression.  If @var{regex} contains grouping parentheses, the
+macro invoked is the portion that matched the first group, rather than
+the entire matching string.
+
+The expansion of @code{changeword} is void.
+The macro @code{changeword} is recognized only with parameters.
+@end deffn
+
+Relaxing the lexical rules of @code{m4} might be useful (for example) if
+you wanted to apply translations to a file of numbers:
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+changeword(`[_a-zA-Z0-9]+')
+@result{}
+define(`1', `0')1
+@result{}0
+@end example
+
+Tightening the lexical rules is less useful, because it will generally
+make some of the builtins unavailable.  You could use it to prevent
+accidental call of builtins, for example:
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+define(`_indir', defn(`indir'))
+@result{}
+changeword(`_[_a-zA-Z0-9]*')
+@result{}
+esyscmd(`foo')
+@result{}esyscmd(foo)
+_indir(`esyscmd', `echo hi')
+@result{}hi
+@result{}
+@end example
+
+Because @code{m4} constructs its words a character at a time, there
+is a restriction on the regular expressions that may be passed to
+@code{changeword}.  This is that if your regular expression accepts
+@samp{foo}, it must also accept @samp{f} and @samp{fo}.
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+define(`foo
+', `bar
+')
+@result{}
+dnl This example wants to recognize changeword, dnl, and `foo\n'.
+dnl First, we check that our regexp will match.
+regexp(`changeword', `[cd][a-z]*\|foo[
+]')
+@result{}0
+regexp(`foo
+', `[cd][a-z]*\|foo[
+]')
+@result{}0
+regexp(`f', `[cd][a-z]*\|foo[
+]')
+@result{}-1
+foo
+@result{}foo
+changeword(`[cd][a-z]*\|foo[
+]')
+@result{}
+dnl Even though `foo\n' matches, we forgot to allow `f'.
+foo
+@result{}foo
+changeword(`[cd][a-z]*\|fo*[
+]?')
+@result{}
+dnl Now we can call `foo\n'.
+foo
+@result{}bar
+@end example
+
+@ignore
+@comment One more test of including newline in a macro name; but this
+@comment does not need to be displayed in the manual.  This ensures
+@comment that line numbering is correct when dnl cuts across include
+@comment file boundaries, and when __file__ or __line__ is the last
+@comment token in an include file.
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+define(`bar
+', defn(`dnl'))dnl
+define(`baz', `dnl
+include(`foo') ignored
+dnl')dnl
+changeword(`\([_a-zA-Z][_a-zA-Z0-9]*\|bar
+\)')
+@result{}
+__file__:__line__
+@result{}stdin:10
+include(`foo') ignored
+__file__:__line__
+@result{}stdin:12
+baz ignored
+__file__:__line__
+@result{}stdin:14
+define(`bar
+', defn(`__file__'))
+@result{}
+include(`foo')
+@result{}examples/foo
+define(`bar
+', defn(`__line__'))
+@result{}
+include(`foo')
+@result{}1
+__file__:__line__
+@result{}stdin:21
+@end example
+@end ignore
+
+@code{changeword} has another function.  If the regular expression
+supplied contains any grouped subexpressions, then text outside
+the first of these is discarded before symbol lookup.  So:
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+changecom(`/*', `*/')dnl
+define(`foo', `bar')dnl
+changeword(`#\([_a-zA-Z0-9]*\)')
+@result{}
+#esyscmd(`echo foo \#foo')
+@result{}foo bar
+@result{}
+@end example
+
+@code{m4} now requires a @samp{#} mark at the beginning of every
+macro invocation, so one can use @code{m4} to preprocess plain
+text without losing various words like @samp{divert}.
+
+In @code{m4}, macro substitution is based on text, while in @TeX{}, it
+is based on tokens.  @code{changeword} can throw this difference into
+relief.  For example, here is the same idea represented in @TeX{} and
+@code{m4}.  First, the @TeX{} version:
+
+@comment ignore
+@example
+\def\a@{\message@{Hello@}@}
+\catcode`\@@=0
+\catcode`\\=12
+@@a
+@@bye
+@result{}Hello
+@end example
+
+@noindent
+Then, the @code{m4} version:
+
+@example
+ifdef(`changeword', `', `errprint(` skipping: no changeword support
+')m4exit(`77')')dnl
+define(`a', `errprint(`Hello')')dnl
+changeword(`@@\([_a-zA-Z0-9]*\)')
+@result{}
+@@a
+@result{}errprint(Hello)
+@end example
+
+In the @TeX{} example, the first line defines a macro @code{a} to
+print the message @samp{Hello}.  The second line defines @key{@@} to
+be usable instead of @key{\} as an escape character.  The third line
+defines @key{\} to be a normal printing character, not an escape.
+The fourth line invokes the macro @code{a}.  So, when @TeX{} is run
+on this file, it displays the message @samp{Hello}.
+
+When the @code{m4} example is passed through @code{m4}, it outputs
+@samp{errprint(Hello)}.  The reason for this is that @TeX{} does
+lexical analysis of macro definition when the macro is @emph{defined}.
+@code{m4} just stores the text, postponing the lexical analysis until
+the macro is @emph{used}.
+
+You should note that using @code{changeword} will slow @code{m4} down
+by a factor of about seven, once it is changed to something other
+than the default regular expression.  You can invoke @code{changeword}
+with the empty string to restore the default word definition, and regain
+the parsing speed.
+
+@node M4wrap
+@section Saving text until end of input
+
+@cindex saving input
+@cindex input, saving
+@cindex deferring expansion
+@cindex expansion, deferring
+It is possible to `save' some text until the end of the normal input has
+been seen.  Text can be saved, to be read again by @code{m4} when the
+normal input has been exhausted.  This feature is normally used to
+initiate cleanup actions before normal exit, e.g., deleting temporary
+files.
+
+To save input text, use the builtin @code{m4wrap}:
+
+@deffn Builtin m4wrap (@var{string}, @dots{})
+Stores @var{string} in a safe place, to be reread when end of input is
+reached.  As a GNU extension, additional arguments are
+concatenated with a space to the @var{string}.
+
+The expansion of @code{m4wrap} is void.
+The macro @code{m4wrap} is recognized only with parameters.
+@end deffn
+
+@example
+define(`cleanup', `This is the `cleanup' action.
+')
+@result{}
+m4wrap(`cleanup')
+@result{}
+This is the first and last normal input line.
+@result{}This is the first and last normal input line.
+^D
+@result{}This is the cleanup action.
+@end example
+
+The saved input is only reread when the end of normal input is seen, and
+not if @code{m4exit} is used to exit @code{m4}.
+
+@comment FIXME: this contradicts POSIX, which requires that "If the
+@comment m4wrap macro is used multiple times, the arguments specified
+@comment shall be processed in the order in which the m4wrap macros were
+@comment processed."
+It is safe to call @code{m4wrap} from saved text, but then the order in
+which the saved text is reread is undefined.  If @code{m4wrap} is not used
+recursively, the saved pieces of text are reread in the opposite order
+in which they were saved (LIFO---last in, first out).  However, this
+behavior is likely to change in a future release, to match
+POSIX, so you should not depend on this order.
+
+It is possible to emulate POSIX behavior even
+with older versions of GNU M4 by including the file
+@file{m4-@value{VERSION}/@/examples/@/wrapfifo.m4} from the
+distribution:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`wrapfifo.m4')dnl
+@result{}dnl Redefine m4wrap to have FIFO semantics.
+@result{}define(`_m4wrap_level', `0')dnl
+@result{}define(`m4wrap',
+@result{}`ifdef(`m4wrap'_m4wrap_level,
+@result{}       `define(`m4wrap'_m4wrap_level,
+@result{}               defn(`m4wrap'_m4wrap_level)`$1')',
+@result{}       `builtin(`m4wrap', `define(`_m4wrap_level',
+@result{}                                  incr(_m4wrap_level))dnl
+@result{}m4wrap'_m4wrap_level)dnl
+@result{}define(`m4wrap'_m4wrap_level, `$1')')')dnl
+include(`wrapfifo.m4')
+@result{}
+m4wrap(`a`'m4wrap(`c
+', `d')')m4wrap(`b')
+@result{}
+^D
+@result{}abc
+@end example
+
+It is likewise possible to emulate LIFO behavior without resorting to
+the GNU M4 extension of @code{builtin}, by including the file
+@file{m4-@value{VERSION}/@/examples/@/wraplifo.m4} from the
+distribution.  (Unfortunately, both examples shown here share some
+subtle bugs.  See if you can find and correct them; or @pxref{Improved
+m4wrap, , Answers}).
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`wraplifo.m4')dnl
+@result{}dnl Redefine m4wrap to have LIFO semantics.
+@result{}define(`_m4wrap_level', `0')dnl
+@result{}define(`_m4wrap', defn(`m4wrap'))dnl
+@result{}define(`m4wrap',
+@result{}`ifdef(`m4wrap'_m4wrap_level,
+@result{}       `define(`m4wrap'_m4wrap_level,
+@result{}               `$1'defn(`m4wrap'_m4wrap_level))',
+@result{}       `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl
+@result{}m4wrap'_m4wrap_level)dnl
+@result{}define(`m4wrap'_m4wrap_level, `$1')')')dnl
+include(`wraplifo.m4')
+@result{}
+m4wrap(`a`'m4wrap(`c
+', `d')')m4wrap(`b')
+@result{}
+^D
+@result{}bac
+@end example
+
+Here is an example of implementing a factorial function using
+@code{m4wrap}:
+
+@example
+define(`f', `ifelse(`$1', `0', `Answer: 0!=1
+', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
+', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
+@result{}
+f(`10')
+@result{}
+^D
+@result{}Answer: 10*9*8*7*6*5*4*3*2*1=3628800
+@end example
+
+Invocations of @code{m4wrap} at the same recursion level are
+concatenated and rescanned as usual:
+
+@example
+define(`aa', `AA
+')
+@result{}
+m4wrap(`a')m4wrap(`a')
+@result{}
+^D
+@result{}AA
+@end example
+
+@noindent
+however, the transition between recursion levels behaves like an end of
+file condition between two input files.
+
+@comment status: 1
+@example
+m4wrap(`m4wrap(`)')len(abc')
+@result{}
+^D
+@error{}m4:stdin:1: ERROR: end of file in argument list
+@end example
+
+@node File Inclusion
+@chapter File inclusion
+
+@cindex file inclusion
+@cindex inclusion, of files
+@code{m4} allows you to include named files at any point in the input.
+
+@menu
+* Include::                     Including named files
+* Search Path::                 Searching for include files
+@end menu
+
+@node Include
+@section Including named files
+
+There are two builtin macros in @code{m4} for including files:
+
+@deffn Builtin include (@var{file})
+@deffnx Builtin sinclude (@var{file})
+Both macros cause the file named @var{file} to be read by
+@code{m4}.  When the end of the file is reached, input is resumed from
+the previous input file.
+
+The expansion of @code{include} and @code{sinclude} is therefore the
+contents of @var{file}.
+
+If @var{file} does not exist, is a directory, or cannot otherwise be
+read, the expansion is void,
+and @code{include} will fail with an error while @code{sinclude} is
+silent.  The empty string counts as a file that does not exist.
+
+The macros @code{include} and @code{sinclude} are recognized only with
+parameters.
+@end deffn
+
+@comment status: 1
+@example
+include(`none')
+@error{}m4:stdin:1: cannot open `none': No such file or directory
+@result{}
+include()
+@error{}m4:stdin:2: cannot open `': No such file or directory
+@result{}
+sinclude(`none')
+@result{}
+sinclude()
+@result{}
+@end example
+
+The rest of this section assumes that @code{m4} is invoked with the
+@option{-I} option (@pxref{Preprocessor features, , Invoking m4})
+pointing to the @file{m4-@value{VERSION}/@/examples}
+directory shipped as part of the GNU @code{m4} package.  The
+file @file{m4-@value{VERSION}/@/examples/@/incl.m4} in the distribution
+contains the lines:
+
+@comment ignore
+@example
+$ @kbd{cat examples/incl.m4}
+@result{}Include file start
+@result{}foo
+@result{}Include file end
+@end example
+
+Normally file inclusion is used to insert the contents of a file
+into the input stream.  The contents of the file will be read by
+@code{m4} and macro calls in the file will be expanded:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+define(`foo', `FOO')
+@result{}
+include(`incl.m4')
+@result{}Include file start
+@result{}FOO
+@result{}Include file end
+@result{}
+@end example
+
+The fact that @code{include} and @code{sinclude} expand to the contents
+of the file can be used to define macros that operate on entire files.
+Here is an example, which defines @samp{bar} to expand to the contents
+of @file{incl.m4}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+define(`bar', include(`incl.m4'))
+@result{}
+This is `bar':  >>bar<<
+@result{}This is bar:  >>Include file start
+@result{}foo
+@result{}Include file end
+@result{}<<
+@end example
+
+This use of @code{include} is not trivial, though, as files can contain
+quotes, commas, and parentheses, which can interfere with the way the
+@code{m4} parser works.  GNU @code{m4} seamlessly concatenates
+the file contents with the next character, even if the included file
+ended in the middle of a comment, string, or macro call.  These
+conditions are only treated as end of file errors if specified as input
+files on the command line.
+
+In GNU @code{m4}, an alternative method of reading files is
+using @code{undivert} (@pxref{Undivert}) on a named file.
+
+@ignore
+@comment Test that include(`file/') detects that file is not a
+@comment directory; we can assume that the current directory contains a
+@comment Makefile.  mingw fails with EINVAL rather than ENOTDIR.
+
+@comment status: 1
+@comment xerr: ignore
+@example
+include(`Makefile/')
+@error{}m4:stdin:1: cannot open `Makefile/': Not a directory
+@result{}
+@end example
+
+@comment POSIX allows, but doesn't require, failure on reading
+@comment directories.  But since they aren't text files, it never makes
+@comment sense, so we globally forbid it even if fopen doesn't.  mingw
+@comment fails with EACCES rather than EISDIR.
+
+@comment status: 1
+@comment xerr: ignore
+@example
+include(`.')
+@error{}m4:stdin:1: cannot open `.': Is a directory
+@result{}
+@end example
+
+@comment Meanwhile, ignore errors with sinclude.
+
+@example
+sinclude(`Makefile/')
+@result{}
+sinclude(`.')
+@result{}
+@end example
+@end ignore
+
+@node Search Path
+@section Searching for include files
+
+@cindex search path for included files
+@cindex included files, search path for
+@cindex GNU extensions
+GNU @code{m4} allows included files to be found in other directories
+than the current working directory.
+
+@cindex @env{M4PATH}
+If the @option{--prepend-include} or @option{-B} command-line option was
+provided (@pxref{Preprocessor features, , Invoking m4}), those
+directories are searched first, in reverse order that those options were
+listed on the command line.  Then @code{m4} looks in the current working
+directory.  Next comes the directories specified with the
+@option{--include} or @option{-I} option, in the order found on the
+command line.  Finally, if the @env{M4PATH} environment variable is set,
+it is expected to contain a colon-separated list of directories, which
+will be searched in order.
+
+If the automatic search for include-files causes trouble, the @samp{p}
+debug flag (@pxref{Debug Levels}) can help isolate the problem.
+
+@node Diversions
+@chapter Diverting and undiverting output
+
+@cindex deferring output
+Diversions are a way of temporarily saving output.  The output of
+@code{m4} can at any time be diverted to a temporary file, and be
+reinserted into the output stream, @dfn{undiverted}, again at a later
+time.
+
+@cindex @env{TMPDIR}
+Numbered diversions are counted from 0 upwards, diversion number 0
+being the normal output stream.  GNU
+@code{m4} tries to keep diversions in memory.  However, there is a
+limit to the overall memory usable by all diversions taken together
+(512K, currently).  When this maximum is about to be exceeded,
+a temporary file is opened to receive the contents of the biggest
+diversion still in memory, freeing this memory for other diversions.
+When creating the temporary file, @code{m4} honors the value of the
+environment variable @env{TMPDIR}, and falls back to @file{/tmp}.
+Thus, the amount of available disk space provides the only real limit on
+the number and aggregate size of diversions.
+
+@ignore
+@comment We need to test spilled diversions, but don't need to expose
+@comment this highly repetitive test in the manual.
+
+@example
+divert(`-1')define(`f', `.')
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+divert`'dnl
+len(f)
+@result{}1048576
+divert(`1')
+f
+divert(`2')
+f
+divert(`-1')undivert
+divert(`1')bye
+^D
+@result{}bye
+@end example
+
+@comment Another test of spilled diversions.
+
+@example
+divert(`-1')define(`f', `.')
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+define(`f', defn(`f')defn(`f'))
+divert`'dnl
+len(f)
+@result{}1048576
+divert(`1')
+f
+m4exit
+@end example
+
+@comment Catch regression in 1.4.10 with spilled diversions.
+
+@example
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+changequote(`[', `]')dnl
+syscmd([echo 'divert(1)hi
+format(%1000000d, 1)' | ']__program__[' | sed -n 1p])dnl
+@result{}hi
+sysval
+@result{}0
+@end example
+
+@comment Avoid quadratic copying time when transferring diversions;
+@comment test both in-memory and spilled to file.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`forloop2.m4')dnl
+divert(`1')format(`%10000s', `')dnl
+forloop(`i', `1', `10000',
+  `divert(incr(i))undivert(i)')dnl
+divert(`9001')format(`%1000000s', `')dnl
+forloop(`i', `9001', `10000',
+  `divert(incr(i))undivert(i)')dnl
+divert(`-1')undivert
+@end example
+@end ignore
+
+Diversions make it possible to generate output in a different order than
+the input was read.  It is possible to implement topological sorting
+dependencies.  For example, GNU Autoconf makes use of
+diversions under the hood to ensure that the expansion of a prerequisite
+macro appears in the output prior to the expansion of a dependent macro,
+regardless of which order the two macros were invoked in the user's
+input file.
+
+@menu
+* Divert::                      Diverting output
+* Undivert::                    Undiverting output
+* Divnum::                      Diversion numbers
+* Cleardivert::                 Discarding diverted text
+@end menu
+
+@node Divert
+@section Diverting output
+
+@cindex diverting output to files
+@cindex output, diverting to files
+@cindex files, diverting output to
+Output is diverted using @code{divert}:
+
+@deffn Builtin divert (@dvar{number, 0})
+The current diversion is changed to @var{number}.  If @var{number} is left
+out or empty, it is assumed to be zero.  If @var{number} cannot be
+parsed, the diversion is unchanged.
+
+The expansion of @code{divert} is void.
+@end deffn
+
+When all the @code{m4} input will have been processed, all existing
+diversions are automatically undiverted, in numerical order.
+
+@example
+divert(`1')
+This text is diverted.
+divert
+@result{}
+This text is not diverted.
+@result{}This text is not diverted.
+^D
+@result{}
+@result{}This text is diverted.
+@end example
+
+Several calls of @code{divert} with the same argument do not overwrite
+the previous diverted text, but append to it.  Diversions are printed
+after any wrapped text is expanded.
+
+@example
+define(`text', `TEXT')
+@result{}
+divert(`1')`diverted text.'
+divert
+@result{}
+m4wrap(`Wrapped text precedes ')
+@result{}
+^D
+@result{}Wrapped TEXT precedes diverted text.
+@end example
+
+@cindex discarding input
+@cindex input, discarding
+If output is diverted to a negative diversion, it is simply discarded.
+This can be used to suppress unwanted output.  A common example of
+unwanted output is the trailing newlines after macro definitions.  Here
+is a common programming idiom in @code{m4} for avoiding them.
+
+@example
+divert(`-1')
+define(`foo', `Macro `foo'.')
+define(`bar', `Macro `bar'.')
+divert
+@result{}
+@end example
+
+@cindex GNU extensions
+Traditional implementations only supported ten diversions.  But as a
+GNU extension, diversion numbers can be as large as positive
+integers will allow, rather than treating a multi-digit diversion number
+as a request to discard text.
+
+@example
+divert(eval(`1<<28'))world
+divert(`2')hello
+^D
+@result{}hello
+@result{}world
+@end example
+
+Note that @code{divert} is an English word, but also an active macro
+without arguments.  When processing plain text, the word might appear in
+normal text and be unintentionally swallowed as a macro invocation.  One
+way to avoid this is to use the @option{-P} option to rename all
+builtins (@pxref{Operation modes, , Invoking m4}).  Another is to write
+a wrapper that requires a parameter to be recognized.
+
+@example
+We decided to divert the stream for irrigation.
+@result{}We decided to  the stream for irrigation.
+define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@@)')')
+@result{}
+divert(`-1')
+Ignored text.
+divert(`0')
+@result{}
+We decided to divert the stream for irrigation.
+@result{}We decided to divert the stream for irrigation.
+@end example
+
+@node Undivert
+@section Undiverting output
+
+Diverted text can be undiverted explicitly using the builtin
+@code{undivert}:
+
+@deffn Builtin undivert (@ovar{diversions@dots{}})
+Undiverts the numeric @var{diversions} given by the arguments, in the
+order given.  If no arguments are supplied, all diversions are
+undiverted, in numerical order.
+
+@cindex file inclusion
+@cindex inclusion, of files
+@cindex GNU extensions
+As a GNU extension, @var{diversions} may contain non-numeric
+strings, which are treated as the names of files to copy into the output
+without expansion.  A warning is issued if a file could not be opened.
+
+The expansion of @code{undivert} is void.
+@end deffn
+
+@example
+divert(`1')
+This text is diverted.
+divert
+@result{}
+This text is not diverted.
+@result{}This text is not diverted.
+undivert(`1')
+@result{}
+@result{}This text is diverted.
+@result{}
+@end example
+
+Notice the last two blank lines.  One of them comes from the newline
+following @code{undivert}, the other from the newline that followed the
+@code{divert}!  A diversion often starts with a blank line like this.
+
+When diverted text is undiverted, it is @emph{not} reread by @code{m4},
+but rather copied directly to the current output, and it is therefore
+not an error to undivert into a diversion.  Undiverting the empty string
+is the same as specifying diversion 0; in either case nothing happens
+since the output has already been flushed.
+
+@example
+divert(`1')diverted text
+divert
+@result{}
+undivert()
+@result{}
+undivert(`0')
+@result{}
+undivert
+@result{}diverted text
+@result{}
+divert(`1')more
+divert(`2')undivert(`1')diverted text`'divert
+@result{}
+undivert(`1')
+@result{}
+undivert(`2')
+@result{}more
+@result{}diverted text
+@end example
+
+When a diversion has been undiverted, the diverted text is discarded,
+and it is not possible to bring back diverted text more than once.
+
+@example
+divert(`1')
+This text is diverted first.
+divert(`0')undivert(`1')dnl
+@result{}
+@result{}This text is diverted first.
+undivert(`1')
+@result{}
+divert(`1')
+This text is also diverted but not appended.
+divert(`0')undivert(`1')dnl
+@result{}
+@result{}This text is also diverted but not appended.
+@end example
+
+Attempts to undivert the current diversion are silently ignored.  Thus,
+when the current diversion is not 0, the current diversion does not get
+rearranged among the other diversions.
+
+@example
+divert(`1')one
+divert(`2')two
+divert(`3')three
+divert(`2')undivert`'dnl
+divert`'undivert`'dnl
+@result{}two
+@result{}one
+@result{}three
+@end example
+
+@cindex GNU extensions
+@cindex file inclusion
+@cindex inclusion, of files
+GNU @code{m4} allows named files to be undiverted.  Given a
+non-numeric argument, the contents of the file named will be copied,
+uninterpreted, to the current output.  This complements the builtin
+@code{include} (@pxref{Include}).  To illustrate the difference, assume
+the file @file{foo} contains:
+
+@comment ignore
+@example
+$ @kbd{cat foo}
+bar
+@end example
+
+@noindent
+then
+
+@example
+define(`bar', `BAR')
+@result{}
+undivert(`foo')
+@result{}bar
+@result{}
+include(`foo')
+@result{}BAR
+@result{}
+@end example
+
+If the file is not found (or cannot be read), an error message is
+issued, and the expansion is void.  It is possible to intermix files
+and diversion numbers.
+
+@example
+divert(`1')diversion one
+divert(`2')undivert(`foo')dnl
+divert(`3')diversion three
+divert`'dnl
+undivert(`1', `2', `foo', `3')dnl
+@result{}diversion one
+@result{}bar
+@result{}bar
+@result{}diversion three
+@end example
+
+@node Divnum
+@section Diversion numbers
+
+@cindex diversion numbers
+The current diversion is tracked by the builtin @code{divnum}:
+
+@deffn Builtin divnum
+Expands to the number of the current diversion.
+@end deffn
+
+@example
+Initial divnum
+@result{}Initial 0
+divert(`1')
+Diversion one: divnum
+divert(`2')
+Diversion two: divnum
+^D
+@result{}
+@result{}Diversion one: 1
+@result{}
+@result{}Diversion two: 2
+@end example
+
+@node Cleardivert
+@section Discarding diverted text
+
+@cindex discarding diverted text
+@cindex diverted text, discarding
+Often it is not known, when output is diverted, whether the diverted
+text is actually needed.  Since all non-empty diversion are brought back
+on the main output stream when the end of input is seen, a method of
+discarding a diversion is needed.  If all diversions should be
+discarded, the easiest is to end the input to @code{m4} with
+@samp{divert(`-1')} followed by an explicit @samp{undivert}:
+
+@example
+divert(`1')
+Diversion one: divnum
+divert(`2')
+Diversion two: divnum
+divert(`-1')
+undivert
+^D
+@end example
+
+@noindent
+No output is produced at all.
+
+Clearing selected diversions can be done with the following macro:
+
+@deffn Composite cleardivert (@ovar{diversions@dots{}})
+Discard the contents of each of the listed numeric @var{diversions}.
+@end deffn
+
+@example
+define(`cleardivert',
+`pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
+@result{}
+@end example
+
+It is called just like @code{undivert}, but the effect is to clear the
+diversions, given by the arguments.  (This macro has a nasty bug!  You
+should try to see if you can find it and correct it; or @pxref{Improved
+cleardivert, , Answers}).
+
+@node Text handling
+@chapter Macros for text handling
+
+There are a number of builtins in @code{m4} for manipulating text in
+various ways, extracting substrings, searching, substituting, and so on.
+
+@menu
+* Len::                         Calculating length of strings
+* Index macro::                 Searching for substrings
+* Regexp::                      Searching for regular expressions
+* Substr::                      Extracting substrings
+* Translit::                    Translating characters
+* Patsubst::                    Substituting text by regular expression
+* Format::                      Formatting strings (printf-like)
+@end menu
+
+@node Len
+@section Calculating length of strings
+
+@cindex length of strings
+@cindex strings, length of
+The length of a string can be calculated by @code{len}:
+
+@deffn Builtin len (@var{string})
+Expands to the length of @var{string}, as a decimal number.
+
+The macro @code{len} is recognized only with parameters.
+@end deffn
+
+@example
+len()
+@result{}0
+len(`abcdef')
+@result{}6
+@end example
+
+@node Index macro
+@section Searching for substrings
+
+@cindex substrings, locating
+Searching for substrings is done with @code{index}:
+
+@deffn Builtin index (@var{string}, @var{substring})
+Expands to the index of the first occurrence of @var{substring} in
+@var{string}.  The first character in @var{string} has index 0.  If
+@var{substring} does not occur in @var{string}, @code{index} expands to
+@samp{-1}.
+
+The macro @code{index} is recognized only with parameters.
+@end deffn
+
+@example
+index(`gnus, gnats, and armadillos', `nat')
+@result{}7
+index(`gnus, gnats, and armadillos', `dag')
+@result{}-1
+@end example
+
+Omitting @var{substring} evokes a warning, but still produces output;
+contrast this with an empty @var{substring}.
+
+@example
+index(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `index'
+@result{}0
+index(`abc', `')
+@result{}0
+index(`abc', `b')
+@result{}1
+@end example
+
+@ignore
+@comment Expose a bug in the strstr() algorithm present in glibc
+@comment 2.9 through 2.12 and in gnulib up to Sep 2010.
+
+@example
+index(`;:11-:12-:12-:12-:12-:12-:12-:12-:12.:12.:12.:12.:12.:12.:12.:12.:12-',
+`:12-:12-:12-:12-:12-:12-:12-:12-')
+@result{}-1
+@end example
+
+@comment Expose a bug in the gnulib replacement strstr() algorithm
+@comment present from Jun 2010 to Feb 2011, including m4 1.4.15.
+
+@example
+index(`..wi.d.', `.d.')
+@result{}4
+@end example
+@end ignore
+
+@node Regexp
+@section Searching for regular expressions
+
+@cindex basic regular expressions
+@cindex regular expressions
+@cindex expressions, regular
+@cindex GNU extensions
+Searching for regular expressions is done with the builtin
+@code{regexp}:
+
+@deffn Builtin regexp (@var{string}, @var{regexp}, @ovar{replacement})
+Searches for @var{regexp} in @var{string}.  The syntax for regular
+expressions is the same as in GNU Emacs, which is similar to
+BRE, Basic Regular Expressions in POSIX.
+@ifnothtml
+@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
+Manual}.
+@end ifnothtml
+@ifhtml
+See
+@uref{http://www.gnu.org/@/software/@/emacs/@/manual/@/emacs.html#Regexps,
+Syntax of Regular Expressions} in the GNU Emacs Manual.
+@end ifhtml
+Support for ERE, Extended Regular Expressions is not
+available, but will be added in GNU M4 2.0.
+
+If @var{replacement} is omitted, @code{regexp} expands to the index of
+the first match of @var{regexp} in @var{string}.  If @var{regexp} does
+not match anywhere in @var{string}, it expands to -1.
+
+If @var{replacement} is supplied, and there was a match, @code{regexp}
+changes the expansion to this argument, with @samp{\@var{n}} substituted
+by the text matched by the @var{n}th parenthesized sub-expression of
+@var{regexp}, up to nine sub-expressions.  The escape @samp{\&} is
+replaced by the text of the entire regular expression matched.  For
+all other characters, @samp{\} treats the next character literally.  A
+warning is issued if there were fewer sub-expressions than the
+@samp{\@var{n}} requested, or if there is a trailing @samp{\}.  If there
+was no match, @code{regexp} expands to the empty string.
+
+The macro @code{regexp} is recognized only with parameters.
+@end deffn
+
+@example
+regexp(`GNUs not Unix', `\<[a-z]\w+')
+@result{}5
+regexp(`GNUs not Unix', `\<Q\w*')
+@result{}-1
+regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
+@result{}*** Unix *** nix ***
+regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
+@result{}
+@end example
+
+Here are some more examples on the handling of backslash:
+
+@example
+regexp(`abc', `\(b\)', `\\\10\a')
+@result{}\b0a
+regexp(`abc', `b', `\1\')
+@error{}m4:stdin:2: Warning: sub-expression 1 not present
+@error{}m4:stdin:2: Warning: trailing \ ignored in replacement
+@result{}
+regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
+@error{}m4:stdin:3: Warning: sub-expression 4 not present
+@error{}m4:stdin:3: Warning: sub-expression 5 not present
+@error{}m4:stdin:3: Warning: sub-expression 6 not present
+@result{}c
+@end example
+
+Omitting @var{regexp} evokes a warning, but still produces output;
+contrast this with an empty @var{regexp} argument.
+
+@example
+regexp(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `regexp'
+@result{}0
+regexp(`abc', `')
+@result{}0
+regexp(`abc', `', `\\def')
+@result{}\def
+@end example
+
+@node Substr
+@section Extracting substrings
+
+@cindex extracting substrings
+@cindex substrings, extracting
+Substrings are extracted with @code{substr}:
+
+@deffn Builtin substr (@var{string}, @var{from}, @ovar{length})
+Expands to the substring of @var{string}, which starts at index
+@var{from}, and extends for @var{length} characters, or to the end of
+@var{string}, if @var{length} is omitted.  The starting index of a string
+is always 0.  The expansion is empty if there is an error parsing
+@var{from} or @var{length}, if @var{from} is beyond the end of
+@var{string}, or if @var{length} is negative.
+
+The macro @code{substr} is recognized only with parameters.
+@end deffn
+
+@example
+substr(`gnus, gnats, and armadillos', `6')
+@result{}gnats, and armadillos
+substr(`gnus, gnats, and armadillos', `6', `5')
+@result{}gnats
+@end example
+
+Omitting @var{from} evokes a warning, but still produces output.
+
+@example
+substr(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `substr'
+@result{}abc
+substr(`abc',)
+@error{}m4:stdin:2: empty string treated as 0 in builtin `substr'
+@result{}abc
+@end example
+
+@node Translit
+@section Translating characters
+
+@cindex translating characters
+@cindex characters, translating
+Character translation is done with @code{translit}:
+
+@deffn Builtin translit (@var{string}, @var{chars}, @ovar{replacement})
+Expands to @var{string}, with each character that occurs in
+@var{chars} translated into the character from @var{replacement} with
+the same index.
+
+If @var{replacement} is shorter than @var{chars}, the excess characters
+of @var{chars} are deleted from the expansion; if @var{chars} is
+shorter, the excess characters in @var{replacement} are silently
+ignored.  If @var{replacement} is omitted, all characters in
+@var{string} that are present in @var{chars} are deleted from the
+expansion.  If a character appears more than once in @var{chars}, only
+the first instance is used in making the translation.  Only a single
+translation pass is made, even if characters in @var{replacement} also
+appear in @var{chars}.
+
+As a GNU extension, both @var{chars} and @var{replacement} can
+contain character-ranges, e.g., @samp{a-z} (meaning all lowercase
+letters) or @samp{0-9} (meaning all digits).  To include a dash @samp{-}
+in @var{chars} or @var{replacement}, place it first or last in the
+entire string, or as the last character of a range.  Back-to-back ranges
+can share a common endpoint.  It is not an error for the last character
+in the range to be `larger' than the first.  In that case, the range
+runs backwards, i.e., @samp{9-0} means the string @samp{9876543210}.
+The expansion of a range is dependent on the underlying encoding of
+characters, so using ranges is not always portable between machines.
+
+The macro @code{translit} is recognized only with parameters.
+@end deffn
+
+@example
+translit(`GNUs not Unix', `A-Z')
+@result{}s not nix
+translit(`GNUs not Unix', `a-z', `A-Z')
+@result{}GNUS NOT UNIX
+translit(`GNUs not Unix', `A-Z', `z-a')
+@result{}tmfs not fnix
+translit(`+,-12345', `+--1-5', `<;>a-c-a')
+@result{}<;>abcba
+translit(`abcdef', `aabdef', `bcged')
+@result{}bgced
+@end example
+
+In the @sc{ascii} encoding, the first example deletes all uppercase
+letters, the second converts lowercase to uppercase, and the third
+`mirrors' all uppercase letters, while converting them to lowercase.
+The two first cases are by far the most common, even though they are not
+portable to @sc{ebcdic} or other encodings.  The fourth example shows a
+range ending in @samp{-}, as well as back-to-back ranges.  The final
+example shows that @samp{a} is mapped to @samp{b}, not @samp{c}; the
+resulting @samp{b} is not further remapped to @samp{g}; the @samp{d} and
+@samp{e} are swapped, and the @samp{f} is discarded.
+
+@ignore
+@comment No need to fight 8-bit characters, as it is difficult to get
+@comment rendering right in both info and dvi.
+
+@example
+translit(`«abc~', `~-»')
+@result{}abc
+@end example
+
+@comment Stress test short arguments, since they use a different code
+@comment path.
+@example
+translit(`abcdeabcde', `a')
+@result{}bcdebcde
+translit(`abcdeabcde', `ab')
+@result{}cdecde
+translit(`abcdeabcde', `a', `f')
+@result{}fbcdefbcde
+translit(`abcdeabcde', `a', `f')
+@result{}fbcdefbcde
+translit(`abcdeabcde', `a', `fg')
+@result{}fbcdefbcde
+translit(`abcdeabcde', `ab', `f')
+@result{}fcdefcde
+translit(`abcdeabcde', `ab', `fg')
+@result{}fgcdefgcde
+translit(`abcdeabcde', `ab', `ba')
+@result{}bacdebacde
+translit(`abcdeabcde', `e', `f')
+@result{}abcdfabcdf
+translit(`abc', `', `cde')
+@result{}abc
+translit(`', `a', `bc')
+@result{}
+@end example
+@end ignore
+
+Omitting @var{chars} evokes a warning, but still produces output.
+
+@example
+translit(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `translit'
+@result{}abc
+@end example
+
+@node Patsubst
+@section Substituting text by regular expression
+
+@cindex basic regular expressions
+@cindex regular expressions
+@cindex expressions, regular
+@cindex pattern substitution
+@cindex substitution by regular expression
+@cindex GNU extensions
+Global substitution in a string is done by @code{patsubst}:
+
+@deffn Builtin patsubst (@var{string}, @var{regexp}, @ovar{replacement})
+Searches @var{string} for matches of @var{regexp}, and substitutes
+@var{replacement} for each match.  The syntax for regular expressions
+is the same as in GNU Emacs (@pxref{Regexp}).
+
+The parts of @var{string} that are not covered by any match of
+@var{regexp} are copied to the expansion.  Whenever a match is found, the
+search proceeds from the end of the match, so a character from
+@var{string} will never be substituted twice.  If @var{regexp} matches a
+string of zero length, the start position for the search is incremented,
+to avoid infinite loops.
+
+When a replacement is to be made, @var{replacement} is inserted into
+the expansion, with @samp{\@var{n}} substituted by the text matched by
+the @var{n}th parenthesized sub-expression of @var{patsubst}, for up to
+nine sub-expressions.  The escape @samp{\&} is replaced by the text of
+the entire regular expression matched.  For all other characters,
+@samp{\} treats the next character literally.  A warning is issued if
+there were fewer sub-expressions than the @samp{\@var{n}} requested, or
+if there is a trailing @samp{\}.
+
+The @var{replacement} argument can be omitted, in which case the text
+matched by @var{regexp} is deleted.
+
+The macro @code{patsubst} is recognized only with parameters.
+@end deffn
+
+@example
+patsubst(`GNUs not Unix', `^', `OBS: ')
+@result{}OBS: GNUs not Unix
+patsubst(`GNUs not Unix', `\<', `OBS: ')
+@result{}OBS: GNUs OBS: not OBS: Unix
+patsubst(`GNUs not Unix', `\w*', `(\&)')
+@result{}(GNUs)() (not)() (Unix)()
+patsubst(`GNUs not Unix', `\w+', `(\&)')
+@result{}(GNUs) (not) (Unix)
+patsubst(`GNUs not Unix', `[A-Z][a-z]+')
+@result{}GN not@w{ }
+patsubst(`GNUs not Unix', `not', `NOT\')
+@error{}m4:stdin:6: Warning: trailing \ ignored in replacement
+@result{}GNUs NOT Unix
+@end example
+
+Here is a slightly more realistic example, which capitalizes individual
+words or whole sentences, by substituting calls of the macros
+@code{upcase} and @code{downcase} into the strings.
+
+@deffn Composite upcase (@var{text})
+@deffnx Composite downcase (@var{text})
+@deffnx Composite capitalize (@var{text})
+Expand to @var{text}, but with capitalization changed: @code{upcase}
+changes all letters to upper case, @code{downcase} changes all letters
+to lower case, and @code{capitalize} changes the first character of each
+word to upper case and the remaining characters to lower case.
+@end deffn
+
+First, an example of their usage, using implementations distributed in
+@file{m4-@value{VERSION}/@/examples/@/capitalize.m4}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`capitalize.m4')
+@result{}
+upcase(`GNUs not Unix')
+@result{}GNUS NOT UNIX
+downcase(`GNUs not Unix')
+@result{}gnus not unix
+capitalize(`GNUs not Unix')
+@result{}Gnus Not Unix
+@end example
+
+Now for the implementation.  There is a helper macro @code{_capitalize}
+which puts only its first word in mixed case.  Then @code{capitalize}
+merely parses out the words, and replaces them with an invocation of
+@code{_capitalize}.  (As presented here, the @code{capitalize} macro has
+some subtle flaws.  You should try to see if you can find and correct
+them; or @pxref{Improved capitalize, , Answers}).
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+undivert(`capitalize.m4')dnl
+@result{}divert(`-1')
+@result{}# upcase(text)
+@result{}# downcase(text)
+@result{}# capitalize(text)
+@result{}#   change case of text, simple version
+@result{}define(`upcase', `translit(`$*', `a-z', `A-Z')')
+@result{}define(`downcase', `translit(`$*', `A-Z', `a-z')')
+@result{}define(`_capitalize',
+@result{}       `regexp(`$1', `^\(\w\)\(\w*\)',
+@result{}               `upcase(`\1')`'downcase(`\2')')')
+@result{}define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')')
+@result{}divert`'dnl
+@end example
+
+While @code{regexp} replaces the whole input with the replacement as
+soon as there is a match, @code{patsubst} replaces each
+@emph{occurrence} of a match and preserves non-matching pieces:
+
+@example
+define(`patreg',
+`patsubst($@@)
+regexp($@@)')dnl
+patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
+@result{}bar FOO baz FOO
+@result{}FOO
+patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
+@result{}bab abb 212
+@result{}bab
+@end example
+
+Omitting @var{regexp} evokes a warning, but still produces output;
+contrast this with an empty @var{regexp} argument.
+
+@example
+patsubst(`abc')
+@error{}m4:stdin:1: Warning: too few arguments to builtin `patsubst'
+@result{}abc
+patsubst(`abc', `')
+@result{}abc
+patsubst(`abc', `', `\\-')
+@result{}\-a\-b\-c\-
+@end example
+
+@node Format
+@section Formatting strings (printf-like)
+
+@cindex formatted output
+@cindex output, formatted
+@cindex GNU extensions
+Formatted output can be made with @code{format}:
+
+@deffn Builtin format (@var{format-string}, @dots{})
+Works much like the C function @code{printf}.  The first argument
+@var{format-string} can contain @samp{%} specifications which are
+satisfied by additional arguments, and the expansion of @code{format} is
+the formatted string.
+
+The macro @code{format} is recognized only with parameters.
+@end deffn
+
+Its use is best described by a few examples:
+
+@comment This test is a bit fragile, if someone tries to port to a
+@comment platform without infinity.
+@example
+define(`foo', `The brown fox jumped over the lazy dog')
+@result{}
+format(`The string "%s" uses %d characters', foo, len(foo))
+@result{}The string "The brown fox jumped over the lazy dog" uses 38 characters
+format(`%*.*d', `-1', `-1', `1')
+@result{}1
+format(`%.0f', `56789.9876')
+@result{}56790
+len(format(`%-*X', `5000', `1'))
+@result{}5000
+ifelse(format(`%010F', `infinity'), `       INF', `success',
+       format(`%010F', `infinity'), `  INFINITY', `success',
+       format(`%010F', `infinity'))
+@result{}success
+ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
+       format(`%.1A', `1.999'), `0X2.0P+0', `success',
+       format(`%.1A', `1.999'))
+@result{}success
+format(`%g', `0xa.P+1')
+@result{}20
+@end example
+
+Using the @code{forloop} macro defined earlier (@pxref{Forloop}), this
+example shows how @code{format} can be used to produce tabular output.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`forloop.m4')
+@result{}
+forloop(`i', `1', `10', `format(`%6d squared is %10d
+', i, eval(i**2))')
+@result{}     1 squared is          1
+@result{}     2 squared is          4
+@result{}     3 squared is          9
+@result{}     4 squared is         16
+@result{}     5 squared is         25
+@result{}     6 squared is         36
+@result{}     7 squared is         49
+@result{}     8 squared is         64
+@result{}     9 squared is         81
+@result{}    10 squared is        100
+@result{}
+@end example
+
+The builtin @code{format} is modeled after the ANSI C @samp{printf}
+function, and supports these @samp{%} specifiers: @samp{c}, @samp{s},
+@samp{d}, @samp{o}, @samp{x}, @samp{X}, @samp{u}, @samp{a}, @samp{A},
+@samp{e}, @samp{E}, @samp{f}, @samp{F}, @samp{g}, @samp{G}, and
+@samp{%}; it supports field widths and precisions, and the flags
+@samp{+}, @samp{-}, @samp{ }, @samp{0}, @samp{#}, and @samp{'}.  For
+integer specifiers, the width modifiers @samp{hh}, @samp{h}, and
+@samp{l} are recognized, and for floating point specifiers, the width
+modifier @samp{l} is recognized.  Items not yet supported include
+positional arguments, the @samp{n}, @samp{p}, @samp{S}, and @samp{C}
+specifiers, the @samp{z}, @samp{t}, @samp{j}, @samp{L} and @samp{ll}
+modifiers, and any platform extensions available in the native
+@code{printf}.  For more details on the functioning of @code{printf},
+see the C Library Manual, or the POSIX specification (for
+example, @samp{%a} is supported even on platforms that haven't yet
+implemented C99 hexadecimal floating point output natively).
+
+Unrecognized specifiers result in a warning.  It is anticipated that a
+future release of GNU @code{m4} will support more specifiers,
+and give better warnings when various problems such as overflow are
+encountered.  Likewise, escape sequences are not yet recognized.
+
+@example
+format(`%p', `0')
+@error{}m4:stdin:1: Warning: unrecognized specifier in `%p'
+@result{}
+@end example
+
+@ignore
+@comment Expose a crash with a bad format string fixed in 1.4.15.
+@comment Unfortuntely, 8-bit bytes are hard to check for; but the
+@comment exit status is enough to sniff the crash in broken versions.
+
+@comment xerr: ignore
+@example
+format(`%'format(`%c', `128'))
+@result{}
+@end example
+@end ignore
+
+@node Arithmetic
+@chapter Macros for doing arithmetic
+
+@cindex arithmetic
+@cindex integer arithmetic
+Integer arithmetic is included in @code{m4}, with a C-like syntax.  As
+convenient shorthands, there are builtins for simple increment and
+decrement operations.
+
+@menu
+* Incr::                        Decrement and increment operators
+* Eval::                        Evaluating integer expressions
+@end menu
+
+@node Incr
+@section Decrement and increment operators
+
+@cindex decrement operator
+@cindex increment operator
+Increment and decrement of integers are supported using the builtins
+@code{incr} and @code{decr}:
+
+@deffn Builtin incr (@var{number})
+@deffnx Builtin decr (@var{number})
+Expand to the numerical value of @var{number}, incremented
+or decremented, respectively, by one.  Except for the empty string, the
+expansion is empty if @var{number} could not be parsed.
+
+The macros @code{incr} and @code{decr} are recognized only with
+parameters.
+@end deffn
+
+@example
+incr(`4')
+@result{}5
+decr(`7')
+@result{}6
+incr()
+@error{}m4:stdin:3: empty string treated as 0 in builtin `incr'
+@result{}1
+decr()
+@error{}m4:stdin:4: empty string treated as 0 in builtin `decr'
+@result{}-1
+@end example
+
+@node Eval
+@section Evaluating integer expressions
+
+@cindex integer expression evaluation
+@cindex evaluation, of integer expressions
+@cindex expressions, evaluation of integer
+Integer expressions are evaluated with @code{eval}:
+
+@deffn Builtin eval (@var{expression}, @dvar{radix, 10}, @ovar{width})
+Expands to the value of @var{expression}.  The expansion is empty
+if a problem is encountered while parsing the arguments.  If specified,
+@var{radix} and @var{width} control the format of the output.
+
+Calculations are done with 32-bit signed numbers.  Overflow silently
+results in wraparound.  A warning is issued if division by zero is
+attempted, or if @var{expression} could not be parsed.
+
+Expressions can contain the following operators, listed in order of
+decreasing precedence.
+
+@table @samp
+@item ()
+Parentheses
+@item +  -  ~  !
+Unary plus and minus, and bitwise and logical negation
+@item **
+Exponentiation
+@item *  /  %
+Multiplication, division, and modulo
+@item +  -
+Addition and subtraction
+@item <<  >>
+Shift left or right
+@item >  >=  <  <=
+Relational operators
+@item ==  !=
+Equality operators
+@item &
+Bitwise and
+@item ^
+Bitwise exclusive-or
+@item |
+Bitwise or
+@item &&
+Logical and
+@item ||
+Logical or
+@end table
+
+The macro @code{eval} is recognized only with parameters.
+@end deffn
+
+All binary operators, except exponentiation, are left associative.  C
+operators that perform variable assignment, such as @samp{+=} or
+@samp{--}, are not implemented, since @code{eval} only operates on
+constants, not variables.  Attempting to use them results in an error.
+However, since traditional implementations treated @samp{=} as an
+undocumented alias for @samp{==} as opposed to an assignment operator,
+this usage is supported as a special case.  Be aware that a future
+version of GNU M4 may support assignment semantics as an
+extension when POSIX mode is not requested, and that using
+@samp{=} to check equality is not portable.
+
+@comment status: 1
+@example
+eval(`2 = 2')
+@error{}m4:stdin:1: Warning: recommend ==, not =, for equality operator
+@result{}1
+eval(`++0')
+@error{}m4:stdin:2: invalid operator in eval: ++0
+@result{}
+eval(`0 |= 1')
+@error{}m4:stdin:3: invalid operator in eval: 0 |= 1
+@result{}
+@end example
+
+Note that some older @code{m4} implementations use @samp{^} as an
+alternate operator for the exponentiation, although POSIX
+requires the C behavior of bitwise exclusive-or.  The precedence of the
+negation operators, @samp{~} and @samp{!}, was traditionally lower than
+equality.  The unary operators could not be used reliably more than once
+on the same term without intervening parentheses.  The traditional
+precedence of the equality operators @samp{==} and @samp{!=} was
+identical instead of lower than the relational operators such as
+@samp{<}, even through GNU M4 1.4.8.  Starting with version
+1.4.9, GNU M4 correctly follows POSIX precedence
+rules.  M4 scripts designed to be portable between releases must be
+aware that parentheses may be required to enforce C precedence rules.
+Likewise, division by zero, even in the unused branch of a
+short-circuiting operator, is not always well-defined in other
+implementations.
+
+Following are some examples where the current version of M4 follows C
+precedence rules, but where older versions and some other
+implementations of @code{m4} require explicit parentheses to get the
+correct result:
+
+@example
+eval(`1 == 2 > 0')
+@result{}1
+eval(`(1 == 2) > 0')
+@result{}0
+eval(`! 0 * 2')
+@result{}2
+eval(`! (0 * 2)')
+@result{}1
+eval(`1 | 1 ^ 1')
+@result{}1
+eval(`(1 | 1) ^ 1')
+@result{}0
+eval(`+ + - ~ ! ~ 0')
+@result{}1
+eval(`2 || 1 / 0')
+@result{}1
+eval(`0 || 1 / 0')
+@error{}m4:stdin:9: divide by zero in eval: 0 || 1 / 0
+@result{}
+eval(`0 && 1 % 0')
+@result{}0
+eval(`2 && 1 % 0')
+@error{}m4:stdin:11: modulo by zero in eval: 2 && 1 % 0
+@result{}
+@end example
+
+@cindex GNU extensions
+As a GNU extension, the operator @samp{**} performs integral
+exponentiation.  The operator is right-associative, and if evaluated,
+the exponent must be non-negative, and at least one of the arguments
+must be non-zero, or a warning is issued.
+
+@example
+eval(`2 ** 3 ** 2')
+@result{}512
+eval(`(2 ** 3) ** 2')
+@result{}64
+eval(`0 ** 1')
+@result{}0
+eval(`2 ** 0')
+@result{}1
+eval(`0 ** 0')
+@result{}
+@error{}m4:stdin:5: divide by zero in eval: 0 ** 0
+eval(`4 ** -2')
+@error{}m4:stdin:6: negative exponent in eval: 4 ** -2
+@result{}
+@end example
+
+Within @var{expression}, (but not @var{radix} or @var{width}), numbers
+without a special prefix are decimal.  A simple @samp{0} prefix
+introduces an octal number.  @samp{0x} introduces a hexadecimal number.
+As GNU extensions, @samp{0b} introduces a binary number.
+@samp{0r} introduces a number expressed in any radix between 1 and 36:
+the prefix should be immediately followed by the decimal expression of
+the radix, a colon, then the digits making the number.  For radix 1,
+leading zeros are ignored, and all remaining digits must be @samp{1};
+for all other radices, the digits are @samp{0}, @samp{1}, @samp{2},
+@dots{}.  Beyond @samp{9}, the digits are @samp{a}, @samp{b} @dots{} up
+to @samp{z}.  Lower and upper case letters can be used interchangeably
+in numbers prefixes and as number digits.
+
+Parentheses may be used to group subexpressions whenever needed.  For the
+relational operators, a true relation returns @code{1}, and a false
+relation return @code{0}.
+
+Here are a few examples of use of @code{eval}.
+
+@example
+eval(`-3 * 5')
+@result{}-15
+eval(`-99 / 10')
+@result{}-9
+eval(`-99 % 10')
+@result{}-9
+eval(`99 % -10')
+@result{}9
+eval(index(`Hello world', `llo') >= 0)
+@result{}1
+eval(`0r1:0111 + 0b100 + 0r3:12')
+@result{}12
+define(`square', `eval(`($1) ** 2')')
+@result{}
+square(`9')
+@result{}81
+square(square(`5')` + 1')
+@result{}676
+define(`foo', `666')
+@result{}
+eval(`foo / 6')
+@error{}m4:stdin:11: bad expression in eval: foo / 6
+@result{}
+eval(foo / 6)
+@result{}111
+@end example
+
+As the last two lines show, @code{eval} does not handle macro
+names, even if they expand to a valid expression (or part of a valid
+expression).  Therefore all macros must be expanded before they are
+passed to @code{eval}.
+
+Some calculations are not portable to other implementations, since they
+have undefined semantics in C, but GNU @code{m4} has
+well-defined behavior on overflow.  When shifting, an out-of-range shift
+amount is implicitly brought into the range of 32-bit signed integers
+using an implicit bit-wise and with 0x1f).
+
+@example
+define(`max_int', eval(`0x7fffffff'))
+@result{}
+define(`min_int', incr(max_int))
+@result{}
+eval(min_int` < 0')
+@result{}1
+eval(max_int` > 0')
+@result{}1
+ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
+@result{}overflow occurred
+min_int
+@result{}-2147483648
+eval(`0x80000000 % -1')
+@result{}0
+eval(`-4 >> 1')
+@result{}-2
+eval(`-4 >> 33')
+@result{}-2
+@end example
+
+If @var{radix} is specified, it specifies the radix to be used in the
+expansion.  The default radix is 10; this is also the case if
+@var{radix} is the empty string.  A warning results if the radix is
+outside the range of 1 through 36, inclusive.  The result of @code{eval}
+is always taken to be signed.  No radix prefix is output, and for
+radices greater than 10, the digits are lower case.  The @var{width}
+argument specifies the minimum output width, excluding any negative
+sign.  The result is zero-padded to extend the expansion to the
+requested width.  A warning results if the width is negative.  If
+@var{radix} or @var{width} is out of bounds, the expansion of
+@code{eval} is empty.
+
+@example
+eval(`666', `10')
+@result{}666
+eval(`666', `11')
+@result{}556
+eval(`666', `6')
+@result{}3030
+eval(`666', `6', `10')
+@result{}0000003030
+eval(`-666', `6', `10')
+@result{}-0000003030
+eval(`10', `', `0')
+@result{}10
+`0r1:'eval(`10', `1', `11')
+@result{}0r1:01111111111
+eval(`10', `16')
+@result{}a
+eval(`1', `37')
+@error{}m4:stdin:9: radix 37 in builtin `eval' out of range
+@result{}
+eval(`1', , `-1')
+@error{}m4:stdin:10: negative width to builtin `eval'
+@result{}
+eval()
+@error{}m4:stdin:11: empty string treated as 0 in builtin `eval'
+@result{}0
+@end example
+
+@node Shell commands
+@chapter Macros for running shell commands
+
+@cindex UNIX commands, running
+@cindex executing shell commands
+@cindex running shell commands
+@cindex shell commands, running
+@cindex commands, running shell
+There are a few builtin macros in @code{m4} that allow you to run shell
+commands from within @code{m4}.
+
+Note that the definition of a valid shell command is system dependent.
+On UNIX systems, this is the typical @command{/bin/sh}.  But on other
+systems, such as native Windows, the shell has a different syntax of
+commands that it understands.  Some examples in this chapter assume
+@command{/bin/sh}, and also demonstrate how to quit early with a known
+exit value if this is not the case.
+
+@menu
+* Platform macros::             Determining the platform
+* Syscmd::                      Executing simple commands
+* Esyscmd::                     Reading the output of commands
+* Sysval::                      Exit status
+* Mkstemp::                     Making temporary files
+@end menu
+
+@node Platform macros
+@section Determining the platform
+
+@cindex platform macros
+Sometimes it is desirable for an input file to know which platform
+@code{m4} is running on.  GNU @code{m4} provides several
+macros that are predefined to expand to the empty string; checking for
+their existence will confirm platform details.
+
+@deffn {Optional builtin} __gnu__
+@deffnx {Optional builtin} __os2__
+@deffnx {Optional builtin} os2
+@deffnx {Optional builtin} __unix__
+@deffnx {Optional builtin} unix
+@deffnx {Optional builtin} __windows__
+@deffnx {Optional builtin} windows
+Each of these macros is conditionally defined as needed to describe the
+environment of @code{m4}.  If defined, each macro expands to the empty
+string.  For now, these macros silently ignore all arguments, but in a
+future release of M4, they might warn if arguments are present.
+@end deffn
+
+When GNU extensions are in effect (that is, when you did not
+use the @option{-G} option, @pxref{Limits control, , Invoking m4}),
+GNU @code{m4} will define the macro @code{@w{__gnu__}} to
+expand to the empty string.
+
+@example
+$ @kbd{m4}
+__gnu__
+@result{}
+__gnu__(`ignored')
+@result{}
+Extensions are ifdef(`__gnu__', `active', `inactive')
+@result{}Extensions are active
+@end example
+
+@comment options: -G
+@example
+$ @kbd{m4 -G}
+__gnu__
+@result{}__gnu__
+__gnu__(`ignored')
+@result{}__gnu__(ignored)
+Extensions are ifdef(`__gnu__', `active', `inactive')
+@result{}Extensions are inactive
+@end example
+
+On UNIX systems, GNU @code{m4} will define @code{@w{__unix__}}
+by default, or @code{unix} when the @option{-G} option is specified.
+
+On native Windows systems, GNU @code{m4} will define
+@code{@w{__windows__}} by default, or @code{windows} when the
+@option{-G} option is specified.
+
+On OS/2 systems, GNU @code{m4} will define @code{@w{__os2__}}
+by default, or @code{os2} when the @option{-G} option is specified.
+
+If GNU @code{m4} does not provide a platform macro for your system,
+please report that as a bug.
+
+@example
+define(`provided', `0')
+@result{}
+ifdef(`__unix__', `define(`provided', incr(provided))')
+@result{}
+ifdef(`__windows__', `define(`provided', incr(provided))')
+@result{}
+ifdef(`__os2__', `define(`provided', incr(provided))')
+@result{}
+provided
+@result{}1
+@end example
+
+@node Syscmd
+@section Executing simple commands
+
+Any shell command can be executed, using @code{syscmd}:
+
+@deffn Builtin syscmd (@var{shell-command})
+Executes @var{shell-command} as a shell command.
+
+The expansion of @code{syscmd} is void, @emph{not} the output from
+@var{shell-command}!  Output or error messages from @var{shell-command}
+are not read by @code{m4}.  @xref{Esyscmd}, if you need to process the
+command output.
+
+Prior to executing the command, @code{m4} flushes its buffers.
+The default standard input, output and error of @var{shell-command} are
+the same as those of @code{m4}.
+
+By default, the @var{shell-command} will be used as the argument to the
+@option{-c} option of the @command{/bin/sh} shell (or the version of
+@command{sh} specified by @samp{command -p getconf PATH}, if your system
+supports that).  If you prefer a different shell, the
+@command{configure} script can be given the option
+@option{--with-syscmd-shell=@var{location}} to set the location of an
+alternative shell at GNU @code{m4} installation; the
+alternative shell must still support @option{-c}.
+
+The macro @code{syscmd} is recognized only with parameters.
+@end deffn
+
+@example
+define(`foo', `FOO')
+@result{}
+syscmd(`echo foo')
+@result{}foo
+@result{}
+@end example
+
+Note how the expansion of @code{syscmd} keeps the trailing newline of
+the command, as well as using the newline that appeared after the macro.
+
+The following is an example of @var{shell-command} using the same
+standard input as @code{m4}:
+
+@comment ignore
+@example
+$ @kbd{echo "m4wrap(\`syscmd(\`cat')')" | m4}
+@result{}
+@end example
+
+@ignore
+@comment If the user types the example below with stdin being an
+@comment interactive terminal, then cat will hang waiting for additional
+@comment input after m4 has exited.  But the testsuite is using a pipe
+@comment for stdin.  Hence, we have two versions - the one we feed the
+@comment testsuite below, and the one we display to the user above that
+@comment more accurately shows what the testsuite is really doing but
+@comment which the testsuite cannot parse.
+
+@example
+m4wrap(`syscmd(`cat')')
+@result{}
+^D
+@end example
+@end ignore
+
+It tells @code{m4} to read all of its input before executing the wrapped
+text, then hand a valid (albeit emptied) pipe as standard input for the
+@code{cat} subcommand.  Therefore, you should be careful when using
+standard input (either by specifying no files, or by passing @samp{-} as
+a file name on the command line, @pxref{Command line files, , Invoking
+m4}), and also invoking subcommands via @code{syscmd} or @code{esyscmd}
+that consume data from standard input.  When standard input is a
+seekable file, the subprocess will pick up with the next character not
+yet processed by @code{m4}; when it is a pipe or other non-seekable
+file, there is no guarantee how much data will already be buffered by
+@code{m4} and thus unavailable to the child.
+
+@node Esyscmd
+@section Reading the output of commands
+
+@cindex GNU extensions
+If you want @code{m4} to read the output of a shell command, use
+@code{esyscmd}:
+
+@deffn Builtin esyscmd (@var{shell-command})
+Expands to the standard output of the shell command
+@var{shell-command}.
+
+Prior to executing the command, @code{m4} flushes its buffers.
+The default standard input and standard error of @var{shell-command} are
+the same as those of @code{m4}.  The error output of @var{shell-command}
+is not a part of the expansion: it will appear along with the error
+output of @code{m4}.
+
+By default, the @var{shell-command} will be used as the argument to the
+@option{-c} option of the @command{/bin/sh} shell (or the version of
+@command{sh} specified by @samp{command -p getconf PATH}, if your system
+supports that).  If you prefer a different shell, the
+@command{configure} script can be given the option
+@option{--with-syscmd-shell=@var{location}} to set the location of an
+alternative shell at GNU @code{m4} installation; the
+alternative shell must still support @option{-c}.
+
+The macro @code{esyscmd} is recognized only with parameters.
+@end deffn
+
+@example
+define(`foo', `FOO')
+@result{}
+esyscmd(`echo foo')
+@result{}FOO
+@result{}
+@end example
+
+Note how the expansion of @code{esyscmd} keeps the trailing newline of
+the command, as well as using the newline that appeared after the macro.
+
+Just as with @code{syscmd}, care must be exercised when sharing standard
+input between @code{m4} and the child process of @code{esyscmd}.
+
+@node Sysval
+@section Exit status
+
+@cindex UNIX commands, exit status from
+@cindex exit status from shell commands
+@cindex shell commands, exit status from
+@cindex commands, exit status from shell
+@cindex status of shell commands
+To see whether a shell command succeeded, use @code{sysval}:
+
+@deffn Builtin sysval
+Expands to the exit status of the last shell command run with
+@code{syscmd} or @code{esyscmd}.  Expands to 0 if no command has been
+run yet.
+@end deffn
+
+@example
+sysval
+@result{}0
+syscmd(`false')
+@result{}
+ifelse(sysval, `0', `zero', `non-zero')
+@result{}non-zero
+syscmd(`exit 2')
+@result{}
+sysval
+@result{}2
+syscmd(`true')
+@result{}
+sysval
+@result{}0
+esyscmd(`false')
+@result{}
+ifelse(sysval, `0', `zero', `non-zero')
+@result{}non-zero
+esyscmd(`echo dnl && exit 127')
+@result{}
+sysval
+@result{}127
+esyscmd(`true')
+@result{}
+sysval
+@result{}0
+@end example
+
+@code{sysval} results in 127 if there was a problem executing the
+command, for example, if the system-imposed argument length is exceeded,
+or if there were not enough resources to fork.  It is not possible to
+distinguish between failed execution and successful execution that had
+an exit status of 127, unless there was output from the child process.
+
+On UNIX platforms, where it is possible to detect when command execution
+is terminated by a signal, rather than a normal exit, the result is the
+signal number shifted left by eight bits.
+
+@comment This test has difficulties being portable, even on platforms
+@comment where syscmd invokes /bin/sh.  Kill is not portable with signal
+@comment names.  According to autoconf, the only portable signal numbers
+@comment are 1 (HUP), 2 (INT), 9 (KILL), 13 (PIPE) and 15 (TERM).  But
+@comment all shells handle SIGINT, and ksh handles HUP (as in, the shell
+@comment exits normally rather than letting the signal terminate it).
+@comment Also, TERM is flaky, as it can also kill the running m4 on
+@comment systems where /bin/sh does not create its own process group.
+@comment And PIPE is unreliable, since people tend to run with it
+@comment ignored, with m4 inheriting that choice.  That leaves KILL as
+@comment the only signal we can reliably test.
+@example
+dnl This test assumes kill is a shell builtin, and that signals are
+dnl recognizable.
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+syscmd(`kill -9 $$')
+@result{}
+sysval
+@result{}2304
+syscmd()
+@result{}
+sysval
+@result{}0
+esyscmd(`kill -9 $$')
+@result{}
+sysval
+@result{}2304
+@end example
+
+@node Mkstemp
+@section Making temporary files
+
+@cindex temporary file names
+@cindex files, names of temporary
+Commands specified to @code{syscmd} or @code{esyscmd} might need a
+temporary file, for output or for some other purpose.  There is a
+builtin macro, @code{mkstemp}, for making a temporary file:
+
+@deffn Builtin mkstemp (@var{template})
+@deffnx Builtin maketemp (@var{template})
+Expands to the quoted name of a new, empty file, made from the string
+@var{template}, which should end with the string @samp{XXXXXX}.  The six
+@samp{X} characters are then replaced with random characters matching
+the regular expression @samp{[a-zA-Z0-9._-]}, in order to make the file
+name unique.  If fewer than six @samp{X} characters are found at the end
+of @code{template}, the result will be longer than the template.  The
+created file will have access permissions as if by @kbd{chmod =rw,go=},
+meaning that the current umask of the @code{m4} process is taken into
+account, and at most only the current user can read and write the file.
+
+The traditional behavior, standardized by POSIX, is that
+@code{maketemp} merely replaces the trailing @samp{X} with the process
+id, without creating a file or quoting the expansion, and without
+ensuring that the resulting
+string is a unique file name.  In part, this means that using the same
+@var{template} twice in the same input file will result in the same
+expansion.  This behavior is a security hole, as it is very easy for
+another process to guess the name that will be generated, and thus
+interfere with a subsequent use of @code{syscmd} trying to manipulate
+that file name.  Hence, POSIX has recommended that all new
+implementations of @code{m4} provide the secure @code{mkstemp} builtin,
+and that users of @code{m4} check for its existence.
+
+The expansion is void and an error issued if a temporary file could
+not be created.
+
+The macros @code{mkstemp} and @code{maketemp} are recognized only with
+parameters.
+@end deffn
+
+If you try this next example, you will most likely get different output
+for the two file names, since the replacement characters are randomly
+chosen:
+
+@comment ignore
+@example
+$ @kbd{m4}
+define(`tmp', `oops')
+@result{}
+maketemp(`/tmp/fooXXXXXX')
+@result{}/tmp/fooa07346
+ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
+      `define(`mkstemp', defn(`maketemp'))dnl
+errprint(`warning: potentially insecure maketemp implementation
+')')
+@result{}
+mkstemp(`doc')
+@result{}docQv83Uw
+@end example
+
+@cindex GNU extensions
+Unless you use the @option{--traditional} command line option (or
+@option{-G}, @pxref{Limits control, , Invoking m4}), the GNU
+version of @code{maketemp} is secure.  This means that using the same
+template to multiple calls will generate multiple files.  However, we
+recommend that you use the new @code{mkstemp} macro, introduced in
+GNU M4 1.4.8, which is secure even in traditional mode.  Also,
+as of M4 1.4.11, the secure implementation quotes the resulting file
+name, so that you are guaranteed to know what file was created even if
+the random file name happens to match an existing macro.  Notice that
+this example is careful to use @code{defn} to avoid unintended expansion
+of @samp{foo}.
+
+@example
+$ @kbd{m4}
+define(`foo', `errprint(`oops')')
+@result{}
+syscmd(`rm -f foo-??????')sysval
+@result{}0
+define(`file1', maketemp(`foo-XXXXXX'))dnl
+ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ',
+       `no file', `created')
+@result{}created
+define(`file2', maketemp(`foo-XX'))dnl
+define(`file3', mkstemp(`foo-XXXXXX'))dnl
+ifelse(len(defn(`file1')), len(defn(`file2')),
+       `same length', `different')
+@result{}same length
+ifelse(defn(`file1'), defn(`file2'), `same', `different file')
+@result{}different file
+ifelse(defn(`file2'), defn(`file3'), `same', `different file')
+@result{}different file
+ifelse(defn(`file1'), defn(`file3'), `same', `different file')
+@result{}different file
+syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3'))
+@result{}
+sysval
+@result{}0
+@end example
+
+@ignore
+@c Not worth documenting, but make sure we don't leave trailing NUL in
+@c the expansion.
+
+@example
+syscmd(`rm -rf foodir')sysval
+@result{}0
+syscmd(`mkdir foodir')sysval
+@result{}0
+len(mkstemp(`foodir/fooXXXXX'))
+@result{}16
+syscmd(`rm -r foodir')sysval
+@result{}0
+@end example
+
+@c Likewise, and ensure that traditional mode leaves the result unquoted
+@c without creating a file.
+
+@comment options: -G
+@example
+syscmd(`rm -f foo-*')sysval
+@result{}0
+len(maketemp(`foo-XXXXX'))
+@error{}m4:stdin:2: recommend using mkstemp instead
+@result{}9
+define(`abc', `def')
+@result{}
+maketemp(`foo-abc')
+@result{}foo-def
+@error{}m4:stdin:4: recommend using mkstemp instead
+syscmd(`test -f foo-*')ifelse(sysval, `0', `0', `1')
+@result{}1
+@end example
+@end ignore
+
+@node Miscellaneous
+@chapter Miscellaneous builtin macros
+
+This chapter describes various builtins, that do not really belong in
+any of the previous chapters.
+
+@menu
+* Errprint::                    Printing error messages
+* Location::                    Printing current location
+* M4exit::                      Exiting from @code{m4}
+@end menu
+
+@node Errprint
+@section Printing error messages
+
+@cindex printing error messages
+@cindex error messages, printing
+@cindex messages, printing error
+@cindex standard error, output to
+You can print error messages using @code{errprint}:
+
+@deffn Builtin errprint (@var{message}, @dots{})
+Prints @var{message} and the rest of the arguments to standard error,
+separated by spaces.  Standard error is used, regardless of the
+@option{--debugfile} option (@pxref{Debugging options, , Invoking m4}).
+
+The expansion of @code{errprint} is void.
+The macro @code{errprint} is recognized only with parameters.
+@end deffn
+
+@example
+errprint(`Invalid arguments to forloop
+')
+@error{}Invalid arguments to forloop
+@result{}
+errprint(`1')errprint(`2',`3
+')
+@error{}12 3
+@result{}
+@end example
+
+A trailing newline is @emph{not} printed automatically, so it should be
+supplied as part of the argument, as in the example.  Unfortunately, the
+exact output of @code{errprint} is not very portable to other @code{m4}
+implementations: POSIX requires that all arguments be printed,
+but some implementations of @code{m4} only print the first.
+Furthermore, some BSD implementations always append a newline
+for each @code{errprint} call, regardless of whether the last argument
+already had one, and POSIX is silent on whether this is
+acceptable.
+
+@node Location
+@section Printing current location
+
+@cindex location, input
+@cindex input location
+To make it possible to specify the location of an error, three
+utility builtins exist:
+
+@deffn Builtin __file__
+@deffnx Builtin __line__
+@deffnx Builtin __program__
+Expand to the quoted name of the current input file, the
+current input line number in that file, and the quoted name of the
+current invocation of @code{m4}.
+@end deffn
+
+@example
+errprint(__program__:__file__:__line__: `input error
+')
+@error{}m4:stdin:1: input error
+@result{}
+@end example
+
+Line numbers start at 1 for each file.  If the file was found due to the
+@option{-I} option or @env{M4PATH} environment variable, that is
+reflected in the file name.  The syncline option (@option{-s},
+@pxref{Preprocessor features, , Invoking m4}), and the
+@samp{f} and @samp{l} flags of @code{debugmode} (@pxref{Debug Levels}),
+also use this notion of current file and line.  Redefining the three
+location macros has no effect on syncline, debug, warning, or error
+message output.
+
+This example reuses the file @file{incl.m4} mentioned earlier
+(@pxref{Include}):
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+define(`foo', ``$0' called at __file__:__line__')
+@result{}
+foo
+@result{}foo called at stdin:2
+include(`incl.m4')
+@result{}Include file start
+@result{}foo called at examples/incl.m4:2
+@result{}Include file end
+@result{}
+@end example
+
+The location of macros invoked during the rescanning of macro expansion
+text corresponds to the location in the file where the expansion was
+triggered, regardless of how many newline characters the expansion text
+contains.  As of GNU M4 1.4.8, the location of text wrapped
+with @code{m4wrap} (@pxref{M4wrap}) is the point at which the
+@code{m4wrap} was invoked.  Previous versions, however, behaved as
+though wrapped text came from line 0 of the file ``''.
+
+@example
+define(`echo', `$@@')
+@result{}
+define(`foo', `echo(__line__
+__line__)')
+@result{}
+echo(__line__
+__line__)
+@result{}4
+@result{}5
+m4wrap(`foo
+')
+@result{}
+foo(errprint(__line__
+__line__
+))
+@error{}8
+@error{}9
+@result{}8
+@result{}8
+__line__
+@result{}11
+m4wrap(`__line__
+')
+@result{}
+^D
+@result{}12
+@result{}6
+@result{}6
+@end example
+
+The @code{@w{__program__}} macro behaves like @samp{$0} in shell
+terminology.  If you invoke @code{m4} through an absolute path or a link
+with a different spelling, rather than by relying on a @env{PATH} search
+for plain @samp{m4}, it will affect how @code{@w{__program__}} expands.
+The intent is that you can use it to produce error messages with the
+same formatting that @code{m4} produces internally.  It can also be used
+within @code{syscmd} (@pxref{Syscmd}) to pick the same version of
+@code{m4} that is currently running, rather than whatever version of
+@code{m4} happens to be first in @env{PATH}.  It was first introduced in
+GNU M4 1.4.6.
+
+@node M4exit
+@section Exiting from @code{m4}
+
+@cindex exiting from @code{m4}
+@cindex status, setting @code{m4} exit
+If you need to exit from @code{m4} before the entire input has been
+read, you can use @code{m4exit}:
+
+@deffn Builtin m4exit (@dvar{code, 0})
+Causes @code{m4} to exit, with exit status @var{code}.  If @var{code} is
+left out, the exit status is zero.  If @var{code} cannot be parsed, or
+is outside the range of 0 to 255, the exit status is one.  No further
+input is read, and all wrapped and diverted text is discarded.
+@end deffn
+
+@example
+m4wrap(`This text is lost due to `m4exit'.')
+@result{}
+divert(`1') So is this.
+divert
+@result{}
+m4exit And this is never read.
+@end example
+
+A common use of this is to abort processing:
+
+@deffn Composite fatal_error (@var{message})
+Abort processing with an error message and non-zero status.  Prefix
+@var{message} with details about where the error occurred, and print the
+resulting string to standard error.
+@end deffn
+
+@comment status: 1
+@example
+define(`fatal_error',
+       `errprint(__program__:__file__:__line__`: fatal error: $*
+')m4exit(`1')')
+@result{}
+fatal_error(`this is a BAD one, buster')
+@error{}m4:stdin:4: fatal error: this is a BAD one, buster
+@end example
+
+After this macro call, @code{m4} will exit with exit status 1.  This macro
+is only intended for error exits, since the normal exit procedures are
+not followed, i.e., diverted text is not undiverted, and saved text
+(@pxref{M4wrap}) is not reread.  (This macro could be made more robust
+to earlier versions of @code{m4}.  You should try to see if you can find
+weaknesses and correct them; or @pxref{Improved fatal_error, , Answers}).
+
+Note that it is still possible for the exit status to be different than
+what was requested by @code{m4exit}.  If @code{m4} detects some other
+error, such as a write error on standard output, the exit status will be
+non-zero even if @code{m4exit} requested zero.
+
+If standard input is seekable, then the file will be positioned at the
+next unread character.  If it is a pipe or other non-seekable file,
+then there are no guarantees how much data @code{m4} might have read
+into buffers, and thus discarded.
+
+@node Frozen files
+@chapter Fast loading of frozen state
+
+Some bigger @code{m4} applications may be built over a common base
+containing hundreds of definitions and other costly initializations.
+Usually, the common base is kept in one or more declarative files,
+which files are listed on each @code{m4} invocation prior to the
+user's input file, or else each input file uses @code{include}.
+
+Reading the common base of a big application, over and over again, may
+be time consuming.  GNU @code{m4} offers some machinery to
+speed up the start of an application using lengthy common bases.
+
+@menu
+* Using frozen files::          Using frozen files
+* Frozen file format::          Frozen file format
+@end menu
+
+@node Using frozen files
+@section Using frozen files
+
+@cindex fast loading of frozen files
+@cindex frozen files for fast loading
+@cindex initialization, frozen state
+@cindex dumping into frozen file
+@cindex reloading a frozen file
+@cindex GNU extensions
+Suppose a user has a library of @code{m4} initializations in
+@file{base.m4}, which is then used with multiple input files:
+
+@comment ignore
+@example
+$ @kbd{m4 base.m4 input1.m4}
+$ @kbd{m4 base.m4 input2.m4}
+$ @kbd{m4 base.m4 input3.m4}
+@end example
+
+Rather than spending time parsing the fixed contents of @file{base.m4}
+every time, the user might rather execute:
+
+@comment ignore
+@example
+$ @kbd{m4 -F base.m4f base.m4}
+@end example
+
+@noindent
+once, and further execute, as often as needed:
+
+@comment ignore
+@example
+$ @kbd{m4 -R base.m4f input1.m4}
+$ @kbd{m4 -R base.m4f input2.m4}
+$ @kbd{m4 -R base.m4f input3.m4}
+@end example
+
+@noindent
+with the varying input.  The first call, containing the @option{-F}
+option, only reads and executes file @file{base.m4}, defining
+various application macros and computing other initializations.
+Once the input file @file{base.m4} has been completely processed, GNU
+@code{m4} produces in @file{base.m4f} a @dfn{frozen} file, that is, a
+file which contains a kind of snapshot of the @code{m4} internal state.
+
+Later calls, containing the @option{-R} option, are able to reload
+the internal state of @code{m4}, from @file{base.m4f},
+@emph{prior} to reading any other input files.  This means
+instead of starting with a virgin copy of @code{m4}, input will be
+read after having effectively recovered the effect of a prior run.
+In our example, the effect is the same as if file @file{base.m4} has
+been read anew.  However, this effect is achieved a lot faster.
+
+Only one frozen file may be created or read in any one @code{m4}
+invocation.  It is not possible to recover two frozen files at once.
+However, frozen files may be updated incrementally, through using
+@option{-R} and @option{-F} options simultaneously.  For example, if
+some care is taken, the command:
+
+@comment ignore
+@example
+$ @kbd{m4 file1.m4 file2.m4 file3.m4 file4.m4}
+@end example
+
+@noindent
+could be broken down in the following sequence, accumulating the same
+output:
+
+@comment ignore
+@example
+$ @kbd{m4 -F file1.m4f file1.m4}
+$ @kbd{m4 -R file1.m4f -F file2.m4f file2.m4}
+$ @kbd{m4 -R file2.m4f -F file3.m4f file3.m4}
+$ @kbd{m4 -R file3.m4f file4.m4}
+@end example
+
+Some care is necessary because not every effort has been made for
+this to work in all cases.  In particular, the trace attribute of
+macros is not handled, nor the current setting of @code{changeword}.
+Currently, @code{m4wrap} and @code{sysval} also have problems.
+Also, interactions for some options of @code{m4}, being used in one call
+and not in the next, have not been fully analyzed yet.  On the other
+end, you may be confident that stacks of @code{pushdef} definitions
+are handled correctly, as well as undefined or renamed builtins, and
+changed strings for quotes or comments.  And future releases of
+GNU M4 will improve on the utility of frozen files.
+
+@ignore
+@c This example is not worth putting in the manual, but caused core
+@c dumps in all versions prior to 1.4.11.
+
+@comment options: -F /dev/null
+@example
+traceon(`undefined')dnl
+@end example
+
+@c Make sure freezing is successful.
+
+@example
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+changequote(`[', `]')dnl
+syscmd([echo 'changequote([,])pushdef([divnum],[hi])dnl' \
+       | ']__program__[' -F in.m4f \
+     && echo 'divnum popdef([divnum])divnum' \
+       | ']__program__[' -R in.m4f \
+     && rm in.m4f])status sysval
+@result{}hi 0
+@result{}status 0
+@end example
+
+@c Detect inability to freeze.
+@c Some systems harden /, and fail with EACCES rather than ENOENT.
+
+@comment options: -F /none/such
+@comment xerr: ignore
+@comment status: 1
+@example
+$ @kbd{m4 -F /none/such}
+^D
+@error{}m4: cannot open `/none/such': No such file or directory
+@end example
+@end ignore
+
+When an @code{m4} run is to be frozen, the automatic undiversion
+which takes place at end of execution is inhibited.  Instead, all
+positively numbered diversions are saved into the frozen file.
+The active diversion number is also transmitted.
+
+A frozen file to be reloaded need not reside in the current directory.
+It is looked up the same way as an @code{include} file (@pxref{Search
+Path}).
+
+If the frozen file was generated with a newer version of @code{m4}, and
+contains directives that an older @code{m4} cannot parse, attempting to
+load the frozen file with option @option{-R} will cause @code{m4} to
+exit with status 63 to indicate version mismatch.
+
+@node Frozen file format
+@section Frozen file format
+
+@cindex frozen file format
+@cindex file format, frozen file
+Frozen files are sharable across architectures.  It is safe to write
+a frozen file on one machine and read it on another, given that the
+second machine uses the same or newer version of GNU @code{m4}.
+It is conventional, but not required, to give a frozen file the suffix
+of @code{.m4f}.
+
+These are simple (editable) text files, made up of directives,
+each starting with a capital letter and ending with a newline
+(@key{NL}).  Wherever a directive is expected, the character
+@samp{#} introduces a comment line; empty lines are also ignored if they
+are not part of an embedded string.
+In the following descriptions, each @var{len} refers to the length of
+the corresponding strings @var{str} in the next line of input.  Numbers
+are always expressed in decimal.  There are no escape characters.  The
+directives are:
+
+@table @code
+@item C @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Uses @var{str1} and @var{str2} as the begin-comment and
+end-comment strings.  If omitted, then @samp{#} and @key{NL} are the
+comment delimiters.
+
+@item D @var{number}, @var{len} @key{NL} @var{str} @key{NL}
+Selects diversion @var{number}, making it current, then copy
+@var{str} in the current diversion.  @var{number} may be a negative
+number for a non-existing diversion.  To merely specify an active
+selection, use this command with an empty @var{str}.  With 0 as the
+diversion @var{number}, @var{str} will be issued on standard output
+at reload time.  GNU @code{m4} will not produce the @samp{D}
+directive with non-zero length for diversion 0, but this can be done
+with manual edits.  This directive may
+appear more than once for the same diversion, in which case the
+diversion is the concatenation of the various uses.  If omitted, then
+diversion 0 is current.
+
+@item F @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Defines, through @code{pushdef}, a definition for @var{str1}
+expanding to the function whose builtin name is @var{str2}.  If the
+builtin does not exist (for example, if the frozen file was produced by
+a copy of @code{m4} compiled with changeword support, but the version
+of @code{m4} reloading was compiled without it), the reload is silent,
+but any subsequent use of the definition of @var{str1} will result in
+a warning.  This directive may appear more than once for the same name,
+and its order, along with @samp{T}, is important.  If omitted, you will
+have no access to any builtins.
+
+@item Q @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Uses @var{str1} and @var{str2} as the begin-quote and end-quote
+strings.  If omitted, then @samp{`} and @samp{'} are the quote
+delimiters.
+
+@item T @var{len1} , @var{len2} @key{NL} @var{str1} @var{str2} @key{NL}
+Defines, though @code{pushdef}, a definition for @var{str1}
+expanding to the text given by @var{str2}.  This directive may appear
+more than once for the same name, and its order, along with @samp{F}, is
+important.
+
+@item V @var{number} @key{NL}
+Confirms the format of the file.  @code{m4} @value{VERSION} only creates
+and understands frozen files where @var{number} is 1.  This directive
+must be the first non-comment in the file, and may not appear more than
+once.
+@end table
+
+@node Compatibility
+@chapter Compatibility with other versions of @code{m4}
+
+@cindex compatibility
+This chapter describes the many of the differences between this
+implementation of @code{m4}, and of other implementations found under
+UNIX, such as System V Release 4, Solaris, and BSD flavors.
+In particular, it lists the known differences and extensions to
+POSIX.  However, the list is not necessarily comprehensive.
+
+At the time of this writing, POSIX 2001 (also known as IEEE
+Std 1003.1-2001) is the latest standard, although a new version of
+POSIX is under development and includes several proposals for
+modifying what @code{m4} is required to do.  The requirements for
+@code{m4} are shared between SUSv3 and POSIX, and
+can be viewed at
+@uref{http://www.opengroup.org/onlinepubs/@/000095399/@/utilities/@/m4.html}.
+
+@menu
+* Extensions::                  Extensions in GNU M4
+* Incompatibilities::           Facilities in System V m4 not in GNU M4
+* Other Incompatibilities::     Other incompatibilities
+@end menu
+
+@node Extensions
+@section Extensions in GNU M4
+
+@cindex GNU extensions
+@cindex POSIX
+This version of @code{m4} contains a few facilities that do not exist
+in System V @code{m4}.  These extra facilities are all suppressed by
+using the @option{-G} command line option (@pxref{Limits control, ,
+Invoking m4}), unless overridden by other command line options.
+
+@itemize @bullet
+@item
+In the @code{$@var{n}} notation for macro arguments, @var{n} can contain
+several digits, while the System V @code{m4} only accepts one digit.
+This allows macros in GNU @code{m4} to take any number of
+arguments, and not only nine (@pxref{Arguments}).
+
+This means that @code{define(`foo', `$11')} is ambiguous between
+implementations.  To portably choose between grabbing the first
+parameter and appending 1 to the expansion, or grabbing the eleventh
+parameter, you can do the following:
+
+@example
+define(`a1', `A1')
+@result{}
+dnl First argument, concatenated with 1
+define(`_1', `$1')define(`first1', `_1($@@)1')
+@result{}
+dnl Eleventh argument, portable
+define(`_9', `$9')define(`eleventh', `_9(shift(shift($@@)))')
+@result{}
+dnl Eleventh argument, GNU style
+define(`Eleventh', `$11')
+@result{}
+first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+@result{}A1
+eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+@result{}k
+Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
+@result{}k
+@end example
+
+@noindent
+Also see the @code{argn} macro (@pxref{Shift}).
+
+@item
+The @code{divert} (@pxref{Divert}) macro can manage more than 9
+diversions.  GNU @code{m4} treats all positive numbers as valid
+diversions, rather than discarding diversions greater than 9.
+
+@item
+Files included with @code{include} and @code{sinclude} are sought in a
+user specified search path, if they are not found in the working
+directory.  The search path is specified by the @option{-I} option and the
+@env{M4PATH} environment variable (@pxref{Search Path}).
+
+@item
+Arguments to @code{undivert} can be non-numeric, in which case the named
+file will be included uninterpreted in the output (@pxref{Undivert}).
+
+@item
+Formatted output is supported through the @code{format} builtin, which
+is modeled after the C library function @code{printf} (@pxref{Format}).
+
+@item
+Searches and text substitution through basic regular expressions are
+supported by the @code{regexp} (@pxref{Regexp}) and @code{patsubst}
+(@pxref{Patsubst}) builtins.  Some BSD implementations use
+extended regular expressions instead.
+
+@item
+The output of shell commands can be read into @code{m4} with
+@code{esyscmd} (@pxref{Esyscmd}).
+
+@item
+There is indirect access to any builtin macro with @code{builtin}
+(@pxref{Builtin}).
+
+@item
+Macros can be called indirectly through @code{indir} (@pxref{Indir}).
+
+@item
+The name of the program, the current input file, and the current input
+line number are accessible through the builtins @code{@w{__program__}},
+@code{@w{__file__}}, and @code{@w{__line__}} (@pxref{Location}).
+
+@item
+The format of the output from @code{dumpdef} and macro tracing can be
+controlled with @code{debugmode} (@pxref{Debug Levels}).
+
+@item
+The destination of trace and debug output can be controlled with
+@code{debugfile} (@pxref{Debug Output}).
+
+@item
+The @code{maketemp} (@pxref{Mkstemp}) macro behaves like @code{mkstemp},
+creating a new file with a unique name on every invocation, rather than
+following the insecure behavior of replacing the trailing @samp{X}
+characters with the @code{m4} process id.
+
+@item
+POSIX only requires support for the command line options
+@option{-s}, @option{-D}, and @option{-U}, so all other options accepted
+by GNU M4 are extensions.  @xref{Invoking m4}, for a
+description of these options.
+
+The debugging and tracing facilities in GNU @code{m4} are much
+more extensive than in most other versions of @code{m4}.
+@end itemize
+
+@node Incompatibilities
+@section Facilities in System V @code{m4} not in GNU @code{m4}
+
+The version of @code{m4} from System V contains a few facilities that
+have not been implemented in GNU @code{m4} yet.  Additionally,
+POSIX requires some behaviors that GNU @code{m4} has not
+implemented yet.  Relying on these behaviors is non-portable, as a
+future release of GNU @code{m4} may change.
+
+@itemize @bullet
+@item
+POSIX requires support for multiple arguments to @code{defn},
+without any clarification on how @code{defn} behaves when one of the
+multiple arguments names a builtin.  System V @code{m4} and some other
+implementations allow mixing builtins and text macros into a single
+macro.  GNU @code{m4} only supports joining multiple text
+arguments, although a future implementation may lift this restriction to
+behave more like System V@.  The only portable way to join text macros
+with builtins is via helper macros and implicit concatenation of macro
+results.
+
+@item
+POSIX requires an application to exit with non-zero status if
+it wrote an error message to stderr.  This has not yet been consistently
+implemented for the various builtins that are required to issue an error
+(such as @code{eval} (@pxref{Eval}) when an argument cannot be parsed).
+
+@item
+Some traditional implementations only allow reading standard input
+once, but GNU @code{m4} correctly handles multiple instances
+of @samp{-} on the command line.
+
+@item
+POSIX requires @code{m4wrap} (@pxref{M4wrap}) to act in FIFO
+(first-in, first-out) order, but GNU @code{m4} currently uses
+LIFO order.  Furthermore, POSIX states that only the first
+argument to @code{m4wrap} is saved for later evaluation, but
+GNU @code{m4} saves and processes all arguments, with output
+separated by spaces.
+
+@item
+POSIX states that builtins that require arguments, but are
+called without arguments, have undefined behavior.  Traditional
+implementations simply behave as though empty strings had been passed.
+For example, @code{a`'define`'b} would expand to @code{ab}.  But
+GNU @code{m4} ignores certain builtins if they have missing
+arguments, giving @code{adefineb} for the above example.
+
+@item
+Traditional implementations handle @code{define(`f',`1')} (@pxref{Define})
+by undefining the entire stack of previous definitions, and if doing
+@code{undefine(`f')} first.  GNU @code{m4} replaces just the top
+definition on the stack, as if doing @code{popdef(`f')} followed by
+@code{pushdef(`f',`1')}.  POSIX allows either behavior.
+
+@item
+POSIX 2001 requires @code{syscmd} (@pxref{Syscmd}) to evaluate
+command output for macro expansion, but this was a mistake that is
+anticipated to be corrected in the next version of POSIX.
+GNU @code{m4} follows traditional behavior in @code{syscmd}
+where output is not rescanned, and provides the extension @code{esyscmd}
+that does scan the output.
+
+@item
+At one point, POSIX required @code{changequote(@var{arg})}
+(@pxref{Changequote}) to use newline as the close quote, but this was a
+bug, and the next version of POSIX is anticipated to state
+that using empty strings or just one argument is unspecified.
+Meanwhile, the GNU @code{m4} behavior of treating an empty
+end-quote delimiter as @samp{'} is not portable, as Solaris treats it as
+repeating the start-quote delimiter, and BSD treats it as leaving the
+previous end-quote delimiter unchanged.  For predictable results, never
+call changequote with just one argument, or with empty strings for
+arguments.
+
+@item
+At one point, POSIX required @code{changecom(@var{arg},)}
+(@pxref{Changecom}) to make it impossible to end a comment, but this is
+a bug, and the next version of POSIX is anticipated to state
+that using empty strings is unspecified.  Meanwhile, the GNU
+@code{m4} behavior of treating an empty end-comment delimiter as newline
+is not portable, as BSD treats it as leaving the previous end-comment
+delimiter unchanged.  It is also impossible in BSD implementations to
+disable comments, even though that is required by POSIX.  For
+predictable results, never call changecom with empty strings for
+arguments.
+
+@item
+Most implementations of @code{m4} give macros a higher precedence than
+comments when parsing, meaning that if the start delimiter given to
+@code{changecom} (@pxref{Changecom}) starts with a macro name, comments
+are effectively disabled.  POSIX does not specify what the
+precedence is, so this version of GNU @code{m4} parser
+recognizes comments, then macros, then quoted strings.
+
+@item
+Traditional implementations allow argument collection, but not string
+and comment processing, to span file boundaries.  Thus, if @file{a.m4}
+contains @samp{len(}, and @file{b.m4} contains @samp{abc)},
+@kbd{m4 a.m4 b.m4} outputs @samp{3} with traditional @code{m4}, but
+gives an error message that the end of file was encountered inside a
+macro with GNU @code{m4}.  On the other hand, traditional
+implementations do end of file processing for files included with
+@code{include} or @code{sinclude} (@pxref{Include}), while GNU
+@code{m4} seamlessly integrates the content of those files.  Thus
+@code{include(`a.m4')include(`b.m4')} will output @samp{3} instead of
+giving an error.
+
+@item
+Traditional @code{m4} treats @code{traceon} (@pxref{Trace}) without
+arguments as a global variable, independent of named macro tracing.
+Also, once a macro is undefined, named tracing of that macro is lost.
+On the other hand, when GNU @code{m4} encounters
+@code{traceon} without
+arguments, it turns tracing on for all existing definitions at the time,
+but does not trace future definitions; @code{traceoff} without arguments
+turns tracing off for all definitions regardless of whether they were
+also traced by name; and tracing by name, such as with @option{-tfoo} at
+the command line or @code{traceon(`foo')} in the input, is an attribute
+that is preserved even if the macro is currently undefined.
+
+Additionally, while POSIX requires trace output, it makes no
+demands on the formatting of that output.  Parsing trace output is not
+guaranteed to be reliable, even between different releases of
+GNU M4; however, the intent is that any future changes in
+trace output will only occur under the direction of additional
+@code{debugmode} flags (@pxref{Debug Levels}).
+
+@item
+POSIX requires @code{eval} (@pxref{Eval}) to treat all
+operators with the same precedence as C@.  However, earlier versions of
+GNU @code{m4} followed the traditional behavior of other
+@code{m4} implementations, where bitwise and logical negation (@samp{~}
+and @samp{!}) have lower precedence than equality operators; and where
+equality operators (@samp{==} and @samp{!=}) had the same precedence as
+relational operators (such as @samp{<}).  Use explicit parentheses to
+ensure proper precedence.  As extensions to POSIX,
+GNU @code{m4} gives well-defined semantics to operations that
+C leaves undefined, such as when overflow occurs, when shifting negative
+numbers, or when performing division by zero.  POSIX also
+requires @samp{=} to cause an error, but many traditional
+implementations allowed it as an alias for @samp{==}.
+
+@item
+POSIX 2001 requires @code{translit} (@pxref{Translit}) to
+treat each character of the second and third arguments literally.
+However, it is anticipated that the next version of POSIX will
+allow the GNU @code{m4} behavior of treating @samp{-} as a
+range operator.
+
+@item
+POSIX requires @code{m4} to honor the locale environment
+variables of @env{LANG}, @env{LC_ALL}, @env{LC_CTYPE},
+@env{LC_MESSAGES}, and @env{NLSPATH}, but this has not yet been
+implemented in GNU @code{m4}.
+
+@item
+POSIX states that only unquoted leading newlines and blanks
+(that is, space and tab) are ignored when collecting macro arguments.
+However, this appears to be a bug in POSIX, since most
+traditional implementations also ignore all whitespace (formfeed,
+carriage return, and vertical tab).  GNU @code{m4} follows
+tradition and ignores all leading unquoted whitespace.
+
+@item
+@cindex @env{POSIXLY_CORRECT}
+A strictly-compliant POSIX client is not allowed to use
+command-line arguments not specified by POSIX.  However, since
+this version of M4 ignores @env{POSIXLY_CORRECT} and enables the option
+@code{--gnu} by default (@pxref{Limits control, , Invoking m4}), a
+client desiring to be strictly compliant has no way to disable
+GNU extensions that conflict with POSIX when
+directly invoking the compiled @code{m4}.  A future version of
+@code{GNU} M4 will honor the environment variable @env{POSIXLY_CORRECT},
+implicitly enabling @option{--traditional} if it is set, in order to
+allow a strictly-compliant client.  In the meantime, a client needing
+strict POSIX compliance can use the workaround of invoking a
+shell script wrapper, where the wrapper then adds @option{--traditional}
+to the arguments passed to the compiled @code{m4}.
+@end itemize
+
+@node Other Incompatibilities
+@section Other incompatibilities
+
+There are a few other incompatibilities between this implementation of
+@code{m4}, and the System V version.
+
+@itemize @bullet
+@item
+GNU @code{m4} implements sync lines differently from System V
+@code{m4}, when text is being diverted.  GNU @code{m4} outputs
+the sync lines when the text is being diverted, and System V @code{m4}
+when the diverted text is being brought back.
+
+The problem is which lines and file names should be attached to text
+that is being, or has been, diverted.  System V @code{m4} regards all
+the diverted text as being generated by the source line containing the
+@code{undivert} call, whereas GNU @code{m4} regards the
+diverted text as being generated at the time it is diverted.
+
+The sync line option is used mostly when using @code{m4} as
+a front end to a compiler.  If a diverted line causes a compiler error,
+the error messages should most probably refer to the place where the
+diversion was made, and not where it was inserted again.
+
+@comment options: -s
+@example
+divert(2)2
+divert(1)1
+divert`'0
+@result{}#line 3 "stdin"
+@result{}0
+^D
+@result{}#line 2 "stdin"
+@result{}1
+@result{}#line 1 "stdin"
+@result{}2
+@end example
+
+The current @code{m4} implementation has a limitation that the syncline
+output at the start of each diversion occurs no matter what, even if the
+previous diversion did not end with a newline.  This goes contrary to
+the claim that synclines appear on a line by themselves, so this
+limitation may be corrected in a future version of @code{m4}.  In the
+meantime, when using @option{-s}, it is wisest to make sure all
+diversions end with newline.
+
+@item
+GNU @code{m4} makes no attempt at prohibiting self-referential
+definitions like:
+
+@example
+define(`x', `x')
+@result{}
+define(`x', `x ')
+@result{}
+@end example
+
+@cindex rescanning
+There is nothing inherently wrong with defining @samp{x} to
+return @samp{x}.  The wrong thing is to expand @samp{x} unquoted,
+because that would cause an infinite rescan loop.
+In @code{m4}, one might use macros to hold strings, as we do for
+variables in other programming languages, further checking them with:
+
+@comment ignore
+@example
+ifelse(defn(`@var{holder}'), `@var{value}', @dots{})
+@end example
+
+@noindent
+In cases like this one, an interdiction for a macro to hold its own name
+would be a useless limitation.  Of course, this leaves more rope for the
+GNU @code{m4} user to hang himself!  Rescanning hangs may be
+avoided through careful programming, a little like for endless loops in
+traditional programming languages.
+@end itemize
+
+@node Answers
+@chapter Correct version of some examples
+
+Some of the examples in this manuals are buggy or not very robust, for
+demonstration purposes.  Improved versions of these composite macros are
+presented here.
+
+@menu
+* Improved exch::               Solution for @code{exch}
+* Improved forloop::            Solution for @code{forloop}
+* Improved foreach::            Solution for @code{foreach}
+* Improved copy::               Solution for @code{copy}
+* Improved m4wrap::             Solution for @code{m4wrap}
+* Improved cleardivert::        Solution for @code{cleardivert}
+* Improved capitalize::         Solution for @code{capitalize}
+* Improved fatal_error::        Solution for @code{fatal_error}
+@end menu
+
+@node Improved exch
+@section Solution for @code{exch}
+
+The @code{exch} macro (@pxref{Arguments}) as presented requires clients
+to double quote their arguments.  A nicer definition, which lets
+clients follow the rule of thumb of one level of quoting per level of
+parentheses, involves adding quotes in the definition of @code{exch}, as
+follows:
+
+@example
+define(`exch', ``$2', `$1'')
+@result{}
+define(exch(`expansion text', `macro'))
+@result{}
+macro
+@result{}expansion text
+@end example
+
+@node Improved forloop
+@section Solution for @code{forloop}
+
+The @code{forloop} macro (@pxref{Forloop}) as presented earlier can go
+into an infinite loop if given an iterator that is not parsed as a macro
+name.  It does not do any sanity checking on its numeric bounds, and
+only permits decimal numbers for bounds.  Here is an improved version,
+shipped as @file{m4-@value{VERSION}/@/examples/@/forloop2.m4}; this
+version also optimizes overhead by calling four macros instead of six
+per iteration (excluding those in @var{text}), by not dereferencing the
+@var{iterator} in the helper @code{@w{_forloop}}.
+
+@comment examples
+@example
+$ @kbd{m4 -d -I examples}
+undivert(`forloop2.m4')dnl
+@result{}divert(`-1')
+@result{}# forloop(var, from, to, stmt) - improved version:
+@result{}#   works even if VAR is not a strict macro name
+@result{}#   performs sanity check that FROM is larger than TO
+@result{}#   allows complex numerical expressions in TO and FROM
+@result{}define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
+@result{}  `pushdef(`$1')_$0(`$1', eval(`$2'),
+@result{}    eval(`$3'), `$4')popdef(`$1')')')
+@result{}define(`_forloop',
+@result{}  `define(`$1', `$2')$4`'ifelse(`$2', `$3', `',
+@result{}    `$0(`$1', incr(`$2'), `$3', `$4')')')
+@result{}divert`'dnl
+include(`forloop2.m4')
+@result{}
+forloop(`i', `2', `1', `no iteration occurs')
+@result{}
+forloop(`', `1', `2', ` odd iterator name')
+@result{} odd iterator name odd iterator name
+forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')')
+@result{} 0xa 0xb 0xc
+forloop(`i', `a', `b', `non-numeric bounds')
+@error{}m4:stdin:6: bad expression in eval (bad input): (a) <= (b)
+@result{}
+@end example
+
+One other change to notice is that the improved version used @samp{_$0}
+rather than @samp{_foreach} to invoke the helper routine.  In general,
+this is a good practice to follow, because then the set of macros can be
+uniformly transformed.  The following example shows a transformation
+that doubles the current quoting and appends a suffix @samp{2} to each
+transformed macro.  If @code{foreach} refers to the literal
+@samp{_foreach}, then @code{foreach2} invokes @code{_foreach} instead of
+the intended @code{_foreach2}, and the mixing of quoting paradigms leads
+to an infinite recursion loop in this example.
+
+@comment options: -L9
+@comment status: 1
+@comment examples
+@example
+$ @kbd{m4 -d -L 9 -I examples}
+define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4')
+@result{}
+define(`double', `define(`$1'`2',
+  arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))')
+@result{}
+double(`forloop')double(`_forloop')defn(`forloop2')
+@result{}ifelse(eval(``($2) <= ($3)''), ``1'',
+@result{}  ``pushdef(``$1'')_$0(``$1'', eval(``$2''),
+@result{}    eval(``$3''), ``$4'')popdef(``$1'')'')
+forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
+@result{}
+changequote(`[', `]')changequote([``], [''])
+@result{}
+forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
+@result{}
+changequote`'include(`forloop.m4')
+@result{}
+double(`forloop')double(`_forloop')defn(`forloop2')
+@result{}pushdef(``$1'', ``$2'')_forloop($@@)popdef(``$1'')
+forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
+@result{}
+changequote(`[', `]')changequote([``], [''])
+@result{}
+forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
+@error{}m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it
+@end example
+
+One more optimization is still possible.  Instead of repeatedly
+assigning a variable then invoking or dereferencing it, it is possible
+to pass the current iterator value as a single argument.  Coupled with
+@code{curry} if other arguments are needed (@pxref{Composition}), or
+with helper macros if the argument is needed in more than one place in
+the expansion, the output can be generated with three, rather than four,
+macros of overhead per iteration.  Notice how the file
+@file{m4-@value{VERSION}/@/examples/@/forloop3.m4} rearranges the
+arguments of the helper @code{_forloop} to take two arguments that are
+placed around the current value.  By splitting a balanced set of
+parantheses across multiple arguments, the helper macro can now be
+shared by @code{forloop} and the new @code{forloop_arg}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`forloop3.m4')
+@result{}
+undivert(`forloop3.m4')dnl
+@result{}divert(`-1')
+@result{}# forloop_arg(from, to, macro) - invoke MACRO(value) for
+@result{}#   each value between FROM and TO, without define overhead
+@result{}define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1',
+@result{}  `_forloop(`$1', eval(`$2'), `$3(', `)')')')
+@result{}# forloop(var, from, to, stmt) - refactored to share code
+@result{}define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
+@result{}  `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'),
+@result{}    `define(`$1',', `)$4')popdef(`$1')')')
+@result{}define(`_forloop',
+@result{}  `$3`$1'$4`'ifelse(`$1', `$2', `',
+@result{}    `$0(incr(`$1'), `$2', `$3', `$4')')')
+@result{}divert`'dnl
+forloop(`i', `1', `3', ` i')
+@result{} 1 2 3
+define(`echo', `$@@')
+@result{}
+forloop_arg(`1', `3', ` echo')
+@result{} 1 2 3
+include(`curry.m4')
+@result{}
+forloop_arg(`1', `3', `curry(`pushdef', `a')')
+@result{}
+a
+@result{}3
+popdef(`a')a
+@result{}2
+popdef(`a')a
+@result{}1
+popdef(`a')a
+@result{}a
+@end example
+
+Of course, it is possible to make even more improvements, such as
+adding an optional step argument, or allowing iteration through
+descending sequences.  GNU Autoconf provides some of these
+additional bells and whistles in its @code{m4_for} macro.
+
+@node Improved foreach
+@section Solution for @code{foreach}
+
+The @code{foreach} and @code{foreachq} macros (@pxref{Foreach}) as
+presented earlier each have flaws.  First, we will examine and fix the
+quadratic behavior of @code{foreachq}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreachq.m4')
+@result{}
+traceon(`shift')debugmode(`aq')
+@result{}
+foreachq(`x', ``1', `2', `3', `4'', `x
+')dnl
+@result{}1
+@error{}m4trace: -3- shift(`1', `2', `3', `4')
+@error{}m4trace: -2- shift(`1', `2', `3', `4')
+@result{}2
+@error{}m4trace: -4- shift(`1', `2', `3', `4')
+@error{}m4trace: -3- shift(`2', `3', `4')
+@error{}m4trace: -3- shift(`1', `2', `3', `4')
+@error{}m4trace: -2- shift(`2', `3', `4')
+@result{}3
+@error{}m4trace: -5- shift(`1', `2', `3', `4')
+@error{}m4trace: -4- shift(`2', `3', `4')
+@error{}m4trace: -3- shift(`3', `4')
+@error{}m4trace: -4- shift(`1', `2', `3', `4')
+@error{}m4trace: -3- shift(`2', `3', `4')
+@error{}m4trace: -2- shift(`3', `4')
+@result{}4
+@error{}m4trace: -6- shift(`1', `2', `3', `4')
+@error{}m4trace: -5- shift(`2', `3', `4')
+@error{}m4trace: -4- shift(`3', `4')
+@error{}m4trace: -3- shift(`4')
+@end example
+
+@cindex quadratic behavior, avoiding
+@cindex avoiding quadratic behavior
+Each successive iteration was adding more quoted @code{shift}
+invocations, and the entire list contents were passing through every
+iteration.  In general, when recursing, it is a good idea to make the
+recursion use fewer arguments, rather than adding additional quoted
+uses of @code{shift}.  By doing so, @code{m4} uses less memory, invokes
+fewer macros, is less likely to run into machine limits, and most
+importantly, performs faster.  The fixed version of @code{foreachq} can
+be found in @file{m4-@value{VERSION}/@/examples/@/foreachq2.m4}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreachq2.m4')
+@result{}
+undivert(`foreachq2.m4')dnl
+@result{}include(`quote.m4')dnl
+@result{}divert(`-1')
+@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt)
+@result{}#   quoted list, improved version
+@result{}define(`foreachq', `pushdef(`$1')_$0($@@)popdef(`$1')')
+@result{}define(`_arg1q', ``$1'')
+@result{}define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@@))')')
+@result{}define(`_foreachq', `ifelse(`$2', `', `',
+@result{}  `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')')
+@result{}divert`'dnl
+traceon(`shift')debugmode(`aq')
+@result{}
+foreachq(`x', ``1', `2', `3', `4'', `x
+')dnl
+@result{}1
+@error{}m4trace: -3- shift(`1', `2', `3', `4')
+@result{}2
+@error{}m4trace: -3- shift(`2', `3', `4')
+@result{}3
+@error{}m4trace: -3- shift(`3', `4')
+@result{}4
+@end example
+
+Note that the fixed version calls unquoted helper macros in
+@code{@w{_foreachq}} to trim elements immediately; those helper macros
+in turn must re-supply the layer of quotes lost in the macro invocation.
+Contrast the use of @code{@w{_arg1q}}, which quotes the first list
+element, with @code{@w{_arg1}} of the earlier implementation that
+returned the first list element directly.  Additionally, by calling the
+helper method immediately, the @samp{defn(`@var{iterator}')} no longer
+contains unexpanded macros.
+
+The astute m4 programmer might notice that the solution above still uses
+more memory and macro invocations, and thus more time, than strictly
+necessary.  Note that @samp{$2}, which contains an arbitrarily long
+quoted list, is expanded and rescanned three times per iteration of
+@code{_foreachq}. Furthermore, every iteration of the algorithm
+effectively unboxes then reboxes the list, which costs a couple of macro
+invocations.  It is possible to rewrite the algorithm for a bit more
+speed by swapping the order of the arguments to @code{_foreachq} in
+order to operate on an unboxed list in the first place, and by using the
+fixed-length @samp{$#} instead of an arbitrary length list as the key to
+end recursion.  The result is an overhead of six macro invocations per
+loop (excluding any macros in @var{text}), instead of eight.  This
+alternative approach is available as
+@file{m4-@value{VERSION}/@/examples/@/foreach3.m4}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreachq3.m4')
+@result{}
+undivert(`foreachq3.m4')dnl
+@result{}divert(`-1')
+@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt)
+@result{}#   quoted list, alternate improved version
+@result{}define(`foreachq', `ifelse(`$2', `', `',
+@result{}  `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')')
+@result{}define(`_foreachq', `ifelse(`$#', `3', `',
+@result{}  `define(`$1', `$4')$2`'$0(`$1', `$2',
+@result{}    shift(shift(shift($@@))))')')
+@result{}divert`'dnl
+traceon(`shift')debugmode(`aq')
+@result{}
+foreachq(`x', ``1', `2', `3', `4'', `x
+')dnl
+@result{}1
+@error{}m4trace: -4- shift(`x', `x
+@error{}', `', `1', `2', `3', `4')
+@error{}m4trace: -3- shift(`x
+@error{}', `', `1', `2', `3', `4')
+@error{}m4trace: -2- shift(`', `1', `2', `3', `4')
+@result{}2
+@error{}m4trace: -4- shift(`x', `x
+@error{}', `1', `2', `3', `4')
+@error{}m4trace: -3- shift(`x
+@error{}', `1', `2', `3', `4')
+@error{}m4trace: -2- shift(`1', `2', `3', `4')
+@result{}3
+@error{}m4trace: -4- shift(`x', `x
+@error{}', `2', `3', `4')
+@error{}m4trace: -3- shift(`x
+@error{}', `2', `3', `4')
+@error{}m4trace: -2- shift(`2', `3', `4')
+@result{}4
+@error{}m4trace: -4- shift(`x', `x
+@error{}', `3', `4')
+@error{}m4trace: -3- shift(`x
+@error{}', `3', `4')
+@error{}m4trace: -2- shift(`3', `4')
+@end example
+
+In the current version of M4, every instance of @samp{$@@} is rescanned
+as it is encountered.  Thus, the @file{foreachq3.m4} alternative uses
+much less memory than @file{foreachq2.m4}, and executes as much as 10%
+faster, since each iteration encounters fewer @samp{$@@}.  However, the
+implementation of rescanning every byte in @samp{$@@} is quadratic in
+the number of bytes scanned (for example, making the broken version in
+@file{foreachq.m4} cubic, rather than quadratic, in behavior).  A future
+release of M4 will improve the underlying implementation by reusing
+results of previous scans, so that both styles of @code{foreachq} can
+become linear in the number of bytes scanned.  Notice how the
+implementation injects an empty argument prior to expanding @samp{$2}
+within @code{foreachq}; the helper macro @code{_foreachq} then ignores
+the third argument altogether, and ends recursion when there are three
+arguments left because there was nothing left to pass through
+@code{shift}.  Thus, each iteration only needs one @code{ifelse}, rather
+than the two conditionals used in the version from @file{foreachq2.m4}.
+
+@cindex nine arguments, more than
+@cindex more than nine arguments
+@cindex arguments, more than nine
+So far, all of the implementations of @code{foreachq} presented have
+been quadratic with M4 1.4.x.  But @code{forloop} is linear, because
+each iteration parses a constant amount of arguments.  So, it is
+possible to design a variant that uses @code{forloop} to do the
+iteration, then uses @samp{$@@} only once at the end, giving a linear
+result even with older M4 implementations.  This implementation relies
+on the GNU extension that @samp{$10} expands to the tenth
+argument rather than the first argument concatenated with @samp{0}.  The
+trick is to define an intermediate macro that repeats the text
+@code{m4_define(`$1', `$@var{n}')$2`'}, with @samp{n} set to successive
+integers corresponding to each argument.  The helper macro
+@code{_foreachq_} is needed in order to generate the literal sequences
+such as @samp{$1} into the intermediate macro, rather than expanding
+them as the arguments of @code{_foreachq}.  With this approach, no
+@code{shift} calls are even needed!  Even though there are seven macros
+of overhead per iteration instead of six in @file{foreachq3.m4}, the
+linear scaling is apparent at relatively small list sizes.  However,
+this approach will need adjustment when a future version of M4 follows
+POSIX by no longer treating @samp{$10} as the tenth argument;
+the anticipation is that @samp{$@{10@}} can be used instead, although
+that alternative syntax is not yet supported.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreachq4.m4')
+@result{}
+undivert(`foreachq4.m4')dnl
+@result{}include(`forloop2.m4')dnl
+@result{}divert(`-1')
+@result{}# foreachq(x, `item_1, item_2, ..., item_n', stmt)
+@result{}#   quoted list, version based on forloop
+@result{}define(`foreachq',
+@result{}`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')')
+@result{}define(`_foreachq',
+@result{}`pushdef(`$1', forloop(`$1', `3', `$#',
+@result{}  `$0_(`1', `2', indir(`$1'))')`popdef(
+@result{}    `$1')')indir(`$1', $@@)')
+@result{}define(`_foreachq_',
+@result{}``define(`$$1', `$$3')$$2`''')
+@result{}divert`'dnl
+traceon(`shift')debugmode(`aq')
+@result{}
+foreachq(`x', ``1', `2', `3', `4'', `x
+')dnl
+@result{}1
+@result{}2
+@result{}3
+@result{}4
+@end example
+
+For yet another approach, the improved version of @code{foreach},
+available in @file{m4-@value{VERSION}/@/examples/@/foreach2.m4}, simply
+overquotes the arguments to @code{@w{_foreach}} to begin with, using
+@code{dquote_elt}.  Then @code{@w{_foreach}} can just use
+@code{@w{_arg1}} to remove the extra layer of quoting that was added up
+front:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreach2.m4')
+@result{}
+undivert(`foreach2.m4')dnl
+@result{}include(`quote.m4')dnl
+@result{}divert(`-1')
+@result{}# foreach(x, (item_1, item_2, ..., item_n), stmt)
+@result{}#   parenthesized list, improved version
+@result{}define(`foreach', `pushdef(`$1')_$0(`$1',
+@result{}  (dquote(dquote_elt$2)), `$3')popdef(`$1')')
+@result{}define(`_arg1', `$1')
+@result{}define(`_foreach', `ifelse(`$2', `(`')', `',
+@result{}  `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')')
+@result{}divert`'dnl
+traceon(`shift')debugmode(`aq')
+@result{}
+foreach(`x', `(`1', `2', `3', `4')', `x
+')dnl
+@error{}m4trace: -4- shift(`1', `2', `3', `4')
+@error{}m4trace: -4- shift(`2', `3', `4')
+@error{}m4trace: -4- shift(`3', `4')
+@result{}1
+@error{}m4trace: -3- shift(``1'', ``2'', ``3'', ``4'')
+@result{}2
+@error{}m4trace: -3- shift(``2'', ``3'', ``4'')
+@result{}3
+@error{}m4trace: -3- shift(``3'', ``4'')
+@result{}4
+@error{}m4trace: -3- shift(``4'')
+@end example
+
+It is likewise possible to write a variant of @code{foreach} that
+performs in linear time on M4 1.4.x; the easiest method is probably
+writing a version of @code{foreach} that unboxes its list, then invokes
+@code{_foreachq} as previously defined in @file{foreachq4.m4}.
+
+In summary, recursion over list elements is trickier than it appeared at
+first glance, but provides a powerful idiom within @code{m4} processing.
+As a final demonstration, both list styles are now able to handle
+several scenarios that would wreak havoc on one or both of the original
+implementations.  This points out one other difference between the
+list styles.  @code{foreach} evaluates unquoted list elements only once,
+in preparation for calling @code{@w{_foreach}}, similary for
+@code{foreachq} as provided by @file{foreachq3.m4} or
+@file{foreachq4.m4}.  But
+@code{foreachq}, as provided by @file{foreachq2.m4},
+evaluates unquoted list elements twice while visiting the first list
+element, once in @code{@w{_arg1q}} and once in @code{@w{_rest}}.  When
+deciding which list style to use, one must take into account whether
+repeating the side effects of unquoted list elements will have any
+detrimental effects.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`foreach2.m4')
+@result{}
+include(`foreachq2.m4')
+@result{}
+dnl 0-element list:
+foreach(`x', `', `<x>') / foreachq(`x', `', `<x>')
+@result{} /@w{ }
+dnl 1-element list of empty element
+foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>')
+@result{}<> / <>
+dnl 2-element list of empty elements
+foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>')
+@result{}<><> / <><>
+dnl 1-element list of a comma
+foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>')
+@result{}<,> / <,>
+dnl 2-element list of unbalanced parentheses
+foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
+@result{}<(><)> / <(><)>
+define(`ab', `oops')dnl using defn(`iterator')
+foreach(`x', `(`a', `b')', `defn(`x')') /dnl
+ foreachq(`x', ``a', `b'', `defn(`x')')
+@result{}ab / ab
+define(`active', `ACT, IVE')
+@result{}
+traceon(`active')
+@result{}
+dnl list of unquoted macros; expansion occurs before recursion
+foreach(`x', `(active, active)', `<x>
+')dnl
+@error{}m4trace: -4- active -> `ACT, IVE'
+@error{}m4trace: -4- active -> `ACT, IVE'
+@result{}<ACT>
+@result{}<IVE>
+@result{}<ACT>
+@result{}<IVE>
+foreachq(`x', `active, active', `<x>
+')dnl
+@error{}m4trace: -3- active -> `ACT, IVE'
+@error{}m4trace: -3- active -> `ACT, IVE'
+@result{}<ACT>
+@error{}m4trace: -3- active -> `ACT, IVE'
+@error{}m4trace: -3- active -> `ACT, IVE'
+@result{}<IVE>
+@result{}<ACT>
+@result{}<IVE>
+dnl list of quoted macros; expansion occurs during recursion
+foreach(`x', `(`active', `active')', `<x>
+')dnl
+@error{}m4trace: -1- active -> `ACT, IVE'
+@result{}<ACT, IVE>
+@error{}m4trace: -1- active -> `ACT, IVE'
+@result{}<ACT, IVE>
+foreachq(`x', ``active', `active'', `<x>
+')dnl
+@error{}m4trace: -1- active -> `ACT, IVE'
+@result{}<ACT, IVE>
+@error{}m4trace: -1- active -> `ACT, IVE'
+@result{}<ACT, IVE>
+dnl list of double-quoted macro names; no expansion
+foreach(`x', `(``active'', ``active'')', `<x>
+')dnl
+@result{}<active>
+@result{}<active>
+foreachq(`x', ```active'', ``active''', `<x>
+')dnl
+@result{}<active>
+@result{}<active>
+@end example
+
+@ignore
+@comment Not worth putting in the manual, but make sure that foreach
+@comment implementations behave, and that final implementation is
+@comment linear.
+
+@comment boxed recursion
+
+@comment examples
+@comment options: -Dlimit=10 -Dverbose
+@example
+$ @kbd {m4 -I examples -Dlimit=10 -Dverbose}
+include(`loop.m4')dnl
+@result{} 1 2 3 4 5 6 7 8 9 10
+@end example
+
+@comment unboxed recursion
+
+@comment examples
+@comment options: -Dlimit=10 -Dverbose -Dalt
+@example
+$ @kbd {m4 -I examples -Dlimit=10 -Dverbose -Dalt}
+include(`loop.m4')dnl
+@result{} 1 2 3 4 5 6 7 8 9 10
+@end example
+
+@comment foreach via forloop recursion
+
+@comment examples
+@comment options: -Dlimit=10 -Dverbose -Dalt=4
+@example
+$ @kbd {m4 -I examples -Dlimit=10 -Dverbose -Dalt=4}
+include(`loop.m4')dnl
+@result{} 1 2 3 4 5 6 7 8 9 10
+@end example
+
+@comment examples
+@comment options: -Dlimit=2500 -Dalt=4
+@example
+$ @kbd {m4 -I examples -Dlimit=2500 -Dalt=4}
+include(`loop.m4')dnl
+@end example
+
+@comment examples
+@comment options: -Dlimit=10000 -Dalt=4
+@example
+$ @kbd {m4 -I examples -Dlimit=10000 -Dalt=4}
+define(`foo', `divert`'len(popdef(`_foreachq')_foreachq($@@))')dnl
+define(`debug', `pushdef(`_foreachq', defn(`foo'))')
+@result{}
+include(`loop.m4')dnl
+@result{}48894
+@end example
+
+@end ignore
+
+@node Improved copy
+@section Solution for @code{copy}
+
+The macro @code{copy} presented above
+is unable to handle builtin tokens with M4 1.4.x, because it tries to
+pass the builtin token through the macro @code{curry}, where it is
+silently flattened to an empty string (@pxref{Composition}).  Rather
+than using the problematic @code{curry} to work around the limitation
+that @code{stack_foreach} expects to invoke a macro that takes exactly
+one argument, we can write a new macro that lets us form the exact
+two-argument @code{pushdef} call sequence needed, so that we are no
+longer passing a builtin token through a text macro.
+
+@deffn Composite stack_foreach_sep (@var{macro}, @var{pre}, @var{post}, @
+  @var{sep})
+@deffnx Composite stack_foreach_sep_lifo (@var{macro}, @var{pre}, @
+  @var{post}, @var{sep})
+For each of the @code{pushdef} definitions associated with @var{macro},
+expand the sequence @samp{@var{pre}`'definition`'@var{post}}.
+Additionally, expand @var{sep} between definitions.
+@code{stack_foreach_sep} visits the oldest definition first, while
+@code{stack_foreach_sep_lifo} visits the current definition first.  The
+expansion may dereference @var{macro}, but should not modify it.  There
+are a few special macros, such as @code{defn}, which cannot be used as
+the @var{macro} parameter.
+@end deffn
+
+Note that @code{stack_foreach(`@var{macro}', `@var{action}')} is
+equivalent to @code{stack_foreach_sep(`@var{macro}', `@var{action}(',
+`)')}.  By supplying explicit parentheses, split among the @var{pre} and
+@var{post} arguments to @code{stack_foreach_sep}, it is now possible to
+construct macro calls with more than one argument, without passing
+builtin tokens through a macro call.  It is likewise possible to
+directly reference the stack definitions without a macro call, by
+leaving @var{pre} and @var{post} empty.  Thus, in addition to fixing
+@code{copy} on builtin tokens, it also executes with fewer macro
+invocations.
+
+The new macro also adds a separator that is only output after the first
+iteration of the helper @code{_stack_reverse_sep}, implemented by
+prepending the original @var{sep} to @var{pre} and omitting a @var{sep}
+argument in subsequent iterations.  Note that the empty string that
+separates @var{sep} from @var{pre} is provided as part of the fourth
+argument when originally calling @code{_stack_reverse_sep}, and not by
+writing @code{$4`'$3} as the third argument in the recursive call; while
+the other approach would give the same output, it does so at the expense
+of increasing the argument size on each iteration of
+@code{_stack_reverse_sep}, which results in quadratic instead of linear
+execution time.  The improved stack walking macros are available in
+@file{m4-@value{VERSION}/@/examples/@/stack_sep.m4}:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`stack_sep.m4')
+@result{}
+define(`copy', `ifdef(`$2', `errprint(`$2 already defined
+')m4exit(`1')',
+   `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl
+pushdef(`a', `1')pushdef(`a', defn(`divnum'))
+@result{}
+copy(`a', `b')
+@result{}
+b
+@result{}0
+popdef(`b')
+@result{}
+b
+@result{}1
+pushdef(`c', `1')pushdef(`c', `2')
+@result{}
+stack_foreach_sep_lifo(`c', `', `', `, ')
+@result{}2, 1
+undivert(`stack_sep.m4')dnl
+@result{}divert(`-1')
+@result{}# stack_foreach_sep(macro, pre, post, sep)
+@result{}# Invoke PRE`'defn`'POST with a single argument of each definition
+@result{}# from the definition stack of MACRO, starting with the oldest, and
+@result{}# separated by SEP between definitions.
+@result{}define(`stack_foreach_sep',
+@result{}`_stack_reverse_sep(`$1', `tmp-$1')'dnl
+@result{}`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')')
+@result{}# stack_foreach_sep_lifo(macro, pre, post, sep)
+@result{}# Like stack_foreach_sep, but starting with the newest definition.
+@result{}define(`stack_foreach_sep_lifo',
+@result{}`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl
+@result{}`_stack_reverse_sep(`tmp-$1', `$1')')
+@result{}define(`_stack_reverse_sep',
+@result{}`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0(
+@result{}  `$1', `$2', `$4$3')')')
+@result{}divert`'dnl
+@end example
+
+@ignore
+@comment Not worth putting in the manual, but make sure that
+@comment stack_foreach_sep has linear performance.
+
+@comment examples
+@example
+$ @kbd {m4 -I examples}
+include(`forloop3.m4')include(`stack_sep.m4')dnl
+forloop(`i', `1', `10000', `pushdef(`s', i)')
+@result{}
+define(`colon', `:')define(`dash', `-')
+@result{}
+len(stack_foreach_sep(`s', `dash', `', `colon'))
+@result{}58893
+@end example
+@end ignore
+
+@node Improved m4wrap
+@section Solution for @code{m4wrap}
+
+The replacement @code{m4wrap} versions presented above, designed to
+guarantee FIFO or LIFO order regardless of the underlying M4
+implementation, share a bug when dealing with wrapped text that looks
+like parameter expansion.  Note how the invocation of
+@code{m4wrap@var{n}} interprets these parameters, while using the
+builtin preserves them for their intended use.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`wraplifo.m4')
+@result{}
+m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
+')
+@result{}
+builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b')
+')
+@result{}
+^D
+@result{}bar:-a-a,b-2-
+@result{}m4wrap0:---0-
+@end example
+
+Additionally, the computation of @code{_m4wrap_level} and creation of
+multiple @code{m4wrap@var{n}} placeholders in the original examples is
+more expensive in time and memory than strictly necessary.  Notice how
+the improved version grabs the wrapped text via @code{defn} to avoid
+parameter expansion, then undefines @code{_m4wrap_text}, before
+stripping a level of quotes with @code{_arg1} to expand the text.  That
+way, each level of wrapping reuses the single placeholder, which starts
+each nesting level in an undefined state.
+
+Finally, it is worth emulating the GNU M4 extension of saving
+all arguments to @code{m4wrap}, separated by a space, rather than saving
+just the first argument.  This is done with the @code{join} macro
+documented previously (@pxref{Shift}).  The improved LIFO example is
+shipped as @file{m4-@value{VERSION}/@/examples/@/wraplifo2.m4}, and can
+easily be converted to a FIFO solution by swapping the adjacent
+invocations of @code{joinall} and @code{defn}.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`wraplifo2.m4')
+@result{}
+undivert(`wraplifo2.m4')dnl
+@result{}dnl Redefine m4wrap to have LIFO semantics, improved example.
+@result{}include(`join.m4')dnl
+@result{}define(`_m4wrap', defn(`m4wrap'))dnl
+@result{}define(`_arg1', `$1')dnl
+@result{}define(`m4wrap',
+@result{}`ifdef(`_$0_text',
+@result{}       `define(`_$0_text', joinall(` ', $@@)defn(`_$0_text'))',
+@result{}       `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl
+@result{}define(`_$0_text', joinall(` ', $@@))')')dnl
+m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
+')
+@result{}
+m4wrap(`lifo text
+m4wrap(`nested', `', `$@@
+')')
+@result{}
+^D
+@result{}lifo text
+@result{}foo:-a-a,b-2-
+@result{}nested  $@@
+@end example
+
+@node Improved cleardivert
+@section Solution for @code{cleardivert}
+
+The @code{cleardivert} macro (@pxref{Cleardivert}) cannot, as it stands, be
+called without arguments to clear all pending diversions.  That is
+because using undivert with an empty string for an argument is different
+than using it with no arguments at all.  Compare the earlier definition
+with one that takes the number of arguments into account:
+
+@example
+define(`cleardivert',
+  `pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
+@result{}
+divert(`1')one
+divert
+@result{}
+cleardivert
+@result{}
+undivert
+@result{}one
+@result{}
+define(`cleardivert',
+  `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
+    `undivert`'', `undivert($@@)')divert(_num)popdef(`_num')')
+@result{}
+divert(`2')two
+divert
+@result{}
+cleardivert
+@result{}
+undivert
+@result{}
+@end example
+
+@node Improved capitalize
+@section Solution for @code{capitalize}
+
+The @code{capitalize} macro (@pxref{Patsubst}) as presented earlier does
+not allow clients to follow the quoting rule of thumb.  Consider the
+three macros @code{active}, @code{Active}, and @code{ACTIVE}, and the
+difference between calling @code{capitalize} with the expansion of a
+macro, expanding the result of a case change, and changing the case of a
+double-quoted string:
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`capitalize.m4')dnl
+define(`active', `act1, ive')dnl
+define(`Active', `Act2, Ive')dnl
+define(`ACTIVE', `ACT3, IVE')dnl
+upcase(active)
+@result{}ACT1,IVE
+upcase(`active')
+@result{}ACT3, IVE
+upcase(``active'')
+@result{}ACTIVE
+downcase(ACTIVE)
+@result{}act3,ive
+downcase(`ACTIVE')
+@result{}act1, ive
+downcase(``ACTIVE'')
+@result{}active
+capitalize(active)
+@result{}Act1
+capitalize(`active')
+@result{}Active
+capitalize(``active'')
+@result{}_capitalize(`active')
+define(`A', `OOPS')
+@result{}
+capitalize(active)
+@result{}OOPSct1
+capitalize(`active')
+@result{}OOPSctive
+@end example
+
+First, when @code{capitalize} is called with more than one argument, it
+was throwing away later arguments, whereas @code{upcase} and
+@code{downcase} used @samp{$*} to collect them all.  The fix is simple:
+use @samp{$*} consistently.
+
+Next, with single-quoting, @code{capitalize} outputs a single character,
+a set of quotes, then the rest of the characters, making it impossible
+to invoke @code{Active} after the fact, and allowing the alternate macro
+@code{A} to interfere.  Here, the solution is to use additional quoting
+in the helper macros, then pass the final over-quoted output string
+through @code{_arg1} to remove the extra quoting and finally invoke the
+concatenated portions as a single string.
+
+Finally, when passed a double-quoted string, the nested macro
+@code{_capitalize} is never invoked because it ended up nested inside
+quotes.  This one is the toughest to fix.  In short, we have no idea how
+many levels of quotes are in effect on the substring being altered by
+@code{patsubst}.  If the replacement string cannot be expressed entirely
+in terms of literal text and backslash substitutions, then we need a
+mechanism to guarantee that the helper macros are invoked outside of
+quotes.  In other words, this sounds like a job for @code{changequote}
+(@pxref{Changequote}).  By changing the active quoting characters, we
+can guarantee that replacement text injected by @code{patsubst} always
+occurs in the middle of a string that has exactly one level of
+over-quoting using alternate quotes; so the replacement text closes the
+quoted string, invokes the helper macros, then reopens the quoted
+string.  In turn, that means the replacement text has unbalanced quotes,
+necessitating another round of @code{changequote}.
+
+In the fixed version below, (also shipped as
+@file{m4-@value{VERSION}/@/examples/@/capitalize2.m4}), @code{capitalize}
+uses the alternate quotes of @samp{<<[} and @samp{]>>} (the longer
+strings are chosen so as to be less likely to appear in the text being
+converted).  The helpers @code{_to_alt} and @code{_from_alt} merely
+reduce the number of characters required to perform a
+@code{changequote}, since the definition changes twice.  The outermost
+pair means that @code{patsubst} and @code{_capitalize_alt} are invoked
+with alternate quoting; the innermost pair is used so that the third
+argument to @code{patsubst} can contain an unbalanced
+@samp{]>>}/@samp{<<[} pair.  Note that @code{upcase} and @code{downcase}
+must be redefined as @code{_upcase_alt} and @code{_downcase_alt}, since
+they contain nested quotes but are invoked with the alternate quoting
+scheme in effect.
+
+@comment examples
+@example
+$ @kbd{m4 -I examples}
+include(`capitalize2.m4')dnl
+define(`active', `act1, ive')dnl
+define(`Active', `Act2, Ive')dnl
+define(`ACTIVE', `ACT3, IVE')dnl
+define(`A', `OOPS')dnl
+capitalize(active; `active'; ``active''; ```actIVE''')
+@result{}Act1,Ive; Act2, Ive; Active; `Active'
+undivert(`capitalize2.m4')dnl
+@result{}divert(`-1')
+@result{}# upcase(text)
+@result{}# downcase(text)
+@result{}# capitalize(text)
+@result{}#   change case of text, improved version
+@result{}define(`upcase', `translit(`$*', `a-z', `A-Z')')
+@result{}define(`downcase', `translit(`$*', `A-Z', `a-z')')
+@result{}define(`_arg1', `$1')
+@result{}define(`_to_alt', `changequote(`<<[', `]>>')')
+@result{}define(`_from_alt', `changequote(<<[`]>>, <<[']>>)')
+@result{}define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)')
+@result{}define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)')
+@result{}define(`_capitalize_alt',
+@result{}  `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>,
+@result{}    <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)')
+@result{}define(`capitalize',
+@result{}  `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>,
+@result{}    _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())')
+@result{}divert`'dnl
+@end example
+
+@node Improved fatal_error
+@section Solution for @code{fatal_error}
+
+The @code{fatal_error} macro (@pxref{M4exit}) is not robust to versions
+of GNU M4 earlier than 1.4.8, where invoking
+@code{@w{__file__}} (@pxref{Location}) inside @code{m4wrap} would result
+in an empty string, and @code{@w{__line__}} resulted in @samp{0} even
+though all files start at line 1.  Furthermore, versions earlier than
+1.4.6 did not support the @code{@w{__program__}} macro.  If you want
+@code{fatal_error} to work across the entire 1.4.x release series, a
+better implementation would be:
+
+@comment status: 1
+@example
+define(`fatal_error',
+  `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
+`:ifelse(__line__, `0', `',
+    `__file__:__line__:')` fatal error: $*
+')m4exit(`1')')
+@result{}
+m4wrap(`divnum(`demo of internal message')
+fatal_error(`inside wrapped text')')
+@result{}
+^D
+@error{}m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored
+@result{}0
+@error{}m4:stdin:6: fatal error: inside wrapped text
+@end example
+
+@c ========================================================== Appendices
+
+@node Copying This Package
+@appendix How to make copies of the overall M4 package
+@cindex License, code
+
+This appendix covers the license for copying the source code of the
+overall M4 package.  This manual is under a different set of
+restrictions, covered later (@pxref{Copying This Manual}).
+
+@menu
+* GNU General Public License::  License for copying the M4 package
+@end menu
+
+@node GNU General Public License
+@appendixsec License for copying the M4 package
+@cindex GPL, GNU General Public License
+@cindex GNU General Public License
+@cindex General Public License (GPL), GNU
+@include gpl-3.0.texi
+
+@node Copying This Manual
+@appendix How to make copies of this manual
+@cindex License, manual
+
+This appendix covers the license for copying this manual.  Note that
+some of the longer examples in this manual are also distributed in the
+directory @file{m4-@value{VERSION}/@/examples/}, where a more
+permissive license is in effect when copying just the examples.
+
+@menu
+* GNU Free Documentation License::  License for copying this manual
+@end menu
+
+@node GNU Free Documentation License
+@appendixsec License for copying this manual
+@cindex FDL, GNU Free Documentation License
+@cindex GNU Free Documentation License
+@cindex Free Documentation License (FDL), GNU
+@include fdl-1.3.texi
+
+@node Indices
+@appendix Indices of concepts and macros
+
+@menu
+* Macro index::                 Index for all @code{m4} macros
+* Concept index::               Index for many concepts
+@end menu
+
+@node Macro index
+@appendixsec Index for all @code{m4} macros
+
+This index covers all @code{m4} builtins, as well as several useful
+composite macros.  References are exclusively to the places where a
+macro is introduced the first time.
+
+@printindex fn
+
+@node Concept index
+@appendixsec Index for many concepts
+
+@printindex cp
+
+@bye
+
+@c Local Variables:
+@c coding: iso-8859-1
+@c fill-column: 72
+@c ispell-local-dictionary: "american"
+@c indent-tabs-mode: nil
+@c whitespace-check-buffer-indent: nil
+@c End:
diff --git a/doc/stamp-vti b/doc/stamp-vti
new file mode 100644
index 0000000..1ba5096
--- /dev/null
+++ b/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 22 September 2013
+@set UPDATED-MONTH September 2013
+@set EDITION 1.4.17
+@set VERSION 1.4.17
diff --git a/doc/version.texi b/doc/version.texi
new file mode 100644
index 0000000..1ba5096
--- /dev/null
+++ b/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 22 September 2013
+@set UPDATED-MONTH September 2013
+@set EDITION 1.4.17
+@set VERSION 1.4.17