Adding upstream version 2.52+20231210.upstream/2.52+20231210

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

10 files changed, 31880 insertions, 0 deletions

diff --git a/doc/Makefile.in b/doc/Makefile.in
new file mode 100644
index 0000000..db3130e
--- /dev/null
+++ b/doc/Makefile.in
@@ -0,0 +1,341 @@
+# Copyright 2010-2012,2023 Thomas E. Dickey
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
+# 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@
+
+SHELL = @SHELL@
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datarootdir = @datarootdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+top_builddir = ..
+
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+
+INSTALL_INFO = @INSTALL_INFO@
+
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = @program_transform_name@
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+AWK = @AWK@
+EXPR = @EXPR@
+HELP2MAN = @HELP2MAN@
+M4 = @M4@
+PACKAGE = @PACKAGE@
+PACKAGE_NAME = @PACKAGE_NAME@
+PERL = @PERL@
+PERLSCRIPTS = @PERLSCRIPTS@
+VERSION = @VERSION@
+
+MAKEINFO = @MAKEINFO@ --no-split
+TEXI2HTML = texi2html
+
+info_TEXINFOS = autoconf.texi standards.texi
+autoconf_TEXINFOS = install.texi
+standards_TEXINFOS = make-stds.texi
+
+# Files from texi2dvi that should be removed, but which Automake does
+# not know.
+CLEANFILES = autoconf.cvs autoconf.ev autoconf.evs autoconf.ma autoconf.mas \
+             autoconf.ov autoconf.ovs autoconf.ms autoconf.mss autoconf.tmp
+
+subdir = doc
+CONFIG_CLEAN_FILES =
+DIST_SOURCES =
+TEXINFO_TEX = $(top_srcdir)/config/texinfo.tex
+INFO_DEPS = autoconf.info standards.info
+DVIS = autoconf.dvi standards.dvi
+TEXINFOS = autoconf.texi standards.texi
+DIST_COMMON = $(autoconf_TEXINFOS) $(standards_TEXINFOS) Makefile.am \
+	Makefile.in stamp-vti version.texi
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .dvi .info .ps .texi
+
+Makefile:  $(srcdir)/Makefile.in  $(top_builddir)/config.status
+	cd $(top_builddir) && \
+	  CONFIG_HEADERS= CONFIG_LINKS= \
+	  CONFIG_FILES=$(subdir)/$@ $(SHELL) ./config.status
+
+$(srcdir)/version.texi:  $(srcdir)/stamp-vti
+	@:
+$(srcdir)/stamp-vti: autoconf.texi $(top_srcdir)/configure.ac
+	@(set `$(SHELL) $(top_srcdir)/config/mdate-sh $(srcdir)/autoconf.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
+
+autoconf.info: autoconf.texi $(srcdir)/version.texi $(autoconf_TEXINFOS)
+autoconf.dvi: autoconf.texi $(srcdir)/version.texi $(autoconf_TEXINFOS)
+
+standards.info: standards.texi $(standards_TEXINFOS)
+standards.dvi: standards.texi $(standards_TEXINFOS)
+
+.texi.info:
+	@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	cd $(srcdir) \
+	  && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+	       `echo $< | sed 's,.*/,,'`
+
+.texi.dvi:
+	TEXINPUTS=$(top_srcdir)/config:$$TEXINPUTS \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2DVI) $<
+
+.texi:
+	@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
+	cd $(srcdir) \
+	  && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+	       `echo $< | sed 's,.*/,,'`
+TEXI2DVI = texi2dvi
+DVIPS = dvips
+.dvi.ps:
+	$(DVIPS) $< -o $@
+
+uninstall-info-am:
+	$(PRE_UNINSTALL)
+	@if test $(INSTALL_INFO) != no; then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    name=`basename "$$file" .info | sed -e '$(transform)'`; \
+	    FILE=$$name.info; \
+	    echo " $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$FILE"; \
+	    $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$FILE; \
+	  done; \
+	else :; fi
+	@$(NORMAL_UNINSTALL)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  name=`basename "$$file" .info | sed -e '$(transform)'`; \
+	  FILE=$$name.info; \
+	  (if cd $(DESTDIR)$(infodir); then \
+	     echo " rm -f $$FILE $$FILE-[0-9] $$FILE-[0-9][0-9])"; \
+	     rm -f $$file $$file-[0-9] $$file-[0-9][0-9]; \
+	   else :; fi); \
+	done
+
+dist-info: $(INFO_DEPS)
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  d=$(srcdir); \
+	  for file in `CDPATH=: && cd $$d && eval echo $$base*`; do \
+	    test -f $(distdir)/$$file \
+	    || cp -p $$d/$$file $(distdir)/$$file; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -f autoconf.aux autoconf.cp autoconf.cps autoconf.cv autoconf.dvi \
+	  autoconf.ev autoconf.fn autoconf.fns autoconf.ky autoconf.log \
+	  autoconf.ma autoconf.ms autoconf.ov autoconf.pg autoconf.ps \
+	  autoconf.toc autoconf.tp autoconf.vr autoconf.vrs \
+	  standards.aux standards.cp standards.cps standards.dvi \
+	  standards.fn standards.ky standards.log standards.pg \
+	  standards.ps standards.toc standards.tp standards.vr
+
+maintainer-clean-aminfo:
+	cd $(srcdir) && \
+	for i in $(INFO_DEPS); do \
+	  rm -f $$i; \
+	  if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
+	    rm -f $$i-[0-9]*; \
+	  fi; \
+	done
+tags: TAGS
+TAGS:
+
+
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+
+top_distdir = ..
+distdir = $(top_distdir)/$(PACKAGE)-$(VERSION)
+
+distdir: $(DISTFILES)
+	@for file in $(DISTFILES); do \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
+	  if test "$$dir" != "$$file" && test "$$dir" != "."; then \
+	    mkdir -p "$(distdir)/$$dir"; \
+	  fi; \
+	  if test -d $$d/$$file; then \
+	    cp -pR $$d/$$file $(distdir) \
+	    || 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)
+
+installdirs:
+	mkdir -p $(DESTDIR)$(infodir)
+
+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:
+	$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	  `test -z '$(STRIP)' || \
+	    echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+	-rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]*
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic mostlyclean-am
+
+distclean: distclean-am
+
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am: $(DVIS)
+
+info: info-am
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am
+
+install-exec-am:
+
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	mkdir -p $(DESTDIR)$(infodir)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  name=`basename "$$file" .info | sed -e '$(transform)'`; \
+	  FILE=$$name.info; \
+	  d=$(srcdir); \
+	  for ifile in `CDPATH=: && cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \
+	    if test -f $$d/$$ifile; then \
+	      $(SHELL) $$d/rename.sh $$d/$$ifile $$FILE; \
+	      echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$FILE"; \
+	      $(INSTALL_DATA) $$FILE $(DESTDIR)$(infodir)/$$FILE; \
+	      test "$$file" != "$$FILE" && rm -f "$$FILE"; \
+	      break; \
+	    else : ; fi; \
+	  done; \
+	done
+	@$(POST_INSTALL)
+	@if test $(INSTALL_INFO) != no; then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    name=`basename "$$file" .info | sed -e '$(transform)'`; \
+	    FILE=$$name.info; \
+	    echo " $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$FILE";\
+	    $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$FILE || :;\
+	  done; \
+	else : ; fi
+install-man:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+
+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
+
+uninstall-am: uninstall-info-am
+
+.PHONY: all all-am check check-am clean clean-generic dist-info \
+	distclean distclean-generic distdir dvi dvi-am info info-am \
+	install install-am install-data install-data-am install-exec \
+	install-exec-am install-info install-info-am install-man \
+	install-strip installcheck installcheck-am installdirs \
+	maintainer-clean maintainer-clean-aminfo \
+	maintainer-clean-generic maintainer-clean-vti mostlyclean \
+	mostlyclean-aminfo mostlyclean-generic mostlyclean-vti \
+	uninstall uninstall-am uninstall-info-am
+
+
+# The documentation
+
+html: autoconf_1.html standards_1.html
+
+autoconf_1.html: autoconf.texi install.texi
+	$(TEXI2HTML) -split_chapter $(srcdir)/autoconf.texi
+
+standards_1.html: standards.texi make-stds.texi
+	$(TEXI2HTML) -split_chapter $(srcdir)/standards.texi
+# 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/autoconf.info b/doc/autoconf.info
new file mode 100644
index 0000000..d64dd17
--- /dev/null
+++ b/doc/autoconf.info
@@ -0,0 +1,10852 @@
+This is autoconf.info, produced by makeinfo version 6.7 from
+autoconf.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* Autoconf: (autoconf).         Create source code configuration scripts
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* autoscan: (autoconf)autoscan Invocation.
+                                Semi-automatic 'configure.ac' writing
+* ifnames: (autoconf)ifnames Invocation.
+                                Listing the conditionals in source code
+* autoconf: (autoconf)autoconf Invocation.
+                                How to create configuration scripts
+* autoreconf: (autoconf)autoreconf Invocation.
+                                Remaking multiple 'configure' scripts
+* configure: (autoconf)configure Invocation.
+                                Configuring a package
+* config.status: (autoconf)config.status Invocation.
+                                Recreating a configuration
+END-INFO-DIR-ENTRY
+
+Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie.
+
+   This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and an 'm4' macro
+package.
+
+   Copyright 2003-2022,2023	Thomas E. Dickey
+Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 Free
+Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+
+File: autoconf.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+
+This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and the GNU M4 macro
+package.  This is edition 2.52.20231210, for Autoconf version
+2.52.20231210.
+
+* Menu:
+
+* Introduction::                Autoconf's purpose, strengths, and weaknesses
+* The GNU build system::        A set of tools for portable software packages
+* Making configure Scripts::    How to organize and produce Autoconf scripts
+* Setup::                       Initialization and output
+* Existing Tests::              Macros that check for particular features
+* Writing Tests::               How to write new feature checks
+* Results::                     What to do with results from feature checks
+* Programming in M4::           Layers on top of which Autoconf is written
+* Writing Autoconf Macros::     Adding new macros to Autoconf
+* Portable Shell::              Shell script portability pitfalls
+* Manual Configuration::        Selecting features that can't be guessed
+* Site Configuration::          Local defaults for 'configure'
+* Running configure scripts::   How to use the Autoconf output
+* config.status Invocation::    Recreating a configuration
+* Obsolete Constructs::         Kept for backward compatibility
+* Questions::                   Questions about Autoconf, with answers
+* History::                     History of Autoconf
+* Environment Variable Index::  Index of environment variables used
+* Output Variable Index::       Index of variables set in output files
+* Preprocessor Symbol Index::   Index of C preprocessor symbols defined
+* Autoconf Macro Index::        Index of Autoconf macros
+* M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
+* Concept Index::               General index
+
+
+The GNU build system
+
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+
+Making 'configure' Scripts
+
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic 'configure.ac' writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple 'configure' scripts
+
+Writing 'configure.ac'
+
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+
+Initialization and Output Files
+
+* Notices::                     Copyright, version numbers in 'configure'
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in 'Makefile's
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+
+Substitutions in Makefiles
+
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+
+Configuration Header Files
+
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+
+Existing Tests
+
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+
+Common Behavior
+
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+
+Alternative Programs
+
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+
+Library Functions
+
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+
+Header Files
+
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+
+Declarations
+
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+
+Structures
+
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+
+Types
+
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+
+Compilers and Preprocessors
+
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+
+Writing Tests
+
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+
+Checking Run Time Behavior
+
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+
+Results of Tests
+
+* Defining Symbols::            Defining C preprocessor symbols
+* Setting Output Variables::    Replacing variables in output files
+* Caching Results::             Speeding up subsequent 'configure' runs
+* Printing Messages::           Notifying 'configure' users
+
+Caching Results
+
+* Cache Variable Names::        Shell variables used in caches
+* Cache Files::                 Files 'configure' uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
+
+Programming in M4
+
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+
+M4 Quotation
+
+* Active Characters::           Characters that change the behavior of m4
+* One Macro Call::              Quotation and one macro call
+* Quotation and Nested Macros::  Macros calling macros
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+
+Programming in M4sugar
+
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+
+Writing Autoconf Macros
+
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* Reporting Messages::          Notifying 'autoconf' users
+* Dependencies Between Macros::  What to do when macros depend on other macros
+* Obsoleting Macros::           Warning about old ways of doing things
+* Coding Style::                Writing Autoconf macros à la Autoconf
+
+Dependencies Between Macros
+
+* Prerequisite Macros::         Ensuring required information
+* Suggested Ordering::          Warning about possible ordering problems
+
+Portable Shell Programming
+
+* Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
+* File Descriptors::            FDs and redirections
+* File System Conventions::     File- and pathnames
+* Shell Substitutions::         Variable and command expansions
+* Assignments::                 Varying side effects of assignments
+* Special Shell Variables::     Variables you should not change
+* Limitations of Builtins::     Portable use of not so portable /bin/sh
+* Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
+
+Manual Configuration
+
+* Specifying Names::            Specifying the system type
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+
+Site Configuration
+
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving 'configure' local defaults
+
+Transforming Program Names When Installing
+
+* Transformation Options::      'configure' options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        'Makefile' uses of transforming names
+
+Running 'configure' Scripts
+
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for 'configure'
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how 'configure' runs
+
+Obsolete Constructs
+
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in 'config.h.in'
+* autoupdate Invocation::       Automatic update of 'configure.ac'
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+
+Upgrading From Version 1
+
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in 'Makefile.in'
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+
+Upgrading From Version 2.13
+
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+
+Questions About Autoconf
+
+* Distributing::                Distributing 'configure' scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses 'configure' instead of Imake
+
+History of Autoconf
+
+* Genesis::                     Prehistory and naming of 'configure'
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+
+
+
+File: autoconf.info,  Node: Introduction,  Next: The GNU build system,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+ A physicist, an engineer, and a computer scientist were discussing the
+     nature of God.  "Surely a Physicist," said the physicist, "because
+         early in the Creation, God made Light; and you know, Maxwell's
+  equations, the dual nature of electromagnetic waves, the relativistic
+           consequences..." "An Engineer!," said the engineer, "because
+before making Light, God split the Chaos into Land and Water; it takes a
+      hell of an engineer to handle that big amount of mud, and orderly
+           separation of solids from liquids..." The computer scientist
+  shouted: "And the Chaos, where do you think it was coming from, hmm?"
+
+                                                            --Anonymous
+
+   Autoconf is a tool for producing shell scripts that automatically
+configure software source code packages to adapt to many kinds of
+UNIX-like systems.  The configuration scripts produced by Autoconf are
+independent of Autoconf when they are run, so their users do not need to
+have Autoconf.
+
+   The configuration scripts produced by Autoconf require no manual user
+intervention when run; they do not normally even need an argument
+specifying the system type.  Instead, they individually test for the
+presence of each feature that the software package they are for might
+need.  (Before each check, they print a one-line message stating what
+they are checking for, so the user doesn't get too bored while waiting
+for the script to finish.)  As a result, they deal well with systems
+that are hybrids or customized from the more common UNIX variants.
+There is no need to maintain files that list the features supported by
+each release of each variant of UNIX.
+
+   For each software package that Autoconf is used with, it creates a
+configuration script from a template file that lists the system features
+that the package needs or can use.  After the shell code to recognize
+and respond to a system feature has been written, Autoconf allows it to
+be shared by many software packages that can use (or need) that feature.
+If it later turns out that the shell code needs adjustment for some
+reason, it needs to be changed in only one place; all of the
+configuration scripts can be regenerated automatically to take advantage
+of the updated code.
+
+   The Metaconfig package is similar in purpose to Autoconf, but the
+scripts it produces require manual user intervention, which is quite
+inconvenient when configuring large source trees.  Unlike Metaconfig
+scripts, Autoconf scripts can support cross-compiling, if some care is
+taken in writing them.
+
+   Autoconf does not solve all problems related to making portable
+software packages--for a more complete solution, it should be used in
+concert with other GNU build tools like Automake and Libtool.  These
+other tools take on jobs like the creation of a portable, recursive
+'Makefile' with all of the standard targets, linking of shared
+libraries, and so on.  *Note The GNU build system::, for more
+information.
+
+   Autoconf imposes some restrictions on the names of macros used with
+'#if' in C programs (*note Preprocessor Symbol Index::).
+
+   Autoconf requires GNU M4 in order to generate the scripts.  It uses
+features that some UNIX versions of M4, including GNU M4 1.3, do not
+have.  You must use version 1.4 or later of GNU M4.
+
+   *Note Autoconf 1::, for information about upgrading from version 1.
+*Note History::, for the story of Autoconf's development.  *Note
+Questions::, for answers to some common questions about Autoconf.
+
+   See the Autoconf web page(1) for up-to-date information, details on
+the mailing lists, pointers to a list of known bugs, etc.
+
+   Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>.
+
+   Bug reports should be preferably submitted to the Autoconf Gnats
+database(2), or sent to the Autoconf Bugs mailing list
+<bug-autoconf@gnu.org>.  If possible, first check that your bug is not
+already solved in current development versions, and that it has not been
+reported yet.  Be sure to include all the needed information and a short
+'configure.ac' that demonstrates the problem.
+
+   Autoconf's development tree is accessible via CVS; see the Autoconf
+web page for details.  There is also a CVSweb interface to the Autoconf
+development tree(3).  Patches relative to the current CVS version can be
+sent for review to the Autoconf Patches mailing list
+<autoconf-patches@gnu.org>.
+
+   Because of its mission, Autoconf includes only a set of often-used
+macros that have already demonstrated their usefulness.  Nevertheless,
+if you wish to share your macros, or find existing ones, see the
+Autoconf Macro Archive(4), which is kindly run by Peter Simons
+<simons@computer.org>.
+
+   ---------- Footnotes ----------
+
+   (1) Autoconf web page,
+<http://www.gnu.org/software/autoconf/autoconf.html>.
+
+   (2) Autoconf Gnats database,
+<http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf>.
+
+   (3) CVSweb interface to the Autoconf development tree,
+<http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/>.
+
+   (4) Autoconf Macro Archive,
+<http://www.gnu.org/software/ac-archive/>.
+
+
+File: autoconf.info,  Node: The GNU build system,  Next: Making configure Scripts,  Prev: Introduction,  Up: Top
+
+2 The GNU build system
+**********************
+
+Autoconf solves an important problem--reliable discovery of
+system-specific build and runtime information--but this is only one
+piece of the puzzle for the development of portable software.  To this
+end, the GNU project has developed a suite of integrated utilities to
+finish the job Autoconf started: the GNU build system, whose most
+important components are Autoconf, Automake, and Libtool.  In this
+chapter, we introduce you to those tools, point you to sources of more
+information, and try to convince you to use the entire GNU build system
+for your software.
+
+* Menu:
+
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+
+
+File: autoconf.info,  Node: Automake,  Next: Libtool,  Prev: The GNU build system,  Up: The GNU build system
+
+2.1 Automake
+============
+
+The ubiquity of 'make' means that a 'Makefile' is almost the only viable
+way to distribute automatic build rules for software, but one quickly
+runs into 'make''s numerous limitations.  Its lack of support for
+automatic dependency tracking, recursive builds in subdirectories,
+reliable timestamps (e.g.  for network filesystems), and so on, mean
+that developers must painfully (and often incorrectly) reinvent the
+wheel for each project.  Portability is non-trivial, thanks to the
+quirks of 'make' on many systems.  On top of all this is the manual
+labor required to implement the many standard targets that users have
+come to expect ('make install', 'make distclean', 'make uninstall',
+etc.).  Since you are, of course, using Autoconf, you also have to
+insert repetitive code in your 'Makefile.in' to recognize '@CC@',
+'@CFLAGS@', and other substitutions provided by 'configure'.  Into this
+mess steps "Automake".
+
+   Automake allows you to specify your build needs in a 'Makefile.am'
+file with a vastly simpler and more powerful syntax than that of a plain
+'Makefile', and then generates a portable 'Makefile.in' for use with
+Autoconf.  For example, the 'Makefile.am' to build and install a simple
+"Hello world" program might look like:
+
+     bin_PROGRAMS = hello
+     hello_SOURCES = hello.c
+
+The resulting 'Makefile.in' (~400 lines) automatically supports all the
+standard targets, the substitutions provided by Autoconf, automatic
+dependency tracking, 'VPATH' building, and so on.  'make' will build the
+'hello' program, and 'make install' will install it in '/usr/local/bin'
+(or whatever prefix was given to 'configure', if not '/usr/local').
+
+   Automake may require that additional tools be present on the
+_developer's_ machine.  For example, the 'Makefile.in' that the
+developer works with may not be portable (e.g.  it might use special
+features of your compiler to automatically generate dependency
+information).  Running 'make dist', however, produces a
+'hello-1.0.tar.gz' package (or whatever the program/version is) with a
+'Makefile.in' that will work on any system.
+
+   The benefits of Automake increase for larger packages (especially
+ones with subdirectories), but even for small programs the added
+convenience and portability can be substantial.  And that's not all...
+
+
+File: autoconf.info,  Node: Libtool,  Next: Pointers,  Prev: Automake,  Up: The GNU build system
+
+2.2 Libtool
+===========
+
+Very often, one wants to build not only programs, but libraries, so that
+other programs can benefit from the fruits of your labor.  Ideally, one
+would like to produce _shared_ (dynamically-linked) libraries, which can
+be used by multiple programs without duplication on disk or in memory
+and can be updated independently of the linked programs.  Producing
+shared libraries portably, however, is the stuff of nightmares--each
+system has its own incompatible tools, compiler flags, and magic
+incantations.  Fortunately, GNU provides a solution: "Libtool".
+
+   Libtool handles all the requirements of building shared libraries for
+you, and at this time seems to be the _only_ way to do so with any
+portability.  It also handles many other headaches, such as: the
+interaction of 'Makefile' rules with the variable suffixes of shared
+libraries, linking reliably to shared libraries before they are
+installed by the superuser, and supplying a consistent versioning system
+(so that different versions of a library can be installed or upgraded
+without breaking binary compatibility).  Although Libtool, like
+Autoconf, can be used on its own, it is most simply utilized in
+conjunction with Automake--there, Libtool is used automatically whenever
+shared libraries are needed, and you need not know its syntax.
+
+
+File: autoconf.info,  Node: Pointers,  Prev: Libtool,  Up: The GNU build system
+
+2.3 Pointers
+============
+
+Developers who are used to the simplicity of 'make' for small projects
+on a single system might be daunted at the prospect of learning to use
+Automake and Autoconf.  As your software is distributed to more and more
+users, however, you will otherwise quickly find yourself putting lots of
+effort into reinventing the services that the GNU build tools provide,
+and making the same mistakes that they once made and overcame.
+(Besides, since you're already learning Autoconf, Automake will be a
+piece of cake.)
+
+   There are a number of places that you can go to for more information
+on the GNU build tools.
+
+   - Web
+
+     The home pages for Autoconf(1), and Libtool(2).
+
+   - Books
+
+     The book 'GNU Autoconf, Automake and Libtool'(3) describes the
+     complete GNU build environment.  You can also find the entire book
+     on-line at "The Goat Book" home page(4).
+
+   - Tutorials and Examples
+
+     The Autoconf Developer Page(5) maintains links to a number of
+     Autoconf/Automake tutorials online, and also links to the Autoconf
+     Macro Archive(6).
+
+   ---------- Footnotes ----------
+
+   (1) Autoconf, <http://www.gnu.org/software/autoconf/>.
+
+   (2) Libtool, <http://www.gnu.org/software/libtool/>.
+
+   (3) 'GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B.
+Elliston, T. Tromey, and I. L. Taylor.  New Riders, 2000, ISBN
+1578701902.
+
+   (4) "The Goat Book" home page, <http://sources.redhat.com/autobook/>.
+
+   (5) Autoconf Developer Page, <http://sources.redhat.com/autoconf/>.
+
+   (6) Autoconf Macro Archive,
+<http://www.gnu.org/software/ac-archive/>.
+
+
+File: autoconf.info,  Node: Making configure Scripts,  Next: Setup,  Prev: The GNU build system,  Up: Top
+
+3 Making 'configure' Scripts
+****************************
+
+The configuration scripts that Autoconf produces are by convention
+called 'configure'.  When run, 'configure' creates several files,
+replacing configuration parameters in them with appropriate values.  The
+files that 'configure' creates are:
+
+   - one or more 'Makefile' files, one in each subdirectory of the
+     package (*note Makefile Substitutions::);
+
+   - optionally, a C header file, the name of which is configurable,
+     containing '#define' directives (*note Configuration Headers::);
+
+   - a shell script called 'config.status' that, when run, will recreate
+     the files listed above (*note config.status Invocation::);
+
+   - an optional shell script normally called 'config.cache' (created
+     when using 'configure --config-cache') that saves the results of
+     running many of the tests (*note Cache Files::);
+
+   - a file called 'config.log' containing any messages produced by
+     compilers, to help debugging if 'configure' makes a mistake.
+
+   To create a 'configure' script with Autoconf, you need to write an
+Autoconf input file 'configure.ac' (or 'configure.in') and run
+'autoconf' on it.  If you write your own feature tests to supplement
+those that come with Autoconf, you might also write files called
+'aclocal.m4' and 'acsite.m4'.  If you use a C header file to contain
+'#define' directives, you might also run 'autoheader', and you will
+distribute the generated file 'config.h.in' with the package.
+
+   Here is a diagram showing how the files that can be used in
+configuration are produced.  Programs that are executed are suffixed by
+'*'.  Optional files are enclosed in square brackets ('[]').  'autoconf'
+and 'autoheader' also read the installed Autoconf macro files (by
+reading 'autoconf.m4').
+
+Files used in preparing a software package for distribution:
+     your source files --> [autoscan*] --> [configure.scan] --> configure.ac
+
+     configure.ac --.
+                    |   .------> autoconf* -----> configure
+     [aclocal.m4] --+---+
+                    |   `-----> [autoheader*] --> [config.h.in]
+     [acsite.m4] ---'
+
+     Makefile.in -------------------------------> Makefile.in
+
+Files used in configuring a software package:
+                            .-------------> [config.cache]
+     configure* ------------+-------------> config.log
+                            |
+     [config.h.in] -.       v            .-> [config.h] -.
+                    +--> config.status* -+               +--> make*
+     Makefile.in ---'                    `-> Makefile ---'
+
+* Menu:
+
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic 'configure.ac' writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple 'configure' scripts
+
+
+File: autoconf.info,  Node: Writing configure.ac,  Next: autoscan Invocation,  Prev: Making configure Scripts,  Up: Making configure Scripts
+
+3.1 Writing 'configure.ac'
+==========================
+
+To produce a 'configure' script for a software package, create a file
+called 'configure.ac' that contains invocations of the Autoconf macros
+that test the system features your package needs or can use.  Autoconf
+macros already exist to check for many features; see *note Existing
+Tests::, for their descriptions.  For most other features, you can use
+Autoconf template macros to produce custom checks; see *note Writing
+Tests::, for information about them.  For especially tricky or
+specialized features, 'configure.ac' might need to contain some
+hand-crafted shell commands; see *note Portable Shell::.  The 'autoscan'
+program can give you a good start in writing 'configure.ac' (*note
+autoscan Invocation::, for more information).
+
+   Previous versions of Autoconf promoted the name 'configure.in', which
+is somewhat ambiguous (the tool needed to produce this file is not
+described by its extension), and introduces a slight confusion with
+'config.h.in' and so on (for which '.in' means "to be processed by
+'configure'").  Using 'configure.ac' is now preferred.
+
+* Menu:
+
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+
+
+File: autoconf.info,  Node: Shell Script Compiler,  Next: Autoconf Language,  Prev: Writing configure.ac,  Up: Writing configure.ac
+
+3.1.1 A Shell Script Compiler
+-----------------------------
+
+Just as for any other computer language, in order to properly program
+'configure.ac' in Autoconf you must understand _what_ problem the
+language tries to address and _how_ it does so.
+
+   The problem Autoconf addresses is that the world is a mess.  After
+all, you are using Autoconf in order to have your package compile easily
+on all sorts of different systems, some of them being extremely hostile.
+Autoconf itself bears the price for these differences: 'configure' must
+run on all those systems, and thus 'configure' must limit itself to
+their lowest common denominator of features.
+
+   Naturally, you might then think of shell scripts; who needs
+'autoconf'?  A set of properly written shell functions is enough to make
+it easy to write 'configure' scripts by hand.  Sigh!  Unfortunately,
+shell functions do not belong to the least common denominator;
+therefore, where you would like to define a function and use it ten
+times, you would instead need to copy its body ten times.
+
+   So, what is really needed is some kind of compiler, 'autoconf', that
+takes an Autoconf program, 'configure.ac', and transforms it into a
+portable shell script, 'configure'.
+
+   How does 'autoconf' perform this task?
+
+   There are two obvious possibilities: creating a brand new language or
+extending an existing one.  The former option is very attractive: all
+sorts of optimizations could easily be implemented in the compiler and
+many rigorous checks could be performed on the Autoconf program (e.g.
+rejecting any non-portable construct).  Alternatively, you can extend an
+existing language, such as the 'sh' (Bourne shell) language.
+
+   Autoconf does the latter: it is a layer on top of 'sh'.  It was
+therefore most convenient to implement 'autoconf' as a macro expander: a
+program that repeatedly performs "macro expansions" on text input,
+replacing macro calls with macro bodies and producing a pure 'sh' script
+in the end.  Instead of implementing a dedicated Autoconf macro
+expander, it is natural to use an existing general-purpose macro
+language, such as M4, and implement the extensions as a set of M4
+macros.
+
+
+File: autoconf.info,  Node: Autoconf Language,  Next: configure.ac Layout,  Prev: Shell Script Compiler,  Up: Writing configure.ac
+
+3.1.2 The Autoconf Language
+---------------------------
+
+The Autoconf language is very different from many other computer
+languages because it treats actual code the same as plain text.  Whereas
+in C, for instance, data and instructions have very different syntactic
+status, in Autoconf their status is rigorously the same.  Therefore, we
+need a means to distinguish literal strings from text to be expanded:
+quotation.
+
+   When calling macros that take arguments, there must not be any blank
+space between the macro name and the open parenthesis.  Arguments should
+be enclosed within the M4 quote characters '[' and ']', and be separated
+by commas.  Any leading spaces in arguments are ignored, unless they are
+quoted.  You may safely leave out the quotes when the argument is simple
+text, but _always_ quote complex arguments such as other macro calls.
+This rule applies recursively for every macro call, including macros
+called from other macros.
+
+   For instance:
+
+     AC_CHECK_HEADER([stdio.h],
+                     [AC_DEFINE([HAVE_STDIO_H])],
+                     [AC_MSG_ERROR([Sorry, can't do anything for you])])
+
+is quoted properly.  You may safely simplify its quotation to:
+
+     AC_CHECK_HEADER(stdio.h,
+                     [AC_DEFINE(HAVE_STDIO_H)],
+                     [AC_MSG_ERROR([Sorry, can't do anything for you])])
+
+Notice that the argument of 'AC_MSG_ERROR' is still quoted; otherwise,
+its comma would have been interpreted as an argument separator.
+
+   The following example is wrong and dangerous, as it is underquoted:
+
+     AC_CHECK_HEADER(stdio.h,
+                     AC_DEFINE(HAVE_STDIO_H),
+                     AC_MSG_ERROR([Sorry, can't do anything for you]))
+
+   In other cases, you may have to use text that also resembles a macro
+call.  You must quote that text even when it is not passed as a macro
+argument:
+
+     echo "Hard rock was here!  --[AC_DC]"
+
+which will result in
+
+     echo "Hard rock was here!  --AC_DC"
+
+When you use the same text in a macro argument, you must therefore have
+an extra quotation level (since one is stripped away by the macro
+substitution).  In general, then, it is a good idea to _use double
+quoting for all literal string arguments_:
+
+     AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
+
+   You are now able to understand one of the constructs of Autoconf that
+has been continually misunderstood... The rule of thumb is that
+_whenever you expect macro expansion, expect quote expansion_; i.e.,
+expect one level of quotes to be lost.  For instance:
+
+     AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
+
+is incorrect: here, the first argument of 'AC_COMPILE_IFELSE' is 'char
+b[10];' and will be expanded once, which results in 'char b10;'.  (There
+was an idiom common in Autoconf's past to address this issue via the M4
+'changequote' primitive, but do not use it!)  Let's take a closer look:
+the author meant the first argument to be understood as a literal, and
+therefore it must be quoted twice:
+
+     AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
+
+Voilà, you actually produce 'char b[10];' this time!
+
+   The careful reader will notice that, according to these guidelines,
+the "properly" quoted 'AC_CHECK_HEADER' example above is actually
+lacking three pairs of quotes!  Nevertheless, for the sake of
+readability, double quotation of literals is used only where needed in
+this manual.
+
+   Some macros take optional arguments, which this documentation
+represents as [ARG] (not to be confused with the quote characters).  You
+may just leave them empty, or use '[]' to make the emptiness of the
+argument explicit, or you may simply omit the trailing commas.  The
+three lines below are equivalent:
+
+     AC_CHECK_HEADERS(stdio.h, [], [], [])
+     AC_CHECK_HEADERS(stdio.h,,,)
+     AC_CHECK_HEADERS(stdio.h)
+
+   It is best to put each macro call on its own line in 'configure.ac'.
+Most of the macros don't add extra newlines; they rely on the newline
+after the macro call to terminate the commands.  This approach makes the
+generated 'configure' script a little easier to read by not inserting
+lots of blank lines.  It is generally safe to set shell variables on the
+same line as a macro call, because the shell allows assignments without
+intervening newlines.
+
+   You can include comments in 'configure.ac' files by starting them
+with the '#'.  For example, it is helpful to begin 'configure.ac' files
+with a line like this:
+
+     # Process this file with autoconf to produce a configure script.
+
+
+File: autoconf.info,  Node: configure.ac Layout,  Prev: Autoconf Language,  Up: Writing configure.ac
+
+3.1.3 Standard 'configure.ac' Layout
+------------------------------------
+
+The order in which 'configure.ac' calls the Autoconf macros is not
+important, with a few exceptions.  Every 'configure.ac' must contain a
+call to 'AC_INIT' before the checks, and a call to 'AC_OUTPUT' at the
+end (*note Output::).  Additionally, some macros rely on other macros
+having been called first, because they check previously set values of
+some variables to decide what to do.  These macros are noted in the
+individual descriptions (*note Existing Tests::), and they also warn you
+when 'configure' is created if they are called out of order.
+
+   To encourage consistency, here is a suggested order for calling the
+Autoconf macros.  Generally speaking, the things near the end of this
+list are those that could depend on things earlier in it.  For example,
+library functions could be affected by types and libraries.
+
+     Autoconf requirements
+     'AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)'
+     information on the package
+     checks for programs
+     checks for libraries
+     checks for header files
+     checks for types
+     checks for structures
+     checks for compiler characteristics
+     checks for library functions
+     checks for system services
+     'AC_CONFIG_FILES([FILE...])'
+     'AC_OUTPUT'
+
+
+File: autoconf.info,  Node: autoscan Invocation,  Next: ifnames Invocation,  Prev: Writing configure.ac,  Up: Making configure Scripts
+
+3.2 Using 'autoscan' to Create 'configure.ac'
+=============================================
+
+The 'autoscan' program can help you create and/or maintain a
+'configure.ac' file for a software package.  'autoscan' examines source
+files in the directory tree rooted at a directory given as a command
+line argument, or the current directory if none is given.  It searches
+the source files for common portability problems and creates a file
+'configure.scan' which is a preliminary 'configure.ac' for that package,
+and checks a possibly existing 'configure.ac' for completeness.
+
+   When using 'autoscan' to create a 'configure.ac', you should manually
+examine 'configure.scan' before renaming it to 'configure.ac'; it will
+probably need some adjustments.  Occasionally, 'autoscan' outputs a
+macro in the wrong order relative to another macro, so that 'autoconf'
+produces a warning; you need to move such macros manually.  Also, if you
+want the package to use a configuration header file, you must add a call
+to 'AC_CONFIG_HEADERS' (*note Configuration Headers::).  You might also
+have to change or add some '#if' directives to your program in order to
+make it work with Autoconf (*note ifnames Invocation::, for information
+about a program that can help with that job).
+
+   When using 'autoscan' to maintain a 'configure.ac', simply consider
+adding its suggestions.  The file 'autoscan.log' will contain detailed
+information on why a macro is requested.
+
+   'autoscan' uses several data files (installed along with Autoconf) to
+determine which macros to output when it finds particular symbols in a
+package's source files.  These data files all have the same format: each
+line consists of a symbol, whitespace, and the Autoconf macro to output
+if that symbol is encountered.  Lines starting with '#' are comments.
+
+   'autoscan' is only installed if you already have Perl installed.
+'autoscan' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--verbose'
+'-v'
+     Print the names of the files it examines and the potentially
+     interesting symbols it finds in them.  This output can be
+     voluminous.
+
+'--autoconf-dir=DIR'
+'-A DIR'
+     Override the location where the installed Autoconf data files are
+     looked for.  You can also set the 'AC_MACRODIR' environment
+     variable to a directory; this option overrides the environment
+     variable.
+
+     This option is rarely needed and dangerous; it is only used when
+     one plays with different versions of Autoconf simultaneously.
+
+
+File: autoconf.info,  Node: ifnames Invocation,  Next: autoconf Invocation,  Prev: autoscan Invocation,  Up: Making configure Scripts
+
+3.3 Using 'ifnames' to List Conditionals
+========================================
+
+'ifnames' can help you write 'configure.ac' for a software package.  It
+prints the identifiers that the package already uses in C preprocessor
+conditionals.  If a package has already been set up to have some
+portability, 'ifnames' can thus help you figure out what its 'configure'
+needs to check for.  It may help fill in some gaps in a 'configure.ac'
+generated by 'autoscan' (*note autoscan Invocation::).
+
+   'ifnames' scans all of the C source files named on the command line
+(or the standard input, if none are given) and writes to the standard
+output a sorted list of all the identifiers that appear in those files
+in '#if', '#elif', '#ifdef', or '#ifndef' directives.  It prints each
+identifier on a line, followed by a space-separated list of the files in
+which that identifier occurs.
+
+'ifnames' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+
+File: autoconf.info,  Node: autoconf Invocation,  Next: autoreconf Invocation,  Prev: ifnames Invocation,  Up: Making configure Scripts
+
+3.4 Using 'autoconf' to Create 'configure'
+==========================================
+
+To create 'configure' from 'configure.ac', run the 'autoconf' program
+with no arguments.  'autoconf' processes 'configure.ac' with the 'm4'
+macro processor, using the Autoconf macros.  If you give 'autoconf' an
+argument, it reads that file instead of 'configure.ac' and writes the
+configuration script to the standard output instead of to 'configure'.
+If you give 'autoconf' the argument '-', it reads from the standard
+input instead of 'configure.ac' and writes the configuration script to
+the standard output.
+
+   The Autoconf macros are defined in several files.  Some of the files
+are distributed with Autoconf; 'autoconf' reads them first.  Then it
+looks for the optional file 'acsite.m4' in the directory that contains
+the distributed Autoconf macro files, and for the optional file
+'aclocal.m4' in the current directory.  Those files can contain your
+site's or the package's own Autoconf macro definitions (*note Writing
+Autoconf Macros::, for more information).  If a macro is defined in more
+than one of the files that 'autoconf' reads, the last definition it
+reads overrides the earlier ones.
+
+   'autoconf' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--verbose'
+'-v'
+     Report processing steps.
+
+'--debug'
+'-d'
+     Don't remove the temporary files.
+
+'--autoconf-dir=DIR'
+'-A DIR'
+     Override the location where the installed Autoconf data files are
+     looked for.  You can also set the 'AC_MACRODIR' environment
+     variable to a directory; this option overrides the environment
+     variable.
+
+     This option is rarely needed and dangerous; it is only used when
+     one plays with different versions of Autoconf simultaneously.
+
+'--localdir=DIR'
+'-l DIR'
+     Look for the package file 'aclocal.m4' in directory DIR instead of
+     in the current directory.
+
+'--output=FILE'
+'-o FILE'
+     Save output (script or trace) to FILE.  The file '-' stands for the
+     standard output.
+
+'--warnings=CATEGORY'
+'-W CATEGORY'
+     Report the warnings related to CATEGORY (which can actually be a
+     comma separated list).  *Note Reporting Messages::, macro
+     'AC_DIAGNOSE', for a comprehensive list of categories.  Special
+     values include:
+
+     'all'
+          report all the warnings
+
+     'none'
+          report none
+
+     'error'
+          treats warnings as errors
+
+     'no-CATEGORY'
+          disable warnings falling into CATEGORY
+
+     Warnings about 'syntax' are enabled by default, and the environment
+     variable 'WARNINGS', a comma separated list of categories, is
+     honored.  'autoconf -W CATEGORY' will actually behave as if you had
+     run:
+
+          autoconf --warnings=syntax,$WARNINGS,CATEGORY
+
+     If you want to disable 'autoconf''s defaults and 'WARNINGS', but
+     (for example) enable the warnings about obsolete constructs, you
+     would use '-W none,obsolete'.
+
+     'autoconf' displays a back trace for errors, but not for warnings;
+     if you want them, just pass '-W error'.  For instance, on this
+     'configure.ac':
+
+          AC_DEFUN([INNER],
+          [AC_TRY_RUN([true])])
+
+          AC_DEFUN([OUTER],
+          [INNER])
+
+          AC_INIT
+          OUTER
+
+     you get:
+
+          $ autoconf -Wcross
+          configure.ac:8: warning: AC_TRY_RUN called without default \
+          to allow cross compiling
+          $ autoconf -Wcross,error
+          configure.ac:8: error: AC_TRY_RUN called without default \
+          to allow cross compiling
+          acgeneral.m4:3044: AC_TRY_RUN is expanded from...
+          configure.ac:2: INNER is expanded from...
+          configure.ac:5: OUTER is expanded from...
+          configure.ac:8: the top level
+
+'--trace=MACRO[:FORMAT]'
+'-t MACRO[:FORMAT]'
+     Do not create the 'configure' script, but list the calls to MACRO
+     according to the FORMAT.  Multiple '--trace' arguments can be used
+     to list several macros.  Multiple '--trace' arguments for a single
+     macro are not cumulative; instead, you should just make FORMAT as
+     long as needed.
+
+     The FORMAT is a regular string, with newlines if desired, and
+     several special escape codes.  It defaults to '$f:$l:$n:$%'; see
+     below for details on the FORMAT.
+
+'--initialization'
+'-i'
+     By default, '--trace' does not trace the initialization of the
+     Autoconf macros (typically the 'AC_DEFUN' definitions).  This
+     results in a noticeable speedup, but can be disabled by this
+     option.
+
+   It is often necessary to check the content of a 'configure.ac' file,
+but parsing it yourself is extremely fragile and error-prone.  It is
+suggested that you rely upon '--trace' to scan 'configure.ac'.
+
+   The FORMAT of '--trace' can use the following special escapes:
+
+'$$'
+     The character '$'.
+
+'$f'
+     The filename from which MACRO is called.
+
+'$l'
+     The line number from which MACRO is called.
+
+'$d'
+     The depth of the MACRO call.  This is an M4 technical detail that
+     you probably don't want to know about.
+
+'$n'
+     The name of the MACRO.
+
+'$NUM'
+     The NUMth argument of the call to MACRO.
+
+'$@'
+'$SEP@'
+'${SEPARATOR}@'
+     All the arguments passed to MACRO, separated by the character SEP
+     or the string SEPARATOR (',' by default).  Each argument is quoted,
+     i.e.  enclosed in a pair of square brackets.
+
+'$*'
+'$SEP*'
+'${SEPARATOR}*'
+     As above, but the arguments are not quoted.
+
+'$%'
+'$SEP%'
+'${SEPARATOR}%'
+     As above, but the arguments are not quoted, all new line characters
+     in the arguments are smashed, and the default separator is ':'.
+
+     The escape '$%' produces single-line trace outputs (unless you put
+     newlines in the 'separator'), while '$@' and '$*' do not.
+
+   For instance, to find the list of variables that are substituted,
+use:
+
+     $ autoconf -t AC_SUBST
+     configure.ac:2:AC_SUBST:ECHO_C
+     configure.ac:2:AC_SUBST:ECHO_N
+     configure.ac:2:AC_SUBST:ECHO_T
+     More traces deleted
+
+The example below highlights the difference between '$@', '$*', and
+*$%*.
+
+     $ cat configure.ac
+     AC_DEFINE(This, is, [an
+     [example]])
+     $ autoconf -t 'AC_DEFINE:@: $@
+     *: $*
+     $: $%'
+     @: [This],[is],[an
+     [example]]
+     *: This,is,an
+     [example]
+     $: This:is:an [example]
+
+The FORMAT gives you a lot of freedom:
+
+     $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";'
+     $ac_subst{"ECHO_C"} = "configure.ac:2";
+     $ac_subst{"ECHO_N"} = "configure.ac:2";
+     $ac_subst{"ECHO_T"} = "configure.ac:2";
+     More traces deleted
+
+A long SEPARATOR can be used to improve the readability of complex
+structures, and to ease its parsing (for instance when no single
+character is suitable as a separator)):
+
+     $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*'
+     AUTOCONF|:::::|autoconf|:::::|$missing_dir
+     More traces deleted
+
+
+File: autoconf.info,  Node: autoreconf Invocation,  Prev: autoconf Invocation,  Up: Making configure Scripts
+
+3.5 Using 'autoreconf' to Update 'configure' Scripts
+====================================================
+
+If you have a lot of Autoconf-generated 'configure' scripts, the
+'autoreconf' program can save you some work.  It runs 'autoconf' (and
+'autoheader', where appropriate) repeatedly to remake the Autoconf
+'configure' scripts and configuration header templates in the directory
+tree rooted at the current directory.  By default, it only remakes those
+files that are older than their 'configure.ac' or (if present)
+'aclocal.m4'.  Since 'autoheader' does not change the timestamp of its
+output file if the file wouldn't be changing, this is not necessarily
+the minimum amount of work.  If you install a new version of Autoconf,
+you can make 'autoreconf' remake _all_ of the files by giving it the
+'--force' option.
+
+   If you give 'autoreconf' the '--autoconf-dir=DIR' or '--localdir=DIR'
+options, it passes them down to 'autoconf' and 'autoheader' (with
+relative paths adjusted properly).
+
+   'autoreconf' does not support having, in the same directory tree,
+both directories that are parts of a larger package (sharing
+'aclocal.m4' and 'acconfig.h') and directories that are independent
+packages (each with their own 'aclocal.m4' and 'acconfig.h').  It
+assumes that they are all part of the same package if you use
+'--localdir', or that each directory is a separate package if you don't
+use it.  This restriction may be removed in the future.
+
+   *Note Automatic Remaking::, for 'Makefile' rules to automatically
+remake 'configure' scripts when their source files change.  That method
+handles the timestamps of configuration header templates properly, but
+does not pass '--autoconf-dir=DIR' or '--localdir=DIR'.
+
+'autoreconf' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--verbose'
+     Print the name of each directory where 'autoreconf' runs 'autoconf'
+     (and 'autoheader', if appropriate).
+
+'--debug'
+'-d'
+     Don't remove the temporary files.
+
+'--force'
+'-f'
+     Remake even 'configure' scripts and configuration headers that are
+     newer than their input files ('configure.ac' and, if present,
+     'aclocal.m4').
+
+'--install'
+'-i'
+     Copy missing auxiliary files.  This option is similar to the option
+     '--add-missing' in other tools.
+
+'--symlink'
+'-s'
+     Instead of copying missing auxiliary files, install symbolic links.
+
+'--localdir=DIR'
+'-l DIR'
+     Have 'autoconf' and 'autoheader' look for the package files
+     'aclocal.m4' and ('autoheader' only) 'acconfig.h' (but not
+     'FILE.top' and 'FILE.bot') in directory DIR instead of in the
+     directory containing each 'configure.ac'.
+
+'--autoconf-dir=DIR'
+'-A DIR'
+     Override the location where the installed Autoconf data files are
+     looked for.  You can also set the 'AC_MACRODIR' environment
+     variable to a directory; this option overrides the environment
+     variable.
+
+     This option is rarely needed and dangerous; it is only used when
+     one plays with different versions of Autoconf simultaneously.
+
+'--m4dir=DIR'
+'-M DIR'
+     Specify location of additional macro files ('m4' by default).
+
+
+File: autoconf.info,  Node: Setup,  Next: Existing Tests,  Prev: Making configure Scripts,  Up: Top
+
+4 Initialization and Output Files
+*********************************
+
+Autoconf-generated 'configure' scripts need some information about how
+to initialize, such as how to find the package's source files; and about
+the output files to produce.  The following sections describe
+initialization and the creation of output files.
+
+* Menu:
+
+* Notices::                     Copyright, version numbers in 'configure'
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in 'Makefile's
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+
+
+File: autoconf.info,  Node: Notices,  Next: Input,  Prev: Setup,  Up: Setup
+
+4.1 Notices in 'configure'
+==========================
+
+The following macros manage version numbers for 'configure' scripts.
+Using them is optional.
+
+ -- Macro: AC_PREREQ (VERSION)
+     Ensure that a recent enough version of Autoconf is being used.  If
+     the version of Autoconf being used to create 'configure' is earlier
+     than VERSION, print an error message to the standard error output
+     and do not create 'configure'.  For example:
+
+          AC_PREREQ(2.52.20231210)
+
+     This macro is the only macro that may be used before 'AC_INIT', but
+     for consistency, you are invited not to do so.
+
+ -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE)
+     State that, in addition to the Free Software Foundation's copyright
+     on the Autoconf macros, parts of your 'configure' are covered by
+     the COPYRIGHT-NOTICE.
+
+     The COPYRIGHT-NOTICE will show up in both the head of 'configure'
+     and in 'configure --version'.
+
+ -- Macro: AC_REVISION (REVISION-INFO)
+     Copy revision stamp REVISION-INFO into the 'configure' script, with
+     any dollar signs or double-quotes removed.  This macro lets you put
+     a revision stamp from 'configure.ac' into 'configure' without RCS
+     or 'cvs' changing it when you check in 'configure'.  That way, you
+     can determine easily which revision of 'configure.ac' a particular
+     'configure' corresponds to.
+
+     For example, this line in 'configure.ac':
+
+          AC_REVISION($Revision: 1.77 $)
+
+     produces this in 'configure':
+
+          #! /bin/sh
+          # From configure.ac Revision: 1.30
+
+
+File: autoconf.info,  Node: Input,  Next: Output,  Prev: Notices,  Up: Setup
+
+4.2 Finding 'configure' Input
+=============================
+
+Every 'configure' script must call 'AC_INIT' before doing anything else.
+The only other required macro is 'AC_OUTPUT' (*note Output::).
+
+ -- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT-ADDRESS])
+     Process any command-line arguments and perform various
+     initializations and verifications.  Set the name of the PACKAGE and
+     its VERSION.  The optional argument BUG-REPORT-ADDRESS should be
+     the email to which users should send bug reports.
+
+ -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR)
+     UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's
+     source directory; 'configure' checks for this file's existence to
+     make sure that the directory that it is told contains the source
+     code in fact does.  Occasionally people accidentally specify the
+     wrong directory with '--srcdir'; this is a safety check.  *Note
+     configure Invocation::, for more information.
+
+   Packages that do manual configuration or use the 'install' program
+might need to tell 'configure' where to find some other shell scripts by
+calling 'AC_CONFIG_AUX_DIR', though the default places it looks are
+correct for most cases.
+
+ -- Macro: AC_CONFIG_AUX_DIR (DIR)
+     Use the auxiliary build tools (e.g., 'install-sh', 'config.sub',
+     'config.guess', Cygnus 'configure', Automake and Libtool scripts
+     etc.)  that are in directory DIR.  These are auxiliary files used
+     in configuration.  DIR can be either absolute or relative to
+     'SRCDIR'.  The default is 'SRCDIR' or 'SRCDIR/..' or
+     'SRCDIR/../..', whichever is the first that contains 'install-sh'.
+     The other files are not checked for, so that using
+     'AC_PROG_INSTALL' does not automatically require distributing the
+     other auxiliary files.  It checks for 'install.sh' also, but that
+     name is obsolete because some 'make' have a rule that creates
+     'install' from it if there is no 'Makefile'.
+
+
+File: autoconf.info,  Node: Output,  Next: Configuration Actions,  Prev: Input,  Up: Setup
+
+4.3 Outputting Files
+====================
+
+Every Autoconf-generated 'configure' script must finish by calling
+'AC_OUTPUT'.  It is the macro that generates 'config.status', which will
+create the 'Makefile's and any other files resulting from configuration.
+The only other required macro is 'AC_INIT' (*note Input::).
+
+ -- Macro: AC_OUTPUT
+     Generate 'config.status' and launch it.  Call this macro once, at
+     the end of 'configure.ac'.
+
+     'config.status' will take all the configuration actions: all the
+     output files (see *note Configuration Files::, macro
+     'AC_CONFIG_FILES'), header files (see *note Configuration
+     Headers::, macro 'AC_CONFIG_HEADERS'), commands (see *note
+     Configuration Commands::, macro 'AC_CONFIG_COMMANDS'), links (see
+     *note Configuration Links::, macro 'AC_CONFIG_LINKS'),
+     subdirectories to configure (see *note Subdirectories::, macro
+     'AC_CONFIG_SUBDIRS') are honored.
+
+   Historically, the usage of 'AC_OUTPUT' was somewhat different.  *Note
+Obsolete Macros::, for a description of the arguments that 'AC_OUTPUT'
+used to support.
+
+   If you run 'make' on subdirectories, you should run it using the
+'make' variable 'MAKE'.  Most versions of 'make' set 'MAKE' to the name
+of the 'make' program plus any options it was given.  (But many do not
+include in it the values of any variables set on the command line, so
+those are not passed on automatically.)  Some old versions of 'make' do
+not set this variable.  The following macro allows you to use it even
+with those versions.
+
+ -- Macro: AC_PROG_MAKE_SET
+     If 'make' predefines the variable 'MAKE', define output variable
+     'SET_MAKE' to be empty.  Otherwise, define 'SET_MAKE' to contain
+     'MAKE=make'.  Calls 'AC_SUBST' for 'SET_MAKE'.
+
+   To use this macro, place a line like this in each 'Makefile.in' that
+runs 'MAKE' on other directories:
+
+     @SET_MAKE@
+
+
+File: autoconf.info,  Node: Configuration Actions,  Next: Configuration Files,  Prev: Output,  Up: Setup
+
+4.4 Taking Configuration Actions
+================================
+
+'configure' is designed so that it appears to do everything itself, but
+there is actually a hidden slave: 'config.status'.  'configure' is in
+charge of examining your system, but it is 'config.status' that actually
+takes the proper actions based on the results of 'configure'.  The most
+typical task of 'config.status' is to _instantiate_ files.
+
+   This section describes the common behavior of the four standard
+instantiating macros: 'AC_CONFIG_FILES', 'AC_CONFIG_HEADERS',
+'AC_CONFIG_COMMANDS' and 'AC_CONFIG_LINKS'.  They all have this
+prototype:
+
+     AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS])
+
+where the arguments are:
+
+TAG...
+     A whitespace-separated list of tags, which are typically the names
+     of the files to instantiate.
+
+COMMANDS
+     Shell commands output literally into 'config.status', and
+     associated with a tag that the user can use to tell 'config.status'
+     which the commands to run.  The commands are run each time a TAG
+     request is given to 'config.status'; typically, each time the file
+     'TAG' is created.
+
+INIT-CMDS
+     Shell commands output _unquoted_ near the beginning of
+     'config.status', and executed each time 'config.status' runs
+     (regardless of the tag).  Because they are unquoted, for example,
+     '$var' will be output as the value of 'var'.  INIT-CMDS is
+     typically used by 'configure' to give 'config.status' some
+     variables it needs to run the COMMANDS.
+
+   All these macros can be called multiple times, with different TAGs,
+of course!
+
+   You are encouraged to use literals as TAGS.  In particular, you
+should avoid
+
+     ... && my_foos="$my_foos fooo"
+     ... && my_foos="$my_foos foooo"
+     AC_CONFIG_FOOS($my_foos)
+
+and use this instead:
+
+     ... && AC_CONFIG_FOOS(fooo)
+     ... && AC_CONFIG_FOOS(foooo)
+
+   The macro 'AC_CONFIG_FILES' and 'AC_CONFIG_HEADERS' use specials
+TAGs: they may have the form 'OUTPUT' or 'OUTPUT:INPUTS'.  The file
+OUTPUT is instantiated from its templates, INPUTS if specified,
+defaulting to 'OUTPUT.in'.
+
+   For instance 'AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)'
+asks for the creation of 'Makefile' that will be the expansion of the
+output variables in the concatenation of 'boiler/top.mk' and
+'boiler/bot.mk'.
+
+   The special value '-' might be used to denote the standard output
+when used in OUTPUT, or the standard input when used in the INPUTS.  You
+most probably don't need to use this in 'configure.ac', but it is
+convenient when using the command line interface of './config.status',
+see *note config.status Invocation::, for more details.
+
+   The INPUTS may be absolute or relative filenames.  In the latter case
+they are first looked for in the build tree, and then in the source
+tree.
+
+
+File: autoconf.info,  Node: Configuration Files,  Next: Makefile Substitutions,  Prev: Configuration Actions,  Up: Setup
+
+4.5 Creating Configuration Files
+================================
+
+Be sure to read the previous section, *note Configuration Actions::.
+
+ -- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS])
+     Make 'AC_OUTPUT' create each 'FILE' by copying an input file (by
+     default 'FILE.in'), substituting the output variable values.  This
+     macro is one of the instantiating macros, see *note Configuration
+     Actions::.  *Note Makefile Substitutions::, for more information on
+     using output variables.  *Note Setting Output Variables::, for more
+     information on creating them.  This macro creates the directory
+     that the file is in if it doesn't exist.  Usually, 'Makefile's are
+     created this way, but other files, such as '.gdbinit', can be
+     specified as well.
+
+     Typical calls to 'AC_CONFIG_FILES' look like this:
+
+          AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile)
+          AC_CONFIG_FILES(autoconf, chmod +x autoconf)
+
+     You can override an input file name by appending to FILE a
+     colon-separated list of input files.  Examples:
+
+          AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk
+                          lib/Makefile:boiler/lib.mk)
+
+     Doing this allows you to keep your file names acceptable to MS-DOS,
+     or to prepend and/or append boilerplate to the file.
+
+
+File: autoconf.info,  Node: Makefile Substitutions,  Next: Configuration Headers,  Prev: Configuration Files,  Up: Setup
+
+4.6 Substitutions in Makefiles
+==============================
+
+Each subdirectory in a distribution that contains something to be
+compiled or installed should come with a file 'Makefile.in', from which
+'configure' will create a 'Makefile' in that directory.  To create a
+'Makefile', 'configure' performs a simple variable substitution,
+replacing occurrences of '@VARIABLE@' in 'Makefile.in' with the value
+that 'configure' has determined for that variable.  Variables that are
+substituted into output files in this way are called "output variables".
+They are ordinary shell variables that are set in 'configure'.  To make
+'configure' substitute a particular variable into the output files, the
+macro 'AC_SUBST' must be called with that variable name as an argument.
+Any occurrences of '@VARIABLE@' for other variables are left unchanged.
+*Note Setting Output Variables::, for more information on creating
+output variables with 'AC_SUBST'.
+
+   A software package that uses a 'configure' script should be
+distributed with a file 'Makefile.in', but no 'Makefile'; that way, the
+user has to properly configure the package for the local system before
+compiling it.
+
+   *Note Makefile Conventions: (standards)Makefile Conventions, for more
+information on what to put in 'Makefile's.
+
+* Menu:
+
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+
+
+File: autoconf.info,  Node: Preset Output Variables,  Next: Installation Directory Variables,  Prev: Makefile Substitutions,  Up: Makefile Substitutions
+
+4.6.1 Preset Output Variables
+-----------------------------
+
+Some output variables are preset by the Autoconf macros.  Some of the
+Autoconf macros set additional output variables, which are mentioned in
+the descriptions for those macros.  *Note Output Variable Index::, for a
+complete list of output variables.  *Note Installation Directory
+Variables::, for the list of the preset ones related to installation
+directories.  Below are listed the other preset ones.  They all are
+precious variables (*note Setting Output Variables::, 'AC_ARG_VAR').
+
+ -- Variable: CFLAGS
+     Debugging and optimization options for the C compiler.  If it is
+     not set in the environment when 'configure' runs, the default value
+     is set when you call 'AC_PROG_CC' (or empty if you don't).
+     'configure' uses this variable when compiling programs to test for
+     C features.
+
+ -- Variable: configure_input
+     A comment saying that the file was generated automatically by
+     'configure' and giving the name of the input file.  'AC_OUTPUT'
+     adds a comment line containing this variable to the top of every
+     'Makefile' it creates.  For other files, you should reference this
+     variable in a comment at the top of each input file.  For example,
+     an input shell script should begin like this:
+
+          #! /bin/sh
+          # @configure_input@
+
+     The presence of that line also reminds people editing the file that
+     it needs to be processed by 'configure' in order to be used.
+
+ -- Variable: CPPFLAGS
+     Header file search directory ('-IDIR') and any other miscellaneous
+     options for the C and C++ preprocessors and compilers.  If it is
+     not set in the environment when 'configure' runs, the default value
+     is empty.  'configure' uses this variable when compiling or
+     preprocessing programs to test for C and C++ features.
+
+ -- Variable: CXXFLAGS
+     Debugging and optimization options for the C++ compiler.  If it is
+     not set in the environment when 'configure' runs, the default value
+     is set when you call 'AC_PROG_CXX' (or empty if you don't).
+     'configure' uses this variable when compiling programs to test for
+     C++ features.
+
+ -- Variable: DEFS
+     '-D' options to pass to the C compiler.  If 'AC_CONFIG_HEADERS' is
+     called, 'configure' replaces '@DEFS@' with '-DHAVE_CONFIG_H'
+     instead (*note Configuration Headers::).  This variable is not
+     defined while 'configure' is performing its tests, only when
+     creating the output files.  *Note Setting Output Variables::, for
+     how to check the results of previous tests.
+
+ -- Variable: ECHO_C
+ -- Variable: ECHO_N
+ -- Variable: ECHO_T
+     How does one suppress the trailing newline from 'echo' for
+     question-answer message pairs?  These variables provide a way:
+
+          echo $ECHO_N "And the winner is... $ECHO_C"
+          sleep 100000000000
+          echo "${ECHO_T}dead."
+
+     Some old and uncommon 'echo' implementations offer no means to
+     achieve this, in which case 'ECHO_T' is set to tab.  You might not
+     want to use it.
+
+ -- Variable: FFLAGS
+     Debugging and optimization options for the Fortran 77 compiler.  If
+     it is not set in the environment when 'configure' runs, the default
+     value is set when you call 'AC_PROG_F77' (or empty if you don't).
+     'configure' uses this variable when compiling programs to test for
+     Fortran 77 features.
+
+ -- Variable: LDFLAGS
+     Stripping ('-s'), path ('-L'), and any other miscellaneous options
+     for the linker.  Don't use this variable to pass library names
+     ('-l') to the linker, use 'LIBS' instead.  If it is not set in the
+     environment when 'configure' runs, the default value is empty.
+     'configure' uses this variable when linking programs to test for C,
+     C++ and Fortran 77 features.
+
+ -- Variable: LIBS
+     '-l' options to pass to the linker.  The default value is empty,
+     but some Autoconf macros may prepend extra libraries to this
+     variable if those libraries are found and provide necessary
+     functions, see *note Libraries::.  'configure' uses this variable
+     when linking programs to test for C, C++ and Fortran 77 features.
+
+ -- Variable: srcdir
+     The directory that contains the source code for that 'Makefile'.
+
+ -- Variable: top_srcdir
+     The top-level source code directory for the package.  In the
+     top-level directory, this is the same as 'srcdir'.
+
+
+File: autoconf.info,  Node: Installation Directory Variables,  Next: Build Directories,  Prev: Preset Output Variables,  Up: Makefile Substitutions
+
+4.6.2 Installation Directory Variables
+--------------------------------------
+
+The following variables specify the directories where the package will
+be installed, see *note Variables for Installation Directories:
+(standards)Directory Variables, for more information.  See the end of
+this section for details on when and how to use these variables.
+
+ -- Variable: bindir
+     The directory for installing executables that users run.
+
+ -- Variable: datadir
+     The directory for installing read-only architecture-independent
+     data.
+
+ -- Variable: exec_prefix
+     The installation prefix for architecture-dependent files.  By
+     default it's the same as PREFIX.  You should avoid installing
+     anything directly to EXEC_PREFIX.  However, the default value for
+     directories containing architecture-dependent files should be
+     relative to EXEC_PREFIX.
+
+ -- Variable: includedir
+     The directory for installing C header files.
+
+ -- Variable: infodir
+     The directory for installing documentation in Info format.
+
+ -- Variable: libdir
+     The directory for installing object code libraries.
+
+ -- Variable: libexecdir
+     The directory for installing executables that other programs run.
+
+ -- Variable: localstatedir
+     The directory for installing modifiable single-machine data.
+
+ -- Variable: mandir
+     The top-level directory for installing documentation in man format.
+
+ -- Variable: oldincludedir
+     The directory for installing C header files for non-gcc compilers.
+
+ -- Variable: prefix
+     The common installation prefix for all files.  If EXEC_PREFIX is
+     defined to a different value, PREFIX is used only for
+     architecture-independent files.
+
+ -- Variable: sbindir
+     The directory for installing executables that system administrators
+     run.
+
+ -- Variable: sharedstatedir
+     The directory for installing modifiable architecture-independent
+     data.
+
+ -- Variable: sysconfdir
+     The directory for installing read-only single-machine data.
+
+   Most of these variables have values that rely on 'prefix' or
+'exec_prefix'.  It is on purpose that the directory output variables
+keep them unexpanded: typically '@datadir@' will be replaced by
+'${prefix}/share', not '/usr/local/share'.
+
+   This behavior is mandated by the GNU coding standards, so that when
+the user runs:
+
+'make'
+     she can still specify a different prefix from the one specified to
+     'configure', in which case, if needed, the package shall hard code
+     dependencies to her late desires.
+
+'make install'
+     she can specify a different installation location, in which case
+     the package _must_ still depend on the location which was compiled
+     in (i.e., never recompile when 'make install' is run).  This is an
+     extremely important feature, as many people may decide to install
+     all the files of a package grouped together, and then install links
+     from the final locations to there.
+
+   In order to support these features, it is essential that 'datadir'
+remains being defined as '${prefix}/share' to depend upon the current
+value of 'prefix'.
+
+   A corollary is that you should not use these variables but in
+Makefiles.  For instance, instead of trying to evaluate 'datadir' in
+'configure' and hardcoding it in Makefiles using e.g.
+'AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add
+'-DDATADIR="$(datadir)"' to your 'CPPFLAGS'.
+
+   Similarly you should not rely on 'AC_OUTPUT_FILES' to replace
+'datadir' and friends in your shell scripts and other files, rather let
+'make' manage their replacement.  For instance Autoconf ships templates
+of its shell scripts ending with '.sh', and uses this Makefile snippet:
+
+     .sh:
+             rm -f $@ $@.tmp
+             sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp
+             chmod +x $@.tmp
+             mv $@.tmp $@
+
+   Three things are noteworthy:
+
+'@datadir\@'
+     The backslash prevents 'configure' from replacing '@datadir@' in
+     the sed expression itself.
+
+'$(pkgdatadir)'
+     Don't use '@pkgdatadir@'!  Use the matching makefile variable
+     instead.
+
+','
+     Don't use '/' in the sed expression(s) since most probably the
+     variables you use, such as '$(pkgdatadir)', will contain some.
+
+
+File: autoconf.info,  Node: Build Directories,  Next: Automatic Remaking,  Prev: Installation Directory Variables,  Up: Makefile Substitutions
+
+4.6.3 Build Directories
+-----------------------
+
+You can support compiling a software package for several architectures
+simultaneously from the same copy of the source code.  The object files
+for each architecture are kept in their own directory.
+
+   To support doing this, 'make' uses the 'VPATH' variable to find the
+files that are in the source directory.  GNU 'make' and most other
+recent 'make' programs can do this.  Older 'make' programs do not
+support 'VPATH'; when using them, the source code must be in the same
+directory as the object files.
+
+   To support 'VPATH', each 'Makefile.in' should contain two lines that
+look like:
+
+     srcdir = @srcdir@
+     VPATH = @srcdir@
+
+   Do not set 'VPATH' to the value of another variable, for example
+'VPATH = $(srcdir)', because some versions of 'make' do not do variable
+substitutions on the value of 'VPATH'.
+
+   'configure' substitutes in the correct value for 'srcdir' when it
+produces 'Makefile'.
+
+   Do not use the 'make' variable '$<', which expands to the file name
+of the file in the source directory (found with 'VPATH'), except in
+implicit rules.  (An implicit rule is one such as '.c.o', which tells
+how to create a '.o' file from a '.c' file.)  Some versions of 'make' do
+not set '$<' in explicit rules; they expand it to an empty value.
+
+   Instead, 'Makefile' command lines should always refer to source files
+by prefixing them with '$(srcdir)/'.  For example:
+
+     time.info: time.texinfo
+             $(MAKEINFO) $(srcdir)/time.texinfo
+
+
+File: autoconf.info,  Node: Automatic Remaking,  Prev: Build Directories,  Up: Makefile Substitutions
+
+4.6.4 Automatic Remaking
+------------------------
+
+You can put rules like the following in the top-level 'Makefile.in' for
+a package to automatically update the configuration information when you
+change the configuration files.  This example includes all of the
+optional files, such as 'aclocal.m4' and those related to configuration
+header files.  Omit from the 'Makefile.in' rules for any of these files
+that your package does not use.
+
+   The '$(srcdir)/' prefix is included because of limitations in the
+'VPATH' mechanism.
+
+   The 'stamp-' files are necessary because the timestamps of
+'config.h.in' and 'config.h' will not be changed if remaking them does
+not change their contents.  This feature avoids unnecessary
+recompilation.  You should include the file 'stamp-h.in' your package's
+distribution, so 'make' will consider 'config.h.in' up to date.  Don't
+use 'touch' (*note Limitations of Usual Tools::), rather use 'echo'
+(using 'date' would cause needless differences, hence CVS conflicts
+etc.).
+
+     $(srcdir)/configure: configure.ac aclocal.m4
+             cd $(srcdir) && autoconf
+
+     # autoheader might not change config.h.in, so touch a stamp file.
+     $(srcdir)/config.h.in: stamp-h.in
+     $(srcdir)/stamp-h.in: configure.ac aclocal.m4
+             cd $(srcdir) && autoheader
+             echo timestamp > $(srcdir)/stamp-h.in
+
+     config.h: stamp-h
+     stamp-h: config.h.in config.status
+             ./config.status
+
+     Makefile: Makefile.in config.status
+             ./config.status
+
+     config.status: configure
+             ./config.status --recheck
+
+(Be careful if you copy these lines directly into your Makefile, as you
+will need to convert the indented lines to start with the tab
+character.)
+
+   In addition, you should use 'AC_CONFIG_FILES(stamp-h, echo timestamp
+> stamp-h)' so 'config.status' will ensure that 'config.h' is considered
+up to date.  *Note Output::, for more information about 'AC_OUTPUT'.
+
+   *Note config.status Invocation::, for more examples of handling
+configuration-related dependencies.
+
+
+File: autoconf.info,  Node: Configuration Headers,  Next: Configuration Commands,  Prev: Makefile Substitutions,  Up: Setup
+
+4.7 Configuration Header Files
+==============================
+
+When a package tests more than a few C preprocessor symbols, the command
+lines to pass '-D' options to the compiler can get quite long.  This
+causes two problems.  One is that the 'make' output is hard to visually
+scan for errors.  More seriously, the command lines can exceed the
+length limits of some operating systems.  As an alternative to passing
+'-D' options to the compiler, 'configure' scripts can create a C header
+file containing '#define' directives.  The 'AC_CONFIG_HEADERS' macro
+selects this kind of output.  It should be called right after 'AC_INIT'.
+
+   The package should '#include' the configuration header file before
+any other header files, to prevent inconsistencies in declarations (for
+example, if it redefines 'const').  Use '#include <config.h>' instead of
+'#include "config.h"', and pass the C compiler a '-I.' option (or
+'-I..'; whichever directory contains 'config.h').  That way, even if the
+source directory is configured itself (perhaps to make a distribution),
+other build directories can also be configured without finding the
+'config.h' from the source directory.
+
+ -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS])
+     This macro is one of the instantiating macros, see *note
+     Configuration Actions::.  Make 'AC_OUTPUT' create the file(s) in
+     the whitespace-separated list HEADER containing C preprocessor
+     '#define' statements, and replace '@DEFS@' in generated files with
+     '-DHAVE_CONFIG_H' instead of the value of 'DEFS'.  The usual name
+     for HEADER is 'config.h'.
+
+     If HEADER already exists and its contents are identical to what
+     'AC_OUTPUT' would put in it, it is left alone.  Doing this allows
+     some changes in configuration without needlessly causing object
+     files that depend on the header file to be recompiled.
+
+     Usually the input file is named 'HEADER.in'; however, you can
+     override the input file name by appending to HEADER, a
+     colon-separated list of input files.  Examples:
+
+          AC_CONFIG_HEADERS(config.h:config.hin)
+          AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post)
+
+     Doing this allows you to keep your file names acceptable to MS-DOS,
+     or to prepend and/or append boilerplate to the file.
+
+   *Note Configuration Actions::, for more details on HEADER.
+
+* Menu:
+
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+
+
+File: autoconf.info,  Node: Header Templates,  Next: autoheader Invocation,  Prev: Configuration Headers,  Up: Configuration Headers
+
+4.7.1 Configuration Header Templates
+------------------------------------
+
+Your distribution should contain a template file that looks as you want
+the final header file to look, including comments, with '#undef'
+statements which are used as hooks.  For example, suppose your
+'configure.ac' makes these calls:
+
+     AC_CONFIG_HEADERS(conf.h)
+     AC_CHECK_HEADERS(unistd.h)
+
+Then you could have code like the following in 'conf.h.in'.  On systems
+that have 'unistd.h', 'configure' will '#define' 'HAVE_UNISTD_H' to 1.
+On other systems, the whole line will be commented out (in case the
+system predefines that symbol).
+
+     /* Define as 1 if you have unistd.h.  */
+     #undef HAVE_UNISTD_H
+
+   You can then decode the configuration header using the preprocessor
+directives:
+
+     #include <conf.h>
+
+     #if HAVE_UNISTD_H
+     # include <unistd.h>
+     #else
+     /* We are in trouble. */
+     #endif
+
+   The use of old form templates, with '#define' instead of '#undef' is
+strongly discouraged.
+
+   Since it is a tedious task to keep a template header up to date, you
+may use 'autoheader' to generate it, see *note autoheader Invocation::.
+
+
+File: autoconf.info,  Node: autoheader Invocation,  Next: Autoheader Macros,  Prev: Header Templates,  Up: Configuration Headers
+
+4.7.2 Using 'autoheader' to Create 'config.h.in'
+------------------------------------------------
+
+The 'autoheader' program can create a template file of C '#define'
+statements for 'configure' to use.  If 'configure.ac' invokes
+'AC_CONFIG_HEADERS(FILE)', 'autoheader' creates 'FILE.in'; if multiple
+file arguments are given, the first one is used.  Otherwise,
+'autoheader' creates 'config.h.in'.
+
+   In order to do its job, 'autoheader' needs you to document all of the
+symbols that you might use; i.e., there must be at least one 'AC_DEFINE'
+or one 'AC_DEFINE_UNQUOTED' using its third argument for each symbol
+(*note Defining Symbols::).  An additional constraint is that the first
+argument of 'AC_DEFINE' must be a literal.  Note that all symbols
+defined by Autoconf's built-in tests are already documented properly;
+you only need to document those that you define yourself.
+
+   You might wonder why 'autoheader' is needed: after all, why would
+'configure' need to "patch" a 'config.h.in' to produce a 'config.h'
+instead of just creating 'config.h' from scratch?  Well, when everything
+rocks, the answer is just that we are wasting our time maintaining
+'autoheader': generating 'config.h' directly is all that is needed.
+When things go wrong, however, you'll be thankful for the existence of
+'autoheader'.
+
+   The fact that the symbols are documented is important in order to
+_check_ that 'config.h' makes sense.  The fact that there is a well
+defined list of symbols that should be '#define''d (or not) is also
+important for people who are porting packages to environments where
+'configure' cannot be run: they just have to _fill in the blanks_.
+
+   But let's come back to the point: 'autoheader''s invocation...
+
+   If you give 'autoheader' an argument, it uses that file instead of
+'configure.ac' and writes the header file to the standard output instead
+of to 'config.h.in'.  If you give 'autoheader' an argument of '-', it
+reads the standard input instead of 'configure.ac' and writes the header
+file to the standard output.
+
+   'autoheader' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--debug'
+'-d'
+     Don't remove the temporary files.
+
+'--verbose'
+'-v'
+     Report processing steps.
+
+'--autoconf-dir=DIR'
+'-A DIR'
+     Override the location where the installed Autoconf data files are
+     looked for.  You can also set the 'AC_MACRODIR' environment
+     variable to a directory; this option overrides the environment
+     variable.
+
+     This option is rarely needed and dangerous; it is only used when
+     one plays with different versions of Autoconf simultaneously.
+
+'--localdir=DIR'
+'-l DIR'
+     Look for the package files 'aclocal.m4' and 'acconfig.h' (but not
+     'FILE.top' and 'FILE.bot') in directory DIR instead of in the
+     current directory.
+
+'--warnings=CATEGORY'
+'-W CATEGORY'
+     Report the warnings related to CATEGORY (which can actually be a
+     comma separated list).  Current categories include:
+
+     'obsolete'
+          report the uses of obsolete constructs
+
+     'all'
+          report all the warnings
+
+     'none'
+          report none
+
+     'error'
+          treats warnings as errors
+
+     'no-CATEGORY'
+          disable warnings falling into CATEGORY
+
+
+File: autoconf.info,  Node: Autoheader Macros,  Prev: autoheader Invocation,  Up: Configuration Headers
+
+4.7.3 Autoheader Macros
+-----------------------
+
+'autoheader' scans 'configure.ac' and figures out which C preprocessor
+symbols it might define.  It knows how to generate templates for symbols
+defined by 'AC_CHECK_HEADERS', 'AC_CHECK_FUNCS' etc., but if you
+'AC_DEFINE' any additional symbol, you must define a template for it.
+If there are missing templates, 'autoheader' fails with an error
+message.
+
+   The simplest way to create a template for a SYMBOL is to supply the
+DESCRIPTION argument to an 'AC_DEFINE(SYMBOL)'; see *note Defining
+Symbols::.  You may also use one of the following macros.
+
+ -- Macro: AH_VERBATIM (KEY, TEMPLATE)
+     Tell 'autoheader' to include the TEMPLATE as-is in the header
+     template file.  This TEMPLATE is associated with the KEY, which is
+     used to sort all the different templates and guarantee their
+     uniqueness.  It should be the symbol that can be 'AC_DEFINE''d.
+
+     For example:
+
+          AH_VERBATIM([_GNU_SOURCE],
+          [/* Enable GNU extensions on systems that have them.  */
+          #ifndef _GNU_SOURCE
+          # define _GNU_SOURCE
+          #endif])
+
+ -- Macro: AH_TEMPLATE (KEY, DESCRIPTION)
+     Tell 'autoheader' to generate a template for KEY.  This macro
+     generates standard templates just like 'AC_DEFINE' when a
+     DESCRIPTION is given.
+
+     For example:
+
+          AH_TEMPLATE([CRAY_STACKSEG_END],
+                      [Define to one of _getb67, GETB67, getb67
+                       for Cray-2 and Cray-YMP systems.  This
+                       function is required for alloca.c support
+                       on those systems.])
+
+     will generate the following template, with the description properly
+     justified.
+
+          /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
+             Cray-YMP systems. This function is required for alloca.c
+             support on those systems. */
+          #undef CRAY_STACKSEG_END
+
+ -- Macro: AH_TOP (TEXT)
+     Include TEXT at the top of the header template file.
+
+ -- Macro: AH_BOTTOM (TEXT)
+     Include TEXT at the bottom of the header template file.
+
+
+File: autoconf.info,  Node: Configuration Commands,  Next: Configuration Links,  Prev: Configuration Headers,  Up: Setup
+
+4.8 Running Arbitrary Configuration Commands
+============================================
+
+You execute arbitrary commands either before, during and after
+'config.status' is run.  The three following macros accumulate the
+commands to run when they are called multiple times.
+'AC_CONFIG_COMMANDS' replaces the obsolete macro 'AC_OUTPUT_COMMANDS',
+see *note Obsolete Macros::, for details.
+
+ -- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS])
+     Specify additional shell commands to run at the end of
+     'config.status', and shell commands to initialize any variables
+     from 'configure'.  Associate the commands to the TAG.  Since
+     typically the CMDS create a file, TAG should naturally be the name
+     of that file.  This macro is one of the instantiating macros, see
+     *note Configuration Actions::.
+
+     Here is an unrealistic example:
+          fubar=42
+          AC_CONFIG_COMMANDS(fubar,
+                             [echo this is extra $fubar, and so on.],
+                             [fubar=$fubar])
+
+     Here is a better one:
+          AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp])
+
+ -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS)
+     Execute the CMDS right before creating 'config.status'.  A typical
+     use is computing values derived from variables built during the
+     execution of 'configure':
+
+          AC_CONFIG_COMMANDS_PRE(
+          [LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
+          AC_SUBST(LTLIBOBJS)])
+
+ -- Macro: AC_CONFIG_COMMANDS_POST (CMDS)
+     Execute the CMDS right after creating 'config.status'.
+
+
+File: autoconf.info,  Node: Configuration Links,  Next: Subdirectories,  Prev: Configuration Commands,  Up: Setup
+
+4.9 Creating Configuration Links
+================================
+
+You may find it convenient to create links whose destinations depend
+upon results of tests.  One can use 'AC_CONFIG_COMMANDS' but the
+creation of relative symbolic links can be delicate when the package is
+built in another directory than its sources.
+
+ -- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS])
+     Make 'AC_OUTPUT' link each of the existing files SOURCE to the
+     corresponding link name DEST.  Makes a symbolic link if possible,
+     otherwise a hard link.  The DEST and SOURCE names should be
+     relative to the top level source or build directory.  This macro is
+     one of the instantiating macros, see *note Configuration Actions::.
+
+     For example, this call:
+
+          AC_CONFIG_LINKS(host.h:config/$machine.h
+                          object.h:config/$obj_format.h)
+
+     creates in the current directory 'host.h' as a link to
+     'SRCDIR/config/$machine.h', and 'object.h' as a link to
+     'SRCDIR/config/$obj_format.h'.
+
+     The tempting value '.' for DEST is invalid: it makes it impossible
+     for 'config.status' to guess the links to establish.
+
+     One can then run:
+          ./config.status host.h object.h
+     to create the links.
+
+
+File: autoconf.info,  Node: Subdirectories,  Next: Default Prefix,  Prev: Configuration Links,  Up: Setup
+
+4.10 Configuring Other Packages in Subdirectories
+=================================================
+
+In most situations, calling 'AC_OUTPUT' is sufficient to produce
+'Makefile's in subdirectories.  However, 'configure' scripts that
+control more than one independent package can use 'AC_CONFIG_SUBDIRS' to
+run 'configure' scripts for other packages in subdirectories.
+
+ -- Macro: AC_CONFIG_SUBDIRS (DIR ...)
+     Make 'AC_OUTPUT' run 'configure' in each subdirectory DIR in the
+     given whitespace-separated list.  Each DIR should be a literal,
+     i.e., please do not use:
+
+          if test "$package_foo_enabled" = yes; then
+            $my_subdirs="$my_subdirs foo"
+          fi
+          AC_CONFIG_SUBDIRS($my_subdirs)
+
+     because this prevents './configure --help=recursive' from
+     displaying the options of the package 'foo'.  Rather, you should
+     write:
+
+          if test "$package_foo_enabled" = yes then;
+            AC_CONFIG_SUBDIRS(foo)
+          fi
+
+     If a given DIR is not found, no error is reported, so a 'configure'
+     script can configure whichever parts of a large source tree are
+     present.  If a given DIR contains 'configure.gnu', it is run
+     instead of 'configure'.  This is for packages that might use a
+     non-autoconf script 'Configure', which can't be called through a
+     wrapper 'configure' since it would be the same file on
+     case-insensitive filesystems.  Likewise, if a DIR contains
+     'configure.ac' but no 'configure', the Cygnus 'configure' script
+     found by 'AC_CONFIG_AUX_DIR' is used.
+
+     The subdirectory 'configure' scripts are given the same command
+     line options that were given to this 'configure' script, with minor
+     changes if needed (e.g., to adjust a relative path for the cache
+     file or source directory).  This macro also sets the output
+     variable 'subdirs' to the list of directories 'DIR ...'.
+     'Makefile' rules can use this variable to determine which
+     subdirectories to recurse into.  This macro may be called multiple
+     times.
+
+
+File: autoconf.info,  Node: Default Prefix,  Prev: Subdirectories,  Up: Setup
+
+4.11 Default Prefix
+===================
+
+By default, 'configure' sets the prefix for files it installs to
+'/usr/local'.  The user of 'configure' can select a different prefix
+using the '--prefix' and '--exec-prefix' options.  There are two ways to
+change the default: when creating 'configure', and when running it.
+
+   Some software packages might want to install in a directory besides
+'/usr/local' by default.  To accomplish that, use the
+'AC_PREFIX_DEFAULT' macro.
+
+ -- Macro: AC_PREFIX_DEFAULT (PREFIX)
+     Set the default installation prefix to PREFIX instead of
+     '/usr/local'.
+
+   It may be convenient for users to have 'configure' guess the
+installation prefix from the location of a related program that they
+have already installed.  If you wish to do that, you can call
+'AC_PREFIX_PROGRAM'.
+
+ -- Macro: AC_PREFIX_PROGRAM (PROGRAM)
+     If the user did not specify an installation prefix (using the
+     '--prefix' option), guess a value for it by looking for PROGRAM in
+     'PATH', the way the shell does.  If PROGRAM is found, set the
+     prefix to the parent of the directory containing PROGRAM; otherwise
+     leave the prefix specified in 'Makefile.in' unchanged.  For
+     example, if PROGRAM is 'gcc' and the 'PATH' contains
+     '/usr/local/gnu/bin/gcc', set the prefix to '/usr/local/gnu'.
+
+
+File: autoconf.info,  Node: Existing Tests,  Next: Writing Tests,  Prev: Setup,  Up: Top
+
+5 Existing Tests
+****************
+
+These macros test for particular system features that packages might
+need or want to use.  If you need to test for a kind of feature that
+none of these macros check for, you can probably do it by calling
+primitive test macros with appropriate arguments (*note Writing
+Tests::).
+
+   These tests print messages telling the user which feature they're
+checking for, and what they find.  They cache their results for future
+'configure' runs (*note Caching Results::).
+
+   Some of these macros set output variables.  *Note Makefile
+Substitutions::, for how to get their values.  The phrase "define NAME"
+is used below as a shorthand to mean "define C preprocessor symbol NAME
+to the value 1".  *Note Defining Symbols::, for how to get those symbol
+definitions into your program.
+
+* Menu:
+
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+
+
+File: autoconf.info,  Node: Common Behavior,  Next: Alternative Programs,  Prev: Existing Tests,  Up: Existing Tests
+
+5.1 Common Behavior
+===================
+
+Much effort has been expended to make Autoconf easy to learn.  The most
+obvious way to reach this goal is simply to enforce standard interfaces
+and behaviors, avoiding exceptions as much as possible.  Because of
+history and inertia, unfortunately, there are still too many exceptions
+in Autoconf; nevertheless, this section describes some of the common
+rules.
+
+* Menu:
+
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+
+
+File: autoconf.info,  Node: Standard Symbols,  Next: Default Includes,  Prev: Common Behavior,  Up: Common Behavior
+
+5.1.1 Standard Symbols
+----------------------
+
+All the generic macros that 'AC_DEFINE' a symbol as a result of their
+test transform their ARGUMENTs to a standard alphabet.  First, ARGUMENT
+is converted to upper case and any asterisks ('*') are each converted to
+'P'.  Any remaining characters that are not alphanumeric are converted
+to underscores.
+
+   For instance,
+
+     AC_CHECK_TYPES(struct $Expensive*)
+
+will define the symbol 'HAVE_STRUCT__EXPENSIVEP' if the check succeeds.
+
+
+File: autoconf.info,  Node: Default Includes,  Prev: Standard Symbols,  Up: Common Behavior
+
+5.1.2 Default Includes
+----------------------
+
+Several tests depend upon a set of header files.  Since these headers
+are not universally available, tests actually have to provide a set of
+protected includes, such as:
+
+     #if TIME_WITH_SYS_TIME
+     # include <sys/time.h>
+     # include <time.h>
+     #else
+     # if HAVE_SYS_TIME_H
+     #  include <sys/time.h>
+     # else
+     #  include <time.h>
+     # endif
+     #endif
+
+Unless you know exactly what you are doing, you should avoid using
+unconditional includes, and check the existence of the headers you
+include beforehand (*note Header Files::).
+
+   Most generic macros provide the following default set of includes:
+
+     #include <stdio.h>
+     #if HAVE_SYS_TYPES_H
+     # include <sys/types.h>
+     #endif
+     #if HAVE_SYS_STAT_H
+     # include <sys/stat.h>
+     #endif
+     #if STDC_HEADERS
+     # include <stdlib.h>
+     # include <stddef.h>
+     #else
+     # if HAVE_STDLIB_H
+     #  include <stdlib.h>
+     # endif
+     #endif
+     #if HAVE_STRING_H
+     # if !STDC_HEADERS && HAVE_MEMORY_H
+     #  include <memory.h>
+     # endif
+     # include <string.h>
+     #endif
+     #if HAVE_STRINGS_H
+     # include <strings.h>
+     #endif
+     #if HAVE_INTTYPES_H
+     # include <inttypes.h>
+     #else
+     # if HAVE_STDINT_H
+     #  include <stdint.h>
+     # endif
+     #endif
+     #if HAVE_UNISTD_H
+     # include <unistd.h>
+     #endif
+
+   If the default includes are used, then Autoconf will automatically
+check for the presence of these headers and their compatibility, i.e.,
+you don't need to run 'AC_HEADERS_STDC', nor check for 'stdlib.h' etc.
+
+   These headers are checked for in the same order as they are included.
+For instance, on some systems 'string.h' and 'strings.h' both exist, but
+conflict.  Then 'HAVE_STRING_H' will be defined, but 'HAVE_STRINGS_H'
+won't.
+
+
+File: autoconf.info,  Node: Alternative Programs,  Next: Files,  Prev: Common Behavior,  Up: Existing Tests
+
+5.2 Alternative Programs
+========================
+
+These macros check for the presence or behavior of particular programs.
+They are used to choose between several alternative programs and to
+decide what to do once one has been chosen.  If there is no macro
+specifically defined to check for a program you need, and you don't need
+to check for any special properties of it, then you can use one of the
+general program-check macros.
+
+* Menu:
+
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+
+
+File: autoconf.info,  Node: Particular Programs,  Next: Generic Programs,  Prev: Alternative Programs,  Up: Alternative Programs
+
+5.2.1 Particular Program Checks
+-------------------------------
+
+These macros check for particular programs--whether they exist, and in
+some cases whether they support certain features.
+
+ -- Macro: AC_PROG_AWK
+     Check for 'mawk', 'gawk', 'nawk', and 'awk', in that order, and set
+     output variable 'AWK' to the first one that is found.  It tries
+     'mawk' first because that is reported to be the fastest
+     implementation.
+
+ -- Macro: AC_PROG_EGREP
+     Check for 'grep -E', 'egrep' in that order, and set output variable
+     'EGREP' to the first one that is found.
+
+ -- Macro: AC_PROG_FGREP
+     Check for 'grep -F', 'fgrep' in that order, and set output variable
+     'FGREP' to the first one that is found.
+
+ -- Macro: AC_PROG_GREP
+     Check for 'grep', 'ggrep' in that order, and set output variable
+     'GREP' to the first one that is found.
+
+ -- Macro: AC_PROG_INSTALL
+     Set output variable 'INSTALL' to the path of a BSD compatible
+     'install' program, if one is found in the current 'PATH'.
+     Otherwise, set 'INSTALL' to 'DIR/install-sh -c', checking the
+     directories specified to 'AC_CONFIG_AUX_DIR' (or its default
+     directories) to determine DIR (*note Output::).  Also set the
+     variables 'INSTALL_PROGRAM' and 'INSTALL_SCRIPT' to '${INSTALL}'
+     and 'INSTALL_DATA' to '${INSTALL} -m 644'.
+
+     This macro screens out various instances of 'install' known not to
+     work.  It prefers to find a C program rather than a shell script,
+     for speed.  Instead of 'install-sh', it can also use 'install.sh',
+     but that name is obsolete because some 'make' programs have a rule
+     that creates 'install' from it if there is no 'Makefile'.
+
+     Autoconf comes with a copy of 'install-sh' that you can use.  If
+     you use 'AC_PROG_INSTALL', you must include either 'install-sh' or
+     'install.sh' in your distribution, or 'configure' will produce an
+     error message saying it can't find them--even if the system you're
+     on has a good 'install' program.  This check is a safety measure to
+     prevent you from accidentally leaving that file out, which would
+     prevent your package from installing on systems that don't have a
+     BSD-compatible 'install' program.
+
+     If you need to use your own installation program because it has
+     features not found in standard 'install' programs, there is no
+     reason to use 'AC_PROG_INSTALL'; just put the file name of your
+     program into your 'Makefile.in' files.
+
+ -- Macro: AC_PROG_LEX
+     If 'flex' is found, set output variable 'LEX' to 'flex' and
+     'LEXLIB' to '-lfl', if that library is in a standard place.
+     Otherwise set 'LEX' to 'lex' and 'LEXLIB' to '-ll'.
+
+     Define 'YYTEXT_POINTER' if 'yytext' is a 'char *' instead of a
+     'char []'.  Also set output variable 'LEX_OUTPUT_ROOT' to the base
+     of the file name that the lexer generates; usually 'lex.yy', but
+     sometimes something else.  These results vary according to whether
+     'lex' or 'flex' is being used.
+
+     You are encouraged to use Flex in your sources, since it is both
+     more pleasant to use than plain Lex and the C source it produces is
+     portable.  In order to ensure portability, however, you must either
+     provide a function 'yywrap' or, if you don't use it (e.g., your
+     scanner has no '#include'-like feature), simply include a
+     '%noyywrap' statement in the scanner's source.  Once this done, the
+     scanner is portable (unless _you_ felt free to use nonportable
+     constructs) and does not depend on any library.  In this case, and
+     in this case only, it is suggested that you use this Autoconf
+     snippet:
+
+          AC_PROG_LEX
+          if test "$LEX" != flex; then
+            LEX="$SHELL $missing_dir/missing flex"
+            AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
+            AC_SUBST(LEXLIB, '')
+          fi
+
+     The shell script 'missing' can be found in the Automake
+     distribution.
+
+     To ensure backward compatibility, Automake's 'AM_PROG_LEX' invokes
+     (indirectly) this macro twice, which will cause an annoying but
+     benign "'AC_PROG_LEX' invoked multiple times" warning.  Future
+     versions of Automake will fix this issue, meanwhile, just ignore
+     this message.
+
+ -- Macro: AC_PROG_LN_S
+     If 'ln -s' works on the current file system (the operating system
+     and file system support symbolic links), set the output variable
+     'LN_S' to 'ln -s'; otherwise, if 'ln' works, set 'LN_S' to 'ln' and
+     otherwise set it to 'cp -p'.
+
+     If you make a link a directory other than the current directory,
+     its meaning depends on whether 'ln' or 'ln -s' is used.  To safely
+     create links using '$(LN_S)', either find out which form is used
+     and adjust the arguments, or always invoke 'ln' in the directory
+     where the link is to be created.
+
+     In other words, it does not work to do:
+          $(LN_S) foo /x/bar
+
+     Instead, do:
+
+          (cd /x && $(LN_S) foo bar)
+
+ -- Macro: AC_PROG_RANLIB
+     Set output variable 'RANLIB' to 'ranlib' if 'ranlib' is found, and
+     otherwise to ':' (do nothing).
+
+ -- Macro: AC_PROG_YACC
+     If 'byacc' is found, set 'YACC' to 'byacc'.  Otherwise, if 'bison'
+     is found, set output variable 'YACC' to 'bison -y'.  Finally, if
+     neither 'byacc' or 'bison' is found, set 'YACC' to 'yacc'.
+
+
+File: autoconf.info,  Node: Generic Programs,  Prev: Particular Programs,  Up: Alternative Programs
+
+5.2.2 Generic Program and File Checks
+-------------------------------------
+
+These macros are used to find programs not covered by the "particular"
+test macros.  If you need to check the behavior of a program as well as
+find out whether it is present, you have to write your own test for it
+(*note Writing Tests::).  By default, these macros use the environment
+variable 'PATH'.  If you need to check for a program that might not be
+in the user's 'PATH', you can pass a modified path to use instead, like
+this:
+
+     AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd,
+       $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc)
+
+   You are strongly encouraged to declare the VARIABLE passed to
+'AC_CHECK_PROG' etc.  as precious, *Note Setting Output Variables::,
+'AC_ARG_VAR', for more details.
+
+ -- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND,
+          [VALUE-IF-NOT-FOUND], [PATH], [REJECT])
+     Check whether program PROG-TO-CHECK-FOR exists in 'PATH'.  If it is
+     found, set VARIABLE to VALUE-IF-FOUND, otherwise to
+     VALUE-IF-NOT-FOUND, if given.  Always pass over REJECT (an absolute
+     file name) even if it is the first found in the search path; in
+     that case, set VARIABLE using the absolute file name of the
+     PROG-TO-CHECK-FOR found that is not REJECT.  If VARIABLE was
+     already set, do nothing.  Calls 'AC_SUBST' for VARIABLE.
+
+ -- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Check for each program in the whitespace-separated list
+     PROGS-TO-CHECK-FOR exists on the 'PATH'.  If it is found, set
+     VARIABLE to the name of that program.  Otherwise, continue checking
+     the next program in the list.  If none of the programs in the list
+     are found, set VARIABLE to VALUE-IF-NOT-FOUND; if
+     VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not
+     changed.  Calls 'AC_SUBST' for VARIABLE.
+
+ -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Like 'AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a
+     prefix of the host type as determined by 'AC_CANONICAL_HOST',
+     followed by a dash (*note Canonicalizing::).  For example, if the
+     user runs 'configure --host=i386-gnu', then this call:
+          AC_CHECK_TOOL(RANLIB, ranlib, :)
+     sets 'RANLIB' to 'i386-gnu-ranlib' if that program exists in
+     'PATH', or otherwise to 'ranlib' if that program exists in 'PATH',
+     or to ':' if neither program exists.
+
+ -- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Like 'AC_CHECK_TOOL', each of the tools in the list
+     PROGS-TO-CHECK-FOR are checked with a prefix of the host type as
+     determined by 'AC_CANONICAL_HOST', followed by a dash (*note
+     Canonicalizing::).  If none of the tools can be found with a
+     prefix, then the first one without a prefix is used.  If a tool is
+     found, set VARIABLE to the name of that program.  If none of the
+     tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if
+     VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not
+     changed.  Calls 'AC_SUBST' for VARIABLE.
+
+ -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Like 'AC_CHECK_PROG', but set VARIABLE to the entire path of
+     PROG-TO-CHECK-FOR if found.
+
+ -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Like 'AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found,
+     set VARIABLE to the entire path of the program found.
+
+ -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR,
+          [VALUE-IF-NOT-FOUND], [PATH])
+     Like 'AC_CHECK_TOOL', but set VARIABLE to the entire path of the
+     program if it is found.
+
+
+File: autoconf.info,  Node: Files,  Next: Libraries,  Prev: Alternative Programs,  Up: Existing Tests
+
+5.3 Files
+=========
+
+You might also need to check for the existence of files.  Before using
+these macros, ask yourself whether a run time test might not be a better
+solution.  Be aware that, like most Autoconf macros, they test a feature
+of the host machine, and therefore, they die when cross-compiling.
+
+ -- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Check whether file FILE exists on the native system.  If it is
+     found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND,
+     if given.
+
+ -- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Executes 'AC_CHECK_FILE' once for each file listed in FILES.
+     Additionally, defines 'HAVE_FILE' (*note Standard Symbols::) for
+     each file found.
+
+
+File: autoconf.info,  Node: Libraries,  Next: Library Functions,  Prev: Files,  Up: Existing Tests
+
+5.4 Library Files
+=================
+
+The following macros check for the presence of certain C, C++ or Fortran
+77 library archive files.
+
+ -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES])
+     Depending on the current language(*note Language Choice::), try to
+     ensure that the C, C++, or Fortran 77 function FUNCTION is
+     available by checking whether a test program can be linked with the
+     library LIBRARY to get the function.  LIBRARY is the base name of
+     the library; e.g., to check for '-lmp', use 'mp' as the LIBRARY
+     argument.
+
+     ACTION-IF-FOUND is a list of shell commands to run if the link with
+     the library succeeds; ACTION-IF-NOT-FOUND is a list of shell
+     commands to run if the link fails.  If ACTION-IF-FOUND is not
+     specified, the default action will prepend '-lLIBRARY' to 'LIBS'
+     and define 'HAVE_LIBLIBRARY' (in all capitals).  This macro is
+     intended to support building of 'LIBS' in a right-to-left
+     (least-dependent to most-dependent) fashion such that library
+     dependencies are satisfied as a natural side-effect of consecutive
+     tests.  Some linkers are very sensitive to library ordering so the
+     order in which 'LIBS' is generated is important to reliable
+     detection of libraries.
+
+     If linking with LIBRARY results in unresolved symbols that would be
+     resolved by linking with additional libraries, give those libraries
+     as the OTHER-LIBRARIES argument, separated by spaces: e.g.  '-lXt
+     -lX11'.  Otherwise, this macro will fail to detect that LIBRARY is
+     present, because linking the test program will always fail with
+     unresolved symbols.  The OTHER-LIBRARIES argument should be limited
+     to cases where it is desirable to test for one library in the
+     presence of another that is not already in 'LIBS'.
+
+ -- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES])
+     Search for a library defining FUNCTION if it's not already
+     available.  This equates to calling 'AC_TRY_LINK_FUNC' first with
+     no libraries, then for each library listed in SEARCH-LIBS.
+
+     Add '-lLIBRARY' to 'LIBS' for the first library found to contain
+     FUNCTION, and run ACTION-IF-FOUND.  If the function is not found,
+     run ACTION-IF-NOT-FOUND.
+
+     If linking with LIBRARY results in unresolved symbols that would be
+     resolved by linking with additional libraries, give those libraries
+     as the OTHER-LIBRARIES argument, separated by spaces: e.g.  '-lXt
+     -lX11'.  Otherwise, this macro will fail to detect that FUNCTION is
+     present, because linking the test program will always fail with
+     unresolved symbols.
+
+
+File: autoconf.info,  Node: Library Functions,  Next: Header Files,  Prev: Libraries,  Up: Existing Tests
+
+5.5 Library Functions
+=====================
+
+The following macros check for particular C library functions.  If there
+is no macro specifically defined to check for a function you need, and
+you don't need to check for any special properties of it, then you can
+use one of the general function-check macros.
+
+* Menu:
+
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+
+
+File: autoconf.info,  Node: Function Portability,  Next: Particular Functions,  Prev: Library Functions,  Up: Library Functions
+
+5.5.1 Portability of Classical Functions
+----------------------------------------
+
+Most usual functions can either be missing, or be buggy, or be limited
+on some architectures.  This section tries to make an inventory of these
+portability issues.  By definition, this list will always require
+additions, please help us keeping it as complete as possible
+
+'unlink'
+     The POSIX spec says that 'unlink' causes the given files to be
+     removed only after there are no more open file handles for it.  Not
+     all OS's support this behaviour though.  So even on systems that
+     provide 'unlink', you cannot portably assume it is OK to call it on
+     files that are open.  For example, on Windows 9x and ME, such a
+     call would fail; on DOS it could even lead to file system
+     corruption, as the file might end up being written to after the OS
+     has removed it.
+
+
+File: autoconf.info,  Node: Particular Functions,  Next: Generic Functions,  Prev: Function Portability,  Up: Library Functions
+
+5.5.2 Particular Function Checks
+--------------------------------
+
+These macros check for particular C functions--whether they exist, and
+in some cases how they respond when given certain arguments.
+
+ -- Macro: AC_FUNC_ALLOCA
+     Check how to get 'alloca'.  Tries to get a builtin version by
+     checking for 'alloca.h' or the predefined C preprocessor macros
+     '__GNUC__' and '_AIX'.  If this macro finds 'alloca.h', it defines
+     'HAVE_ALLOCA_H'.
+
+     If those attempts fail, it looks for the function in the standard C
+     library.  If any of those methods succeed, it defines
+     'HAVE_ALLOCA'.  Otherwise, it sets the output variable 'ALLOCA' to
+     'alloca.o' and defines 'C_ALLOCA' (so programs can periodically
+     call 'alloca(0)' to garbage collect).  This variable is separate
+     from 'LIBOBJS' so multiple programs can share the value of 'ALLOCA'
+     without needing to create an actual library, in case only some of
+     them use the code in 'LIBOBJS'.
+
+     This macro does not try to get 'alloca' from the System V R3
+     'libPW' or the System V R4 'libucb' because those libraries contain
+     some incompatible functions that cause trouble.  Some versions do
+     not even contain 'alloca' or contain a buggy version.  If you still
+     want to use their 'alloca', use 'ar' to extract 'alloca.o' from
+     them instead of compiling 'alloca.c'.
+
+     Source files that use 'alloca' should start with a piece of code
+     like the following, to declare it properly.  In some versions of
+     AIX, the declaration of 'alloca' must precede everything else
+     except for comments and preprocessor directives.  The '#pragma'
+     directive is indented so that pre-ANSI C compilers will ignore it,
+     rather than choke on it.
+
+          /* AIX requires this to be the first thing in the file.  */
+          #ifndef __GNUC__
+          # if HAVE_ALLOCA_H
+          #  include <alloca.h>
+          # else
+          #  ifdef _AIX
+           #pragma alloca
+          #  else
+          #   ifndef alloca /* predefined by HP cc +Olibcalls */
+          char *alloca ();
+          #   endif
+          #  endif
+          # endif
+          #endif
+
+ -- Macro: AC_FUNC_CHOWN
+     If the 'chown' function is available and works (in particular, it
+     should accept '-1' for 'uid' and 'gid'), define 'HAVE_CHOWN'.
+
+ -- Macro: AC_FUNC_CLOSEDIR_VOID
+     If the 'closedir' function does not return a meaningful value,
+     define 'CLOSEDIR_VOID'.  Otherwise, callers ought to check its
+     return value for an error indicator.
+
+ -- Macro: AC_FUNC_ERROR_AT_LINE
+     If the 'error_at_line' function is not found, require an
+     'AC_LIBOBJ' replacement of 'error'.
+
+ -- Macro: AC_FUNC_FNMATCH
+     If the 'fnmatch' function is available and works (unlike the one on
+     Solaris 2.4), define 'HAVE_FNMATCH'.
+
+ -- Macro: AC_FUNC_FORK
+     This macro checks for the 'fork' and 'vfork' functions.  If a
+     working 'fork' is found, define 'HAVE_WORKING_FORK'.  This macro
+     checks whether 'fork' is just a stub by trying to run it.
+
+     If 'vfork.h' is found, define 'HAVE_VFORK_H'.  If a working 'vfork'
+     is found, define 'HAVE_WORKING_VFORK'.  Otherwise, define 'vfork'
+     to be 'fork' for backward compatibility with previous versions of
+     'autoconf'.  This macro checks for several known errors in
+     implementations of 'vfork' and considers the system to not have a
+     working 'vfork' if it detects any of them.  It is not considered to
+     be an implementation error if a child's invocation of 'signal'
+     modifies the parent's signal handler, since child processes rarely
+     change their signal handlers.
+
+     Since this macro defines 'vfork' only for backward compatibility
+     with previous versions of 'autoconf' you're encouraged to define it
+     yourself in new code:
+          #if !HAVE_WORKING_VFORK
+          # define vfork fork
+          #endif
+
+ -- Macro: AC_FUNC_FSEEKO
+     If the 'fseeko' function is available, define 'HAVE_FSEEKO'.
+     Define '_LARGEFILE_SOURCE' if necessary.
+
+ -- Macro: AC_FUNC_GETGROUPS
+     If the 'getgroups' function is available and works (unlike on
+     Ultrix 4.3, where 'getgroups (0, 0)' always fails), define
+     'HAVE_GETGROUPS'.  Set 'GETGROUPS_LIBS' to any libraries needed to
+     get that function.  This macro runs 'AC_TYPE_GETGROUPS'.
+
+ -- Macro: AC_FUNC_GETLOADAVG
+     Check how to get the system load averages.  If the system has the
+     'getloadavg' function, define 'HAVE_GETLOADAVG', and set
+     'GETLOADAVG_LIBS' to any libraries needed to get that function.
+     Also add 'GETLOADAVG_LIBS' to 'LIBS'.
+
+     Otherwise, require an 'AC_LIBOBJ' replacement ('getloadavg.c') of
+     'getloadavg', and possibly define several other C preprocessor
+     macros and output variables:
+
+       1. Define 'C_GETLOADAVG'.
+
+       2. Define 'SVR4', 'DGUX', 'UMAX', or 'UMAX4_3' if on those
+          systems.
+
+       3. If 'nlist.h' is found, define 'NLIST_STRUCT'.
+
+       4. If 'struct nlist' has an 'n_un.n_name' member, define
+          'HAVE_STRUCT_NLIST_N_UN_N_NAME'.  The obsolete symbol
+          'NLIST_NAME_UNION' is still defined, but do not depend upon
+          it.
+
+       5. Programs may need to be installed setgid (or setuid) for
+          'getloadavg' to work.  In this case, define
+          'GETLOADAVG_PRIVILEGED', set the output variable 'NEED_SETGID'
+          to 'true' (and otherwise to 'false'), and set 'KMEM_GROUP' to
+          the name of the group that should own the installed program.
+
+ -- Macro: AC_FUNC_GETMNTENT
+     Check for 'getmntent' in the 'sun', 'seq', and 'gen' libraries, for
+     Irix 4, PTX, and Unixware, respectively.  Then, if 'getmntent' is
+     available, define 'HAVE_GETMNTENT'.
+
+ -- Macro: AC_FUNC_GETPGRP
+     If 'getpgrp' takes no argument (the POSIX.1 version), define
+     'GETPGRP_VOID'.  Otherwise, it is the BSD version, which takes a
+     process ID as an argument.  This macro does not check whether
+     'getpgrp' exists at all; if you need to work in that situation,
+     first call 'AC_CHECK_FUNC' for 'getpgrp'.
+
+ -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+     If 'link' is a symbolic link, then 'lstat' should treat 'link/' the
+     same as 'link/.'.  However, many older 'lstat' implementations
+     incorrectly ignore trailing slashes.
+
+     It is safe to assume that if 'lstat' incorrectly ignores trailing
+     slashes, then other symbolic-link-aware functions like 'unlink' and
+     'unlink' also incorrectly ignore trailing slashes.
+
+     If 'lstat' behaves properly, define
+     'LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an 'AC_LIBOBJ'
+     replacement of 'lstat'.
+
+ -- Macro: AC_FUNC_MALLOC
+     If the 'malloc' works correctly ('malloc (0)' returns a valid
+     pointer), define 'HAVE_MALLOC'.
+
+ -- Macro: AC_FUNC_MEMCMP
+     If the 'memcmp' function is not available, or does not work on
+     8-bit data (like the one on SunOS 4.1.3), or fails when comparing
+     16 bytes or more and with at least one buffer not starting on a
+     4-byte boundary (such as the one on NeXT x86 OpenStep), require an
+     'AC_LIBOBJ' replacement for 'memcmp'.
+
+ -- Macro: AC_FUNC_MKTIME
+     If the 'mktime' function is not available, or does not work
+     correctly, require an 'AC_LIBOBJ' replacement for 'mktime'.
+
+ -- Macro: AC_FUNC_MMAP
+     If the 'mmap' function exists and works correctly, define
+     'HAVE_MMAP'.  Only checks private fixed mapping of already-mapped
+     memory.
+
+ -- Macro: AC_FUNC_OBSTACK
+     If the obstacks are found, define 'HAVE_OBSTACK', else require an
+     'AC_LIBOBJ' replacement for 'obstack'.
+
+ -- Macro: AC_FUNC_SELECT_ARGTYPES
+     Determines the correct type to be passed for each of the 'select'
+     function's arguments, and defines those types in
+     'SELECT_TYPE_ARG1', 'SELECT_TYPE_ARG234', and 'SELECT_TYPE_ARG5'
+     respectively.  'SELECT_TYPE_ARG1' defaults to 'int',
+     'SELECT_TYPE_ARG234' defaults to 'int *', and 'SELECT_TYPE_ARG5'
+     defaults to 'struct timeval *'.
+
+ -- Macro: AC_FUNC_SETPGRP
+     If 'setpgrp' takes no argument (the POSIX.1 version), define
+     'SETPGRP_VOID'.  Otherwise, it is the BSD version, which takes two
+     process IDs as arguments.  This macro does not check whether
+     'setpgrp' exists at all; if you need to work in that situation,
+     first call 'AC_CHECK_FUNC' for 'setpgrp'.
+
+ -- Macro: AC_FUNC_STAT
+ -- Macro: AC_FUNC_LSTAT
+     Determine whether 'stat' or 'lstat' have the bug that it succeeds
+     when given the zero-length file name argument.  The 'stat' and
+     'lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this.
+
+     If it does, then define 'HAVE_STAT_EMPTY_STRING_BUG' (or
+     'HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an 'AC_LIBOBJ'
+     replacement of it.
+
+ -- Macro: AC_FUNC_SETVBUF_REVERSED
+     If 'setvbuf' takes the buffering type as its second argument and
+     the buffer pointer as the third, instead of the other way around,
+     define 'SETVBUF_REVERSED'.
+
+ -- Macro: AC_FUNC_STRCOLL
+     If the 'strcoll' function exists and works correctly, define
+     'HAVE_STRCOLL'.  This does a bit more than
+     'AC_CHECK_FUNCS(strcoll)', because some systems have incorrect
+     definitions of 'strcoll' that should not be used.
+
+ -- Macro: AC_FUNC_STRTOD
+     If the 'strtod' function does not exist or doesn't work correctly,
+     ask for an 'AC_LIBOBJ' replacement of 'strtod'.  In this case,
+     because 'strtod.c' is likely to need 'pow', set the output variable
+     'POW_LIB' to the extra library needed.
+
+ -- Macro: AC_FUNC_STRERROR_R
+     If 'strerror_r' is available, define 'HAVE_STRERROR_R'.  If its
+     implementation correctly returns a 'char *', define
+     'HAVE_WORKING_STRERROR_R'.  On at least DEC UNIX 4.0[A-D] and HP-UX
+     B.10.20, 'strerror_r' returns 'int'.  Actually, this tests only
+     whether it returns a scalar or an array, but that should be enough.
+     This is used by the common 'error.c'.
+
+ -- Macro: AC_FUNC_STRFTIME
+     Check for 'strftime' in the 'intl' library, for SCO UNIX.  Then, if
+     'strftime' is available, define 'HAVE_STRFTIME'.
+
+ -- Macro: AC_FUNC_UTIME_NULL
+     If 'utime(FILE, NULL)' sets FILE's timestamp to the present, define
+     'HAVE_UTIME_NULL'.
+
+ -- Macro: AC_FUNC_VPRINTF
+     If 'vprintf' is found, define 'HAVE_VPRINTF'.  Otherwise, if
+     '_doprnt' is found, define 'HAVE_DOPRNT'.  (If 'vprintf' is
+     available, you may assume that 'vfprintf' and 'vsprintf' are also
+     available.)
+
+
+File: autoconf.info,  Node: Generic Functions,  Prev: Particular Functions,  Up: Library Functions
+
+5.5.3 Generic Function Checks
+-----------------------------
+
+These macros are used to find functions not covered by the "particular"
+test macros.  If the functions might be in libraries other than the
+default C library, first call 'AC_CHECK_LIB' for those libraries.  If
+you need to check the behavior of a function as well as find out whether
+it is present, you have to write your own test for it (*note Writing
+Tests::).
+
+ -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     If C function FUNCTION is available, run shell commands
+     ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND.  If you just want
+     to define a symbol if the function is available, consider using
+     'AC_CHECK_FUNCS' instead.  This macro checks for functions with C
+     linkage even when 'AC_LANG(C++)' has been called, since C is more
+     standardized than C++.  (*note Language Choice::, for more
+     information about selecting the language for checks.)
+
+ -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     For each FUNCTION in the whitespace-separated argument list, define
+     'HAVE_FUNCTION' (in all capitals) if it is available.  If
+     ACTION-IF-FOUND is given, it is additional shell code to execute
+     when one of the functions is found.  You can give it a value of
+     'break' to break out of the loop on the first match.  If
+     ACTION-IF-NOT-FOUND is given, it is executed when one of the
+     functions is not found.
+
+   Autoconf follows a philosophy that was formed over the years by those
+who have struggled for portability: isolate the portability issues in
+specific files, and then program as if you were in a POSIX environment.
+Some functions may be missing or unfixable, and your package must be
+ready to replace them.
+
+   Use the first three of the following macros to specify a function to
+be replaced, and the last one ('AC_REPLACE_FUNCS') to check for and
+replace the function if needed.
+
+ -- Macro: AC_LIBOBJ (FUNCTION)
+     Specify that 'FUNCTION.c' must be included in the executables to
+     replace a missing or broken implementation of FUNCTION.
+
+     Technically, it adds 'FUNCTION.$ac_objext' to the output variable
+     'LIBOBJS' and calls 'AC_LIBSOURCE' for 'FUNCTION.c'.  You should
+     not directly change 'LIBOBJS', since this is not traceable.
+
+ -- Macro: AC_LIBSOURCE (FILE)
+     Specify that FILE might be needed to compile the project.  If you
+     need to know what files might be needed by a 'configure.ac', you
+     should trace 'AC_LIBSOURCE'.  FILE must be a literal.
+
+     This macro is called automatically from 'AC_LIBOBJ', but you must
+     call it explicitly if you pass a shell variable to 'AC_LIBOBJ'.  In
+     that case, since shell variables cannot be traced statically, you
+     must pass to 'AC_LIBSOURCE' any possible files that the shell
+     variable might cause 'AC_LIBOBJ' to need.  For example, if you want
+     to pass a variable '$foo_or_bar' to 'AC_LIBOBJ' that holds either
+     '"foo"' or '"bar"', you should do:
+
+          AC_LIBSOURCE(foo.c)
+          AC_LIBSOURCE(bar.c)
+          AC_LIBOBJ($foo_or_bar)
+
+     There is usually a way to avoid this, however, and you are
+     encouraged to simply call 'AC_LIBOBJ' with literal arguments.
+
+     Note that this macro replaces the obsolete 'AC_LIBOBJ_DECL', with
+     slightly different semantics: the old macro took the function name,
+     e.g.  'foo', as its argument rather than the file name.
+
+ -- Macro: AC_LIBSOURCES (FILES)
+     Like 'AC_LIBSOURCE', but accepts one or more FILES in a
+     comma-separated M4 list.  Thus, the above example might be
+     rewritten:
+
+          AC_LIBSOURCES([foo.c, bar.c])
+          AC_LIBOBJ($foo_or_bar)
+
+ -- Macro: AC_REPLACE_FUNCS (FUNCTION...)
+     Like 'AC_CHECK_FUNCS', but uses 'AC_LIBOBJ(FUNCTION)' as
+     ACTION-IF-NOT-FOUND.  You can declare your replacement function by
+     enclosing the prototype in '#if !HAVE_FUNCTION'.  If the system has
+     the function, it probably declares it in a header file you should
+     be including, so you shouldn't redeclare it lest your declaration
+     conflict.
+
+
+File: autoconf.info,  Node: Header Files,  Next: Declarations,  Prev: Library Functions,  Up: Existing Tests
+
+5.6 Header Files
+================
+
+The following macros check for the presence of certain C header files.
+If there is no macro specifically defined to check for a header file you
+need, and you don't need to check for any special properties of it, then
+you can use one of the general header-file check macros.
+
+* Menu:
+
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+
+
+File: autoconf.info,  Node: Particular Headers,  Next: Generic Headers,  Prev: Header Files,  Up: Header Files
+
+5.6.1 Particular Header Checks
+------------------------------
+
+These macros check for particular system header files--whether they
+exist, and in some cases whether they declare certain symbols.
+
+ -- Macro: AC_HEADER_DIRENT
+     Check for the following header files.  For the first one that is
+     found and defines 'DIR', define the listed C preprocessor macro:
+
+     'dirent.h'     'HAVE_DIRENT_H'
+     'sys/ndir.h'   'HAVE_SYS_NDIR_H'
+     'sys/dir.h'    'HAVE_SYS_DIR_H'
+     'ndir.h'       'HAVE_NDIR_H'
+
+     The directory-library declarations in your source code should look
+     something like the following:
+
+          #if HAVE_DIRENT_H
+          # include <dirent.h>
+          # define NAMLEN(dirent) strlen((dirent)->d_name)
+          #else
+          # define dirent direct
+          # define NAMLEN(dirent) (dirent)->d_namlen
+          # if HAVE_SYS_NDIR_H
+          #  include <sys/ndir.h>
+          # endif
+          # if HAVE_SYS_DIR_H
+          #  include <sys/dir.h>
+          # endif
+          # if HAVE_NDIR_H
+          #  include <ndir.h>
+          # endif
+          #endif
+
+     Using the above declarations, the program would declare variables
+     to be of type 'struct dirent', not 'struct direct', and would
+     access the length of a directory entry name by passing a pointer to
+     a 'struct dirent' to the 'NAMLEN' macro.
+
+     This macro also checks for the SCO Xenix 'dir' and 'x' libraries.
+
+ -- Macro: AC_HEADER_MAJOR
+     If 'sys/types.h' does not define 'major', 'minor', and 'makedev',
+     but 'sys/mkdev.h' does, define 'MAJOR_IN_MKDEV'; otherwise, if
+     'sys/sysmacros.h' does, define 'MAJOR_IN_SYSMACROS'.
+
+ -- Macro: AC_HEADER_STAT
+     If the macros 'S_ISDIR', 'S_ISREG' et al.  defined in 'sys/stat.h'
+     do not work properly (returning false positives), define
+     'STAT_MACROS_BROKEN'.  This is the case on Tektronix UTekV, Amdahl
+     UTS and Motorola System V/88.
+
+ -- Macro: AC_HEADER_STDC
+     Define 'STDC_HEADERS' if the system has ANSI C header files.
+     Specifically, this macro checks for 'stdlib.h', 'stdarg.h',
+     'string.h', and 'float.h'; if the system has those, it probably has
+     the rest of the ANSI C header files.  This macro also checks
+     whether 'string.h' declares 'memchr' (and thus presumably the other
+     'mem' functions), whether 'stdlib.h' declare 'free' (and thus
+     presumably 'malloc' and other related functions), and whether the
+     'ctype.h' macros work on characters with the high bit set, as ANSI
+     C requires.
+
+     Use 'STDC_HEADERS' instead of '__STDC__' to determine whether the
+     system has ANSI-compliant header files (and probably C library
+     functions) because many systems that have GCC do not have ANSI C
+     header files.
+
+     On systems without ANSI C headers, there is so much variation that
+     it is probably easier to declare the functions you use than to
+     figure out exactly what the system header files declare.  Some
+     systems contain a mix of functions ANSI and BSD; some are mostly
+     ANSI but lack 'memmove'; some define the BSD functions as macros in
+     'string.h' or 'strings.h'; some have only the BSD functions but
+     'string.h'; some declare the memory functions in 'memory.h', some
+     in 'string.h'; etc.  It is probably sufficient to check for one
+     string function and one memory function; if the library has the
+     ANSI versions of those then it probably has most of the others.  If
+     you put the following in 'configure.ac':
+
+          AC_HEADER_STDC
+          AC_CHECK_FUNCS(strchr memcpy)
+
+     then, in your code, you can put declarations like this:
+
+          #if STDC_HEADERS
+          # include <string.h>
+          #else
+          # if !HAVE_STRCHR
+          #  define strchr index
+          #  define strrchr rindex
+          # endif
+          char *strchr (), *strrchr ();
+          # if !HAVE_MEMCPY
+          #  define memcpy(d, s, n) bcopy ((s), (d), (n))
+          #  define memmove(d, s, n) bcopy ((s), (d), (n))
+          # endif
+          #endif
+
+     If you use a function like 'memchr', 'memset', 'strtok', or
+     'strspn', which have no BSD equivalent, then macros won't suffice;
+     you must provide an implementation of each function.  An easy way
+     to incorporate your implementations only when needed (since the
+     ones in system C libraries may be hand optimized) is to, taking
+     'memchr' for example, put it in 'memchr.c' and use
+     'AC_REPLACE_FUNCS(memchr)'.
+
+ -- Macro: AC_HEADER_SYS_WAIT
+     If 'sys/wait.h' exists and is compatible with POSIX.1, define
+     'HAVE_SYS_WAIT_H'.  Incompatibility can occur if 'sys/wait.h' does
+     not exist, or if it uses the old BSD 'union wait' instead of 'int'
+     to store a status value.  If 'sys/wait.h' is not POSIX.1
+     compatible, then instead of including it, define the POSIX.1 macros
+     with their usual interpretations.  Here is an example:
+
+          #include <sys/types.h>
+          #if HAVE_SYS_WAIT_H
+          # include <sys/wait.h>
+          #endif
+          #ifndef WEXITSTATUS
+          # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
+          #endif
+          #ifndef WIFEXITED
+          # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
+          #endif
+
+   '_POSIX_VERSION' is defined when 'unistd.h' is included on POSIX.1
+systems.  If there is no 'unistd.h', it is definitely not a POSIX.1
+system.  However, some non-POSIX.1 systems do have 'unistd.h'.
+
+   The way to check if the system supports POSIX.1 is:
+
+     #if HAVE_UNISTD_H
+     # include <sys/types.h>
+     # include <unistd.h>
+     #endif
+
+     #ifdef _POSIX_VERSION
+     /* Code for POSIX.1 systems.  */
+     #endif
+
+ -- Macro: AC_HEADER_TIME
+     If a program may include both 'time.h' and 'sys/time.h', define
+     'TIME_WITH_SYS_TIME'.  On some older systems, 'sys/time.h' includes
+     'time.h', but 'time.h' is not protected against multiple inclusion,
+     so programs should not explicitly include both files.  This macro
+     is useful in programs that use, for example, 'struct timeval' or
+     'struct timezone' as well as 'struct tm'.  It is best used in
+     conjunction with 'HAVE_SYS_TIME_H', which can be checked for using
+     'AC_CHECK_HEADERS(sys/time.h)'.
+
+          #if TIME_WITH_SYS_TIME
+          # include <sys/time.h>
+          # include <time.h>
+          #else
+          # if HAVE_SYS_TIME_H
+          #  include <sys/time.h>
+          # else
+          #  include <time.h>
+          # endif
+          #endif
+
+ -- Macro: AC_HEADER_TIOCGWINSZ
+     If the use of 'TIOCGWINSZ' requires '<sys/ioctl.h>', then define
+     'GWINSZ_IN_SYS_IOCTL'.  Otherwise 'TIOCGWINSZ' can be found in
+     '<termios.h>'.
+
+     Use:
+
+          #if HAVE_TERMIOS_H
+          # include <termios.h>
+          #endif
+
+          #if GWINSZ_IN_SYS_IOCTL
+          # include <sys/ioctl.h>
+          #endif
+
+
+File: autoconf.info,  Node: Generic Headers,  Prev: Particular Headers,  Up: Header Files
+
+5.6.2 Generic Header Checks
+---------------------------
+
+These macros are used to find system header files not covered by the
+"particular" test macros.  If you need to check the contents of a header
+as well as find out whether it is present, you have to write your own
+test for it (*note Writing Tests::).
+
+ -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     If the system header file HEADER-FILE is usable, execute shell
+     commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND.
+     If you just want to define a symbol if the header file is
+     available, consider using 'AC_CHECK_HEADERS' instead.
+
+     The meaning of "usable" depends upon the content of INCLUDES:
+
+     if INCLUDES is empty
+          check whether
+
+               HEADER-FILE
+
+          can be _preprocessed_ without error.
+
+     if INCLUDE is set
+          Check whether
+
+               INCLUDES
+               #include <HEADER-FILE>
+
+          can be _compiled_ without error.  You may use
+          'AC_CHECK_HEADER' (and 'AC_CHECK_HEADERS') to check whether
+          two headers are compatible.
+
+     You may pass any kind of dummy content for INCLUDES, such as a
+     single space, a comment, to check whether HEADER-FILE compiles with
+     success.
+
+ -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     For each given system header file HEADER-FILE in the
+     whitespace-separated argument list that exists, define
+     'HAVE_HEADER-FILE' (in all capitals).  If ACTION-IF-FOUND is given,
+     it is additional shell code to execute when one of the header files
+     is found.  You can give it a value of 'break' to break out of the
+     loop on the first match.  If ACTION-IF-NOT-FOUND is given, it is
+     executed when one of the header files is not found.
+
+     Be sure to read the documentation of 'AC_CHECK_HEADER' to
+     understand the influence of INCLUDES.
+
+
+File: autoconf.info,  Node: Declarations,  Next: Structures,  Prev: Header Files,  Up: Existing Tests
+
+5.7 Declarations
+================
+
+The following macros check for the declaration of variables and
+functions.  If there is no macro specifically defined to check for a
+symbol you need, then you can use the general macros (*note Generic
+Declarations::) or, for more complex tests, you may use 'AC_TRY_COMPILE'
+(*note Examining Syntax::).
+
+* Menu:
+
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+
+
+File: autoconf.info,  Node: Particular Declarations,  Next: Generic Declarations,  Prev: Declarations,  Up: Declarations
+
+5.7.1 Particular Declaration Checks
+-----------------------------------
+
+The following macros check for certain declarations.
+
+ -- Macro: AC_DECL_SYS_SIGLIST
+     Define 'SYS_SIGLIST_DECLARED' if the variable 'sys_siglist' is
+     declared in a system header file, either 'signal.h' or 'unistd.h'.
+
+
+File: autoconf.info,  Node: Generic Declarations,  Prev: Particular Declarations,  Up: Declarations
+
+5.7.2 Generic Declaration Checks
+--------------------------------
+
+These macros are used to find declarations not covered by the
+"particular" test macros.
+
+ -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     If SYMBOL (a function or a variable) is not declared in INCLUDES
+     and a declaration is needed, run the shell commands
+     ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND.  If no INCLUDES are
+     specified, the default includes are used (*note Default
+     Includes::).
+
+     This macro actually tests whether it is valid to use SYMBOL as an
+     r-value, not if it is really declared, because it is much safer to
+     avoid introducing extra declarations when they are not needed.
+
+ -- Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     For each of the SYMBOLS (_comma_-separated list), define
+     'HAVE_DECL_SYMBOL' (in all capitals) to '1' if SYMBOL is declared,
+     otherwise to '0'.  If ACTION-IF-NOT-FOUND is given, it is
+     additional shell code to execute when one of the function
+     declarations is needed, otherwise ACTION-IF-FOUND is executed.
+
+     This macro uses an m4 list as first argument:
+          AC_CHECK_DECLS(strdup)
+          AC_CHECK_DECLS([strlen])
+          AC_CHECK_DECLS([malloc, realloc, calloc, free])
+
+     Unlike the other 'AC_CHECK_*S' macros, when a SYMBOL is not
+     declared, 'HAVE_DECL_SYMBOL' is defined to '0' instead of leaving
+     'HAVE_DECL_SYMBOL' undeclared.  When you are _sure_ that the check
+     was performed, use 'HAVE_DECL_SYMBOL' just like any other result of
+     Autoconf:
+
+          #if !HAVE_DECL_SYMBOL
+          extern char *symbol;
+          #endif
+
+     If the test may have not been performed, however, because it is
+     safer _not_ to declare a symbol than to use a declaration that
+     conflicts with the system's one, you should use:
+
+          #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
+          char *malloc (size_t *s);
+          #endif
+
+     You fall into the second category only in extreme situations:
+     either your files may be used without being configured, or they are
+     used during the configuration.  In most cases the traditional
+     approach is enough.
+
+
+File: autoconf.info,  Node: Structures,  Next: Types,  Prev: Declarations,  Up: Existing Tests
+
+5.8 Structures
+==============
+
+The following macros check for the presence of certain members in C
+structures.  If there is no macro specifically defined to check for a
+member you need, then you can use the general structure-member macro
+(*note Generic Structures::) or, for more complex tests, you may use
+'AC_TRY_COMPILE' (*note Examining Syntax::).
+
+* Menu:
+
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+
+
+File: autoconf.info,  Node: Particular Structures,  Next: Generic Structures,  Prev: Structures,  Up: Structures
+
+5.8.1 Particular Structure Checks
+---------------------------------
+
+The following macros check for certain structures or structure members.
+
+ -- Macro: AC_STRUCT_ST_BLKSIZE
+     If 'struct stat' contains an 'st_blksize' member, define
+     'HAVE_STRUCT_STAT_ST_BLKSIZE'.  The former name, 'HAVE_ST_BLKSIZE'
+     is to be avoided, as its support will cease in the future.  This
+     macro is obsoleted, and should be replaced by
+
+          AC_CHECK_MEMBERS([struct stat.st_blksize])
+
+ -- Macro: AC_STRUCT_ST_BLOCKS
+     If 'struct stat' contains an 'st_blocks' member, define
+     'HAVE_STRUCT STAT_ST_BLOCKS'.  Otherwise, require an 'AC_LIBOBJ'
+     replacement of 'fileblocks'.  The former name, 'HAVE_ST_BLOCKS' is
+     to be avoided, as its support will cease in the future.
+
+ -- Macro: AC_STRUCT_ST_RDEV
+     If 'struct stat' contains an 'st_rdev' member, define
+     'HAVE_STRUCT_STAT_ST_RDEV'.  The former name for this macro,
+     'HAVE_ST_RDEV', is to be avoided as it will cease to be supported
+     in the future.  Actually, even the new macro is obsolete, and
+     should be replaced by:
+          AC_CHECK_MEMBERS([struct stat.st_rdev])
+
+ -- Macro: AC_STRUCT_TM
+     If 'time.h' does not define 'struct tm', define 'TM_IN_SYS_TIME',
+     which means that including 'sys/time.h' had better define 'struct
+     tm'.
+
+ -- Macro: AC_STRUCT_TIMEZONE
+     Figure out how to get the current timezone.  If 'struct tm' has a
+     'tm_zone' member, define 'HAVE_STRUCT_TM_TM_ZONE' (and the
+     obsoleted 'HAVE_TM_ZONE').  Otherwise, if the external array
+     'tzname' is found, define 'HAVE_TZNAME'.
+
+
+File: autoconf.info,  Node: Generic Structures,  Prev: Particular Structures,  Up: Structures
+
+5.8.2 Generic Structure Checks
+------------------------------
+
+These macros are used to find structure members not covered by the
+"particular" test macros.
+
+ -- Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     Check whether MEMBER is a member of the aggregate AGGREGATE.  If no
+     INCLUDES are specified, the default includes are used (*note
+     Default Includes::).
+
+          AC_CHECK_MEMBER(struct passwd.pw_gecos,,
+                          [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
+                          [#include <pwd.h>])
+
+     You can use this macro for sub-members:
+
+          AC_CHECK_MEMBER(struct top.middle.bot)
+
+ -- Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     Check for the existence of each 'AGGREGATE.MEMBER' of MEMBERS using
+     the previous macro.  When MEMBER belongs to AGGREGATE, define
+     'HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and dots
+     replaced by underscores).
+
+     This macro uses m4 lists:
+          AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
+
+
+File: autoconf.info,  Node: Types,  Next: Compilers and Preprocessors,  Prev: Structures,  Up: Existing Tests
+
+5.9 Types
+=========
+
+The following macros check for C types, either builtin or typedefs.  If
+there is no macro specifically defined to check for a type you need, and
+you don't need to check for any special properties of it, then you can
+use a general type-check macro.
+
+* Menu:
+
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+
+
+File: autoconf.info,  Node: Particular Types,  Next: Generic Types,  Prev: Types,  Up: Types
+
+5.9.1 Particular Type Checks
+----------------------------
+
+These macros check for particular C types in 'sys/types.h', 'stdlib.h'
+and others, if they exist.
+
+ -- Macro: AC_TYPE_GETGROUPS
+     Define 'GETGROUPS_T' to be whichever of 'gid_t' or 'int' is the
+     base type of the array argument to 'getgroups'.
+
+ -- Macro: AC_TYPE_MODE_T
+     Equivalent to 'AC_CHECK_TYPE(mode_t, int)'.
+
+ -- Macro: AC_TYPE_OFF_T
+     Equivalent to 'AC_CHECK_TYPE(off_t, long)'.
+
+ -- Macro: AC_TYPE_PID_T
+     Equivalent to 'AC_CHECK_TYPE(pid_t, int)'.
+
+ -- Macro: AC_TYPE_SIGNAL
+     If 'signal.h' declares 'signal' as returning a pointer to a
+     function returning 'void', define 'RETSIGTYPE' to be 'void';
+     otherwise, define it to be 'int'.
+
+     Define signal handlers as returning type 'RETSIGTYPE':
+
+          RETSIGTYPE
+          hup_handler ()
+          {
+          ...
+          }
+
+ -- Macro: AC_TYPE_SIZE_T
+     Equivalent to 'AC_CHECK_TYPE(size_t, unsigned)'.
+
+ -- Macro: AC_TYPE_UID_T
+     If 'uid_t' is not defined, define 'uid_t' to be 'int' and 'gid_t'
+     to be 'int'.
+
+
+File: autoconf.info,  Node: Generic Types,  Prev: Particular Types,  Up: Types
+
+5.9.2 Generic Type Checks
+-------------------------
+
+These macros are used to check for types not covered by the "particular"
+test macros.
+
+ -- Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     Check whether TYPE is defined.  It may be a compiler builtin type
+     or defined by the [INCLUDES] (*note Default Includes::).
+
+ -- Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [INCLUDES])
+     For each TYPE of the TYPES that is defined, define 'HAVE_TYPE' (in
+     all capitals).  If no INCLUDES are specified, the default includes
+     are used (*note Default Includes::).  If ACTION-IF-FOUND is given,
+     it is additional shell code to execute when one of the types is
+     found.  If ACTION-IF-NOT-FOUND is given, it is executed when one of
+     the types is not found.
+
+     This macro uses m4 lists:
+          AC_CHECK_TYPES(ptrdiff_t)
+          AC_CHECK_TYPES([unsigned long long, uintmax_t])
+
+   Autoconf, up to 2.13, used to provide to another version of
+'AC_CHECK_TYPE', broken by design.  In order to keep backward
+compatibility, a simple heuristics, quite safe but not totally, is
+implemented.  In case of doubt, read the documentation of the former
+'AC_CHECK_TYPE', see *note Obsolete Macros::.
+
+
+File: autoconf.info,  Node: Compilers and Preprocessors,  Next: System Services,  Prev: Types,  Up: Existing Tests
+
+5.10 Compilers and Preprocessors
+================================
+
+All the tests for compilers ('AC_PROG_CC', 'AC_PROG_CXX', 'AC_PROG_F77')
+define the output variable 'EXEEXT' based on the output of the compiler,
+typically to the empty string if Unix and '.exe' if Win32 or OS/2.
+
+   They also define the output variable 'OBJEXT' based on the output of
+the compiler, after .c files have been excluded, typically to 'o' if
+Unix, 'obj' if Win32.
+
+   If the compiler being used does not produce executables, they fail.
+If the executables can't be run, and cross-compilation is not enabled,
+they fail too.  *Note Manual Configuration::, for more on support for
+cross compiling.
+
+* Menu:
+
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+
+
+File: autoconf.info,  Node: Generic Compiler Characteristics,  Next: C Compiler,  Prev: Compilers and Preprocessors,  Up: Compilers and Preprocessors
+
+5.10.1 Generic Compiler Characteristics
+---------------------------------------
+
+ -- Macro: AC_CHECK_SIZEOF (TYPE, [UNUSED], [INCLUDES])
+     Define 'SIZEOF_TYPE' (*note Standard Symbols::) to be the size in
+     bytes of TYPE.  If 'type' is unknown, it gets a size of 0.  If no
+     INCLUDES are specified, the default includes are used (*note
+     Default Includes::).  If you provide INCLUDE, make sure to include
+     'stdio.h' which is required for this macro to run.
+
+     This macro now works even when cross-compiling.  The UNUSED
+     argument was used when cross-compiling.
+
+     For example, the call
+
+          AC_CHECK_SIZEOF(int *)
+
+     defines 'SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems.
+
+
+File: autoconf.info,  Node: C Compiler,  Next: C++ Compiler,  Prev: Generic Compiler Characteristics,  Up: Compilers and Preprocessors
+
+5.10.2 C Compiler Characteristics
+---------------------------------
+
+ -- Macro: AC_PROG_CC ([COMPILER-SEARCH-LIST])
+     Determine a C compiler to use.  If 'CC' is not already set in the
+     environment, check for 'gcc' and 'cc', then for other C compilers.
+     Set output variable 'CC' to the name of the compiler found.
+
+     This macro may, however, be invoked with an optional first argument
+     which, if specified, must be a space separated list of C compilers
+     to search for.  This just gives the user an opportunity to specify
+     an alternative search list for the C compiler.  For example, if you
+     didn't like the default order, then you could invoke 'AC_PROG_CC'
+     like this:
+
+          AC_PROG_CC(cl egcs gcc cc)
+
+     If using the GNU C compiler, set shell variable 'GCC' to 'yes'.  If
+     output variable 'CFLAGS' was not already set, set it to '-g -O2'
+     for the GNU C compiler ('-O2' on systems where GCC does not accept
+     '-g'), or '-g' for other compilers.
+
+ -- Macro: AC_PROG_CC_C_O
+     If the C compiler does not accept the '-c' and '-o' options
+     simultaneously, define 'NO_MINUS_C_MINUS_O'.  This macro actually
+     tests both the compiler found by 'AC_PROG_CC', and, if different,
+     the first 'cc' in the path.  The test fails if one fails.  This
+     macro was created for GNU Make to choose the default C compilation
+     rule.
+
+ -- Macro: AC_PROG_CC_STDC
+     If the C compiler is not in ANSI C mode by default, try to add an
+     option to output variable 'CC' to make it so.  This macro tries
+     various options that select ANSI C on some system or another.  It
+     considers the compiler to be in ANSI C mode if it handles function
+     prototypes correctly.
+
+     If you use this macro, you should check after calling it whether
+     the C compiler has been set to accept ANSI C; if not, the shell
+     variable 'ac_cv_prog_cc_stdc' is set to 'no'.  If you wrote your
+     source code in ANSI C, you can make an un-ANSIfied copy of it by
+     using the program 'ansi2knr', which comes with Automake.
+
+ -- Macro: AC_PROG_CPP
+     Set output variable 'CPP' to a command that runs the C
+     preprocessor.  If '$CC -E' doesn't work, '/lib/cpp' is used.  It is
+     only portable to run 'CPP' on files with a '.c' extension.
+
+     If the current language is C (*note Language Choice::), many of the
+     specific test macros use the value of 'CPP' indirectly by calling
+     'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or
+     'AC_EGREP_CPP'.
+
+     Some preprocessors don't indicate missing include files by the
+     error status.  For such preprocessors an internal variable is set
+     that causes other macros to check the standard error from the
+     preprocessor and consider the test failed if any warnings have been
+     reported.
+
+   The following macros check for C compiler or machine architecture
+features.  To check for characteristics not listed here, use
+'AC_TRY_COMPILE' (*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run
+Time::)
+
+ -- Macro: AC_C_BIGENDIAN
+     If words are stored with the most significant byte first (like
+     Motorola and SPARC, but not Intel and VAX, CPUs), define
+     'WORDS_BIGENDIAN'.
+
+ -- Macro: AC_C_CONST
+     If the C compiler does not fully support the ANSI C qualifier
+     'const', define 'const' to be empty.  Some C compilers that do not
+     define '__STDC__' do support 'const'; some compilers that define
+     '__STDC__' do not completely support 'const'.  Programs can simply
+     use 'const' as if every C compiler supported it; for those that
+     don't, the 'Makefile' or configuration header file will define it
+     as empty.
+
+     Occasionally installers use a C++ compiler to compile C code,
+     typically because they lack a C compiler.  This causes problems
+     with 'const', because C and C++ treat 'const' differently.  For
+     example:
+
+          const int foo;
+
+     is valid in C but not in C++.  These differences unfortunately
+     cannot be papered over by defining 'const' to be empty.
+
+     If 'autoconf' detects this situation, it leaves 'const' alone, as
+     this generally yields better results in practice.  However, using a
+     C++ compiler to compile C code is not recommended or supported, and
+     installers who run into trouble in this area should get a C
+     compiler like GCC to compile their C code.
+
+ -- Macro: AC_C_VOLATILE
+     If the C compiler does not understand the keyword 'volatile',
+     define 'volatile' to be empty.  Programs can simply use 'volatile'
+     as if every C compiler supported it; for those that do not, the
+     'Makefile' or configuration header will define it as empty.
+
+     If the correctness of your program depends on the semantics of
+     'volatile', simply defining it to be empty does, in a sense, break
+     your code.  However, given that the compiler does not support
+     'volatile', you are at its mercy anyway.  At least your program
+     will compile, when it wouldn't before.
+
+     In general, the 'volatile' keyword is a feature of ANSI C, so you
+     might expect that 'volatile' is available only when '__STDC__' is
+     defined.  However, Ultrix 4.3's native compiler does support
+     volatile, but does not defined '__STDC__'.
+
+ -- Macro: AC_C_INLINE
+     If the C compiler supports the keyword 'inline', do nothing.
+     Otherwise define 'inline' to '__inline__' or '__inline' if it
+     accepts one of those, otherwise define 'inline' to be empty.
+
+ -- Macro: AC_C_CHAR_UNSIGNED
+     If the C type 'char' is unsigned, define '__CHAR_UNSIGNED__',
+     unless the C compiler predefines it.
+
+ -- Macro: AC_C_LONG_DOUBLE
+     If the C compiler supports the 'long double' type, define
+     'HAVE_LONG_DOUBLE'.  Some C compilers that do not define '__STDC__'
+     do support the 'long double' type; some compilers that define
+     '__STDC__' do not support 'long double'.
+
+ -- Macro: AC_C_STRINGIZE
+     If the C preprocessor supports the stringizing operator, define
+     'HAVE_STRINGIZE'.  The stringizing operator is '#' and is found in
+     macros such as this:
+
+          #define x(y) #y
+
+ -- Macro: AC_C_PROTOTYPES
+     Check to see if function prototypes are understood by the compiler.
+     If so, define 'PROTOTYPES'.  In the case the compiler does not
+     handle prototypes, you should use 'ansi2knr', which comes with the
+     Automake distribution, to unprotoize function definitions.  For
+     function prototypes, you should first define 'PARAMS':
+
+          #ifndef PARAMS
+          # if PROTOTYPES
+          #  define PARAMS(protos) protos
+          # else /* no PROTOTYPES */
+          #  define PARAMS(protos) ()
+          # endif /* no PROTOTYPES */
+          #endif
+
+     then use it this way:
+
+          size_t my_strlen PARAMS ((const char *));
+
+ -- Macro: AC_PROG_GCC_TRADITIONAL
+     Add '-traditional' to output variable 'CC' if using the GNU C
+     compiler and 'ioctl' does not work properly without '-traditional'.
+     That usually happens when the fixed header files have not been
+     installed on an old system.  Since recent versions of the GNU C
+     compiler fix the header files automatically when installed, this is
+     becoming a less prevalent problem.
+
+
+File: autoconf.info,  Node: C++ Compiler,  Next: Fortran 77 Compiler,  Prev: C Compiler,  Up: Compilers and Preprocessors
+
+5.10.3 C++ Compiler Characteristics
+-----------------------------------
+
+ -- Macro: AC_PROG_CXX ([COMPILER-SEARCH-LIST])
+     Determine a C++ compiler to use.  Check if the environment variable
+     'CXX' or 'CCC' (in that order) is set; if so, then set output
+     variable 'CXX' to its value.
+
+     Otherwise, if the macro is invoked without an argument, then search
+     for a C++ compiler under the likely names (first 'g++' and 'c++'
+     then other names).  If none of those checks succeed, then as a last
+     resort set 'CXX' to 'g++'.
+
+     This macro may, however, be invoked with an optional first argument
+     which, if specified, must be a space separated list of C++
+     compilers to search for.  This just gives the user an opportunity
+     to specify an alternative search list for the C++ compiler.  For
+     example, if you didn't like the default order, then you could
+     invoke 'AC_PROG_CXX' like this:
+
+          AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
+
+     If using the GNU C++ compiler, set shell variable 'GXX' to 'yes'.
+     If output variable 'CXXFLAGS' was not already set, set it to '-g
+     -O2' for the GNU C++ compiler ('-O2' on systems where G++ does not
+     accept '-g'), or '-g' for other compilers.
+
+ -- Macro: AC_PROG_CXXCPP
+     Set output variable 'CXXCPP' to a command that runs the C++
+     preprocessor.  If '$CXX -E' doesn't work, '/lib/cpp' is used.  It
+     is only portable to run 'CXXCPP' on files with a '.c', '.C', or
+     '.cc' extension.
+
+     If the current language is C++ (*note Language Choice::), many of
+     the specific test macros use the value of 'CXXCPP' indirectly by
+     calling 'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or
+     'AC_EGREP_CPP'.
+
+     Some preprocessors don't indicate missing include files by the
+     error status.  For such preprocessors an internal variable is set
+     that causes other macros to check the standard error from the
+     preprocessor and consider the test failed if any warnings have been
+     reported.  However, it is not known whether such broken
+     preprocessors exist for C++.
+
+
+File: autoconf.info,  Node: Fortran 77 Compiler,  Prev: C++ Compiler,  Up: Compilers and Preprocessors
+
+5.10.4 Fortran 77 Compiler Characteristics
+------------------------------------------
+
+ -- Macro: AC_PROG_F77 ([COMPILER-SEARCH-LIST])
+     Determine a Fortran 77 compiler to use.  If 'F77' is not already
+     set in the environment, then check for 'g77' and 'f77', and then
+     some other names.  Set the output variable 'F77' to the name of the
+     compiler found.
+
+     This macro may, however, be invoked with an optional first argument
+     which, if specified, must be a space separated list of Fortran 77
+     compilers to search for.  This just gives the user an opportunity
+     to specify an alternative search list for the Fortran 77 compiler.
+     For example, if you didn't like the default order, then you could
+     invoke 'AC_PROG_F77' like this:
+
+          AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)
+
+     If using 'g77' (the GNU Fortran 77 compiler), then 'AC_PROG_F77'
+     will set the shell variable 'G77' to 'yes'.  If the output variable
+     'FFLAGS' was not already set in the environment, then set it to '-g
+     -02' for 'g77' (or '-O2' where 'g77' does not accept '-g').
+     Otherwise, set 'FFLAGS' to '-g' for all other Fortran 77 compilers.
+
+ -- Macro: AC_PROG_F77_C_O
+     Test if the Fortran 77 compiler accepts the options '-c' and '-o'
+     simultaneously, and define 'F77_NO_MINUS_C_MINUS_O' if it does not.
+
+   The following macros check for Fortran 77 compiler characteristics.
+To check for characteristics not listed here, use 'AC_TRY_COMPILE'
+(*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run Time::), making
+sure to first set the current language to Fortran 77 'AC_LANG(Fortran
+77)' (*note Language Choice::).
+
+ -- Macro: AC_F77_LIBRARY_LDFLAGS
+     Determine the linker flags (e.g.  '-L' and '-l') for the "Fortran
+     77 intrinsic and run-time libraries" that are required to
+     successfully link a Fortran 77 program or shared library.  The
+     output variable 'FLIBS' is set to these flags.
+
+     This macro is intended to be used in those situations when it is
+     necessary to mix, e.g.  C++ and Fortran 77 source code into a
+     single program or shared library (*note (automake)Mixing Fortran 77
+     With C and C++::).
+
+     For example, if object files from a C++ and Fortran 77 compiler
+     must be linked together, then the C++ compiler/linker must be used
+     for linking (since special C++-ish things need to happen at link
+     time like calling global constructors, instantiating templates,
+     enabling exception support, etc.).
+
+     However, the Fortran 77 intrinsic and run-time libraries must be
+     linked in as well, but the C++ compiler/linker doesn't know by
+     default how to add these Fortran 77 libraries.  Hence, the macro
+     'AC_F77_LIBRARY_LDFLAGS' was created to determine these Fortran 77
+     libraries.
+
+     The macro 'AC_F77_DUMMY_MAIN' or 'AC_F77_MAIN' will probably also
+     be necessary to link C/C++ with Fortran; see below.
+
+ -- Macro: AC_F77_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
+     With many compilers, the Fortran libraries detected by
+     'AC_F77_LIBRARY_LDFLAGS' provide their own 'main' entry function
+     that initializes things like Fortran I/O, and which then calls a
+     user-provided entry function named e.g.  'MAIN__' to run the user's
+     program.  The 'AC_F77_DUMMY_MAIN' or 'AC_F77_MAIN' macro figures
+     out how to deal with this interaction.
+
+     When using Fortran for purely numerical functions (no I/O,
+     etcetera), users often prefer to provide their own 'main' and skip
+     the Fortran library initializations.  In this case, however, one
+     may still need to provide a dummy 'MAIN__' routine in order to
+     prevent linking errors on some systems.  'AC_F77_DUMMY_MAIN'
+     detects whether any such routine is _required_ for linking, and
+     what its name is; the shell variable 'F77_DUMMY_MAIN' holds this
+     name, 'unknown' when no solution was found, and 'none' when no such
+     dummy main is needed.
+
+     By default, ACTION-IF-FOUND defines 'F77_DUMMY_MAIN' to the name of
+     this routine (e.g.  'MAIN__') _if_ it is required.
+     [ACTION-IF-NOT-FOUND] defaults to exiting with an error.
+
+     In order to link with Fortran routines, the user's C/C++ program
+     should then include the following code to define the dummy main if
+     it is needed:
+
+          #ifdef F77_DUMMY_MAIN
+          #  ifdef __cplusplus
+               extern "C"
+          #  endif
+             int F77_DUMMY_MAIN() { return 1; }
+          #endif
+
+     Note that 'AC_F77_DUMMY_MAIN' is called automatically from
+     'AC_F77_WRAPPERS'; there is generally no need to call it explicitly
+     unless one wants to change the default actions.
+
+ -- Macro: AC_F77_MAIN
+     As discussed above for 'AC_F77_DUMMY_MAIN', many Fortran libraries
+     allow you to provide an entry point called e.g.  'MAIN__' instead
+     of the usual 'main', which is then called by a 'main' function in
+     the Fortran libraries that initializes things like Fortran I/O. The
+     'AC_F77_MAIN' macro detects whether it is _possible_ to utilize
+     such an alternate main function, and defines 'F77_MAIN' to the name
+     of the function.  (If no alternate main function name is found,
+     'F77_MAIN' is simply defined to 'main'.)
+
+     Thus, when calling Fortran routines from C that perform things like
+     I/O, one should use this macro and name the "main" function
+     'F77_MAIN' instead of 'main'.
+
+ -- Macro: AC_F77_WRAPPERS
+     Defines C macros 'F77_FUNC(name,NAME)' and 'F77_FUNC_(name,NAME)'
+     to properly mangle the names of C/C++ identifiers, and identifiers
+     with underscores, respectively, so that they match the
+     name-mangling scheme used by the Fortran 77 compiler.
+
+     Fortran 77 is case-insensitive, and in order to achieve this the
+     Fortran 77 compiler converts all identifiers into a canonical case
+     and format.  To call a Fortran 77 subroutine from C or to write a C
+     function that is callable from Fortran 77, the C program must
+     explicitly use identifiers in the format expected by the Fortran 77
+     compiler.  In order to do this, one simply wraps all C identifiers
+     in one of the macros provided by 'AC_F77_WRAPPERS'.  For example,
+     suppose you have the following Fortran 77 subroutine:
+
+                subroutine foobar(x,y)
+                double precision x, y
+                y = 3.14159 * x
+                return
+                end
+
+     You would then declare its prototype in C or C++ as:
+
+          #define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
+          #ifdef __cplusplus
+          extern "C"  /* prevent C++ name mangling */
+          #endif
+          void FOOBAR_F77(double *x, double *y);
+
+     Note that we pass both the lowercase and uppercase versions of the
+     function name to 'F77_FUNC' so that it can select the right one.
+     Note also that all parameters to Fortran 77 routines are passed as
+     pointers (*note (automake)Mixing Fortran 77 With C and C++::).
+
+     Although Autoconf tries to be intelligent about detecting the
+     name-mangling scheme of the Fortran 77 compiler, there may be
+     Fortran 77 compilers that it doesn't support yet.  In this case,
+     the above code will generate a compile-time error, but some other
+     behavior (e.g.  disabling Fortran-related features) can be induced
+     by checking whether the 'F77_FUNC' macro is defined.
+
+     Now, to call that routine from a C program, we would do something
+     like:
+
+          {
+              double x = 2.7183, y;
+              FOOBAR_F77(&x, &y);
+          }
+
+     If the Fortran 77 identifier contains an underscore (e.g.
+     'foo_bar'), you should use 'F77_FUNC_' instead of 'F77_FUNC' (with
+     the same arguments).  This is because some Fortran 77 compilers
+     mangle names differently if they contain an underscore.
+
+ -- Macro: AC_F77_FUNC (NAME, [SHELLVAR])
+     Given an identifier NAME, set the shell variable SHELLVAR to hold
+     the mangled version NAME according to the rules of the Fortran 77
+     linker (see also 'AC_F77_WRAPPERS').  SHELLVAR is optional; if it
+     is not supplied, the shell variable will be simply NAME.  The
+     purpose of this macro is to give the caller a way to access the
+     name-mangling information other than through the C preprocessor as
+     above; for example, to call Fortran routines from some language
+     other than C/C++.
+
+
+File: autoconf.info,  Node: System Services,  Next: UNIX Variants,  Prev: Compilers and Preprocessors,  Up: Existing Tests
+
+5.11 System Services
+====================
+
+The following macros check for operating system services or
+capabilities.
+
+ -- Macro: AC_PATH_X
+     Try to locate the X Window System include files and libraries.  If
+     the user gave the command line options '--x-includes=DIR' and
+     '--x-libraries=DIR', use those directories.  If either or both were
+     not given, get the missing values by running 'xmkmf' on a trivial
+     'Imakefile' and examining the 'Makefile' that it produces.  If that
+     fails (such as if 'xmkmf' is not present), look for them in several
+     directories where they often reside.  If either method is
+     successful, set the shell variables 'x_includes' and 'x_libraries'
+     to their locations, unless they are in directories the compiler
+     searches by default.
+
+     If both methods fail, or the user gave the command line option
+     '--without-x', set the shell variable 'no_x' to 'yes'; otherwise
+     set it to the empty string.
+
+ -- Macro: AC_PATH_XTRA
+     An enhanced version of 'AC_PATH_X'.  It adds the C compiler flags
+     that X needs to output variable 'X_CFLAGS', and the X linker flags
+     to 'X_LIBS'.  Define 'X_DISPLAY_MISSING' if X is not available.
+
+     This macro also checks for special libraries that some systems need
+     in order to compile X programs.  It adds any that the system needs
+     to output variable 'X_EXTRA_LIBS'.  And it checks for special X11R6
+     libraries that need to be linked with before '-lX11', and adds any
+     found to the output variable 'X_PRE_LIBS'.
+
+ -- Macro: AC_SYS_INTERPRETER
+     Check whether the system supports starting scripts with a line of
+     the form '#! /bin/csh' to select the interpreter to use for the
+     script.  After running this macro, shell code in 'configure.ac' can
+     check the shell variable 'interpval'; it will be set to 'yes' if
+     the system supports '#!', 'no' if not.
+
+ -- Macro: AC_SYS_LARGEFILE
+     Arrange for large-file support(1).  On some hosts, one must use
+     special compiler options to build programs that can access large
+     files.  Append any such options to the output variable 'CC'.
+     Define '_FILE_OFFSET_BITS' and '_LARGE_FILES' if necessary.
+
+     Large-file support can be disabled by configuring with the
+     '--disable-largefile' option.
+
+     If you use this macro, check that your program works even when
+     'off_t' is longer than 'long', since this is common when large-file
+     support is enabled.  For example, it is not correct to print an
+     arbitrary 'off_t' value 'X' with 'printf ("%ld", (long) X)'.
+
+ -- Macro: AC_SYS_LONG_FILE_NAMES
+     If the system supports file names longer than 14 characters, define
+     'HAVE_LONG_FILE_NAMES'.
+
+ -- Macro: AC_SYS_POSIX_TERMIOS
+     Check to see if POSIX termios headers and functions are available
+     on the system.  If so, set the shell variable
+     'am_cv_sys_posix_termios' to 'yes'.  If not, set the variable to
+     'no'.
+
+   ---------- Footnotes ----------
+
+   (1) large-file support,
+<http://www.sas.com/standards/large.file/x_open.20Mar96.html>.
+
+
+File: autoconf.info,  Node: UNIX Variants,  Prev: System Services,  Up: Existing Tests
+
+5.12 UNIX Variants
+==================
+
+The following macros check for certain operating systems that need
+special treatment for some programs, due to exceptional oddities in
+their header files or libraries.  These macros are warts; they will be
+replaced by a more systematic approach, based on the functions they make
+available or the environments they provide.
+
+ -- Macro: AC_AIX
+     If on AIX, define '_ALL_SOURCE'.  Allows the use of some BSD
+     functions.  Should be called before any macros that run the C
+     compiler.
+
+ -- Macro: AC_ISC_POSIX
+     If on a POSIXized ISC UNIX, define '_POSIX_SOURCE' and add '-posix'
+     (for the GNU C compiler) or '-Xp' (for other C compilers) to output
+     variable 'CC'.  This allows the use of POSIX facilities.  Must be
+     called after 'AC_PROG_CC' and before any other macros that run the
+     C compiler.
+
+ -- Macro: AC_MINIX
+     If on Minix, define '_MINIX' and '_POSIX_SOURCE' and define
+     '_POSIX_1_SOURCE' to be 2.  This allows the use of POSIX
+     facilities.  Should be called before any macros that run the C
+     compiler.
+
+
+File: autoconf.info,  Node: Writing Tests,  Next: Results,  Prev: Existing Tests,  Up: Top
+
+6 Writing Tests
+***************
+
+If the existing feature tests don't do something you need, you have to
+write new ones.  These macros are the building blocks.  They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+   This chapter contains some suggestions and some of the reasons why
+the existing tests are written the way they are.  You can also learn a
+lot about how to write Autoconf tests by looking at the existing ones.
+If something goes wrong in one or more of the Autoconf tests, this
+information can help you understand the assumptions behind them, which
+might help you figure out how to best solve the problem.
+
+   These macros check the output of the C compiler system.  They do not
+cache the results of their tests for future use (*note Caching
+Results::), because they don't know enough about the information they
+are checking for to generate a cache variable name.  They also do not
+print any messages, for the same reason.  The checks for particular
+kinds of C features call these macros and do cache their results and
+print messages about what they're checking for.
+
+   When you write a feature test that could be applicable to more than
+one software package, the best thing to do is encapsulate it in a new
+macro.  *Note Writing Autoconf Macros::, for how to do that.
+
+* Menu:
+
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+
+
+File: autoconf.info,  Node: Examining Declarations,  Next: Examining Syntax,  Prev: Writing Tests,  Up: Writing Tests
+
+6.1 Examining Declarations
+==========================
+
+The macro 'AC_TRY_CPP' is used to check whether particular header files
+exist.  You can check for one at a time, or more than one if you need
+several header files to all exist for some purpose.
+
+ -- Macro: AC_TRY_CPP (INCLUDES, [ACTION-IF-TRUE], [ACTION-IF-FALSE])
+     INCLUDES is C or C++ '#include' statements and declarations, on
+     which shell variable, back quote, and backslash substitutions are
+     performed.  (Actually, it can be any C program, but other
+     statements are probably not useful.)  If the preprocessor produces
+     no error messages while processing it, run shell commands
+     ACTION-IF-TRUE.  Otherwise run shell commands ACTION-IF-FALSE.
+
+     This macro uses 'CPPFLAGS', but not 'CFLAGS', because '-g', '-O',
+     etc.  are not valid options to many C preprocessors.
+
+   Here is how to find out whether a header file contains a particular
+declaration, such as a typedef, a structure, a structure member, or a
+function.  Use 'AC_EGREP_HEADER' instead of running 'grep' directly on
+the header file; on some systems the symbol might be defined in another
+header file that the file you are checking '#include's.
+
+ -- Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND,
+          [ACTION-IF-NOT-FOUND])
+     If the output of running the preprocessor on the system header file
+     HEADER-FILE matches the 'egrep' regular expression PATTERN, execute
+     shell commands ACTION-IF-FOUND, otherwise execute
+     ACTION-IF-NOT-FOUND.
+
+   To check for C preprocessor symbols, either defined by header files
+or predefined by the C preprocessor, use 'AC_EGREP_CPP'.  Here is an
+example of the latter:
+
+     AC_EGREP_CPP(yes,
+     [#ifdef _AIX
+       yes
+     #endif
+     ], is_aix=yes, is_aix=no)
+
+ -- Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     PROGRAM is the text of a C or C++ program, on which shell variable,
+     back quote, and backslash substitutions are performed.  If the
+     output of running the preprocessor on PROGRAM matches the 'egrep'
+     regular expression PATTERN, execute shell commands ACTION-IF-FOUND,
+     otherwise execute ACTION-IF-NOT-FOUND.
+
+     This macro calls 'AC_PROG_CPP' or 'AC_PROG_CXXCPP' (depending on
+     which language is current, *note Language Choice::), if it hasn't
+     been called already.
+
+
+File: autoconf.info,  Node: Examining Syntax,  Next: Examining Libraries,  Prev: Examining Declarations,  Up: Writing Tests
+
+6.2 Examining Syntax
+====================
+
+To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
+as whether it recognizes a certain keyword, use 'AC_TRY_COMPILE' to try
+to compile a small program that uses that feature.  You can also use it
+to check for structures and structure members that are not present on
+all systems.
+
+ -- Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Create a C, C++ or Fortran 77 test program (depending on which
+     language is current, *note Language Choice::), to see whether a
+     function whose body consists of FUNCTION-BODY can be compiled.
+
+     For C and C++, INCLUDES is any '#include' statements needed by the
+     code in FUNCTION-BODY (INCLUDES will be ignored if the currently
+     selected language is Fortran 77).  This macro also uses 'CFLAGS' or
+     'CXXFLAGS' if either C or C++ is the currently selected language,
+     as well as 'CPPFLAGS', when compiling.  If Fortran 77 is the
+     currently selected language then 'FFLAGS' will be used when
+     compiling.
+
+     If the file compiles successfully, run shell commands
+     ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND.
+
+     This macro does not try to link; use 'AC_TRY_LINK' if you need to
+     do that (*note Examining Libraries::).
+
+
+File: autoconf.info,  Node: Examining Libraries,  Next: Run Time,  Prev: Examining Syntax,  Up: Writing Tests
+
+6.3 Examining Libraries
+=======================
+
+To check for a library, a function, or a global variable, Autoconf
+'configure' scripts try to compile and link a small program that uses
+it.  This is unlike Metaconfig, which by default uses 'nm' or 'ar' on
+the C library to try to figure out which functions are available.
+Trying to link with the function is usually a more reliable approach
+because it avoids dealing with the variations in the options and output
+formats of 'nm' and 'ar' and in the location of the standard libraries.
+It also allows configuring for cross-compilation or checking a
+function's runtime behavior if needed.  On the other hand, it can be
+slower than scanning the libraries once.
+
+   A few systems have linkers that do not return a failure exit status
+when there are unresolved functions in the link.  This bug makes the
+configuration scripts produced by Autoconf unusable on those systems.
+However, some of them can be given options that make the exit status
+correct.  This is a problem that Autoconf does not currently handle
+automatically.  If users encounter this problem, they might be able to
+solve it by setting 'LDFLAGS' in the environment to pass whatever
+options the linker needs (for example, '-Wl,-dn' on MIPS RISC/OS).
+
+   'AC_TRY_LINK' is used to compile test programs to test for functions
+and global variables.  It is also used by 'AC_CHECK_LIB' to check for
+libraries (*note Libraries::), by adding the library being checked for
+to 'LIBS' temporarily and trying to link a small program.
+
+ -- Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Depending on the current language (*note Language Choice::), create
+     a test program to see whether a function whose body consists of
+     FUNCTION-BODY can be compiled and linked.
+
+     For C and C++, INCLUDES is any '#include' statements needed by the
+     code in FUNCTION-BODY (INCLUDES will be ignored if the currently
+     selected language is Fortran 77).  This macro also uses 'CFLAGS' or
+     'CXXFLAGS' if either C or C++ is the currently selected language,
+     as well as 'CPPFLAGS', when compiling.  If Fortran 77 is the
+     currently selected language then 'FFLAGS' will be used when
+     compiling.  However, both 'LDFLAGS' and 'LIBS' will be used during
+     linking in all cases.
+
+     If the file compiles and links successfully, run shell commands
+     ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND.
+
+ -- Macro: AC_TRY_LINK_FUNC (FUNCTION, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND])
+     Depending on the current language (*note Language Choice::), create
+     a test program to see whether a program whose body consists of a
+     prototype of and a call to FUNCTION can be compiled and linked.
+
+     If the file compiles and links successfully, run shell commands
+     ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND.
+
+
+File: autoconf.info,  Node: Run Time,  Next: Systemology,  Prev: Examining Libraries,  Up: Writing Tests
+
+6.4 Checking Run Time Behavior
+==============================
+
+Sometimes you need to find out how a system performs at run time, such
+as whether a given function has a certain capability or bug.  If you
+can, make such checks when your program runs instead of when it is
+configured.  You can check for things like the machine's endianness when
+your program initializes itself.
+
+   If you really need to test for a run-time behavior while configuring,
+you can write a test program to determine the result, and compile and
+run it using 'AC_TRY_RUN'.  Avoid running test programs if possible,
+because this prevents people from configuring your package for
+cross-compiling.
+
+* Menu:
+
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+
+
+File: autoconf.info,  Node: Test Programs,  Next: Guidelines,  Prev: Run Time,  Up: Run Time
+
+6.4.1 Running Test Programs
+---------------------------
+
+Use the following macro if you need to test run-time behavior of the
+system while configuring.
+
+ -- Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE], [ACTION-IF-FALSE],
+          [ACTION-IF-CROSS-COMPILING])
+     PROGRAM is the text of a C program, on which shell variable and
+     back quote substitutions are performed.  If it compiles and links
+     successfully and returns an exit status of 0 when executed, run
+     shell commands ACTION-IF-TRUE.  Otherwise, run shell commands
+     ACTION-IF-FALSE; the exit status of the program is available in the
+     shell variable '$?'.  This macro uses 'CFLAGS' or 'CXXFLAGS',
+     'CPPFLAGS', 'LDFLAGS', and 'LIBS' when compiling.
+
+     If the C compiler being used does not produce executables that run
+     on the system where 'configure' is being run, then the test program
+     is not run.  If the optional shell commands
+     ACTION-IF-CROSS-COMPILING are given, they are run instead.
+     Otherwise, 'configure' prints an error message and exits.
+
+   Try to provide a pessimistic default value to use when
+cross-compiling makes run-time tests impossible.  You do this by passing
+the optional last argument to 'AC_TRY_RUN'.  'autoconf' prints a warning
+message when creating 'configure' each time it encounters a call to
+'AC_TRY_RUN' with no ACTION-IF-CROSS-COMPILING argument given.  You may
+ignore the warning, though users will not be able to configure your
+package for cross-compiling.  A few of the macros distributed with
+Autoconf produce this warning message.
+
+   To configure for cross-compiling you can also choose a value for
+those parameters based on the canonical system name (*note Manual
+Configuration::).  Alternatively, set up a test results cache file with
+the correct values for the host system (*note Caching Results::).
+
+   To provide a default for calls of 'AC_TRY_RUN' that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call 'AC_PROG_CC' before running them.  Then, if the shell variable
+'cross_compiling' is set to 'yes', use an alternate method to get the
+results instead of calling the macros.
+
+
+File: autoconf.info,  Node: Guidelines,  Next: Test Functions,  Prev: Test Programs,  Up: Run Time
+
+6.4.2 Guidelines for Test Programs
+----------------------------------
+
+Test programs should not write anything to the standard output.  They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status.  Test programs should 'exit', not 'return', from 'main', because
+on some systems (old Suns, at least) the argument to 'return' in 'main'
+is ignored.
+
+   Test programs can use '#if' or '#ifdef' to check the values of
+preprocessor macros defined by tests that have already run.  For
+example, if you call 'AC_HEADER_STDC', then later on in 'configure.ac'
+you can have a test program that includes an ANSI C header file
+conditionally:
+
+     #if STDC_HEADERS
+     # include <stdlib.h>
+     #endif
+
+   If a test program needs to use or create a data file, give it a name
+that starts with 'conftest', such as 'conftest.data'.  The 'configure'
+script cleans up by running 'rm -rf conftest*' after running test
+programs and if the script is interrupted.
+
+
+File: autoconf.info,  Node: Test Functions,  Prev: Guidelines,  Up: Run Time
+
+6.4.3 Test Functions
+--------------------
+
+Function declarations in test programs should have a prototype
+conditionalized for C++.  In practice, though, test programs rarely need
+functions that take arguments.
+
+     #ifdef __cplusplus
+     foo (int i)
+     #else
+     foo (i) int i;
+     #endif
+
+   Functions that test programs declare should also be conditionalized
+for C++, which requires 'extern "C"' prototypes.  Make sure to not
+include any header files containing clashing prototypes.
+
+     #ifdef __cplusplus
+     extern "C" void *malloc (size_t);
+     #else
+     char *malloc ();
+     #endif
+
+   If a test program calls a function with invalid parameters (just to
+see whether it exists), organize the program to ensure that it never
+invokes that function.  You can do this by calling it in another
+function that is never invoked.  You can't do it by putting it after a
+call to 'exit', because GCC version 2 knows that 'exit' never returns
+and optimizes out any code that follows it in the same block.
+
+   If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes.  GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, 'memcpy'.  To avoid errors when checking for them,
+either pass them the correct number of arguments or redeclare them with
+a different return type (such as 'char').
+
+
+File: autoconf.info,  Node: Systemology,  Next: Multiple Cases,  Prev: Run Time,  Up: Writing Tests
+
+6.5 Systemology
+===============
+
+This section aims at presenting some systems and pointers to
+documentation.  It may help you addressing particular problems reported
+by users.
+
+QNX 4.25
+     QNX is a realtime operating system running on Intel architecture
+     meant to be scalable from the small embedded systems to hundred
+     processor super-computer.  It claims to be POSIX certified.  More
+     information is available on the QNX home page(1), including the QNX
+     man pages(2).
+
+   ---------- Footnotes ----------
+
+   (1) QNX home page, <www.qnx.com>.
+
+   (2) QNX man pages, <http://support.qnx.com/support/docs/qnx4/>.
+
+
+File: autoconf.info,  Node: Multiple Cases,  Next: Language Choice,  Prev: Systemology,  Up: Writing Tests
+
+6.6 Multiple Cases
+==================
+
+Some operations are accomplished in several possible ways, depending on
+the UNIX variant.  Checking for them essentially requires a "case
+statement".  Autoconf does not directly provide one; however, it is easy
+to simulate by using a shell variable to keep track of whether a way to
+perform the operation has been found yet.
+
+   Here is an example that uses the shell variable 'fstype' to keep
+track of whether the remaining cases need to be checked.
+
+     AC_MSG_CHECKING([how to get file system type])
+     fstype=no
+     # The order of these tests is important.
+     AC_TRY_CPP([#include <sys/statvfs.h>
+     #include <sys/fstyp.h>],
+                [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+     if test $fstype = no; then
+       AC_TRY_CPP([#include <sys/statfs.h>
+     #include <sys/fstyp.h>],
+                  [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+     fi
+     if test $fstype = no; then
+       AC_TRY_CPP([#include <sys/statfs.h>
+     #include <sys/vmount.h>],
+                  [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+     fi
+     # (more cases omitted here)
+     AC_MSG_RESULT([$fstype])
+
+
+File: autoconf.info,  Node: Language Choice,  Prev: Multiple Cases,  Up: Writing Tests
+
+6.7 Language Choice
+===================
+
+Autoconf-generated 'configure' scripts check for the C compiler and its
+features by default.  Packages that use other programming languages
+(maybe more than one, e.g.  C and C++) need to test features of the
+compilers for the respective languages.  The following macros determine
+which programming language is used in the subsequent tests in
+'configure.ac'.
+
+ -- Macro: AC_LANG (LANGUAGE)
+     Do compilation tests using the compiler, preprocessor and file
+     extensions for the specified LANGUAGE.
+
+     Supported languages are:
+
+     'C'
+          Do compilation tests using 'CC' and 'CPP' and use extension
+          '.c' for test programs.
+
+     'C++'
+          Do compilation tests using 'CXX' and 'CXXCPP' and use
+          extension '.C' for test programs.
+
+     'Fortran 77'
+          Do compilation tests using 'F77' and use extension '.f' for
+          test programs.
+
+ -- Macro: AC_LANG_PUSH (LANGUAGE)
+     Remember the current language (as set by 'AC_LANG') on a stack, and
+     then select the LANGUAGE.  Use this macro and 'AC_LANG_POP' in
+     macros that need to temporarily switch to a particular language.
+
+ -- Macro: AC_LANG_POP ([LANGUAGE])
+     Select the language that is saved on the top of the stack, as set
+     by 'AC_LANG_PUSH', and remove it from the stack.
+
+     If given, LANGUAGE specifies the language we just _quit_.  It is a
+     good idea to specify it when it's known (which should be the
+     case...), since Autoconf will detect inconsistencies.
+
+          AC_LANG_PUSH(Fortran 77)
+          # Perform some tests on Fortran 77.
+          # ...
+          AC_LANG_POP(Fortran 77)
+
+ -- Macro: AC_REQUIRE_CPP
+     Ensure that whichever preprocessor would currently be used for
+     tests has been found.  Calls 'AC_REQUIRE' (*note Prerequisite
+     Macros::) with an argument of either 'AC_PROG_CPP' or
+     'AC_PROG_CXXCPP', depending on which language is current.
+
+
+File: autoconf.info,  Node: Results,  Next: Programming in M4,  Prev: Writing Tests,  Up: Top
+
+7 Results of Tests
+******************
+
+Once 'configure' has determined whether a feature exists, what can it do
+to record that information?  There are four sorts of things it can do:
+define a C preprocessor symbol, set a variable in the output files, save
+the result in a cache file for future 'configure' runs, and print a
+message letting the user know the result of the test.
+
+* Menu:
+
+* Defining Symbols::            Defining C preprocessor symbols
+* Setting Output Variables::    Replacing variables in output files
+* Caching Results::             Speeding up subsequent 'configure' runs
+* Printing Messages::           Notifying 'configure' users
+
+
+File: autoconf.info,  Node: Defining Symbols,  Next: Setting Output Variables,  Prev: Results,  Up: Results
+
+7.1 Defining C Preprocessor Symbols
+===================================
+
+A common action to take in response to a feature test is to define a C
+preprocessor symbol indicating the results of the test.  That is done by
+calling 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED'.
+
+   By default, 'AC_OUTPUT' places the symbols defined by these macros
+into the output variable 'DEFS', which contains an option
+'-DSYMBOL=VALUE' for each symbol defined.  Unlike in Autoconf version 1,
+there is no variable 'DEFS' defined while 'configure' is running.  To
+check whether Autoconf macros have already defined a certain C
+preprocessor symbol, test the value of the appropriate cache variable,
+as in this example:
+
+     AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
+     if test "$ac_cv_func_vprintf" != yes; then
+       AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
+     fi
+
+   If 'AC_CONFIG_HEADERS' has been called, then instead of creating
+'DEFS', 'AC_OUTPUT' creates a header file by substituting the correct
+values into '#define' statements in a template file.  *Note
+Configuration Headers::, for more information about this kind of output.
+
+ -- Macro: AC_DEFINE (VARIABLE, [VALUE], [DESCRIPTION])
+     Define C preprocessor variable VARIABLE.  If VALUE is given, set
+     VARIABLE to that value (verbatim), otherwise set it to 1.  VALUE
+     should not contain literal newlines, and if you are not using
+     'AC_CONFIG_HEADERS' it should not contain any '#' characters, as
+     'make' tends to eat them.  To use a shell variable (which you need
+     to do in order to define a value containing the M4 quote characters
+     '[' or ']'), use 'AC_DEFINE_UNQUOTED' instead.  DESCRIPTION is only
+     useful if you are using 'AC_CONFIG_HEADERS'.  In this case,
+     DESCRIPTION is put into the generated 'config.h.in' as the comment
+     before the macro define.  The following example defines the C
+     preprocessor variable 'EQUATION' to be the string constant '"$a >
+     $b"':
+
+          AC_DEFINE(EQUATION, "$a > $b")
+
+ -- Macro: AC_DEFINE_UNQUOTED (VARIABLE, [VALUE], [DESCRIPTION])
+     Like 'AC_DEFINE', but three shell expansions are
+     performed--once--on VARIABLE and VALUE: variable expansion ('$'),
+     command substitution ('`'), and backslash escaping ('\').  Single
+     and double quote characters in the value have no special meaning.
+     Use this macro instead of 'AC_DEFINE' when VARIABLE or VALUE is a
+     shell variable.  Examples:
+
+          AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
+          AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
+          AC_DEFINE_UNQUOTED($ac_tr_hdr)
+
+   Due to the syntactical bizarreness of the Bourne shell, do not use
+semicolons to separate 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED' calls from
+other macro calls or shell code; that can cause syntax errors in the
+resulting 'configure' script.  Use either spaces or newlines.  That is,
+do this:
+
+     AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
+
+or this:
+
+     AC_CHECK_HEADER(elf.h,
+      [AC_DEFINE(SVR4)
+       LIBS="$LIBS -lelf"])
+
+instead of this:
+
+     AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
+
+
+File: autoconf.info,  Node: Setting Output Variables,  Next: Caching Results,  Prev: Defining Symbols,  Up: Results
+
+7.2 Setting Output Variables
+============================
+
+Another way to record the results of tests is to set "output variables",
+which are shell variables whose values are substituted into files that
+'configure' outputs.  The two macros below create new output variables.
+*Note Preset Output Variables::, for a list of output variables that are
+always available.
+
+ -- Macro: AC_SUBST (VARIABLE, [VALUE])
+     Create an output variable from a shell variable.  Make 'AC_OUTPUT'
+     substitute the variable VARIABLE into output files (typically one
+     or more 'Makefile's).  This means that 'AC_OUTPUT' will replace
+     instances of '@VARIABLE@' in input files with the value that the
+     shell variable VARIABLE has when 'AC_OUTPUT' is called.  This value
+     of VARIABLE should not contain literal newlines.
+
+     If VALUE is given, in addition assign it to 'variable'.
+
+ -- Macro: AC_SUBST_FILE (VARIABLE)
+     Another way to create an output variable from a shell variable.
+     Make 'AC_OUTPUT' insert (without substitutions) the contents of the
+     file named by shell variable VARIABLE into output files.  This
+     means that 'AC_OUTPUT' will replace instances of '@VARIABLE@' in
+     output files (such as 'Makefile.in') with the contents of the file
+     that the shell variable VARIABLE names when 'AC_OUTPUT' is called.
+     Set the variable to '/dev/null' for cases that do not have a file
+     to insert.
+
+     This macro is useful for inserting 'Makefile' fragments containing
+     special dependencies or other 'make' directives for particular host
+     or target types into 'Makefile's.  For example, 'configure.ac'
+     could contain:
+
+          AC_SUBST_FILE(host_frag)
+          host_frag=$srcdir/conf/sun4.mh
+
+     and then a 'Makefile.in' could contain:
+
+          @host_frag@
+
+   Running 'configure' in different environments can be extremely
+dangerous.  If for instance the user runs 'CC=bizarre-cc ./configure',
+then the cache, 'config.h' and many other output files will depend upon
+'bizarre-cc' being the C compiler.  If for some reason the user runs
+'/configure' again, or if it is run via './config.status --recheck',
+(*Note Automatic Remaking::, and *note config.status Invocation::), then
+the configuration can be inconsistent, composed of results depending
+upon two different compilers.
+
+   Such variables are named "precious variables", and can be declared as
+such by 'AC_ARG_VAR'.
+
+ -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION)
+     Declare VARIABLE is a precious variable, and include its
+     DESCRIPTION in the variable section of './configure --help'.
+
+     Being precious means that
+        - VARIABLE is 'AC_SUBST''d.
+
+        - VARIABLE is kept in the cache including if it was not
+          specified on the './configure' command line.  Indeed, while
+          'configure' can notice the definition of 'CC' in './configure
+          CC=bizarre-cc', it is impossible to notice it in
+          'CC=bizarre-cc ./configure', which, unfortunately, is what
+          most users do.
+
+        - VARIABLE is checked for consistency between two 'configure'
+          runs.  For instance:
+
+               $ ./configure --silent --config-cache
+               $ CC=cc ./configure --silent --config-cache
+               configure: error: `CC' was not set in the previous run
+               configure: error: changes in the environment can compromise \
+               the build
+               configure: error: run `make distclean' and/or \
+               `rm config.cache' and start over
+
+          and similarly if the variable is unset, or if its content is
+          changed.
+
+        - VARIABLE is kept during automatic reconfiguration (*note
+          config.status Invocation::) as if it had been passed as a
+          command line argument, including when no cache is used:
+
+               $ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent
+               $ ./config.status --recheck
+               running /bin/sh ./configure undeclared_var=raboof --silent \
+                 CC=/usr/bin/cc  --no-create --no-recursion
+
+
+File: autoconf.info,  Node: Caching Results,  Next: Printing Messages,  Prev: Setting Output Variables,  Up: Results
+
+7.3 Caching Results
+===================
+
+To avoid checking for the same features repeatedly in various
+'configure' scripts (or in repeated runs of one script), 'configure' can
+optionally save the results of many checks in a "cache file" (*note
+Cache Files::).  If a 'configure' script runs with caching enabled and
+finds a cache file, it reads the results of previous runs from the cache
+and avoids rerunning those checks.  As a result, 'configure' can then
+run much faster than if it had to perform all of the checks every time.
+
+ -- Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT)
+     Ensure that the results of the check identified by CACHE-ID are
+     available.  If the results of the check were in the cache file that
+     was read, and 'configure' was not given the '--quiet' or '--silent'
+     option, print a message saying that the result was cached;
+     otherwise, run the shell commands COMMANDS-TO-SET-IT.  If the shell
+     commands are run to determine the value, the value will be saved in
+     the cache file just before 'configure' creates its output files.
+     *Note Cache Variable Names::, for how to choose the name of the
+     CACHE-ID variable.
+
+     The COMMANDS-TO-SET-IT _must have no side effects_ except for
+     setting the variable CACHE-ID, see below.
+
+ -- Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS-TO-SET-IT)
+     A wrapper for 'AC_CACHE_VAL' that takes care of printing the
+     messages.  This macro provides a convenient shorthand for the most
+     common way to use these macros.  It calls 'AC_MSG_CHECKING' for
+     MESSAGE, then 'AC_CACHE_VAL' with the CACHE-ID and COMMANDS
+     arguments, and 'AC_MSG_RESULT' with CACHE-ID.
+
+     The COMMANDS-TO-SET-IT _must have no side effects_ except for
+     setting the variable CACHE-ID, see below.
+
+   It is very common to find buggy macros using 'AC_CACHE_VAL' or
+'AC_CACHE_CHECK', because people are tempted to call 'AC_DEFINE' in the
+COMMANDS-TO-SET-IT.  Instead, the code that _follows_ the call to
+'AC_CACHE_VAL' should call 'AC_DEFINE', by examining the value of the
+cache variable.  For instance, the following macro is broken:
+
+     AC_DEFUN([AC_SHELL_TRUE],
+     [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+                     [ac_cv_shell_true_works=no
+                      true && ac_cv_shell_true_works=yes
+                      if test $ac_cv_shell_true_works = yes; then
+                        AC_DEFINE([TRUE_WORKS], 1
+                                  [Define if `true(1)' works properly.])
+                      fi])
+     ])
+
+This fails if the cache is enabled: the second time this macro is run,
+'TRUE_WORKS' _will not be defined_.  The proper implementation is:
+
+     AC_DEFUN([AC_SHELL_TRUE],
+     [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+                     [ac_cv_shell_true_works=no
+                      true && ac_cv_shell_true_works=yes])
+      if test $ac_cv_shell_true_works = yes; then
+        AC_DEFINE([TRUE_WORKS], 1
+                  [Define if `true(1)' works properly.])
+      fi
+     ])
+
+   Also, COMMANDS-TO-SET-IT should not print any messages, for example
+with 'AC_MSG_CHECKING'; do that before calling 'AC_CACHE_VAL', so the
+messages are printed regardless of whether the results of the check are
+retrieved from the cache or determined by running the shell commands.
+
+* Menu:
+
+* Cache Variable Names::        Shell variables used in caches
+* Cache Files::                 Files 'configure' uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
+
+
+File: autoconf.info,  Node: Cache Variable Names,  Next: Cache Files,  Prev: Caching Results,  Up: Caching Results
+
+7.3.1 Cache Variable Names
+--------------------------
+
+The names of cache variables should have the following format:
+
+     PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE_[ADDITIONAL-OPTIONS]
+
+for example, 'ac_cv_header_stat_broken' or 'ac_cv_prog_gcc_traditional'.
+The parts of the variable name are:
+
+PACKAGE-PREFIX
+     An abbreviation for your package or organization; the same prefix
+     you begin local Autoconf macros with, except lowercase by
+     convention.  For cache values used by the distributed Autoconf
+     macros, this value is 'ac'.
+
+'_cv_'
+     Indicates that this shell variable is a cache value.  This string
+     _must_ be present in the variable name, including the leading
+     underscore.
+
+VALUE-TYPE
+     A convention for classifying cache values, to produce a rational
+     naming system.  The values used in Autoconf are listed in *note
+     Macro Names::.
+
+SPECIFIC-VALUE
+     Which member of the class of cache values this test applies to.
+     For example, which function ('alloca'), program ('gcc'), or output
+     variable ('INSTALL').
+
+ADDITIONAL-OPTIONS
+     Any particular behavior of the specific member that this test
+     applies to.  For example, 'broken' or 'set'.  This part of the name
+     may be omitted if it does not apply.
+
+   The values assigned to cache variables may not contain newlines.
+Usually, their values will be boolean ('yes' or 'no') or the names of
+files or functions; so this is not an important restriction.
+
+
+File: autoconf.info,  Node: Cache Files,  Next: Cache Checkpointing,  Prev: Cache Variable Names,  Up: Caching Results
+
+7.3.2 Cache Files
+-----------------
+
+A cache file is a shell script that caches the results of configure
+tests run on one system so they can be shared between configure scripts
+and configure runs.  It is not useful on other systems.  If its contents
+are invalid for some reason, the user may delete or edit it.
+
+   By default, 'configure' uses no cache file (technically, it uses
+'--cache-file=/dev/null'), to avoid problems caused by accidental use of
+stale cache files.
+
+   To enable caching, 'configure' accepts '--config-cache' (or '-C') to
+cache results in the file 'config.cache'.  Alternatively,
+'--cache-file=FILE' specifies that FILE be the cache file.  The cache
+file is created if it does not exist already.  When 'configure' calls
+'configure' scripts in subdirectories, it uses the '--cache-file'
+argument so that they share the same cache.  *Note Subdirectories::, for
+information on configuring subdirectories with the 'AC_CONFIG_SUBDIRS'
+macro.
+
+   'config.status' only pays attention to the cache file if it is given
+the '--recheck' option, which makes it rerun 'configure'.
+
+   It is wrong to try to distribute cache files for particular system
+types.  There is too much room for error in doing that, and too much
+administrative overhead in maintaining them.  For any features that
+can't be guessed automatically, use the standard method of the canonical
+system type and linking files (*note Manual Configuration::).
+
+   The site initialization script can specify a site-wide cache file to
+use, instead of the usual per-program cache.  In this case, the cache
+file will gradually accumulate information whenever someone runs a new
+'configure' script.  (Running 'configure' merges the new cache results
+with the existing cache file.)  This may cause problems, however, if the
+system configuration (e.g.  the installed libraries or compilers)
+changes and the stale cache file is not deleted.
+
+
+File: autoconf.info,  Node: Cache Checkpointing,  Prev: Cache Files,  Up: Caching Results
+
+7.3.3 Cache Checkpointing
+-------------------------
+
+If your configure script, or a macro called from configure.ac, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using 'AC_CACHE_SAVE'.  Doing so will reduce
+the amount of time it takes to re-run the configure script with
+(hopefully) the error that caused the previous abort corrected.
+
+ -- Macro: AC_CACHE_LOAD
+     Loads values from existing cache file, or creates a new cache file
+     if a cache file is not found.  Called automatically from 'AC_INIT'.
+
+ -- Macro: AC_CACHE_SAVE
+     Flushes all cached values to the cache file.  Called automatically
+     from 'AC_OUTPUT', but it can be quite useful to call
+     'AC_CACHE_SAVE' at key points in configure.ac.
+
+   For instance:
+
+      ... AC_INIT, etc. ...
+     # Checks for programs.
+     AC_PROG_CC
+     AC_PROG_GCC_TRADITIONAL
+      ... more program checks ...
+     AC_CACHE_SAVE
+
+     # Checks for libraries.
+     AC_CHECK_LIB(nsl, gethostbyname)
+     AC_CHECK_LIB(socket, connect)
+      ... more lib checks ...
+     AC_CACHE_SAVE
+
+     # Might abort...
+     AM_PATH_GTK(1.0.2,, (exit 1); exit)
+     AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
+      ... AC_OUTPUT, etc. ...
+
+
+File: autoconf.info,  Node: Printing Messages,  Prev: Caching Results,  Up: Results
+
+7.4 Printing Messages
+=====================
+
+'configure' scripts need to give users running them several kinds of
+information.  The following macros print messages in ways appropriate
+for each kind.  The arguments to all of them get enclosed in shell
+double quotes, so the shell performs variable and back-quote
+substitution on them.
+
+   These macros are all wrappers around the 'echo' shell command.
+'configure' scripts should rarely need to run 'echo' directly to print
+messages for the user.  Using these macros makes it easy to change how
+and when each kind of message is printed; such changes need only be made
+to the macro definitions and all of the callers will change
+automatically.
+
+   To diagnose static issues, i.e., when 'autoconf' is run, see *note
+Reporting Messages::.
+
+ -- Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION)
+     Notify the user that 'configure' is checking for a particular
+     feature.  This macro prints a message that starts with 'checking '
+     and ends with '...' and no newline.  It must be followed by a call
+     to 'AC_MSG_RESULT' to print the result of the check and the
+     newline.  The FEATURE-DESCRIPTION should be something like 'whether
+     the Fortran compiler accepts C++ comments' or 'for c89'.
+
+     This macro prints nothing if 'configure' is run with the '--quiet'
+     or '--silent' option.
+
+ -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION)
+     Notify the user of the results of a check.  RESULT-DESCRIPTION is
+     almost always the value of the cache variable for the check,
+     typically 'yes', 'no', or a file name.  This macro should follow a
+     call to 'AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be the
+     completion of the message printed by the call to 'AC_MSG_CHECKING'.
+
+     This macro prints nothing if 'configure' is run with the '--quiet'
+     or '--silent' option.
+
+ -- Macro: AC_MSG_NOTICE (MESSAGE)
+     Deliver the MESSAGE to the user.  It is useful mainly to print a
+     general description of the overall purpose of a group of feature
+     checks, e.g.,
+
+          AC_MSG_NOTICE([checking if stack overflow is detectable])
+
+     This macro prints nothing if 'configure' is run with the '--quiet'
+     or '--silent' option.
+
+ -- Macro: AC_MSG_ERROR (ERROR-DESCRIPTION, [EXIT-STATUS])
+     Notify the user of an error that prevents 'configure' from
+     completing.  This macro prints an error message to the standard
+     error output and exits 'configure' with EXIT-STATUS (1 by default).
+     ERROR-DESCRIPTION should be something like 'invalid value $HOME for
+     \$HOME'.
+
+     The ERROR-DESCRIPTION should start with a lower-case letter, and
+     "cannot" is preferred to "can't".
+
+ -- Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION)
+     Notify the 'configure' user of a possible problem.  This macro
+     prints the message to the standard error output; 'configure'
+     continues running afterward, so macros that call 'AC_MSG_WARN'
+     should provide a default (back-up) behavior for the situations they
+     warn about.  PROBLEM-DESCRIPTION should be something like 'ln -s
+     seems to make hard links'.
+
+
+File: autoconf.info,  Node: Programming in M4,  Next: Writing Autoconf Macros,  Prev: Results,  Up: Top
+
+8 Programming in M4
+*******************
+
+Autoconf is written on top of two layers: "M4sugar", which provides
+convenient macros for pure M4 programming, and "M4sh", which provides
+macros dedicated to shell script generation.
+
+   As of this version of Autoconf, these two layers are still
+experimental, and their interface might change in the future.  As a
+matter of fact, _anything that is not documented must not be used_.
+
+* Menu:
+
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+
+
+File: autoconf.info,  Node: M4 Quotation,  Next: Programming in M4sugar,  Prev: Programming in M4,  Up: Programming in M4
+
+8.1 M4 Quotation
+================
+
+The most common brokenness of existing macros is an improper quotation.
+This section, which users of Autoconf can skip, but which macro writers
+_must_ read, first justifies the quotation scheme that was chosen for
+Autoconf and then ends with a rule of thumb.  Understanding the former
+helps one to follow the latter.
+
+* Menu:
+
+* Active Characters::           Characters that change the behavior of m4
+* One Macro Call::              Quotation and one macro call
+* Quotation and Nested Macros::  Macros calling macros
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+
+
+File: autoconf.info,  Node: Active Characters,  Next: One Macro Call,  Prev: M4 Quotation,  Up: M4 Quotation
+
+8.1.1 Active Characters
+-----------------------
+
+To fully understand where proper quotation is important, you first need
+to know what are the special characters in Autoconf: '#' introduces a
+comment inside which no macro expansion is performed, ',' separates
+arguments, '[' and ']' are the quotes themselves, and finally '(' and
+')' (which 'm4' tries to match by pairs).
+
+   In order to understand the delicate case of macro calls, we first
+have to present some obvious failures.  Below they are "obvious-ified",
+although you find them in real life, they are usually in disguise.
+
+   Comments, introduced by a hash and running up to the newline, are
+opaque tokens to the top level: active characters are turned off, and
+there is no macro expansion:
+
+     # define([def], ine)
+     =># define([def], ine)
+
+   Each time there can be a macro expansion, there is a quotation
+expansion; i.e., one level of quotes is stripped:
+
+     int tab[10];
+     =>int tab10;
+     [int tab[10];]
+     =>int tab[10];
+
+   Without this in mind, the reader will try hopelessly to use her macro
+'array':
+
+     define([array], [int tab[10];])
+     array
+     =>int tab10;
+     [array]
+     =>array
+
+How can you correctly output the intended results(1)?
+
+   ---------- Footnotes ----------
+
+   (1) Using 'defn'.
+
+
+File: autoconf.info,  Node: One Macro Call,  Next: Quotation and Nested Macros,  Prev: Active Characters,  Up: M4 Quotation
+
+8.1.2 One Macro Call
+--------------------
+
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
+
+     define([car], [$1])
+
+The two pairs of quotes above are not part of the arguments of 'define';
+rather, they are understood by the top level when it tries to find the
+arguments of 'define'.  Therefore, it is equivalent to write:
+
+     define(car, $1)
+
+But, while it is acceptable for a 'configure.ac' to avoid unneeded
+quotes, it is bad practice for Autoconf macros which must both be more
+robust and also advocate perfect style.
+
+   At the top level, there are only two possible quotings: either you
+quote or you don't:
+
+     car(foo, bar, baz)
+     =>foo
+     [car(foo, bar, baz)]
+     =>car(foo, bar, baz)
+
+   Let's pay attention to the special characters:
+
+     car(#)
+     error->EOF in argument list
+
+   The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
+
+     car([#)]
+
+Proper quotation, of course, fixes the problem:
+
+     car([#])
+     =>#
+
+   The reader will easily understand the following examples:
+
+     car(foo, bar)
+     =>foo
+     car([foo, bar])
+     =>foo, bar
+     car((foo, bar))
+     =>(foo, bar)
+     car([(foo], [bar)])
+     =>(foo
+     car([], [])
+     =>
+     car([[]], [[]])
+     =>[]
+
+   With this in mind, we can explore the cases where macros invoke
+macros...
+
+
+File: autoconf.info,  Node: Quotation and Nested Macros,  Next: Quadrigraphs,  Prev: One Macro Call,  Up: M4 Quotation
+
+8.1.3 Quotation and Nested Macros
+---------------------------------
+
+The examples below use the following macros:
+
+     define([car], [$1])
+     define([active], [ACT, IVE])
+     define([array], [int tab[10]])
+
+   Each additional embedded macro call introduces other possible
+interesting quotations:
+
+     car(active)
+     =>ACT
+     car([active])
+     =>ACT, IVE
+     car([[active]])
+     =>active
+
+   In the first case, the top level looks for the arguments of 'car',
+and finds 'active'.  Because 'm4' evaluates its arguments before
+applying the macro, 'active' is expanded, which results in:
+
+     car(ACT, IVE)
+     =>ACT
+
+In the second case, the top level gives 'active' as first and only
+argument of 'car', which results in:
+
+     active
+     =>ACT, IVE
+
+i.e., the argument is evaluated _after_ the macro that invokes it.  In
+the third case, 'car' receives '[active]', which results in:
+
+     [active]
+     =>active
+
+exactly as we already saw above.
+
+   The example above, applied to a more realistic example, gives:
+
+     car(int tab[10];)
+     =>int tab10;
+     car([int tab[10];])
+     =>int tab10;
+     car([[int tab[10];]])
+     =>int tab[10];
+
+Huh?  The first case is easily understood, but why is the second wrong,
+and the third right?  To understand that, you must know that after 'm4'
+expands a macro, the resulting text is immediately subjected to macro
+expansion and quote removal.  This means that the quote removal occurs
+twice--first before the argument is passed to the 'car' macro, and
+second after the 'car' macro expands to the first argument.
+
+   As the author of the Autoconf macro 'car', you then consider it to be
+incorrect that your users have to double-quote the arguments of 'car',
+so you "fix" your macro.  Let's call it 'qar' for quoted car:
+
+     define([qar], [[$1]])
+
+and check that 'qar' is properly fixed:
+
+     qar([int tab[10];])
+     =>int tab[10];
+
+Ahhh!  That's much better.
+
+   But note what you've done: now that the arguments are literal
+strings, if the user wants to use the results of expansions as
+arguments, she has to use an _unquoted_ macro call:
+
+     qar(active)
+     =>ACT
+
+where she wanted to reproduce what she used to do with 'car':
+
+     car([active])
+     =>ACT, IVE
+
+Worse yet: she wants to use a macro that produces a set of 'cpp' macros:
+
+     define([my_includes], [#include <stdio.h>])
+     car([my_includes])
+     =>#include <stdio.h>
+     qar(my_includes)
+     error->EOF in argument list
+
+   This macro, 'qar', because it double quotes its arguments, forces its
+users to leave their macro calls unquoted, which is dangerous.  Commas
+and other active symbols are interpreted by 'm4' before they are given
+to the macro, often not in the way the users expect.  Also, because
+'qar' behaves differently from the other macros, it's an exception that
+should be avoided in Autoconf.
+
+
+File: autoconf.info,  Node: Quadrigraphs,  Next: Quotation Rule Of Thumb,  Prev: Quotation and Nested Macros,  Up: M4 Quotation
+
+8.1.4 Quadrigraphs
+------------------
+
+When writing an autoconf macro you may occasionally need to generate
+special characters that are difficult to express with the standard
+autoconf quoting rules.  For example, you may need to output the regular
+expression '[^[]', which matches any character other than '['.  This
+expression contains unbalanced brackets so it cannot be put easily into
+an M4 macro.
+
+   You can work around this problem by using one of the following
+"quadrigraphs":
+
+'@<:@'
+     '['
+'@:>@'
+     ']'
+'@S|@'
+     '$'
+'@%:@'
+     '#'
+
+   Quadrigraphs are replaced at a late stage of the translation process,
+after 'm4' is run, so they do not get in the way of M4 quoting.  For
+example, the string '[^@<:@]', if properly quoted, will appear as '[^[]'
+in the 'configure' script.
+
+
+File: autoconf.info,  Node: Quotation Rule Of Thumb,  Prev: Quadrigraphs,  Up: M4 Quotation
+
+8.1.5 Quotation Rule Of Thumb
+-----------------------------
+
+To conclude, the quotation rule of thumb is:
+
+             _One pair of quotes per pair of parentheses._
+
+   Never over-quote, never under-quote, in particular in the definition
+of macros.  In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), properly quote _the
+arguments_!
+
+   It is common to read Autoconf programs with snippets like:
+
+     AC_TRY_LINK(
+     changequote(<<, >>)dnl
+     <<#include <time.h>
+     #ifndef tzname /* For SGI.  */
+     extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+     #endif>>,
+     changequote([, ])dnl
+     [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+
+which is incredibly useless since 'AC_TRY_LINK' is _already_ double
+quoting, so you just need:
+
+     AC_TRY_LINK(
+     [#include <time.h>
+     #ifndef tzname /* For SGI.  */
+     extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+     #endif],
+                 [atoi (*tzname);],
+                 [ac_cv_var_tzname=yes],
+                 [ac_cv_var_tzname=no])
+
+The M4-fluent reader will note that these two examples are rigorously
+equivalent, since 'm4' swallows both the 'changequote(<<, >>)' and '<<'
+'>>' when it "collects" the arguments: these quotes are not part of the
+arguments!
+
+   Simplified, the example above is just doing this:
+
+     changequote(<<, >>)dnl
+     <<[]>>
+     changequote([, ])dnl
+
+instead of simply:
+
+     [[]]
+
+   With macros that do not double quote their arguments (which is the
+rule), double-quote the (risky) literals:
+
+     AC_LINK_IFELSE([AC_LANG_PROGRAM(
+     [[#include <time.h>
+     #ifndef tzname /* For SGI.  */
+     extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+     #endif]],
+                                     [atoi (*tzname);])],
+                    [ac_cv_var_tzname=yes],
+                    [ac_cv_var_tzname=no])
+
+   See *Note Quadrigraphs::, for what to do if you run into a hopeless
+case where quoting does not suffice.
+
+   When you create a 'configure' script using newly written macros,
+examine it carefully to check whether you need to add more quotes in
+your macros.  If one or more words have disappeared in the 'm4' output,
+you need more quotes.  When in doubt, quote.
+
+   However, it's also possible to put on too many layers of quotes.  If
+this happens, the resulting 'configure' script will contain unexpanded
+macros.  The 'autoconf' program checks for this problem by doing 'grep
+AC_ configure'.
+
+
+File: autoconf.info,  Node: Programming in M4sugar,  Prev: M4 Quotation,  Up: Programming in M4
+
+8.2 Programming in M4sugar
+==========================
+
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros.  M4sugar introduces additional generic macros.  Its name was
+coined by Lars J. Aas: "Readability And Greater Understanding Stands 4
+M4sugar".
+
+* Menu:
+
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+
+
+File: autoconf.info,  Node: Redefined M4 Macros,  Next: Forbidden Patterns,  Prev: Programming in M4sugar,  Up: Programming in M4sugar
+
+8.2.1 Redefined M4 Macros
+-------------------------
+
+All the M4 native macros are moved in the 'm4_' pseudo-namespace, e.g.,
+M4sugar renames 'define' as 'm4_define' etc.  There is one exception:
+'dnl' kept its original name, and no 'm4_dnl' is defined.
+
+   M4sugar redefines some M4 macros, and made them slightly incompatible
+with their native equivalent.
+
+ -- Macro: m4_defn (MACRO)
+     Contrary to the M4 builtin, this macro fails if MACRO is not
+     defined.  See 'm4_undefine'.
+
+ -- Macro: m4_undefine (MACRO)
+     Contrary to the M4 builtin, this macro fails if MACRO is not
+     defined.  Use
+
+          m4_ifdef([MACRO], [m4_undefine([MACRO])])
+
+     to recover the behavior of the builtin.
+
+ -- Macro: m4_popdef (MACRO)
+     Contrary to the M4 builtin, this macro fails if MACRO is not
+     defined.  See 'm4_undefine'.
+
+
+File: autoconf.info,  Node: Forbidden Patterns,  Prev: Redefined M4 Macros,  Up: Programming in M4sugar
+
+8.2.2 Forbidden Patterns
+------------------------
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output.  For
+instance, if an Autoconf 'configure' script includes tokens such as
+'AC_DEFINE', or 'dnl', then most probably something went wrong
+(typically a macro was not evaluated because of over quotation).
+
+   M4sugar forbids all the tokens matching '^m4_' and '^dnl$'.
+
+ -- Macro: m4_pattern_forbid (PATTERN)
+     Declare no token matching PATTERN must be found in the output.
+     Comments are not checked; this can be a problem if, for instance,
+     you have some macro left unexpanded after an '#include'.  No
+     consensus is currently found in the Autoconf community, as some
+     people consider it should be valid to name macros in comments
+     (which doesn't makes sense to the author of this documentation, as
+     '#'-comments should document the output, not the input, documented
+     vy 'dnl'-comments).
+
+   Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to '$m4_flags'.
+
+ -- Macro: m4_pattern_allow (PATTERN)
+     Any token matching PATTERN is allowed, including if it matches an
+     'm4_pattern_forbid' pattern.
+
+
+File: autoconf.info,  Node: Writing Autoconf Macros,  Next: Portable Shell,  Prev: Programming in M4,  Up: Top
+
+9 Writing Autoconf Macros
+*************************
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
+
+* Menu:
+
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* Reporting Messages::          Notifying 'autoconf' users
+* Dependencies Between Macros::  What to do when macros depend on other macros
+* Obsoleting Macros::           Warning about old ways of doing things
+* Coding Style::                Writing Autoconf macros à la Autoconf
+
+
+File: autoconf.info,  Node: Macro Definitions,  Next: Macro Names,  Prev: Writing Autoconf Macros,  Up: Writing Autoconf Macros
+
+9.1 Macro Definitions
+=====================
+
+Autoconf macros are defined using the 'AC_DEFUN' macro, which is similar
+to the M4 builtin 'define' macro.  In addition to defining a macro,
+'AC_DEFUN' adds to it some code that is used to constrain the order in
+which macros are called (*note Prerequisite Macros::).
+
+   An Autoconf macro definition looks like this:
+
+     AC_DEFUN(MACRO-NAME, MACRO-BODY)
+
+   You can refer to any arguments passed to the macro as '$1', '$2',
+etc.  *Note How to define new macros: (m4.info)Definitions, for more
+complete information on writing M4 macros.
+
+   Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME to
+avoid any problems if the macro happens to have been previously defined.
+
+   Each macro should have a header comment that gives its prototype, and
+a brief description.  When arguments have default values, display them
+in the prototype.  For example:
+
+     # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+     # --------------------------------------
+     define([AC_MSG_ERROR],
+     [{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); }])
+
+   Comments about the macro should be left in the header comment.  Most
+other comments will make their way into 'configure', so just keep using
+'#' to introduce comments.
+
+   If you have some very special comments about pure M4 code, comments
+that make no sense in 'configure' and in the header comment, then use
+the builtin 'dnl': it causes 'm4' to discard the text through the next
+newline.
+
+   Keep in mind that 'dnl' is rarely needed to introduce comments; 'dnl'
+is more useful to get rid of the newlines following macros that produce
+no output, such as 'AC_REQUIRE'.
+
+
+File: autoconf.info,  Node: Macro Names,  Next: Reporting Messages,  Prev: Macro Definitions,  Up: Writing Autoconf Macros
+
+9.2 Macro Names
+===============
+
+All of the Autoconf macros have all-uppercase names starting with 'AC_'
+to prevent them from accidentally conflicting with other text.  All
+shell variables that they use for internal purposes have
+mostly-lowercase names starting with 'ac_'.  To ensure that your macros
+don't conflict with present or future Autoconf macros, you should prefix
+your own macro names and any shell variables they use with some other
+sequence.  Possibilities include your initials, or an abbreviation for
+the name of your organization or software package.
+
+   Most of the Autoconf macros' names follow a structured naming
+convention that indicates the kind of feature check by the name.  The
+macro names consist of several words, separated by underscores, going
+from most general to most specific.  The names of their cache variables
+use the same convention (*note Cache Variable Names::, for more
+information on them).
+
+   The first word of the name after 'AC_' usually tells the category of
+feature being tested.  Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write.  They are also used for cache variables, in all-lowercase.  Use
+them where applicable; where they're not, invent your own categories.
+
+'C'
+     C language builtin features.
+'DECL'
+     Declarations of C variables in header files.
+'FUNC'
+     Functions in libraries.
+'GROUP'
+     UNIX group owners of files.
+'HEADER'
+     Header files.
+'LIB'
+     C libraries.
+'PATH'
+     The full path names to files, including programs.
+'PROG'
+     The base names of programs.
+'MEMBER'
+     Members of aggregates.
+'SYS'
+     Operating system features.
+'TYPE'
+     C builtin or declared types.
+'VAR'
+     C variables in libraries.
+
+   After the category comes the name of the particular feature being
+tested.  Any further words in the macro name indicate particular aspects
+of the feature.  For example, 'AC_FUNC_UTIME_NULL' checks the behavior
+of the 'utime' function when called with a 'NULL' pointer.
+
+   An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with '_AC_'.  Additionally, a
+macro that is an internal subroutine of another macro should have a name
+that starts with an underscore and the name of that other macro,
+followed by one or more words saying what the internal macro does.  For
+example, 'AC_PATH_X' has internal macros '_AC_PATH_X_XMKMF' and
+'_AC_PATH_X_DIRECT'.
+
+
+File: autoconf.info,  Node: Reporting Messages,  Next: Dependencies Between Macros,  Prev: Macro Names,  Up: Writing Autoconf Macros
+
+9.3 Reporting Messages
+======================
+
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros.  For dynamic issues, i.e.,
+when 'configure' is run, see *note Printing Messages::.
+
+ -- Macro: AC_DIAGNOSE (CATEGORY, MESSAGE)
+     Report MESSAGE as a warning (or as an error if requested by the
+     user) if it falls into the CATEGORY.  You are encouraged to use
+     standard categories, which currently include:
+
+     'all'
+          messages that don't fall into one of the following category.
+          Use of an empty CATEGORY is equivalent.
+
+     'cross'
+          related to cross compilation issues.
+
+     'obsolete'
+          use of an obsolete construct.
+
+     'syntax'
+          dubious syntactic constructs, incorrectly ordered macro calls.
+
+ -- Macro: AC_WARNING (MESSAGE)
+     Equivalent to 'AC_DIAGNOSE([syntax], MESSAGE)', but you are
+     strongly encouraged to use a finer grained category.
+
+ -- Macro: AC_FATAL (MESSAGE)
+     Report a severe error MESSAGE, and have 'autoconf' die.
+
+   When the user runs 'autoconf -W error', warnings from 'AC_DIAGNOSE'
+and 'AC_WARNING' are reported as error, see *note autoconf Invocation::.
+
+
+File: autoconf.info,  Node: Dependencies Between Macros,  Next: Obsoleting Macros,  Prev: Reporting Messages,  Up: Writing Autoconf Macros
+
+9.4 Dependencies Between Macros
+===============================
+
+Some Autoconf macros depend on other macros having been called first in
+order to work correctly.  Autoconf provides a way to ensure that certain
+macros are called if needed and a way to warn the user if macros are
+called in an order that might cause incorrect operation.
+
+* Menu:
+
+* Prerequisite Macros::         Ensuring required information
+* Suggested Ordering::          Warning about possible ordering problems
+
+
+File: autoconf.info,  Node: Prerequisite Macros,  Next: Suggested Ordering,  Prev: Dependencies Between Macros,  Up: Dependencies Between Macros
+
+9.4.1 Prerequisite Macros
+-------------------------
+
+A macro that you write might need to use values that have previously
+been computed by other macros.  For example, 'AC_DECL_YYTEXT' examines
+the output of 'flex' or 'lex', so it depends on 'AC_PROG_LEX' having
+been called first to set the shell variable 'LEX'.
+
+   Rather than forcing the user of the macros to keep track of the
+dependencies between them, you can use the 'AC_REQUIRE' macro to do it
+automatically.  'AC_REQUIRE' can ensure that a macro is only called if
+it is needed, and only called once.
+
+ -- Macro: AC_REQUIRE (MACRO-NAME)
+     If the M4 macro MACRO-NAME has not already been called, call it
+     (without any arguments).  Make sure to quote MACRO-NAME with square
+     brackets.  MACRO-NAME must have been defined using 'AC_DEFUN' or
+     else contain a call to 'AC_PROVIDE' to indicate that it has been
+     called.
+
+     'AC_REQUIRE' must be used inside an 'AC_DEFUN''d macro; it must not
+     be called from the top level.
+
+   'AC_REQUIRE' is often misunderstood.  It really implements
+dependencies between macros in the sense that if one macro depends upon
+another, the latter will be expanded _before_ the body of the former.
+In particular, 'AC_REQUIRE(FOO)' is not replaced with the body of 'FOO'.
+For instance, this definition of macros:
+
+     AC_DEFUN([TRAVOLTA],
+     [test "$body_temparature_in_celsius" -gt "38" &&
+       dance_floor=occupied])
+     AC_DEFUN([NEWTON_JOHN],
+     [test "$hair_style" = "curly" &&
+       dance_floor=occupied])
+
+     AC_DEFUN([RESERVE_DANCE_FLOOR],
+     [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+       AC_REQUIRE([TRAVOLTA])
+       AC_REQUIRE([NEWTON_JOHN])
+     fi])
+
+with this 'configure.ac'
+
+     AC_INIT
+     RESERVE_DANCE_FLOOR
+     if test "$dance_floor" = occupied; then
+       AC_MSG_ERROR([cannot pick up here, let's move])
+     fi
+
+will not leave you with a better chance to meet a kindred soul at other
+times than Saturday night since it expands into:
+
+     test "$body_temperature_in_Celsius" -gt "38" &&
+       dance_floor=occupied
+     test "$hair_style" = "curly" &&
+       dance_floor=occupied
+     fi
+     if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+
+
+     fi
+
+   This behavior was chosen on purpose: (i) it prevents messages in
+required macros from interrupting the messages in the requiring macros;
+(ii) it avoids bad surprises when shell conditionals are used, as in:
+
+     if ...; then
+       AC_REQUIRE([SOME_CHECK])
+     fi
+     ...
+     SOME_CHECK
+
+   You are encouraged to put all 'AC_REQUIRE's at the beginning of a
+macro.  You can use 'dnl' to avoid the empty lines they leave.
+
+
+File: autoconf.info,  Node: Suggested Ordering,  Prev: Prerequisite Macros,  Up: Dependencies Between Macros
+
+9.4.2 Suggested Ordering
+------------------------
+
+Some macros should be run before another macro if both are called, but
+neither _requires_ that the other be called.  For example, a macro that
+changes the behavior of the C compiler should be called before any
+macros that run the C compiler.  Many of these dependencies are noted in
+the documentation.
+
+   Autoconf provides the 'AC_BEFORE' macro to warn users when macros
+with this kind of dependency appear out of order in a 'configure.ac'
+file.  The warning occurs when creating 'configure' from 'configure.ac',
+not when running 'configure'.
+
+   For example, 'AC_PROG_CPP' checks whether the C compiler can run the
+C preprocessor when given the '-E' option.  It should therefore be
+called after any macros that change which C compiler is being used, such
+as 'AC_PROG_CC'.  So 'AC_PROG_CC' contains:
+
+     AC_BEFORE([$0], [AC_PROG_CPP])dnl
+
+This warns the user if a call to 'AC_PROG_CPP' has already occurred when
+'AC_PROG_CC' is called.
+
+ -- Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME)
+     Make 'm4' print a warning message to the standard error output if
+     CALLED-MACRO-NAME has already been called.  THIS-MACRO-NAME should
+     be the name of the macro that is calling 'AC_BEFORE'.  The macro
+     CALLED-MACRO-NAME must have been defined using 'AC_DEFUN' or else
+     contain a call to 'AC_PROVIDE' to indicate that it has been called.
+
+
+File: autoconf.info,  Node: Obsoleting Macros,  Next: Coding Style,  Prev: Dependencies Between Macros,  Up: Writing Autoconf Macros
+
+9.5 Obsoleting Macros
+=====================
+
+Configuration and portability technology has evolved over the years.
+Often better ways of solving a particular problem are developed, or
+ad-hoc approaches are systematized.  This process has occurred in many
+parts of Autoconf.  One result is that some of the macros are now
+considered "obsolete"; they still work, but are no longer considered the
+best thing to do, hence they should be replaced with more modern macros.
+Ideally, 'autoupdate' should substitute the old macro calls with their
+modern implementation.
+
+   Autoconf provides a simple means to obsolete a macro.
+
+ -- Macro: AU_DEFUN (OLD-MACRO, IMPLEMENTATION, [MESSAGE])
+     Define OLD-MACRO as IMPLEMENTATION.  The only difference with
+     'AC_DEFUN' is that the user will be warned that OLD-MACRO is now
+     obsolete.
+
+     If she then uses 'autoupdate', the call to OLD-MACRO will be
+     replaced by the modern IMPLEMENTATION.  The additional MESSAGE is
+     then printed.
+
+
+File: autoconf.info,  Node: Coding Style,  Prev: Obsoleting Macros,  Up: Writing Autoconf Macros
+
+9.6 Coding Style
+================
+
+The Autoconf macros follow a strict coding style.  You are encouraged to
+follow this style, especially if you intend to distribute your macro,
+either by contributing it to Autoconf itself, or via other means.
+
+   The first requirement is to pay great attention to the quotation, for
+more details, see *note Autoconf Language::, and *note M4 Quotation::.
+
+   Do not try to invent new interfaces.  It is likely that there is a
+macro in Autoconf that resembles the macro you are defining: try to
+stick to this existing interface (order of arguments, default values,
+etc.).  We _are_ conscious that some of these interfaces are not
+perfect; nevertheless, when harmless, homogeneity should be preferred
+over creativity.
+
+   Be careful about clashes both between M4 symbols and between shell
+variables.
+
+   If you stick to the suggested M4 naming scheme (*note Macro Names::),
+you are unlikely to generate conflicts.  Nevertheless, when you need to
+set a special value, _avoid using a regular macro name_; rather, use an
+"impossible" name.  For instance, up to version 2.13, the macro
+'AC_SUBST' used to remember what SYMBOLs were already defined by setting
+'AC_SUBST_SYMBOL', which is a regular macro name.  But since there is a
+macro named 'AC_SUBST_FILE', it was just impossible to 'AC_SUBST(FILE)'!
+In this case, 'AC_SUBST(SYMBOL)' or '_AC_SUBST(SYMBOL)' should have been
+used (yes, with the parentheses)...or better yet, high-level macros such
+as 'AC_EXPAND_ONCE'.
+
+   No Autoconf macro should ever enter the user-variable name space;
+i.e., except for the variables that are the actual result of running the
+macro, all shell variables should start with 'ac_'.  In addition, small
+macros or any macro that is likely to be embedded in other macros should
+be careful not to use obvious names.
+
+   Do not use 'dnl' to introduce comments: most of the comments you are
+likely to write are either header comments which are not output anyway,
+or comments that should make their way into 'configure'.  There are
+exceptional cases where you do want to comment special M4 constructs, in
+which case 'dnl' is right, but keep in mind that it is unlikely.
+
+   M4 ignores the leading spaces before each argument, use this feature
+to indent in such a way that arguments are (more or less) aligned with
+the opening parenthesis of the macro being called.  For instance,
+instead of
+
+     AC_CACHE_CHECK(for EMX OS/2 environment,
+     ac_cv_emxos2,
+     [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
+     [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
+
+write
+
+     AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+     [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+                        [ac_cv_emxos2=yes],
+                        [ac_cv_emxos2=no])])
+
+or even
+
+     AC_CACHE_CHECK([for EMX OS/2 environment],
+                    [ac_cv_emxos2],
+                    [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
+                                                        [return __EMX__;])],
+                                       [ac_cv_emxos2=yes],
+                                       [ac_cv_emxos2=no])])
+
+   When using 'AC_TRY_RUN' or any macro that cannot work when
+cross-compiling, provide a pessimistic value (typically 'no').
+
+   Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly.  For instance,
+instead of:
+
+     patsubst([$1], [$"])
+
+use
+
+     patsubst([$1], [$""])
+
+so that Emacsen do not open a endless "string" at the first quote.  For
+the same reasons, avoid:
+
+     test $[#] != 0
+
+and use:
+
+     test $[@%:@] != 0
+
+Otherwise, the closing bracket would be hidden inside a '#'-comment,
+breaking the bracket-matching highlighting from Emacsen.  Note the
+preferred style to escape from M4: '$[1]', '$[@]', etc.  Do not escape
+when it is unneeded.  Common examples of useless quotation are '[$]$1'
+(write '$$1'), '[$]var' (use '$var'), etc.  If you add portability
+issues to the picture, you'll prefer '${1+"$[@]"}' to '"[$]@"', and
+you'll prefer do something better than hacking Autoconf ':-)'.
+
+   When using 'sed', don't use '-e' except for indenting purpose.  With
+the 's' command, the preferred separator is '/' unless '/' itself is
+used in the command, in which case you should use ','.
+
+   *Note Macro Definitions::, for details on how to define a macro.  If
+a macro doesn't use 'AC_REQUIRE' and it is expected to never be the
+object of an 'AC_REQUIRE' directive, then use 'define'.  In case of
+doubt, use 'AC_DEFUN'.  All the 'AC_REQUIRE' statements should be at the
+beginning of the macro, 'dnl''ed.
+
+   You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty.  It provides
+both a simpler and a more predictable interface to the user, and saves
+room for further arguments.
+
+   Unless the macro is short, try to leave the closing '])' at the
+beginning of a line, followed by a comment that repeats the name of the
+macro being defined.  This introduces an additional newline in
+'configure'; normally, that is not a problem, but if you want to remove
+it you can use '[]dnl' on the last line.  You can similarly use '[]dnl'
+after a macro call to remove its newline.  '[]dnl' is recommended
+instead of 'dnl' to ensure that M4 does not interpret the 'dnl' as being
+attached to the preceding text or macro output.  For example, instead
+of:
+
+     AC_DEFUN([AC_PATH_X],
+     [AC_MSG_CHECKING([for X])
+     AC_REQUIRE_CPP()
+     # ...omitted...
+       AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+     fi])
+
+you would write:
+
+     AC_DEFUN([AC_PATH_X],
+     [AC_REQUIRE_CPP()[]dnl
+     AC_MSG_CHECKING([for X])
+     # ...omitted...
+       AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+     fi[]dnl
+     ])# AC_PATH_X
+
+   If the macro is long, try to split it into logical chunks.
+Typically, macros that check for a bug in a function and prepare its
+'AC_LIBOBJ' replacement should have an auxiliary macro to perform this
+setup.  Do not hesitate to introduce auxiliary macros to factor your
+code.
+
+   In order to highlight the recommended coding style, here is a macro
+written the old way:
+
+     dnl Check for EMX on OS/2.
+     dnl _AC_EMXOS2
+     AC_DEFUN(_AC_EMXOS2,
+     [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
+     [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
+     ac_cv_emxos2=yes, ac_cv_emxos2=no)])
+     test "$ac_cv_emxos2" = yes && EMXOS2=yes])
+
+and the new way:
+
+     # _AC_EMXOS2
+     # ----------
+     # Check for EMX on OS/2.
+     define([_AC_EMXOS2],
+     [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+     [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+                        [ac_cv_emxos2=yes],
+                        [ac_cv_emxos2=no])])
+     test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
+     ])# _AC_EMXOS2
+
+
+File: autoconf.info,  Node: Portable Shell,  Next: Manual Configuration,  Prev: Writing Autoconf Macros,  Up: Top
+
+10 Portable Shell Programming
+*****************************
+
+When writing your own checks, there are some shell-script programming
+techniques you should avoid in order to make your code portable.  The
+Bourne shell and upward-compatible shells like the Korn shell and Bash
+have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after UNIX version 7, circa 1977.
+You should not use shell functions, aliases, negated character classes,
+or other features that are not found in all Bourne-compatible shells;
+restrict yourself to the lowest common denominator.  Even 'unset' is not
+supported by all shells!  Also, include a space after the exclamation
+point in interpreter specifications, like this:
+
+     #! /usr/bin/perl
+
+If you omit the space before the path, then 4.2BSD based systems (such
+as Sequent DYNIX) will ignore the line, because they interpret '#! /' as
+a 4-byte magic number.
+
+   The set of external programs you should run in a 'configure' script
+is fairly small.  *Note Utilities in Makefiles: (standards)Utilities in
+Makefiles, for the list.  This restriction allows users to start out
+with a fairly small set of programs and build the rest, avoiding too
+many interdependencies between packages.
+
+   Some of these external utilities have a portable subset of features;
+see *note Limitations of Usual Tools::.
+
+* Menu:
+
+* Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
+* File Descriptors::            FDs and redirections
+* File System Conventions::     File- and pathnames
+* Shell Substitutions::         Variable and command expansions
+* Assignments::                 Varying side effects of assignments
+* Special Shell Variables::     Variables you should not change
+* Limitations of Builtins::     Portable use of not so portable /bin/sh
+* Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
+
+
+File: autoconf.info,  Node: Shellology,  Next: Here-Documents,  Prev: Portable Shell,  Up: Portable Shell
+
+10.1 Shellology
+===============
+
+There are several families of shells, most prominently the Bourne family
+and the C shell family which are deeply incompatible.  If you want to
+write portable shell scripts, avoid members of the C shell family.
+
+   Below we describe some of the members of the Bourne shell family.
+
+Ash
+     'ash' is often used on GNU/Linux and BSD systems as a light-weight
+     Bourne-compatible shell.  Ash 0.2 has some bugs that are fixed in
+     the 0.3.x series, but portable shell scripts should workaround
+     them, since version 0.2 is still shipped with many GNU/Linux
+     distributions.
+
+     To be compatible with Ash 0.2:
+
+        - don't use '$?' after expanding empty or unset variables:
+
+               foo=
+               false
+               $foo
+               echo "Don't use it: $?"
+
+        - don't use command substitution within variable expansion:
+
+               cat ${FOO=`bar`}
+
+        - beware that single builtin substitutions are not performed by
+          a sub shell, hence their effect applies to the current shell!
+          *Note Shell Substitutions::, item "Command Substitution".
+
+Bash
+     To detect whether you are running 'bash', test if 'BASH_VERSION' is
+     set.  To disable its extensions and require POSIX compatibility,
+     run 'set -o posix'.  *Note Bash POSIX Mode: (bash)Bash POSIX Mode,
+     for details.
+
+'/usr/xpg4/bin/sh' on Solaris
+     The POSIX-compliant Bourne shell on a Solaris system is
+     '/usr/xpg4/bin/sh' and is part of an extra optional package.  There
+     is no extra charge for this package, but it is also not part of a
+     minimal OS install and therefore some folks may not have it.
+
+Zsh
+     To detect whether you are running 'zsh', test if 'ZSH_VERSION' is
+     set.  By default 'zsh' is _not_ compatible with the Bourne shell:
+     you have to run 'emulate sh' and set 'NULLCMD' to ':'.  *Note
+     Compatibility: (zsh)Compatibility, for details.
+
+     Zsh 3.0.8 is the native '/bin/sh' on Mac OS X 10.0.3.
+
+   The following discussion between Russ Allbery and Robert Lipe is
+worth reading:
+
+Russ Allbery:
+
+     The GNU assumption that '/bin/sh' is the one and only shell leads
+     to a permanent deadlock.  Vendors don't want to break user's
+     existent shell scripts, and there are some corner cases in the
+     Bourne shell that are not completely compatible with a POSIX shell.
+     Thus, vendors who have taken this route will _never_ (OK..."never
+     say never") replace the Bourne shell (as '/bin/sh') with a POSIX
+     shell.
+
+Robert Lipe:
+
+     This is exactly the problem.  While most (at least most System V's)
+     do have a bourne shell that accepts shell functions most vendor
+     '/bin/sh' programs are not the POSIX shell.
+
+     So while most modern systems do have a shell _somewhere_ that meets
+     the POSIX standard, the challenge is to find it.
+
+
+File: autoconf.info,  Node: Here-Documents,  Next: File Descriptors,  Prev: Shellology,  Up: Portable Shell
+
+10.2 Here-Documents
+===================
+
+Don't rely on '\' being preserved just because it has no special meaning
+together with the next symbol.  in the native '/bin/sh' on OpenBSD 2.7
+'\"' expands to '"' in here-documents with unquoted delimiter.  As a
+general rule, if '\\' expands to '\' use '\\' to get '\'.
+
+   With OpenBSD 2.7's '/bin/sh'
+
+     $ cat <<EOF
+     > \" \\
+     > EOF
+     " \
+
+and with Bash:
+
+     bash-2.04$ cat <<EOF
+     > \" \\
+     > EOF
+     \" \
+
+   Many older shells (including the Bourne shell) implement
+here-documents inefficiently.  Users can generally speed things up by
+using a faster shell, e.g., by using the command 'bash ./configure'
+rather than plain './configure'.
+
+   Some shells can be extremely inefficient when there are a lot of
+here-documents inside a single statement.  For instance if your
+'configure.ac' includes something like:
+
+     if <cross_compiling>; then
+       assume this and that
+     else
+       check this
+       check that
+       check something else
+       ...
+       on and on forever
+       ...
+     fi
+
+   A shell parses the whole 'if'/'fi' construct, creating temporary
+files for each here document in it.  Some shells create links for such
+here-documents on every 'fork', so that the clean-up code they had
+installed correctly removes them.  It is creating the links that the
+shell can take forever.
+
+   Moving the tests out of the 'if'/'fi', or creating multiple 'if'/'fi'
+constructs, would improve the performance significantly.  Anyway, this
+kind of construct is not exactly the typical use of Autoconf.  In fact,
+it's even not recommended, because M4 macros can't look into shell
+conditionals, so we may fail to expand a macro when it was expanded
+before in a conditional path, and the condition turned out to be false
+at run-time, and we end up not executing the macro at all.
+
+
+File: autoconf.info,  Node: File Descriptors,  Next: File System Conventions,  Prev: Here-Documents,  Up: Portable Shell
+
+10.3 File Descriptors
+=====================
+
+Some file descriptors shall not be used, since some systems, admittedly
+arcane, use them for special purpose:
+
+3
+     some systems may open it to '/dev/tty'.
+
+4
+     used on the Kubota Titan.
+
+   Don't redirect several times the same file descriptor, as you are
+doomed to failure under Ultrix.
+
+     ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
+     UWS V4.4 (Rev. 11)
+     $ eval 'echo matter >fullness' >void
+     illegal io
+     $ eval '(echo matter >fullness)' >void
+     illegal io
+     $ (eval '(echo matter >fullness)') >void
+     Ambiguous output redirect.
+
+In each case the expected result is of course 'fullness' containing
+'matter' and 'void' being empty.
+
+   Don't try to redirect the standard error of a command substitution:
+it must be done _inside_ the command substitution: when running ': `cd
+/zorglub` 2>/dev/null' expect the error message to escape, while ': `cd
+/zorglub 2>/dev/null`' works properly.
+
+   It is worth noting that Zsh (but not Ash nor Bash) makes it possible
+in assignments though: 'foo=`cd /zorglub` 2>/dev/null'.
+
+   Most shells, if not all (including Bash, Zsh, Ash), output traces on
+stderr, even for sub-shells.  This might result in undesired content if
+you meant to capture the standard-error output of the inner command:
+
+     $ ash -x -c '(eval "echo foo >&2") 2>stderr'
+     $ cat stderr
+     + eval echo foo >&2
+     + echo foo
+     foo
+     $ bash -x -c '(eval "echo foo >&2") 2>stderr'
+     $ cat stderr
+     + eval 'echo foo >&2'
+     ++ echo foo
+     foo
+     $ zsh -x -c '(eval "echo foo >&2") 2>stderr'
+     # Traces on startup files deleted here.
+     $ cat stderr
+     +zsh:1> eval echo foo >&2
+     +zsh:1> echo foo
+     foo
+
+You'll appreciate the various levels of detail...
+
+   One workaround is to grep out uninteresting lines, hoping not to
+remove good ones...
+
+
+File: autoconf.info,  Node: File System Conventions,  Next: Shell Substitutions,  Prev: File Descriptors,  Up: Portable Shell
+
+10.4 File System Conventions
+============================
+
+While 'autoconf' and friends will usually be run on some Unix variety,
+it can and will be used on other systems, most notably DOS variants.
+This impacts several assumptions regarding file and path names.
+
+For example, the following code:
+
+     case $foo_dir in
+       /*) # Absolute
+          ;;
+       *)
+          foo_dir=$dots$foo_dir ;;
+     esac
+
+will fail to properly detect absolute paths on those systems, because
+they can use a drivespec, and will usually use a backslash as directory
+separator.  The canonical way to check for absolute paths is:
+
+     case $foo_dir in
+       [\\/]* | ?:[\\/]* ) # Absolute
+          ;;
+       *)
+          foo_dir=$dots$foo_dir ;;
+     esac
+
+Make sure you quote the brackets if appropriate and keep the backslash
+as first character (*note Limitations of Builtins::).
+
+   Also, because the colon is used as part of a drivespec, these systems
+don't use it as path separator.  When creating or accessing paths, use
+'$ac_path_separator' instead (or the 'PATH_SEPARATOR' output variable).
+'autoconf' sets this to the appropriate value (':' or ';') when it
+starts up.
+
+   File names need extra care as well.  While DOS-based environments
+that are Unixy enough to run 'autoconf' (such as DJGPP) will usually be
+able to handle long file names properly, there are still limitations
+that can seriously break packages.  Several of these issues can be
+easily detected by the doschk(1) package.
+
+   A short overview follows; problems are marked with SFN/LFN to
+indicate where they apply: SFN means the issues are only relevant to
+plain DOS, not to DOS boxes under Windows, while LFN identifies problems
+that exist even under Windows.
+
+No multiple dots (SFN)
+     DOS cannot handle multiple dots in filenames.  This is an
+     especially important thing to remember when building a portable
+     configure script, as 'autoconf' uses a .in suffix for template
+     files.
+
+     This is perfectly OK on Unices:
+
+          AC_CONFIG_HEADER(config.h)
+          AC_CONFIG_FILES([source.c foo.bar])
+          AC_OUTPUT
+
+     but it causes problems on DOS, as it requires 'config.h.in',
+     'source.c.in' and 'foo.bar.in'.  To make your package more portable
+     to DOS-based environments, you should use this instead:
+
+          AC_CONFIG_HEADER(config.h:config.hin)
+          AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
+          AC_OUTPUT
+
+No leading dot (SFN)
+     DOS cannot handle filenames that start with a dot.  This is usually
+     not a very important issue for 'autoconf'.
+
+Case insensitivity (LFN)
+     DOS is case insensitive, so you cannot, for example, have both a
+     file called 'INSTALL' and a directory called 'install'.  This also
+     affects 'make'; if there's a file called 'INSTALL' in the
+     directory, 'make install' will do nothing (unless the 'install'
+     target is marked as PHONY).
+
+The 8+3 limit (SFN)
+     Because the DOS file system only stores the first 8 characters of
+     the filename and the first 3 of the extension, those must be
+     unique.  That means that 'foobar-part1.c', 'foobar-part2.c' and
+     'foobar-prettybird.c' all resolve to the same filename
+     ('FOOBAR-P.C').  The same goes for 'foo.bar' and 'foo.bartender'.
+
+     Note: This is not usually a problem under Windows, as it uses
+     numeric tails in the short version of filenames to make them
+     unique.  However, a registry setting can turn this behaviour off.
+     While this makes it possible to share file trees containing long
+     file names between SFN and LFN environments, it also means the
+     above problem applies there as well.
+
+Invalid characters
+     Some characters are invalid in DOS filenames, and should therefore
+     be avoided.  In a LFN environment, these are '/', '\', '?', '*',
+     ':', '<', '>', '|' and '"'.  In a SFN environment, other characters
+     are also invalid.  These include '+', ',', '[' and ']'.
+
+   ---------- Footnotes ----------
+
+   (1) doschk, <ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz>.
+
+
+File: autoconf.info,  Node: Shell Substitutions,  Next: Assignments,  Prev: File System Conventions,  Up: Portable Shell
+
+10.5 Shell Substitutions
+========================
+
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and backquoted expressions, in particular
+on the right-hand side of assignments and in the argument of 'case'.
+For instance, the following code:
+
+     case "$given_srcdir" in
+     .)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+     *)  top_srcdir="$dots$given_srcdir" ;;
+     esac
+
+is more readable when written as:
+
+     case $given_srcdir in
+     .)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
+     *)  top_srcdir=$dots$given_srcdir ;;
+     esac
+
+and in fact it is even _more_ portable: in the first case of the first
+attempt, the computation of 'top_srcdir' is not portable, since not all
+shells properly understand '"`..."..."...`"'.  Worse yet, not all shells
+understand '"`...\"...\"...`"' the same way.  There is just no portable
+way to use double-quoted strings inside double-quoted backquoted
+expressions (pfew!).
+
+'$@'
+     One of the most famous shell-portability issues is related to
+     '"$@"': when there are no positional arguments, it is supposed to
+     be equivalent to nothing.  But some shells, for instance under
+     Digital Unix 4.0 and 5.0, will then replace it with an empty
+     argument.  To be portable, use '${1+"$@"}'.
+
+'${VAR:-VALUE}'
+     Old BSD shells, including the Ultrix 'sh', don't accept the colon
+     for any shell substitution, and complain and die.
+
+'${VAR=LITERAL}'
+     Be sure to quote:
+
+          : ${var='Some words'}
+
+     otherwise some shells, such as on Digital Unix V 5.0, will die
+     because of a "bad substitution".
+
+     Solaris' '/bin/sh' has a frightening bug in its interpretation of
+     this.  Imagine you need set a variable to a string containing '}'.
+     This '}' character confuses Solaris' '/bin/sh' when the affected
+     variable was already set.  This bug can be exercised by running:
+
+          $ unset foo
+          $ foo=${foo='}'}
+          $ echo $foo
+          }
+          $ foo=${foo='}'   # no error; this hints to what the bug is
+          $ echo $foo
+          }
+          $ foo=${foo='}'}
+          $ echo $foo
+          }}
+           ^ ugh!
+
+     It seems that '}' is interpreted as matching '${', even though it
+     is enclosed in single quotes.  The problem doesn't happen using
+     double quotes.
+
+'${VAR=EXPANDED-VALUE}'
+     On Ultrix, running
+
+          default="yu,yaa"
+          : ${var="$default"}
+
+     will set VAR to 'M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of each
+     char will be set.  You won't observe the phenomenon using a simple
+     'echo $var' since apparently the shell resets the 8th bit when it
+     expands $var.  Here are two means to make this shell confess its
+     sins:
+
+          $ cat -v <<EOF
+          $var
+          EOF
+
+     and
+
+          $ set | grep '^var=' | cat -v
+
+     One classic incarnation of this bug is:
+
+          default="a b c"
+          : ${list="$default"}
+          for c in $list; do
+            echo $c
+          done
+
+     You'll get 'a b c' on a single line.  Why?  Because there are no
+     spaces in '$list': there are 'M- ', i.e., spaces with the 8th bit
+     set, hence no IFS splitting is performed!!!
+
+     One piece of good news is that Ultrix works fine with ':
+     ${list=$default}'; i.e., if you _don't_ quote.  The bad news is
+     then that QNX 4.25 then sets LIST to the _last_ item of DEFAULT!
+
+     The portable way out consists in using a double assignment, to
+     switch the 8th bit twice on Ultrix:
+
+          list=${list="$default"}
+
+     ...but beware of the '}' bug from Solaris (see above).  For safety,
+     use:
+
+          test "${var+set}" = set || var={VALUE}
+
+'`COMMANDS`'
+     While in general it makes no sense, do not substitute a single
+     builtin with side effects as Ash 0.2, trying to optimize, does not
+     fork a sub-shell to perform the command.
+
+     For instance, if you wanted to check that 'cd' is silent, do not
+     use 'test -z "`cd /`"' because the following can happen:
+
+          $ pwd
+          /tmp
+          $ test -n "`cd /`" && pwd
+          /
+
+     The result of 'foo=`exit 1`' is left as an exercise to the reader.
+
+'$(COMMANDS)'
+     This construct is meant to replace '`COMMANDS`'; they can be nested
+     while this is impossible to do portably with back quotes.
+     Unfortunately it is not yet widely supported.  Most notably, even
+     recent releases of Solaris don't support it:
+
+          $ showrev -c /bin/sh | grep version
+          Command version: SunOS 5.8 Generic 109324-02 February 2001
+          $ echo $(echo blah)
+          syntax error: `(' unexpected
+
+     nor does IRIX 6.5's Bourne shell:
+          $ uname -a
+          IRIX firebird-image 6.5 07151432 IP22
+          $ echo $(echo blah)
+          $(echo blah)
+
+
+File: autoconf.info,  Node: Assignments,  Next: Special Shell Variables,  Prev: Shell Substitutions,  Up: Portable Shell
+
+10.6 Assignments
+================
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined.  For instance 'foo=1 foo=2; echo $foo' gives
+'1' with sh on Solaris, but '2' with Bash.  You must use ';' to enforce
+the order: 'foo=1; foo=2; echo $foo'.
+
+   Don't rely on the exit status of an assignment: Ash 0.2 does not
+change the status and propagates that of the last statement:
+
+     $ false || foo=bar; echo $?
+     1
+     $ false || foo=`:`; echo $?
+     0
+
+and to make things even worse, QNX 4.25 just sets the exit status to 0
+in any case:
+
+     $ foo=`exit 1`; echo $?
+     0
+
+   To assign default values, follow this algorithm:
+
+  1. If the default value is a literal and does not contain any closing
+     brace, use:
+
+          : ${var='my literal'}
+
+  2. If the default value contains no closing brace, has to be expanded,
+     and the variable being initialized will never be IFS-split (i.e.,
+     it's not a list), then use:
+
+          : ${var="$default"}
+
+  3. If the default value contains no closing brace, has to be expanded,
+     and the variable being initialized will be IFS-split (i.e., it's a
+     list), then use:
+
+          var=${var="$default"}
+
+  4. If the default value contains a closing brace, then use:
+
+          test "${var+set}" = set || var='${indirection}'
+
+   In most cases 'var=${var="$default"}' is fine, but in case of doubt,
+just use the latter.  *Note Shell Substitutions::, items '${VAR:-VALUE}'
+and '${VAR=VALUE}' for the rationale.
+
+
+File: autoconf.info,  Node: Special Shell Variables,  Next: Limitations of Builtins,  Prev: Assignments,  Up: Portable Shell
+
+10.7 Special Shell Variables
+============================
+
+Some shell variables should not be used, since they can have a deep
+influence on the behavior of the shell.  In order to recover a sane
+behavior from the shell, some variables should be unset, but 'unset' is
+not portable (*note Limitations of Builtins::) and a fallback value is
+needed.  We list these values below.
+
+'CDPATH'
+     When this variable is set 'cd' is verbose, so idioms such as
+     'abs=`cd $rel && pwd`' break because 'abs' receives the path twice.
+
+     Setting 'CDPATH' to the empty value is not enough for most shells.
+     A simple colon is enough except for 'zsh', which prefers a leading
+     dot:
+
+          zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
+          /tmp/foo
+          zsh-3.1.6 % (CDPATH=:. cd foo)
+          /tmp/foo
+          zsh-3.1.6 % (CDPATH=.: cd foo)
+          zsh-3.1.6 %
+
+     (of course we could just 'unset' 'CDPATH', since it also behaves
+     properly if set to the empty string).
+
+     Life wouldn't be so much fun if 'bash' and 'zsh' had the same
+     behavior:
+
+          bash-2.02 % (CDPATH=:. cd foo)
+          bash-2.02 % (CDPATH=.: cd foo)
+          /tmp/foo
+
+     Therefore, a portable solution to neutralize 'CDPATH' is
+
+          CDPATH=${ZSH_VERSION+.}:
+
+     Note that since 'zsh' supports 'unset', you may unset 'CDPATH'
+     using ':' as a fallback, see *note Limitations of Builtins::.
+
+'IFS'
+     Don't set the first character of 'IFS' to backslash.  Indeed,
+     Bourne shells use the first character (backslash) when joining the
+     components in '"$@"' and some shells then re-interpret (!)  the
+     backslash escapes, so you can end up with backspace and other
+     strange characters.
+
+'LANG'
+'LC_ALL'
+'LC_TIME'
+'LC_CTYPE'
+'LANGUAGE'
+'LC_COLLATE'
+'LC_NUMERIC'
+'LC_MESSAGES'
+
+     These must not be set unconditionally because not all systems
+     understand e.g.  'LANG=C' (notably SCO). Fixing 'LC_MESSAGES'
+     prevents Solaris 'sh' from translating var values in 'set'!  Non-C
+     'LC_CTYPE' values break the ctype check.  Fixing 'LC_COLLATE' makes
+     scripts more portable in some cases.  For example, it causes the
+     regular expression '[a-z]' to match only lower-case letters on
+     ASCII platforms.  However, '[a-z]' does not work in general even
+     when 'LC_COLLATE' is fixed; for example, it does not work for
+     EBCDIC platforms.  For maximum portability, you should use regular
+     expressions like '[abcdefghijklmnopqrstuvwxyz]' that list
+     characters explicitly instead of relying on ranges.
+
+     _If_ one of these variables is set, you should try to unset it,
+     using 'C' as a fall back value.  see *note Limitations of
+     Builtins::, builtin 'unset', for more details.
+
+'NULLCMD'
+     When executing the command '>foo', 'zsh' executes '$NULLCMD >foo'.
+     The Bourne shell considers 'NULLCMD' is ':', while 'zsh', even in
+     Bourne shell compatibility mode, sets 'NULLCMD' to 'cat'.  If you
+     forgot to set 'NULLCMD', your script might be suspended waiting for
+     data on its standard input.
+
+'status'
+     This variable is an alias to '$?' for 'zsh' (at least 3.1.6), hence
+     read-only.  Do not use it.
+
+'PATH_SEPARATOR'
+     On DJGPP systems, the 'PATH_SEPARATOR' variable can be set to
+     either ':' or ';' to control the path separator 'bash' uses to set
+     up certain environment variables (such as 'PATH').  Since this only
+     works inside bash, you want autoconf to detect the regular DOS path
+     separator ';', so it can be safely substituted in files that may
+     not support ';' as path separator.  So either unset this variable
+     or set it to ';'.
+
+'RANDOM'
+     Many shells provide 'RANDOM', a variable that returns a different
+     integer when used.  Most of the time, its value does not change
+     when it is not used, but on IRIX 6.5 the value changes all the
+     time.  This can be observed by using 'set'.
+
+
+File: autoconf.info,  Node: Limitations of Builtins,  Next: Limitations of Usual Tools,  Prev: Special Shell Variables,  Up: Portable Shell
+
+10.8 Limitations of Shell Builtins
+==================================
+
+No, no, we are serious: some shells do have limitations!  :)
+
+   You should always keep in mind that any built-in or command may
+support options, and therefore have a very different behavior with
+arguments starting with a dash.  For instance, the innocent 'echo
+"$word"' can give unexpected results when 'word' starts with a dash.  It
+is often possible to avoid this problem using 'echo "x$word"', taking
+the 'x' into account later in the pipe.
+
+'!'
+     You can't use '!', you'll have to rewrite your code.
+
+'break'
+     The use of 'break 2', etcetera, is safe.
+
+'case'
+     You don't need to quote the argument; no splitting is performed.
+
+     You don't need the final ';;', but you should use it.
+
+     Because of a bug in its 'fnmatch', 'bash' fails to properly handle
+     backslashes in character classes:
+
+          bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
+          bash-2.02$
+
+     This is extremely unfortunate, since you are likely to use this
+     code to handle UNIX or MS-DOS absolute paths.  To work around this
+     bug, always put the backslash first:
+
+          bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
+          OK
+          bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
+          OK
+
+'echo'
+     The simple 'echo' is probably the most surprising source of
+     portability troubles.  It is not possible to use 'echo' portably
+     unless both options and escape sequences are omitted.  New
+     applications which are not aiming at portability should use
+     'printf' instead of 'echo'.
+
+     Don't expect any option.  *Note Preset Output Variables::, 'ECHO_N'
+     etc.  for a means to simulate '-c'.
+
+     Do not use backslashes in the arguments, as there is no consensus
+     on their handling.  On 'echo '\n' | wc -l', the 'sh' of Digital
+     Unix 4.0, MIPS RISC/OS 4.52, answer 2, but the Solaris' 'sh', Bash
+     and Zsh (in 'sh' emulation mode) report 1.  Please note that the
+     problem is truly 'echo': all the shells understand ''\n'' as the
+     string composed of a backslash and an 'n'.
+
+     Because of these problems, do not pass a string containing
+     arbitrary characters to 'echo'.  For example, 'echo "$foo"' is safe
+     if you know that FOO's value cannot contain backslashes and cannot
+     start with '-', but otherwise you should use a here-document like
+     this:
+
+          cat <<EOF
+          $foo
+          EOF
+
+'exit'
+     The default value of 'exit' is supposed to be '$?'; unfortunately,
+     some shells, such as the DJGPP port of Bash 2.04, just perform
+     'exit 0'.
+
+          bash-2.04$ foo=`exit 1` || echo fail
+          fail
+          bash-2.04$ foo=`(exit 1)` || echo fail
+          fail
+          bash-2.04$ foo=`(exit 1); exit` || echo fail
+          bash-2.04$
+
+     Using 'exit $?' restores the expected behavior.
+
+     Some shell scripts, such as those generated by 'autoconf', use a
+     trap to clean up before exiting.  If the last shell command exited
+     with nonzero status, the trap also exits with nonzero status so
+     that the invoker can tell that an error occurred.
+
+     Unfortunately, in some shells, such as Solaris 8 'sh', an exit trap
+     ignores the 'exit' command's status.  In these shells, a trap
+     cannot determine whether it was invoked by plain 'exit' or by 'exit
+     1'.  Instead of calling 'exit' directly, use the 'AC_MSG_ERROR'
+     macro that has a workaround for this problem.
+
+'export'
+     The builtin 'export' dubs "environment variable" a shell variable.
+     Each update of exported variables corresponds to an update of the
+     environment variables.  Conversely, each environment variable
+     received by the shell when it is launched should be imported as a
+     shell variable marked as exported.
+
+     Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX
+     4.1.5 and DU 4.0, forget to 'export' the environment variables they
+     receive.  As a result, two variables are coexisting: the
+     environment variable and the shell variable.  The following code
+     demonstrates this failure:
+
+          #! /bin/sh
+          echo $FOO
+          FOO=bar
+          echo $FOO
+          exec /bin/sh $0
+
+     when run with 'FOO=foo' in the environment, these shells will print
+     alternately 'foo' and 'bar', although it should only print 'foo'
+     and then a sequence of 'bar's.
+
+     Therefore you should 'export' again each environment variable that
+     you update.
+
+'false'
+     Don't expect 'false' to exit with status 1: in the native Bourne
+     shell of Solaris 8, it exits with status 255.
+
+'for'
+     To loop over positional arguments, use:
+
+          for arg
+          do
+            echo "$arg"
+          done
+
+     You may _not_ leave the 'do' on the same line as 'for', since some
+     shells improperly grok:
+
+          for arg; do
+            echo "$arg"
+          done
+
+     If you want to explicitly refer to the positional arguments, given
+     the '$@' bug (*note Shell Substitutions::), use:
+
+          for arg in ${1+"$@"}; do
+            echo "$arg"
+          done
+
+'if'
+     Using '!' is not portable.  Instead of:
+
+          if ! cmp -s file file.new; then
+            mv file.new file
+          fi
+
+     use:
+
+          if cmp -s file file.new; then :; else
+            mv file.new file
+          fi
+
+     There are shells that do not reset the exit status from an 'if':
+
+          $ if (exit 42); then true; fi; echo $?
+          42
+
+     whereas a proper shell should have printed '0'.  This is especially
+     bad in Makefiles since it produces false failures.  This is why
+     properly written Makefiles, such as Automake's, have such hairy
+     constructs:
+
+          if test -f "$file"; then
+            install "$file" "$dest"
+          else
+            :
+          fi
+
+'set'
+     This builtin faces the usual problem with arguments starting with a
+     dash.  Modern shells such as Bash or Zsh understand '--' to specify
+     the end of the options (any argument after '--' is a parameters,
+     even '-x' for instance), but most shells simply stop the option
+     processing as soon as a non-option argument is found.  Therefore,
+     use 'dummy' or simply 'x' to end the option processing, and use
+     'shift' to pop it out:
+
+          set x $my_list; shift
+
+'shift'
+     Not only is 'shift'ing a bad idea when there is nothing left to
+     shift, but in addition it is not portable: the shell of MIPS
+     RISC/OS 4.52 refuses to do it.
+
+'test'
+     The 'test' program is the way to perform many file and string
+     tests.  It is often invoked by the alternate name '[', but using
+     that name in Autoconf code is asking for trouble since it is an M4
+     quote character.
+
+     If you need to make multiple checks using 'test', combine them with
+     the shell operators '&&' and '||' instead of using the 'test'
+     operators '-a' and '-o'.  On System V, the precedence of '-a' and
+     '-o' is wrong relative to the unary operators; consequently, POSIX
+     does not specify them, so using them is nonportable.  If you
+     combine '&&' and '||' in the same statement, keep in mind that they
+     have equal precedence.
+
+     You may use '!' with 'test', but not with 'if': 'test ! -r foo ||
+     exit 1'.
+
+'test' (files)
+     To enable 'configure' scripts to support cross-compilation, they
+     shouldn't do anything that tests features of the build system
+     instead of the host system.  But occasionally you may find it
+     necessary to check whether some arbitrary file exists.  To do so,
+     use 'test -f' or 'test -r'.  Do not use 'test -x', because 4.3BSD
+     does not have it.  Do not use 'test -e' either, because Solaris 2.5
+     does not have it.
+
+'test' (strings)
+     Avoid 'test "STRING"', in particular if STRING might start with a
+     dash, since 'test' might interpret its argument as an option (e.g.,
+     'STRING = "-n"').
+
+     Contrary to a common belief, 'test -n STRING' and 'test -z STRING'
+     *are* portable, nevertheless many shells (such as Solaris 2.5, AIX
+     3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.)  have bizarre precedence
+     and may be confused if STRING looks like an operator:
+
+          $ test -n =
+          test: argument expected
+
+     If there are risks, use 'test "xSTRING" = x' or 'test "xSTRING" !=
+     x' instead.
+
+     It is frequent to find variations of the following idiom:
+
+          test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
+            ACTION
+
+     to take an action when a token matches a given pattern.  Such
+     constructs should always be avoided by using:
+
+          echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
+            ACTION
+
+     Use 'case' where possible since it is faster, being a shell
+     builtin:
+
+          case $ac_feature in
+            *[!-a-zA-Z0-9_]*) ACTION;;
+          esac
+
+     Alas, negated character classes are probably not portable, although
+     no shell is known to not support the POSIX.2 syntax '[!...]' (when
+     in interactive mode, 'zsh' is confused by the '[!...]' syntax and
+     looks for an event in its history because of '!').  Many shells do
+     not support the alternative syntax '[^...]' (Solaris, Digital Unix,
+     etc.).
+
+     One solution can be:
+
+          expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+            ACTION
+
+     or better yet
+
+          expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+            ACTION
+
+     'expr "XFOO" : "XBAR"' is more robust than 'echo "XFOO" | grep
+     "^XBAR"', because it avoids problems when 'FOO' contains
+     backslashes.
+
+'trap'
+     It is safe to trap at least the signals 1, 2, 13 and 15.  You can
+     also trap 0, i.e., have the 'trap' run when the script ends (either
+     via an explicit 'exit', or the end of the script).
+
+     Although POSIX is not absolutely clear on this point, it is widely
+     admitted that when entering the trap '$?' should be set to the exit
+     status of the last command run before the trap.  The ambiguity can
+     be summarized as: "when the trap is launched by an 'exit', what is
+     the _last_ command run: that before 'exit', or 'exit' itself?"
+
+     Bash considers 'exit' to be the last command, while Zsh and Solaris
+     8 'sh' consider that when the trap is run it is _still_ in the
+     'exit', hence it is the previous exit status that the trap
+     receives:
+
+          $ cat trap.sh
+          trap 'echo $?' 0
+          (exit 42); exit 0
+          $ zsh trap.sh
+          42
+          $ bash trap.sh
+          0
+
+     The portable solution is then simple: when you want to 'exit 42',
+     run '(exit 42); exit 42', the first 'exit' being used to set the
+     exit status to 42 for Zsh, and the second to trigger the trap and
+     pass 42 as exit status for Bash.
+
+     The shell in FreeBSD 4.0 has the following bug: '$?' is reset to 0
+     by empty lines if the code is inside 'trap'.
+
+          $ trap 'false
+
+          echo $?' 0
+          $ exit
+          0
+
+     Fortunately, this bug only affects 'trap'.
+
+'true'
+     Don't worry: as far as we know 'true' is portable.  Nevertheless,
+     it's not always a builtin (e.g., Bash 1.x), and the portable shell
+     community tends to prefer using ':'.  This has a funny side effect:
+     when asked whether 'false' is more portable than 'true' Alexandre
+     Oliva answered:
+
+          In a sense, yes, because if it doesn't exist, the shell will
+          produce an exit status of failure, which is correct for
+          'false', but not for 'true'.
+
+'unset'
+     You cannot assume the support of 'unset', nevertheless, because it
+     is extremely useful to disable embarrassing variables such as
+     'CDPATH' or 'LANG', you can test for its existence and use it
+     _provided_ you give a neutralizing value when 'unset' is not
+     supported:
+
+          if (unset FOO) >/dev/null 2>&1; then
+            unset=unset
+          else
+            unset=false
+          fi
+          $unset CDPATH || CDPATH=:
+
+     *Note Special Shell Variables::, for some neutralizing values.
+     Also, see *note Limitations of Builtins::, documentation of
+     'export', for the case of environment variables.
+
+
+File: autoconf.info,  Node: Limitations of Usual Tools,  Next: Limitations of Make,  Prev: Limitations of Builtins,  Up: Portable Shell
+
+10.9 Limitations of Usual Tools
+===============================
+
+The small set of tools you can expect to find on any machine can still
+include some limitations you should be aware of.
+
+'awk'
+     Don't leave white spaces before the parentheses in user functions
+     calls, GNU awk will reject it:
+
+          $ gawk 'function die () { print "Aaaaarg!"  }
+                  BEGIN { die () }'
+          gawk: cmd. line:2:         BEGIN { die () }
+          gawk: cmd. line:2:                      ^ parse error
+          $ gawk 'function die () { print "Aaaaarg!"  }
+                  BEGIN { die() }'
+          Aaaaarg!
+
+     If you want your program to be deterministic, don't depend on 'for'
+     on arrays:
+
+          $ cat for.awk
+          END {
+            arr["foo"] = 1
+            arr["bar"] = 1
+            for (i in arr)
+              print i
+          }
+          $ gawk -f for.awk </dev/null
+          foo
+          bar
+          $ nawk -f for.awk </dev/null
+          bar
+          foo
+
+     Some AWK, such as HPUX 11.0's native one, have regex engines
+     fragile to inner anchors:
+
+          $ echo xfoo | $AWK '/foo|^bar/ { print }'
+          $ echo bar | $AWK '/foo|^bar/ { print }'
+          bar
+          $ echo xfoo | $AWK '/^bar|foo/ { print }'
+          xfoo
+          $ echo bar | $AWK '/^bar|foo/ { print }'
+          bar
+
+     Either do not depend on such patterns (i.e., use '/^(.*foo|bar)/',
+     or use a simple test to reject such AWK.
+
+'cat'
+     Don't rely on any option.  The option '-v', which displays
+     non-printing characters, _seems_ portable, though.
+
+'cc'
+     When a compilation such as 'cc foo.c -o foo' fails, some compilers
+     (such as CDS on Reliant UNIX) leave a 'foo.o'.
+
+'cmp'
+     'cmp' performs a raw data comparison of two files, while 'diff'
+     compares two text files.  Therefore, if you might compare DOS
+     files, even if only checking whether two files are different, use
+     'diff' to avoid spurious differences due to differences of newline
+     encoding.
+
+'cp'
+     SunOS 'cp' does not support '-f', although its 'mv' does.  It's
+     possible to deduce why 'mv' and 'cp' are different with respect to
+     '-f'.  'mv' prompts by default before overwriting a read-only file.
+     'cp' does not.  Therefore, 'mv' requires a '-f' option, but 'cp'
+     does not.  'mv' and 'cp' behave differently with respect to
+     read-only files because the simplest form of 'cp' cannot overwrite
+     a read-only file, but the simplest form of 'mv' can.  This is
+     because 'cp' opens the target for write access, whereas 'mv' simply
+     calls 'link' (or, in newer systems, 'rename').
+
+'diff'
+     Option '-u' is nonportable.
+
+     Some implementations, such as Tru64's, fail when comparing to
+     '/dev/null'.  Use an empty file instead.
+
+'dirname'
+     Not all hosts have 'dirname', but it is reasonably easy to emulate,
+     e.g.:
+
+          dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
+                    '.'      : '.'
+
+     But there are a few subtilities, e.g., under UN*X, should '//1'
+     give '/'?  Paul Eggert answers:
+
+          No, under some older flavors of Unix, leading '//' is a
+          special path name: it refers to a "super-root" and is used to
+          access other machines' files.  Leading '///', '////', etc.
+          are equivalent to '/'; but leading '//' is special.  I think
+          this tradition started with Apollo Domain/OS, an OS that is
+          still in use on some older hosts.
+
+          POSIX.2 allows but does not require the special treatment for
+          '//'.  It says that the behavior of dirname on path names of
+          the form '//([^/]+/*)?' is implementation defined.  In these
+          cases, GNU 'dirname' returns '/', but it's more portable to
+          return '//' as this works even on those older flavors of Unix.
+
+          I have heard rumors that this special treatment of '//' may be
+          dropped in future versions of POSIX, but for now it's still
+          the standard.
+
+'egrep'
+     The empty alternative is not portable, use '?' instead.  For
+     instance with Digital Unix v5.0:
+
+          > printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
+          |foo
+          > printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
+          bar|
+          > printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
+          foo
+          |bar
+
+     'egrep' also suffers the limitations of 'grep'.
+
+'expr'
+     No 'expr' keyword starts with 'x', so use 'expr x"WORD" : 'xREGEX''
+     to keep 'expr' from misinterpreting WORD.
+
+     Don't use 'length', 'substr', 'match' and 'index'.
+
+'expr' ('|')
+     You can use '|'.  Although POSIX does require that 'expr ''' return
+     the empty string, it does not specify the result when you '|'
+     together the empty string (or zero) with the empty string.  For
+     example:
+
+          expr '' \| ''
+
+     GNU/Linux and POSIX.2-1992 return the empty string for this case,
+     but traditional Unix returns '0' (Solaris is one such example).  In
+     the latest POSIX draft, the specification has been changed to match
+     traditional Unix's behavior (which is bizarre, but it's too late to
+     fix this).  Please note that the same problem does arise when the
+     empty string results from a computation, as in:
+
+          expr bar : foo \| foo : bar
+
+     Avoid this portability problem by avoiding the empty string.
+
+'expr' (':')
+     Don't use '\?', '\+' and '\|' in patterns, they are not supported
+     on Solaris.
+
+     The POSIX.2-1992 standard is ambiguous as to whether 'expr a : b'
+     (and 'expr 'a' : '\(b\)'') output '0' or the empty string.  In
+     practice, it outputs the empty string on most platforms, but
+     portable scripts should not assume this.  For instance, the QNX
+     4.25 native 'expr' returns '0'.
+
+     You may believe that one means to get a uniform behavior would be
+     to use the empty string as a default value:
+
+          expr a : b \| ''
+
+     unfortunately this behaves exactly as the original expression, see
+     the ''expr' (':')' entry for more information.
+
+     Older 'expr' implementations (e.g.  SunOS 4 'expr' and Solaris 8
+     '/usr/ucb/expr') have a silly length limit that causes 'expr' to
+     fail if the matched substring is longer than 120 bytes.  In this
+     case, you might want to fall back on 'echo|sed' if 'expr' fails.
+
+     Don't leave, there is some more!
+
+     The QNX 4.25 'expr', in addition of preferring '0' to the empty
+     string, has a funny behavior in its exit status: it's always 1 when
+     parentheses are used!
+
+          $ val=`expr 'a' : 'a'`; echo "$?: $val"
+          0: 1
+          $ val=`expr 'a' : 'b'`; echo "$?: $val"
+          1: 0
+
+          $ val=`expr 'a' : '\(a\)'`; echo "?: $val"
+          1: a
+          $ val=`expr 'a' : '\(b\)'`; echo "?: $val"
+          1: 0
+
+     In practice this can be a big problem if you are ready to catch
+     failures of 'expr' programs with some other method (such as using
+     'sed'), since you may get twice the result.  For instance
+
+          $ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'
+
+     will output 'a' on most hosts, but 'aa' on QNX 4.25.  A simple work
+     around consists in testing 'expr' and use a variable set to 'expr'
+     or to 'false' according to the result.
+
+'find'
+     The option '-maxdepth' seems to be GNU specific.  Tru64 v5.1,
+     NetBSD 1.5 and Solaris 2.5 'find' commands do not understand it.
+
+'grep'
+     Don't use 'grep -s' to suppress output, because 'grep -s' on System
+     V does not suppress output, only error messages.  Instead, redirect
+     the standard output and standard error (in case the file doesn't
+     exist) of 'grep' to '/dev/null'.  Check the exit status of 'grep'
+     to determine whether it found a match.
+
+     Don't use multiple regexps with '-e', as some 'grep' will only
+     honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1).  Anyway,
+     Stardent Vistra SVR4 'grep' lacks '-e'... Instead, use alternation
+     and 'egrep'.
+
+'ln'
+     Don't rely on 'ln' having a '-f' option.  Symbolic links are not
+     available on old systems, use 'ln' as a fall back.
+
+     For versions of the DJGPP before 2.04, 'ln' emulates soft links for
+     executables by generating a stub that in turn calls the real
+     program.  This feature also works with nonexistent files like in
+     the Unix spec.  So 'ln -s file link' will generate 'link.exe',
+     which will attempt to call 'file.exe' if run.  But this feature
+     only works for executables, so 'cp -p' is used instead for these
+     systems.  DJGPP versions 2.04 and later have full symlink support.
+
+'mv'
+     The only portable options are '-f' and '-i'.
+
+     Moving individual files between file systems is portable (it was in
+     V6), but it is not always atomic: when doing 'mv new existing',
+     there's a critical section where neither the old nor the new
+     version of 'existing' actually exists.
+
+     Moving directories across mount points is not portable, use 'cp'
+     and 'rm'.
+
+'sed'
+     Patterns should not include the separator (unless escaped), even as
+     part of a character class.  In conformance with POSIX, the Cray
+     'sed' will reject 's/[^/]*$//': use 's,[^/]*$,,'.
+
+     Sed scripts should not use branch labels longer than 8 characters
+     and should not contain comments.
+
+     Don't include extra ';', as some 'sed', such as NetBSD 1.4.2's, try
+     to interpret the second as a command:
+
+          $ echo a | sed 's/x/x/;;s/x/x/'
+          sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
+
+     Input should have reasonably long lines, since some 'sed' have an
+     input buffer limited to 4000 bytes.
+
+     Alternation, '\|', is common but not portable.  Anchors ('^' and
+     '$') inside groups are not portable.
+
+     Nested groups are extremely portable, but there is at least one
+     'sed' (System V/68 Base Operating System R3V7.1) that does not
+     support it.
+
+     Of course the option '-e' is portable, but it is not needed.  No
+     valid Sed program can start with a dash, so it does not help
+     disambiguating.  Its sole usefulness is helping enforcing indenting
+     as in:
+
+          sed -e INSTRUCTION-1 \
+              -e INSTRUCTION-2
+
+     as opposed to
+
+          sed INSTRUCTION-1;INSTRUCTION-2
+
+     Contrary to yet another urban legend, you may portably use '&' in
+     the replacement part of the 's' command to mean "what was matched".
+
+'sed' ('t')
+     Some old systems have 'sed' that "forget" to reset their 't' flag
+     when starting a new cycle.  For instance on MIPS RISC/OS, and on
+     IRIX 5.3, if you run the following 'sed' script (the line numbers
+     are not actual part of the texts):
+
+          s/keep me/kept/g  # a
+          t end             # b
+          s/.*/deleted/g    # c
+          : end             # d
+
+     on
+
+          delete me         # 1
+          delete me         # 2
+          keep me           # 3
+          delete me         # 4
+
+     you get
+
+          deleted
+          delete me
+          kept
+          deleted
+
+     instead of
+
+          deleted
+          deleted
+          kept
+          deleted
+
+     Why?  When processing 1, a matches, therefore sets the t flag, b
+     jumps to d, and the output is produced.  When processing line 2,
+     the t flag is still set (this is the bug).  Line a fails to match,
+     but 'sed' is not supposed to clear the t flag when a substitution
+     fails.  Line b sees that the flag is set, therefore it clears it,
+     and jumps to d, hence you get 'delete me' instead of 'deleted'.
+     When processing 3 t is clear, a matches, so the flag is set, hence
+     b clears the flags and jumps.  Finally, since the flag is clear, 4
+     is processed properly.
+
+     There are two things one should remind about 't' in 'sed'.
+     Firstly, always remember that 't' jumps if _some_ substitution
+     succeeded, not only the immediately preceding substitution,
+     therefore, always use a fake 't clear; : clear' to reset the t flag
+     where indeed.
+
+     Secondly, you cannot rely on 'sed' to clear the flag at each new
+     cycle.
+
+     One portable implementation of the script above is:
+
+          t clear
+          : clear
+          s/keep me/kept/g
+          t end
+          s/.*/deleted/g
+          : end
+
+'touch'
+     On some old BSD systems, 'touch' or any command that results in an
+     empty file does not update the timestamps, so use a command like
+     'echo' as a workaround.
+
+     GNU 'touch' 3.16r (and presumably all before that) fails to work on
+     SunOS 4.1.3 when the empty file is on an NFS-mounted 4.2 volume.
+
+
+File: autoconf.info,  Node: Limitations of Make,  Prev: Limitations of Usual Tools,  Up: Portable Shell
+
+10.10 Limitations of Make
+=========================
+
+Make itself suffers a great number of limitations, only a few of which
+being listed here.  First of all, remember that since commands are
+executed by the shell, all its weaknesses are inherited...
+
+Leading underscore in macro names
+     Some Make don't support leading underscores in macro names, such as
+     on NEWS-OS 4.2R.
+
+          $ cat Makefile
+          _am_include = #
+          _am_quote =
+          all:; @echo this is test
+
+          % make
+          Make: Must be a separator on rules line 2.  Stop.
+
+          $ cat Makefile2
+          am_include = #
+          am_quote =
+          all:; @echo this is test
+
+          $ make -f Makefile2
+          this is test
+
+'VPATH'
+     Don't use it!  For instance any assignment to 'VPATH' causes Sun
+     'make' to only execute the first set of double-colon rules.
+
+
+File: autoconf.info,  Node: Manual Configuration,  Next: Site Configuration,  Prev: Portable Shell,  Up: Top
+
+11 Manual Configuration
+***********************
+
+A few kinds of features can't be guessed automatically by running test
+programs.  For example, the details of the object-file format, or
+special options that need to be passed to the compiler or linker.  You
+can check for such features using ad-hoc means, such as having
+'configure' check the output of the 'uname' program, or looking for
+libraries that are unique to particular systems.  However, Autoconf
+provides a uniform method for handling unguessable features.
+
+* Menu:
+
+* Specifying Names::            Specifying the system type
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+
+
+File: autoconf.info,  Node: Specifying Names,  Next: Canonicalizing,  Prev: Manual Configuration,  Up: Manual Configuration
+
+11.1 Specifying the System Type
+===============================
+
+Like other GNU 'configure' scripts, Autoconf-generated 'configure'
+scripts can make decisions based on a canonical name for the system
+type, which has the form: 'CPU-VENDOR-OS', where OS can be 'SYSTEM' or
+'KERNEL-SYSTEM'
+
+   'configure' can usually guess the canonical name for the type of
+system it's running on.  To do so it runs a script called
+'config.guess', which infers the name using the 'uname' command or
+symbols predefined by the C preprocessor.
+
+   Alternately, the user can specify the system type with command line
+arguments to 'configure'.  Doing so is necessary when cross-compiling.
+In the most complex case of cross-compiling, three system types are
+involved.  The options to specify them are(1):
+
+'--build=BUILD-TYPE'
+     the type of system on which the package is being configured and
+     compiled.
+
+'--host=HOST-TYPE'
+     the type of system on which the package will run.
+
+'--target=TARGET-TYPE'
+     the type of system for which any compiler tools in the package will
+     produce code (rarely needed).  By default, it is the same as host.
+
+   They all default to the result of running 'config.guess', unless you
+specify either '--build' or '--host'.  In this case, the default becomes
+the system type you specified.  If you specify both, and they're
+different, 'configure' will enter cross compilation mode, so it won't
+run any tests that require execution.
+
+   Hint: if you mean to override the result of 'config.guess', prefer
+'--build' over '--host'.  In the future, '--host' will not override the
+name of the build system type.  Also, if you specify '--host', but not
+'--build', when 'configure' performs the first compiler test it will try
+to run an executable produced by the compiler.  If the execution fails,
+it will enter cross-compilation mode.  Note, however, that it won't
+guess the build-system type, since this may require running test
+programs.  Moreover, by the time the compiler test is performed, it may
+be too late to modify the build-system type: other tests may have
+already been performed.  Therefore, whenever you specify '--host', be
+sure to specify '--build' too.
+
+     ./configure --build=i686-pc-linux-gnu --host=m68k-coff
+
+will enter cross-compilation mode, but 'configure' will fail if it can't
+run the code generated by the specified compiler if you configure as
+follows:
+
+     ./configure CC=m68k-coff-gcc
+
+   'configure' recognizes short aliases for many system types; for
+example, 'decstation' can be used instead of 'mips-dec-ultrix4.2'.
+'configure' runs a script called 'config.sub' to canonicalize system
+type aliases.
+
+   ---------- Footnotes ----------
+
+   (1) For backward compatibility, 'configure' will accept a system type
+as an option by itself.  Such an option will override the defaults for
+build, host and target system types.  The following configure statement
+will configure a cross toolchain that will run on NetBSD/alpha but
+generate code for GNU Hurd/sparc, which is also the build platform.
+
+     ./configure --host=alpha-netbsd sparc-gnu
+
+
+File: autoconf.info,  Node: Canonicalizing,  Next: Using System Type,  Prev: Specifying Names,  Up: Manual Configuration
+
+11.2 Getting the Canonical System Type
+======================================
+
+The following macros make the system type available to 'configure'
+scripts.
+
+   The variables 'build_alias', 'host_alias', and 'target_alias' are
+always exactly the arguments of '--build', '--host', and '--target'; in
+particular, they are left empty if the user did not use them, even if
+the corresponding 'AC_CANONICAL' macro was run.  Any configure script
+may use these variables anywhere.  These are the variables that should
+be used when in interaction with the user.
+
+   If you need to recognize some special environments based on their
+system type, run the following macros to get canonical system names.
+These variables are not set before the macro call.
+
+   If you use these macros, you must distribute 'config.guess' and
+'config.sub' along with your source code.  *Note Output::, for
+information about the 'AC_CONFIG_AUX_DIR' macro which you can use to
+control in which directory 'configure' looks for those scripts.
+
+ -- Macro: AC_CANONICAL_BUILD
+     Compute the canonical build-system type variable, 'build', and its
+     three individual parts 'build_cpu', 'build_vendor', and 'build_os'.
+
+     If '--build' was specified, then 'build' is the canonicalization of
+     'build_alias' by 'config.sub', otherwise it is determined by the
+     shell script 'config.guess'.
+
+ -- Macro: AC_CANONICAL_HOST
+     Compute the canonical host-system type variable, 'host', and its
+     three individual parts 'host_cpu', 'host_vendor', and 'host_os'.
+
+     If '--host' was specified, then 'host' is the canonicalization of
+     'host_alias' by 'config.sub', otherwise it defaults to 'build'.
+
+     For temporary backward-compatibility, when '--host' is specified by
+     '--build' isn't, the build system will be assumed to be the same as
+     '--host', and 'build_alias' will be set to that value.  Eventually,
+     this historically incorrect behavior will go away.
+
+ -- Macro: AC_CANONICAL_TARGET
+     Compute the canonical target-system type variable, 'target', and
+     its three individual parts 'target_cpu', 'target_vendor', and
+     'target_os'.
+
+     If '--target' was specified, then 'target' is the canonicalization
+     of 'target_alias' by 'config.sub', otherwise it defaults to 'host'.
+
+
+File: autoconf.info,  Node: Using System Type,  Prev: Canonicalizing,  Up: Manual Configuration
+
+11.3 Using the System Type
+==========================
+
+How do you use a canonical system type?  Usually, you use it in one or
+more 'case' statements in 'configure.ac' to select system-specific C
+files.  Then, using 'AC_CONFIG_LINKS', link those files which have names
+based on the system name, to generic names, such as 'host.h' or
+'target.c' (*note Configuration Links::).  The 'case' statement patterns
+can use shell wild cards to group several cases together, like in this
+fragment:
+
+     case "$target" in
+     i386-*-mach* | i386-*-gnu*)
+                  obj_format=aout emulation=mach bfd_gas=yes ;;
+     i960-*-bout) obj_format=bout ;;
+     esac
+
+and in 'configure.ac', use:
+
+     AC_CONFIG_LINKS(host.h:config/$machine.h
+                     object.h:config/$obj_format.h)
+
+   You can also use the host system type to find cross-compilation
+tools.  *Note Generic Programs::, for information about the
+'AC_CHECK_TOOL' macro which does that.
+
+
+File: autoconf.info,  Node: Site Configuration,  Next: Running configure scripts,  Prev: Manual Configuration,  Up: Top
+
+12 Site Configuration
+*********************
+
+'configure' scripts support several kinds of local configuration
+decisions.  There are ways for users to specify where external software
+packages are, include or exclude optional features, install programs
+under modified names, and set default values for 'configure' options.
+
+* Menu:
+
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving 'configure' local defaults
+
+
+File: autoconf.info,  Node: External Software,  Next: Package Options,  Prev: Site Configuration,  Up: Site Configuration
+
+12.1 Working With External Software
+===================================
+
+Some packages require, or can optionally use, other software packages
+that are already installed.  The user can give 'configure' command line
+options to specify which such external software to use.  The options
+have one of these forms:
+
+     --with-PACKAGE=[ARG]
+     --without-PACKAGE
+
+   For example, '--with-gnu-ld' means work with the GNU linker instead
+of some other linker.  '--with-x' means work with The X Window System.
+
+   The user can give an argument by following the package name with '='
+and the argument.  Giving an argument of 'no' is for packages that are
+used by default; it says to _not_ use the package.  An argument that is
+neither 'yes' nor 'no' could include a name or number of a version of
+the other package, to specify more precisely which other package this
+program is supposed to work with.  If no argument is given, it defaults
+to 'yes'.  '--without-PACKAGE' is equivalent to '--with-PACKAGE=no'.
+
+   'configure' scripts do not complain about '--with-PACKAGE' options
+that they do not support.  This behavior permits configuring a source
+tree containing multiple packages with a top-level 'configure' script
+when the packages support different options, without spurious error
+messages about options that some of the packages support.  An
+unfortunate side effect is that option spelling errors are not
+diagnosed.  No better approach to this problem has been suggested so
+far.
+
+   For each external software package that may be used, 'configure.ac'
+should call 'AC_ARG_WITH' to detect whether the 'configure' user asked
+to use it.  Whether each package is used or not by default, and which
+arguments are valid, is up to you.
+
+ -- Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, [ACTION-IF-GIVEN],
+          [ACTION-IF-NOT-GIVEN])
+     If the user gave 'configure' the option '--with-PACKAGE' or
+     '--without-PACKAGE', run shell commands ACTION-IF-GIVEN.  If
+     neither option was given, run shell commands ACTION-IF-NOT-GIVEN.
+     The name PACKAGE indicates another software package that this
+     program should work with.  It should consist only of alphanumeric
+     characters and dashes.
+
+     The option's argument is available to the shell commands
+     ACTION-IF-GIVEN in the shell variable 'withval', which is actually
+     just the value of the shell variable 'with_PACKAGE', with any '-'
+     characters changed into '_'.  You may use that variable instead, if
+     you wish.
+
+     The argument HELP-STRING is a description of the option that looks
+     like this:
+            --with-readline         support fancy command line editing
+
+     HELP-STRING may be more than one line long, if more detail is
+     needed.  Just make sure the columns line up in 'configure --help'.
+     Avoid tabs in the help string.  You'll need to enclose it in '['
+     and ']' in order to produce the leading spaces.
+
+     You should format your HELP-STRING with the macro 'AC_HELP_STRING'
+     (*note Pretty Help Strings::).
+
+ -- Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN])
+     This is an obsolete version of 'AC_ARG_WITH' that does not support
+     providing a help string.
+
+
+File: autoconf.info,  Node: Package Options,  Next: Pretty Help Strings,  Prev: External Software,  Up: Site Configuration
+
+12.2 Choosing Package Options
+=============================
+
+If a software package has optional compile-time features, the user can
+give 'configure' command line options to specify whether to compile
+them.  The options have one of these forms:
+
+     --enable-FEATURE=[ARG]
+     --disable-FEATURE
+
+   These options allow users to choose which optional features to build
+and install.  '--enable-FEATURE' options should never make a feature
+behave differently or cause one feature to replace another.  They should
+only cause parts of the program to be built rather than left out.
+
+   The user can give an argument by following the feature name with '='
+and the argument.  Giving an argument of 'no' requests that the feature
+_not_ be made available.  A feature with an argument looks like
+'--enable-debug=stabs'.  If no argument is given, it defaults to 'yes'.
+'--disable-FEATURE' is equivalent to '--enable-FEATURE=no'.
+
+   'configure' scripts do not complain about '--enable-FEATURE' options
+that they do not support.  This behavior permits configuring a source
+tree containing multiple packages with a top-level 'configure' script
+when the packages support different options, without spurious error
+messages about options that some of the packages support.  An
+unfortunate side effect is that option spelling errors are not
+diagnosed.  No better approach to this problem has been suggested so
+far.
+
+   For each optional feature, 'configure.ac' should call 'AC_ARG_ENABLE'
+to detect whether the 'configure' user asked to include it.  Whether
+each feature is included or not by default, and which arguments are
+valid, is up to you.
+
+ -- Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, [ACTION-IF-GIVEN],
+          [ACTION-IF-NOT-GIVEN])
+     If the user gave 'configure' the option '--enable-FEATURE' or
+     '--disable-FEATURE', run shell commands ACTION-IF-GIVEN.  If
+     neither option was given, run shell commands ACTION-IF-NOT-GIVEN.
+     The name FEATURE indicates an optional user-level facility.  It
+     should consist only of alphanumeric characters and dashes.
+
+     The option's argument is available to the shell commands
+     ACTION-IF-GIVEN in the shell variable 'enableval', which is
+     actually just the value of the shell variable 'enable_FEATURE',
+     with any '-' characters changed into '_'.  You may use that
+     variable instead, if you wish.  The HELP-STRING argument is like
+     that of 'AC_ARG_WITH' (*note External Software::).
+
+     You should format your HELP-STRING with the macro 'AC_HELP_STRING'
+     (*note Pretty Help Strings::).
+
+ -- Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN])
+     This is an obsolete version of 'AC_ARG_ENABLE' that does not
+     support providing a help string.
+
+
+File: autoconf.info,  Node: Pretty Help Strings,  Next: Site Details,  Prev: Package Options,  Up: Site Configuration
+
+12.3 Making Your Help Strings Look Pretty
+=========================================
+
+Properly formatting the 'help strings' which are used in 'AC_ARG_WITH'
+(*note External Software::) and 'AC_ARG_ENABLE' (*note Package
+Options::) can be challenging.  Specifically, you want your own 'help
+strings' to line up in the appropriate columns of 'configure --help'
+just like the standard Autoconf 'help strings' do.  This is the purpose
+of the 'AC_HELP_STRING' macro.
+
+ -- Macro: AC_HELP_STRING (LEFT-HAND-SIDE, RIGHT-HAND-SIDE)
+
+     Expands into an help string that looks pretty when the user
+     executes 'configure --help'.  It is typically used in 'AC_ARG_WITH'
+     (*note External Software::) or 'AC_ARG_ENABLE' (*note Package
+     Options::).  The following example will make this clearer.
+
+          AC_DEFUN(TEST_MACRO,
+          [AC_ARG_WITH(foo,
+                       AC_HELP_STRING([--with-foo],
+                                      [use foo (default is NO)]),
+                       ac_cv_use_foo=$withval, ac_cv_use_foo=no),
+          AC_CACHE_CHECK(whether to use foo,
+                         ac_cv_use_foo, ac_cv_use_foo=no)])
+
+     Please note that the call to 'AC_HELP_STRING' is *unquoted*.  Then
+     the last few lines of 'configure --help' will appear like this:
+
+          --enable and --with options recognized:
+            --with-foo              use foo (default is NO)
+
+     The 'AC_HELP_STRING' macro is particularly helpful when the
+     LEFT-HAND-SIDE and/or RIGHT-HAND-SIDE are composed of macro
+     arguments, as shown in the following example.
+
+          AC_DEFUN(MY_ARG_WITH,
+          [AC_ARG_WITH([$1],
+                       AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
+                       ac_cv_use_$1=$withval, ac_cv_use_$1=no),
+          AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
+
+
+File: autoconf.info,  Node: Site Details,  Next: Transforming Names,  Prev: Pretty Help Strings,  Up: Site Configuration
+
+12.4 Configuring Site Details
+=============================
+
+Some software packages require complex site-specific information.  Some
+examples are host names to use for certain services, company names, and
+email addresses to contact.  Since some configuration scripts generated
+by Metaconfig ask for such information interactively, people sometimes
+wonder how to get that information in Autoconf-generated configuration
+scripts, which aren't interactive.
+
+   Such site configuration information should be put in a file that is
+edited _only by users_, not by programs.  The location of the file can
+either be based on the 'prefix' variable, or be a standard location such
+as the user's home directory.  It could even be specified by an
+environment variable.  The programs should examine that file at run
+time, rather than at compile time.  Run time configuration is more
+convenient for users and makes the configuration process simpler than
+getting the information while configuring.  *Note Variables for
+Installation Directories: (standards)Directory Variables, for more
+information on where to put data files.
+
+
+File: autoconf.info,  Node: Transforming Names,  Next: Site Defaults,  Prev: Site Details,  Up: Site Configuration
+
+12.5 Transforming Program Names When Installing
+===============================================
+
+Autoconf supports changing the names of programs when installing them.
+In order to use these transformations, 'configure.ac' must call the
+macro 'AC_ARG_PROGRAM'.
+
+ -- Macro: AC_ARG_PROGRAM
+     Place in output variable 'program_transform_name' a sequence of
+     'sed' commands for changing the names of installed programs.
+
+     If any of the options described below are given to 'configure',
+     program names are transformed accordingly.  Otherwise, if
+     'AC_CANONICAL_TARGET' has been called and a '--target' value is
+     given that differs from the host type (specified with '--host'),
+     the target type followed by a dash is used as a prefix.  Otherwise,
+     no program name transformation is done.
+
+* Menu:
+
+* Transformation Options::      'configure' options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        'Makefile' uses of transforming names
+
+
+File: autoconf.info,  Node: Transformation Options,  Next: Transformation Examples,  Prev: Transforming Names,  Up: Transforming Names
+
+12.5.1 Transformation Options
+-----------------------------
+
+You can specify name transformations by giving 'configure' these command
+line options:
+
+'--program-prefix=PREFIX'
+     prepend PREFIX to the names;
+
+'--program-suffix=SUFFIX'
+     append SUFFIX to the names;
+
+'--program-transform-name=EXPRESSION'
+     perform 'sed' substitution EXPRESSION on the names.
+
+
+File: autoconf.info,  Node: Transformation Examples,  Next: Transformation Rules,  Prev: Transformation Options,  Up: Transforming Names
+
+12.5.2 Transformation Examples
+------------------------------
+
+These transformations are useful with programs that can be part of a
+cross-compilation development environment.  For example, a
+cross-assembler running on a Sun 4 configured with
+'--target=i960-vxworks' is normally installed as 'i960-vxworks-as',
+rather than 'as', which could be confused with a native Sun 4 assembler.
+
+   You can force a program name to begin with 'g', if you don't want GNU
+programs installed on your system to shadow other programs with the same
+name.  For example, if you configure GNU 'diff' with
+'--program-prefix=g', then when you run 'make install' it is installed
+as '/usr/local/bin/gdiff'.
+
+   As a more sophisticated example, you could use
+
+     --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
+
+   to prepend 'g' to most of the program names in a source tree,
+excepting those like 'gdb' that already have one and those like 'less'
+and 'lesskey' that aren't GNU programs.  (That is assuming that you have
+a source tree containing those programs that is set up to use this
+feature.)
+
+   One way to install multiple versions of some programs simultaneously
+is to append a version number to the name of one or both.  For example,
+if you want to keep Autoconf version 1 around for awhile, you can
+configure Autoconf version 2 using '--program-suffix=2' to install the
+programs as '/usr/local/bin/autoconf2', '/usr/local/bin/autoheader2',
+etc.  Nevertheless, pay attention that only the binaries are renamed,
+therefore you'd have problems with the library files which might
+overlap.
+
+
+File: autoconf.info,  Node: Transformation Rules,  Prev: Transformation Examples,  Up: Transforming Names
+
+12.5.3 Transformation Rules
+---------------------------
+
+Here is how to use the variable 'program_transform_name' in a
+'Makefile.in':
+
+     transform = @program_transform_name@
+     install: all
+             $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \
+                                                    sed '$(transform)'`
+
+     uninstall:
+             rm -f $(bindir)/`echo myprog | sed '$(transform)'`
+
+If you have more than one program to install, you can do it in a loop:
+
+     PROGRAMS = cp ls rm
+     install:
+             for p in $(PROGRAMS); do \
+               $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \
+                                                   sed '$(transform)'`; \
+             done
+
+     uninstall:
+             for p in $(PROGRAMS); do \
+               rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \
+             done
+
+   It is guaranteed that 'program_transform_name' is never empty, and
+that there are no useless separators.  Therefore you may safely embed
+'program_transform_name' within a sed program using ';':
+
+     transform = @program_transform_name@
+     transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
+
+   Whether to do the transformations on documentation files (Texinfo or
+'man') is a tricky question; there seems to be no perfect answer, due to
+the several reasons for name transforming.  Documentation is not usually
+particular to a specific architecture, and Texinfo files do not conflict
+with system documentation.  But they might conflict with earlier
+versions of the same files, and 'man' pages sometimes do conflict with
+system documentation.  As a compromise, it is probably best to do name
+transformations on 'man' pages but not on Texinfo manuals.
+
+
+File: autoconf.info,  Node: Site Defaults,  Prev: Transforming Names,  Up: Site Configuration
+
+12.6 Setting Site Defaults
+==========================
+
+Autoconf-generated 'configure' scripts allow your site to provide
+default values for some configuration values.  You do this by creating
+site- and system-wide initialization files.
+
+   If the environment variable 'CONFIG_SITE' is set, 'configure' uses
+its value as the name of a shell script to read.  Otherwise, it reads
+the shell script 'PREFIX/share/config.site' if it exists, then
+'PREFIX/etc/config.site' if it exists.  Thus, settings in
+machine-specific files override those in machine-independent ones in
+case of conflict.
+
+   Site files can be arbitrary shell scripts, but only certain kinds of
+code are really appropriate to be in them.  Because 'configure' reads
+any cache file after it has read any site files, a site file can define
+a default cache file to be shared between all Autoconf-generated
+'configure' scripts run on that system (*note Cache Files::).  If you
+set a default cache file in a site file, it is a good idea to also set
+the output variable 'CC' in that site file, because the cache file is
+only valid for a particular compiler, but many systems have several
+available.
+
+   You can examine or override the value set by a command line option to
+'configure' in a site file; options set shell variables that have the
+same names as the options, with any dashes turned into underscores.  The
+exceptions are that '--without-' and '--disable-' options are like
+giving the corresponding '--with-' or '--enable-' option and the value
+'no'.  Thus, '--cache-file=localcache' sets the variable 'cache_file' to
+the value 'localcache'; '--enable-warnings=no' or '--disable-warnings'
+sets the variable 'enable_warnings' to the value 'no'; '--prefix=/usr'
+sets the variable 'prefix' to the value '/usr'; etc.
+
+   Site files are also good places to set default values for other
+output variables, such as 'CFLAGS', if you need to give them non-default
+values: anything you would normally do, repetitively, on the command
+line.  If you use non-default values for PREFIX or EXEC_PREFIX (wherever
+you locate the site file), you can set them in the site file if you
+specify it with the 'CONFIG_SITE' environment variable.
+
+   You can set some cache values in the site file itself.  Doing this is
+useful if you are cross-compiling, so it is impossible to check features
+that require running a test program.  You could "prime the cache" by
+setting those values correctly for that system in
+'PREFIX/etc/config.site'.  To find out the names of the cache variables
+you need to set, look for shell variables with '_cv_' in their names in
+the affected 'configure' scripts, or in the Autoconf M4 source code for
+those macros.
+
+   The cache file is careful to not override any variables set in the
+site files.  Similarly, you should not override command-line options in
+the site files.  Your code should check that variables such as 'prefix'
+and 'cache_file' have their default values (as set near the top of
+'configure') before changing them.
+
+   Here is a sample file '/usr/share/local/gnu/share/config.site'.  The
+command 'configure --prefix=/usr/share/local/gnu' would read this file
+(if 'CONFIG_SITE' is not set to a different file).
+
+     # config.site for configure
+     #
+     # Change some defaults.
+     test "$prefix" = NONE && prefix=/usr/share/local/gnu
+     test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
+     test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
+     test "$localstatedir" = '$prefix/var' && localstatedir=/var
+
+     # Give Autoconf 2.x generated configure scripts a shared default
+     # cache file for feature test results, architecture-specific.
+     if test "$cache_file" = /dev/null; then
+       cache_file="$prefix/var/config.cache"
+       # A cache file is only valid for one C compiler.
+       CC=gcc
+     fi
+
+
+File: autoconf.info,  Node: Running configure scripts,  Next: config.status Invocation,  Prev: Site Configuration,  Up: Top
+
+13 Running 'configure' Scripts
+******************************
+
+Below are instructions on how to configure a package that uses a
+'configure' script, suitable for inclusion as an 'INSTALL' file in the
+package.  A plain-text version of 'INSTALL' which you may use comes with
+Autoconf.
+
+* Menu:
+
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for 'configure'
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how 'configure' runs
+
+
+File: autoconf.info,  Node: Basic Installation,  Next: Compilers and Options,  Up: Running configure scripts
+
+13.1 Basic Installation
+=======================
+
+These are generic installation instructions.
+
+   The 'configure' shell script attempts to guess correct values for
+various system-dependent variables used during compilation.  It uses
+those values to create a 'Makefile' in each directory of the package.
+It may also create one or more '.h' files containing system-dependent
+definitions.  Finally, it creates a shell script 'config.status' that
+you can run in the future to recreate the current configuration, and a
+file 'config.log' containing compiler output (useful mainly for
+debugging 'configure').
+
+   It can also use an optional file (typically called 'config.cache' and
+enabled with '--cache-file=config.cache' or simply '-C') that saves the
+results of its tests to speed up reconfiguring.  (Caching is disabled by
+default to prevent problems with accidental use of stale cache files.)
+
+   If you need to do unusual things to compile the package, please try
+to figure out how 'configure' could check whether to do them, and mail
+diffs or instructions to the address given in the 'README' so they can
+be considered for the next release.  If you are using the cache, and at
+some point 'config.cache' contains results you don't want to keep, you
+may remove or edit it.
+
+   The file 'configure.ac' (or 'configure.in') is used to create
+'configure' by a program called 'autoconf'.  You only need
+'configure.ac' if you want to change it or regenerate 'configure' using
+a newer version of 'autoconf'.
+
+The simplest way to compile this package is:
+
+  1. 'cd' to the directory containing the package's source code and type
+     './configure' to configure the package for your system.  If you're
+     using 'csh' on an old version of System V, you might need to type
+     'sh ./configure' instead to prevent 'csh' from trying to execute
+     'configure' itself.
+
+     Running 'configure' takes awhile.  While running, it prints some
+     messages telling which features it is checking for.
+
+  2. Type 'make' to compile the package.
+
+  3. Optionally, type 'make check' to run any self-tests that come with
+     the package.
+
+  4. Type 'make install' to install the programs and any data files and
+     documentation.
+
+  5. You can remove the program binaries and object files from the
+     source code directory by typing 'make clean'.  To also remove the
+     files that 'configure' created (so you can compile the package for
+     a different kind of computer), type 'make distclean'.  There is
+     also a 'make maintainer-clean' target, but that is intended mainly
+     for the package's developers.  If you use it, you may have to get
+     all sorts of other programs in order to regenerate files that came
+     with the distribution.
+
+
+File: autoconf.info,  Node: Compilers and Options,  Next: Multiple Architectures,  Prev: Basic Installation,  Up: Running configure scripts
+
+13.2 Compilers and Options
+==========================
+
+Some systems require unusual options for compilation or linking that the
+'configure' script does not know about.  Run './configure --help' for
+details on some of the pertinent environment variables.
+
+   You can give 'configure' initial values for variables by setting them
+in the environment.  You can do that on the command line like this:
+
+     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
+
+   *Note Environment Variables::, for more details.
+
+
+File: autoconf.info,  Node: Multiple Architectures,  Next: Installation Names,  Prev: Compilers and Options,  Up: Running configure scripts
+
+13.3 Compiling For Multiple Architectures
+=========================================
+
+You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory.  To do this, you must use a version of 'make' that
+supports the 'VPATH' variable, such as GNU 'make'.  'cd' to the
+directory where you want the object files and executables to go and run
+the 'configure' script.  'configure' automatically checks for the source
+code in the directory that 'configure' is in and in '..'.
+
+   If you have to use a 'make' that does not support the 'VPATH'
+variable, you have to compile the package for one architecture at a time
+in the source code directory.  After you have installed the package for
+one architecture, use 'make distclean' before reconfiguring for another
+architecture.
+
+
+File: autoconf.info,  Node: Installation Names,  Next: Optional Features,  Prev: Multiple Architectures,  Up: Running configure scripts
+
+13.4 Installation Names
+=======================
+
+By default, 'make install' will install the package's files in
+'/usr/local/bin', '/usr/local/man', etc.  You can specify an
+installation prefix other than '/usr/local' by giving 'configure' the
+option '--prefix=PATH'.
+
+   You can specify separate installation prefixes for
+architecture-specific files and architecture-independent files.  If you
+give 'configure' the option '--exec-prefix=PATH', the package will use
+PATH as the prefix for installing programs and libraries.  Documentation
+and other data files will still use the regular prefix.
+
+   In addition, if you use an unusual directory layout you can give
+options like '--bindir=PATH' to specify different values for particular
+kinds of files.  Run 'configure --help' for a list of the directories
+you can set and what kinds of files go in them.
+
+   If the package supports it, you can cause programs to be installed
+with an extra prefix or suffix on their names by giving 'configure' the
+option '--program-prefix=PREFIX' or '--program-suffix=SUFFIX'.
+
+
+File: autoconf.info,  Node: Optional Features,  Next: System Type,  Prev: Installation Names,  Up: Running configure scripts
+
+13.5 Optional Features
+======================
+
+Some packages pay attention to '--enable-FEATURE' options to
+'configure', where FEATURE indicates an optional part of the package.
+They may also pay attention to '--with-PACKAGE' options, where PACKAGE
+is something like 'gnu-as' or 'x' (for the X Window System).  The
+'README' should mention any '--enable-' and '--with-' options that the
+package recognizes.
+
+   For packages that use the X Window System, 'configure' can usually
+find the X include and library files automatically, but if it doesn't,
+you can use the 'configure' options '--x-includes=DIR' and
+'--x-libraries=DIR' to specify their locations.
+
+
+File: autoconf.info,  Node: System Type,  Next: Sharing Defaults,  Prev: Optional Features,  Up: Running configure scripts
+
+13.6 Specifying the System Type
+===============================
+
+There may be some features 'configure' cannot figure out automatically,
+but needs to determine by the type of host the package will run on.
+Usually 'configure' can figure that out, but if it prints a message
+saying it cannot guess the host type, give it the '--build=TYPE' option.
+TYPE can either be a short name for the system type, such as 'sun4', or
+a canonical name which has the form:
+
+     CPU-COMPANY-SYSTEM
+
+where SYSTEM can have one of these forms:
+
+     OS
+     KERNEL-OS
+
+   See the file 'config.sub' for the possible values of each field.  If
+'config.sub' isn't included in this package, then this package doesn't
+need to know the host type.
+
+   If you are _building_ compiler tools for cross-compiling, you should
+use the '--target=TYPE' option to select the type of system they will
+produce code for.
+
+   If you want to _use_ a cross compiler, that generates code for a
+platform different from the build platform, you should specify the host
+platform (i.e., that on which the generated programs will eventually be
+run) with '--host=TYPE'.  In this case, you should also specify the
+build platform with '--build=TYPE', because, in this case, it may not be
+possible to guess the build platform (it sometimes involves compiling
+and running simple test programs, and this can't be done if the compiler
+is a cross compiler).
+
+
+File: autoconf.info,  Node: Sharing Defaults,  Next: Environment Variables,  Prev: System Type,  Up: Running configure scripts
+
+13.7 Sharing Defaults
+=====================
+
+If you want to set default values for 'configure' scripts to share, you
+can create a site shell script called 'config.site' that gives default
+values for variables like 'CC', 'cache_file', and 'prefix'.  'configure'
+looks for 'PREFIX/share/config.site' if it exists, then
+'PREFIX/etc/config.site' if it exists.  Or, you can set the
+'CONFIG_SITE' environment variable to the location of the site script.
+A warning: not all 'configure' scripts look for a site script.
+
+
+File: autoconf.info,  Node: Environment Variables,  Next: configure Invocation,  Prev: Sharing Defaults,  Up: Running configure scripts
+
+13.8 Environment Variables
+==========================
+
+Variables not defined in a site shell script can be set in the
+environment passed to configure.  However, some packages may run
+configure again during the build, and the customized values of these
+variables may be lost.  In order to avoid this problem, you should set
+them in the 'configure' command line, using 'VAR=value'.  For example:
+
+     ./configure CC=/usr/local2/bin/gcc
+
+will cause the specified gcc to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+
+File: autoconf.info,  Node: configure Invocation,  Prev: Environment Variables,  Up: Running configure scripts
+
+13.9 'configure' Invocation
+===========================
+
+'configure' recognizes the following options to control how it operates.
+
+'--help'
+'-h'
+     Print a summary of the options to 'configure', and exit.
+
+'--version'
+'-V'
+     Print the version of Autoconf used to generate the 'configure'
+     script, and exit.
+
+'--cache-file=FILE'
+     Enable the cache: use and save the results of the tests in FILE,
+     traditionally 'config.cache'.  FILE defaults to '/dev/null' to
+     disable caching.
+
+'--config-cache'
+'-C'
+     Alias for '--cache-file=config.cache'.
+
+'--quiet'
+'--silent'
+'-q'
+     Do not print messages saying which checks are being made.  To
+     suppress all normal output, redirect it to '/dev/null' (any error
+     messages will still be shown).
+
+'--srcdir=DIR'
+     Look for the package's source code in directory DIR.  Usually
+     'configure' can determine that directory automatically.
+
+'configure' also accepts some other, not widely useful, options.  Run
+'configure --help' for more details.
+
+
+File: autoconf.info,  Node: config.status Invocation,  Next: Obsolete Constructs,  Prev: Running configure scripts,  Up: Top
+
+14 Recreating a Configuration
+*****************************
+
+The 'configure' script creates a file named 'config.status', which
+actually configures, "instantiates", the template files.  It also
+records the configuration options that were specified when the package
+was last configured in case reconfiguring is needed.
+
+   Synopsis:
+     ./config.status OPTION... [FILE...]
+
+   It configures the FILES, if none are specified, all the templates are
+instantiated.  The files must be specified without their dependencies,
+as in
+
+     ./config.status foobar
+
+not
+
+     ./config.status foobar:foo.in:bar.in
+
+   The supported OPTIONs are:
+
+'--help'
+'-h'
+     Print a summary of the command line options, the list of the
+     template files and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--debug'
+'-d'
+     Don't remove the temporary files.
+
+'--file=FILE[:TEMPLATE]'
+     Require that FILE be instantiated as if
+     'AC_CONFIG_FILES(FILE:TEMPLATE)' was used.  Both FILE and TEMPLATE
+     may be '-' in which case the standard output and/or standard input,
+     respectively, is used.  If a TEMPLATE filename is relative, it is
+     first looked for in the build tree, and then in the source tree.
+     *Note Configuration Actions::, for more details.
+
+     This option and the following ones provide one way for separately
+     distributed packages to share the values computed by 'configure'.
+     Doing so can be useful if some of the packages need a superset of
+     the features that one of them, perhaps a common library, does.
+     These options allow a 'config.status' file to create files other
+     than the ones that its 'configure.ac' specifies, so it can be used
+     for a different package.
+
+'--header=FILE[:TEMPLATE]'
+     Same as '--file' above, but with 'AC_CONFIG_HEADERS'.
+
+'--recheck'
+     Ask 'config.status' to update itself and exit (no instantiation).
+     This option is useful if you change 'configure', so that the
+     results of some tests might be different from the previous run.
+     The '--recheck' option re-runs 'configure' with the same arguments
+     you used before, plus the '--no-create' option, which prevents
+     'configure' from running 'config.status' and creating 'Makefile'
+     and other files, and the '--no-recursion' option, which prevents
+     'configure' from running other 'configure' scripts in
+     subdirectories.  (This is so other 'Makefile' rules can run
+     'config.status' when it changes; *note Automatic Remaking::, for an
+     example).
+
+   'config.status' checks several optional environment variables that
+can alter its behavior:
+
+ -- Variable: CONFIG_SHELL
+     The shell with which to run 'configure' for the '--recheck' option.
+     It must be Bourne-compatible.  The default is '/bin/sh'.
+
+ -- Variable: CONFIG_STATUS
+     The file name to use for the shell script that records the
+     configuration.  The default is './config.status'.  This variable is
+     useful when one package uses parts of another and the 'configure'
+     scripts shouldn't be merged because they are maintained separately.
+
+   You can use './config.status' in your Makefiles.  For example, in the
+dependencies given above (*note Automatic Remaking::), 'config.status'
+is run twice when 'configure.ac' has changed.  If that bothers you, you
+can make each run only regenerate the files for that rule:
+     config.h: stamp-h
+     stamp-h: config.h.in config.status
+             ./config.status config.h
+             echo > stamp-h
+
+     Makefile: Makefile.in config.status
+             ./config.status Makefile
+
+   The calling convention of 'config.status' has changed, see *note
+Obsolete config.status Use::, for details.
+
+
+File: autoconf.info,  Node: Obsolete Constructs,  Next: Questions,  Prev: config.status Invocation,  Up: Top
+
+15 Obsolete Constructs
+**********************
+
+Autoconf changes, and throughout the years some constructs are
+obsoleted.  Most of the changes involve the macros, but the tools
+themselves, or even some concepts, are now considered obsolete.
+
+   You may completely skip this chapter if you are new to Autoconf, its
+intention is mainly to help maintainers updating their packages by
+understanding how to move to more modern constructs.
+
+* Menu:
+
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in 'config.h.in'
+* autoupdate Invocation::       Automatic update of 'configure.ac'
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+
+
+File: autoconf.info,  Node: Obsolete config.status Use,  Next: acconfig.h,  Prev: Obsolete Constructs,  Up: Obsolete Constructs
+
+15.1 Obsolete 'config.status' Invocation
+========================================
+
+'config.status' now supports arguments to specify the files to
+instantiate, see *note config.status Invocation::, for more details.
+Before, environment variables had to be used.
+
+ -- Variable: CONFIG_COMMANDS
+     The tags of the commands to execute.  The default is the arguments
+     given to 'AC_OUTPUT' and 'AC_CONFIG_COMMANDS' in 'configure.ac'.
+
+ -- Variable: CONFIG_FILES
+     The files in which to perform '@VARIABLE@' substitutions.  The
+     default is the arguments given to 'AC_OUTPUT' and 'AC_CONFIG_FILES'
+     in 'configure.ac'.
+
+ -- Variable: CONFIG_HEADERS
+     The files in which to substitute C '#define' statements.  The
+     default is the arguments given to 'AC_CONFIG_HEADERS'; if that
+     macro was not called, 'config.status' ignores this variable.
+
+ -- Variable: CONFIG_LINKS
+     The symbolic links to establish.  The default is the arguments
+     given to 'AC_CONFIG_LINKS'; if that macro was not called,
+     'config.status' ignores this variable.
+
+   In *note config.status Invocation::, using this old interface, the
+example would be:
+
+     config.h: stamp-h
+     stamp-h: config.h.in config.status
+             CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
+               CONFIG_HEADERS=config.h ./config.status
+             echo > stamp-h
+
+     Makefile: Makefile.in config.status
+             CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
+               CONFIG_FILES=Makefile ./config.status
+
+(If 'configure.ac' does not call 'AC_CONFIG_HEADERS', there is no need
+to set 'CONFIG_HEADERS' in the 'make' rules, equally for
+'CONFIG_COMMANDS' etc.)
+
+
+File: autoconf.info,  Node: acconfig.h,  Next: autoupdate Invocation,  Prev: Obsolete config.status Use,  Up: Obsolete Constructs
+
+15.2 'acconfig.h'
+=================
+
+In order to produce 'config.h.in', 'autoheader' needs to build or to
+find templates for each symbol.  Modern releases of Autoconf use
+'AH_VERBATIM' and 'AH_TEMPLATE' (*note Autoheader Macros::), but in
+older releases a file, 'acconfig.h', contained the list of needed
+templates.  'autoheader' copies comments and '#define' and '#undef'
+statements from 'acconfig.h' in the current directory, if present.  This
+file used to be mandatory if you 'AC_DEFINE' any additional symbols.
+
+   Modern releases of Autoconf also provide 'AH_TOP' and 'AH_BOTTOM' if
+you need to prepend/append some information to 'config.h.in'.  Ancient
+versions of Autoconf had a similar feature: if './acconfig.h' contains
+the string '@TOP@', 'autoheader' copies the lines before the line
+containing '@TOP@' into the top of the file that it generates.
+Similarly, if './acconfig.h' contains the string '@BOTTOM@',
+'autoheader' copies the lines after that line to the end of the file it
+generates.  Either or both of those strings may be omitted.  An even
+older alternate way to produce the same effect in jurasik versions of
+Autoconf is to create the files 'FILE.top' (typically 'config.h.top')
+and/or 'FILE.bot' in the current directory.  If they exist, 'autoheader'
+copies them to the beginning and end, respectively, of its output.
+
+   In former versions of Autoconf, the files used in preparing a
+software package for distribution were:
+     configure.ac --.   .------> autoconf* -----> configure
+                    +---+
+     [aclocal.m4] --+   `---.
+     [acsite.m4] ---'       |
+                            +--> [autoheader*] -> [config.h.in]
+     [acconfig.h] ----.     |
+                      +-----'
+     [config.h.top] --+
+     [config.h.bot] --'
+
+   Use only the 'AH_' macros, 'configure.ac' should be self-contained,
+and should not depend upon 'acconfig.h' etc.
+
+
+File: autoconf.info,  Node: autoupdate Invocation,  Next: Obsolete Macros,  Prev: acconfig.h,  Up: Obsolete Constructs
+
+15.3 Using 'autoupdate' to Modernize 'configure.ac'
+===================================================
+
+The 'autoupdate' program updates a 'configure.ac' file that calls
+Autoconf macros by their old names to use the current macro names.  In
+version 2 of Autoconf, most of the macros were renamed to use a more
+uniform and descriptive naming scheme.  *Note Macro Names::, for a
+description of the new scheme.  Although the old names still work (*note
+Obsolete Macros::, for a list of the old macros and the corresponding
+new names), you can make your 'configure.ac' files more readable and
+make it easier to use the current Autoconf documentation if you update
+them to use the new macro names.
+
+   If given no arguments, 'autoupdate' updates 'configure.ac', backing
+up the original version with the suffix '~' (or the value of the
+environment variable 'SIMPLE_BACKUP_SUFFIX', if that is set).  If you
+give 'autoupdate' an argument, it reads that file instead of
+'configure.ac' and writes the updated file to the standard output.
+
+'autoupdate' accepts the following options:
+
+'--help'
+'-h'
+     Print a summary of the command line options and exit.
+
+'--version'
+'-V'
+     Print the version number of Autoconf and exit.
+
+'--verbose'
+'-v'
+     Report processing steps.
+
+'--debug'
+'-d'
+     Don't remove the temporary files.
+
+'--autoconf-dir=DIR'
+'-A DIR'
+     Override the location where the installed Autoconf data files are
+     looked for.  You can also set the 'AC_MACRODIR' environment
+     variable to a directory; this option overrides the environment
+     variable.
+
+     This option is rarely needed and dangerous; it is only used when
+     one plays with different versions of Autoconf simultaneously.
+
+'--localdir=DIR'
+'-l DIR'
+     Look for the package file 'aclocal.m4' in directory DIR instead of
+     in the current directory.
+
+
+File: autoconf.info,  Node: Obsolete Macros,  Next: Autoconf 1,  Prev: autoupdate Invocation,  Up: Obsolete Constructs
+
+15.4 Obsolete Macros
+====================
+
+Several macros are obsoleted in Autoconf, for various reasons (typically
+they failed to quote properly, couldn't be extended for more recent
+issues etc.).  They are still supported, but deprecated: their use
+should be avoided.
+
+   During the jump from Autoconf version 1 to version 2, most of the
+macros were renamed to use a more uniform and descriptive naming scheme,
+but their signature did not change.  *Note Macro Names::, for a
+description of the new naming scheme.  Below, there is just the mapping
+from old names to new names for these macros, the reader is invited to
+refer to the definition of the new macro for the signature and the
+description.
+
+ -- Macro: AC_ALLOCA
+     'AC_FUNC_ALLOCA'
+
+ -- Macro: AC_ARG_ARRAY
+     removed because of limited usefulness
+
+ -- Macro: AC_C_CROSS
+     This macro is obsolete; it does nothing.
+
+ -- Macro: AC_CANONICAL_SYSTEM
+     Determine the system type and set output variables to the names of
+     the canonical system types.  *Note Canonicalizing::, for details
+     about the variables this macro sets.
+
+     The user is encouraged to use either 'AC_CANONICAL_BUILD', or
+     'AC_CANONICAL_HOST', or 'AC_CANONICAL_TARGET', depending on the
+     needs.  Using 'AC_CANONICAL_TARGET' is enough to run the two other
+     macros.
+
+ -- Macro: AC_CHAR_UNSIGNED
+     'AC_C_CHAR_UNSIGNED'
+
+ -- Macro: AC_CHECK_TYPE (TYPE, DEFAULT)
+     Autoconf, up to 2.13, used to provide this version of
+     'AC_CHECK_TYPE', deprecated because of its flaws.  Firstly,
+     although it is a member of the 'CHECK' clan, singular sub-family,
+     it does more than just checking.  Second, missing types are not
+     'typedef''d, they are '#define''d, which can lead to incompatible
+     code in the case of pointer types.
+
+     This use of 'AC_CHECK_TYPE' is obsolete and discouraged, see *note
+     Generic Types::, for the description of the current macro.
+
+     If the type TYPE is not defined, define it to be the C (or C++)
+     builtin type DEFAULT; e.g., 'short' or 'unsigned'.
+
+     This macro is equivalent to:
+
+          AC_CHECK_TYPE([TYPE],
+                        [AC_DEFINE([TYPE], [DEFAULT],
+                                   [Define to `DEFAULT' if <sys/types.h>
+                                    does not define.])])
+
+     In order to keep backward compatibility, the two versions of
+     'AC_CHECK_TYPE' are implemented, selected by a simple heuristics:
+
+       1. If there are three or four arguments, the modern version is
+          used.
+
+       2. If the second argument appears to be a C or C++ type, then the
+          obsolete version is used.  This happens if the argument is a C
+          or C++ _builtin_ type or a C identifier ending in '_t',
+          optionally followed by one of '[(* ' and then by a string of
+          zero or more characters taken from the set '[]()* _a-zA-Z0-9'.
+
+       3. If the second argument is spelled with the alphabet of valid C
+          and C++ types, the user is warned and the modern version is
+          used.
+
+       4. Otherwise, the modern version is used.
+
+     You are encouraged either to use a valid builtin type, or to use
+     the equivalent modern code (see above), or better yet, to use
+     'AC_CHECK_TYPES' together with
+
+          #if !HAVE_LOFF_T
+          typedef loff_t off_t;
+          #endif
+
+ -- Macro: AC_CHECKING (FEATURE-DESCRIPTION)
+     Same as 'AC_MSG_NOTICE([checking FEATURE-DESCRIPTION...]'.
+
+ -- Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY,
+          ACTION-IF-FOUND, [ACTION-IF-NOT-FOUND])
+     This is an obsolete version of 'AC_TRY_LINK' (*note Examining
+     Libraries::), with the addition that it prints 'checking for
+     ECHO-TEXT' to the standard output first, if ECHO-TEXT is non-empty.
+     Use 'AC_MSG_CHECKING' and 'AC_MSG_RESULT' instead to print messages
+     (*note Printing Messages::).
+
+ -- Macro: AC_CONST
+     'AC_C_CONST'
+
+ -- Macro: AC_CROSS_CHECK
+     Same as 'AC_C_CROSS', which is obsolete too, and does nothing
+     ':-)'.
+
+ -- Macro: AC_CYGWIN
+     Check for the Cygwin environment in which case the shell variable
+     'CYGWIN' is set to 'yes'.  Don't use this macro, the dignified
+     means to check the nature of the host is using 'AC_CANONICAL_HOST'.
+     As a matter of fact this macro is defined as:
+
+          AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
+          case $host_os in
+            *cygwin* ) CYGWIN=yes;;
+                   * ) CYGWIN=no;;
+          esac
+
+     Beware that the variable 'CYGWIN' has a very special meaning when
+     running CygWin32, and should not be changed.  That's yet another
+     reason not to use this macro.
+
+ -- Macro: AC_DECL_YYTEXT
+     Does nothing, now integrated in 'AC_PROG_LEX'.
+
+ -- Macro: AC_DIR_HEADER
+     Like calling 'AC_FUNC_CLOSEDIR_VOID' and'AC_HEADER_DIRENT', but
+     defines a different set of C preprocessor macros to indicate which
+     header file is found:
+
+     Header         Old Symbol   New Symbol
+     'dirent.h'     'DIRENT'     'HAVE_DIRENT_H'
+     'sys/ndir.h'   'SYSNDIR'    'HAVE_SYS_NDIR_H'
+     'sys/dir.h'    'SYSDIR'     'HAVE_SYS_DIR_H'
+     'ndir.h'       'NDIR'       'HAVE_NDIR_H'
+
+ -- Macro: AC_DYNIX_SEQ
+     If on Dynix/PTX (Sequent UNIX), add '-lseq' to output variable
+     'LIBS'.  This macro used to be defined as
+
+          AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
+
+     now it is just 'AC_FUNC_GETMNTENT'.
+
+ -- Macro: AC_EXEEXT
+     Defined the output variable 'EXEEXT' based on the output of the
+     compiler, which is now done automatically.  Typically set to empty
+     string if Unix and '.exe' if Win32 or OS/2.
+
+ -- Macro: AC_EMXOS2
+     Similar to 'AC_CYGWIN' but checks for the EMX environment on OS/2
+     and sets 'EMXOS2'.
+
+ -- Macro: AC_ERROR
+     'AC_MSG_ERROR'
+
+ -- Macro: AC_FIND_X
+     'AC_PATH_X'
+
+ -- Macro: AC_FIND_XTRA
+     'AC_PATH_XTRA'
+
+ -- Macro: AC_FUNC_CHECK
+     'AC_CHECK_FUNC'
+
+ -- Macro: AC_FUNC_WAIT3
+     If 'wait3' is found and fills in the contents of its third argument
+     (a 'struct rusage *'), which HP-UX does not do, define
+     'HAVE_WAIT3'.
+
+     These days portable programs should use 'waitpid', not 'wait3', as
+     'wait3' is being removed from the Open Group standards, and will
+     not appear in the next revision of POSIX.
+
+ -- Macro: AC_GCC_TRADITIONAL
+     'AC_PROG_GCC_TRADITIONAL'
+
+ -- Macro: AC_GETGROUPS_T
+     'AC_TYPE_GETGROUPS'
+
+ -- Macro: AC_GETLOADAVG
+     'AC_FUNC_GETLOADAVG'
+
+ -- Macro: AC_HAVE_FUNCS
+     'AC_CHECK_FUNCS'
+
+ -- Macro: AC_HAVE_HEADERS
+     'AC_CHECK_HEADERS'
+
+ -- Macro: AC_HAVE_LIBRARY (LIBRARY, [ACTION-IF-FOUND],
+          [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES])
+     This macro is equivalent to calling 'AC_CHECK_LIB' with a FUNCTION
+     argument of 'main'.  In addition, LIBRARY can be written as any of
+     'foo', '-lfoo', or 'libfoo.a'.  In all of those cases, the compiler
+     is passed '-lfoo'.  However, LIBRARY cannot be a shell variable; it
+     must be a literal name.
+
+ -- Macro: AC_HAVE_POUNDBANG
+     'AC_SYS_INTERPRETER' (different calling convention)
+
+ -- Macro: AC_HEADER_CHECK
+     'AC_CHECK_HEADER'
+
+ -- Macro: AC_HEADER_EGREP
+     'AC_EGREP_HEADER'
+
+ -- Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR)
+     Formerly 'AC_INIT' used to have a single argument, and was
+     equivalent to:
+
+          AC_INIT
+          AC_CONFIG_SRCDIR(UNIQUE-FILE-IN-SOURCE-DIR)
+
+ -- Macro: AC_INLINE
+     'AC_C_INLINE'
+
+ -- Macro: AC_INT_16_BITS
+     If the C type 'int' is 16 bits wide, define 'INT_16_BITS'.  Use
+     'AC_CHECK_SIZEOF(int)' instead.
+
+ -- Macro: AC_IRIX_SUN
+     If on IRIX (Silicon Graphics UNIX), add '-lsun' to output 'LIBS'.
+     If you were using it to get 'getmntent', use 'AC_FUNC_GETMNTENT'
+     instead.  If you used it for the NIS versions of the password and
+     group functions, use 'AC_CHECK_LIB(sun, getpwnam)'.  Up to Autoconf
+     2.13, it used to be
+
+          AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
+
+     now it is defined as
+
+          AC_FUNC_GETMNTENT
+          AC_CHECK_LIB(sun, getpwnam)
+
+ -- Macro: AC_LANG_C
+     Same as 'AC_LANG(C)'.
+
+ -- Macro: AC_LANG_CPLUSPLUS
+     Same as 'AC_LANG(C++)'.
+
+ -- Macro: AC_LANG_FORTRAN77
+     Same as 'AC_LANG(Fortran 77)'.
+
+ -- Macro: AC_LANG_RESTORE
+     Select the LANGUAGE that is saved on the top of the stack, as set
+     by 'AC_LANG_SAVE', remove it from the stack, and call
+     'AC_LANG(LANGUAGE)'.
+
+ -- Macro: AC_LANG_SAVE
+     Remember the current language (as set by 'AC_LANG') on a stack.
+     The current language does not change.  'AC_LANG_PUSH' is preferred.
+
+ -- Macro: AC_LINK_FILES (SOURCE..., DEST...)
+     This is an obsolete version of 'AC_CONFIG_LINKS'.  An updated
+     version of:
+
+          AC_LINK_FILES(config/$machine.h config/$obj_format.h,
+                        host.h            object.h)
+
+     is:
+
+          AC_CONFIG_LINKS(host.h:config/$machine.h
+                          object.h:config/$obj_format.h)
+
+ -- Macro: AC_LN_S
+     'AC_PROG_LN_S'
+
+ -- Macro: AC_LONG_64_BITS
+     Define 'LONG_64_BITS' if the C type 'long int' is 64 bits wide.
+     Use the generic macro 'AC_CHECK_SIZEOF([long int])' instead.
+
+ -- Macro: AC_LONG_DOUBLE
+     'AC_C_LONG_DOUBLE'
+
+ -- Macro: AC_LONG_FILE_NAMES
+     'AC_SYS_LONG_FILE_NAMES'
+
+ -- Macro: AC_MAJOR_HEADER
+     'AC_HEADER_MAJOR'
+
+ -- Macro: AC_MEMORY_H
+     Used to define 'NEED_MEMORY_H' if the 'mem' functions were defined
+     in 'memory.h'.  Today it is equivalent to
+     'AC_CHECK_HEADERS(memory.h)'.  Adjust your code to depend upon
+     'HAVE_MEMORY_H', not 'NEED_MEMORY_H', see *Note Standard Symbols::.
+
+ -- Macro: AC_MINGW32
+     Similar to 'AC_CYGWIN' but checks for the MingW32 compiler
+     environment and sets 'MINGW32'.
+
+ -- Macro: AC_MINUS_C_MINUS_O
+     'AC_PROG_CC_C_O'
+
+ -- Macro: AC_MMAP
+     'AC_FUNC_MMAP'
+
+ -- Macro: AC_MODE_T
+     'AC_TYPE_MODE_T'
+
+ -- Macro: AC_OBJEXT
+     Defined the output variable 'OBJEXT' based on the output of the
+     compiler, after .c files have been excluded.  Typically set to 'o'
+     if Unix, 'obj' if Win32.  Now the compiler checking macros handle
+     this automatically.
+
+ -- Macro: AC_OBSOLETE (THIS-MACRO-NAME, [SUGGESTION])
+     Make 'm4' print a message to the standard error output warning that
+     THIS-MACRO-NAME is obsolete, and giving the file and line number
+     where it was called.  THIS-MACRO-NAME should be the name of the
+     macro that is calling 'AC_OBSOLETE'.  If SUGGESTION is given, it is
+     printed at the end of the warning message; for example, it can be a
+     suggestion for what to use instead of THIS-MACRO-NAME.
+
+     For instance
+
+          AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
+
+     You are encouraged to use 'AU_DEFUN' instead, since it gives better
+     services to the user.
+
+ -- Macro: AC_OFF_T
+     'AC_TYPE_OFF_T'
+
+ -- Macro: AC_OUTPUT ([FILE]..., [EXTRA-CMDS], [INIT-CMDS], [SAVE-DEFS])
+     The use of 'AC_OUTPUT' with argument is deprecated, this obsoleted
+     interface is equivalent to:
+
+          AC_CONFIG_FILES(FILE...)
+          AC_CONFIG_COMMANDS([default],
+                             EXTRA-CMDS, INIT-CMDS)
+          AC_SETUP_DEFS(SAVE-DEFS)
+          AC_OUTPUT
+
+     If you specify SAVE-DEFS, autoconf will save the '#define's in a
+     different form, for use in the files specified in
+     'AC_CONFIG_HEADERS'.  In this case, autoconf substitutes the
+     C-style '#define's where it finds '@DEFS@'.  This runs faster, and
+     is simpler to maintain than building a file of '#undef's, since
+     autoconf will automatically generate a '#define' for each
+     'AC_DEFINE' that you execute in the 'configure' script.  The value
+     for SAVE-DEFS should be either 'cat', or 'sort'; this value is used
+     to filter the list of '#define's before editing.  Sorted lists are
+     easier to read, but you may wish to see the definitions in the
+     order that they were processed.
+
+ -- Macro: AC_OUTPUT_COMMANDS (EXTRA-CMDS, [INIT-CMDS])
+     Specify additional shell commands to run at the end of
+     'config.status', and shell commands to initialize any variables
+     from 'configure'.  This macro may be called multiple times.  It is
+     obsolete, replaced by 'AC_CONFIG_COMMANDS'.
+
+     Here is an unrealistic example:
+
+          fubar=27
+          AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
+                             fubar=$fubar)
+          AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
+                             [echo init bit])
+
+     Aside from the fact that 'AC_CONFIG_COMMANDS' requires an
+     additional key, an important difference is that
+     'AC_OUTPUT_COMMANDS' is quoting its arguments twice, while
+     'AC_CONFIG_COMMANDS'.  This means that 'AC_CONFIG_COMMANDS' can
+     safely be given macro calls as arguments:
+
+          AC_CONFIG_COMMANDS(foo, [my_FOO()])
+
+     conversely, where one level of quoting was enough for literal
+     strings with 'AC_OUTPUT_COMMANDS', you need two with
+     'AC_CONFIG_COMMANDS'.  The following lines are equivalent:
+
+          AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
+          AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]])
+
+ -- Macro: AC_PID_T
+     'AC_TYPE_PID_T'
+
+ -- Macro: AC_PREFIX
+     'AC_PREFIX_PROGRAM'
+
+ -- Macro: AC_PROGRAMS_CHECK
+     'AC_CHECK_PROGS'
+
+ -- Macro: AC_PROGRAMS_PATH
+     'AC_PATH_PROGS'
+
+ -- Macro: AC_PROGRAM_CHECK
+     'AC_CHECK_PROG'
+
+ -- Macro: AC_PROGRAM_EGREP
+     'AC_EGREP_CPP'
+
+ -- Macro: AC_PROGRAM_PATH
+     'AC_PATH_PROG'
+
+ -- Macro: AC_REMOTE_TAPE
+     removed because of limited usefulness
+
+ -- Macro: AC_RESTARTABLE_SYSCALLS
+     'AC_SYS_RESTARTABLE_SYSCALLS'
+
+ -- Macro: AC_RETSIGTYPE
+     'AC_TYPE_SIGNAL'
+
+ -- Macro: AC_RSH
+     Removed because of limited usefulness.
+
+ -- Macro: AC_SCO_INTL
+     If on SCO UNIX, add '-lintl' to output variable 'LIBS'.  This macro
+     used to
+
+          AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
+
+     now it just calls 'AC_FUNC_STRFTIME' instead.
+
+ -- Macro: AC_SETVBUF_REVERSED
+     'AC_FUNC_SETVBUF_REVERSED'
+
+ -- Macro: AC_SET_MAKE
+     'AC_PROG_MAKE_SET'
+
+ -- Macro: AC_SIZEOF_TYPE
+     'AC_CHECK_SIZEOF'
+
+ -- Macro: AC_SIZE_T
+     'AC_TYPE_SIZE_T'
+
+ -- Macro: AC_STAT_MACROS_BROKEN
+     'AC_HEADER_STAT'
+
+ -- Macro: AC_STDC_HEADERS
+     'AC_HEADER_STDC'
+
+ -- Macro: AC_STRCOLL
+     'AC_FUNC_STRCOLL'
+
+ -- Macro: AC_ST_BLKSIZE
+     'AC_STRUCT_ST_BLKSIZE'
+
+ -- Macro: AC_ST_BLOCKS
+     'AC_STRUCT_ST_BLOCKS'
+
+ -- Macro: AC_ST_RDEV
+     'AC_STRUCT_ST_RDEV'
+
+ -- Macro: AC_SYS_RESTARTABLE_SYSCALLS
+     If the system automatically restarts a system call that is
+     interrupted by a signal, define 'HAVE_RESTARTABLE_SYSCALLS'.  This
+     macro does not check if system calls are restarted in general-it
+     tests whether a signal handler installed with 'signal' (but not
+     'sigaction') causes system calls to be restarted.  It does not test
+     if system calls can be restarted when interrupted by signals that
+     have no handler.
+
+     These days portable programs should use 'sigaction' with
+     'SA_RESTART' if they want restartable system calls.  They should
+     not rely on 'HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a
+     system call is restartable is a dynamic issue, not a
+     configuration-time issue.
+
+ -- Macro: AC_SYS_SIGLIST_DECLARED
+     'AC_DECL_SYS_SIGLIST'
+
+ -- Macro: AC_TEST_CPP
+     'AC_TRY_CPP'
+
+ -- Macro: AC_TEST_PROGRAM
+     'AC_TRY_RUN'
+
+ -- Macro: AC_TIMEZONE
+     'AC_STRUCT_TIMEZONE'
+
+ -- Macro: AC_TIME_WITH_SYS_TIME
+     'AC_HEADER_TIME'
+
+ -- Macro: AC_UID_T
+     'AC_TYPE_UID_T'
+
+ -- Macro: AC_UNISTD_H
+     Same as 'AC_CHECK_HEADERS(unistd.h)'.
+
+ -- Macro: AC_USG
+     Define 'USG' if the BSD string functions are defined in
+     'strings.h'.  You should no longer depend upon 'USG', but on
+     'HAVE_STRING_H', see *Note Standard Symbols::.
+
+ -- Macro: AC_UTIME_NULL
+     'AC_FUNC_UTIME_NULL'
+
+ -- Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([CMD])
+     If the cache file is inconsistent with the current host, target and
+     build system types, it used to execute CMD or print a default error
+     message.
+
+     This is now handled by default.
+
+ -- Macro: AC_VERBOSE (RESULT-DESCRIPTION)
+     'AC_MSG_RESULT'.
+
+ -- Macro: AC_VFORK
+     'AC_FUNC_VFORK'
+
+ -- Macro: AC_VPRINTF
+     'AC_FUNC_VPRINTF'
+
+ -- Macro: AC_WAIT3
+     'AC_FUNC_WAIT3'
+
+ -- Macro: AC_WARN
+     'AC_MSG_WARN'
+
+ -- Macro: AC_WORDS_BIGENDIAN
+     'AC_C_BIGENDIAN'
+
+ -- Macro: AC_XENIX_DIR
+     This macro used to add '-lx' to output variable 'LIBS' if on Xenix.
+     Also, if 'dirent.h' is being checked for, added '-ldir' to 'LIBS'.
+     Now it is merely an alias of 'AC_HEADER_DIRENT' instead, plus some
+     code to detect whether running XENIX on which you should not
+     depend:
+
+          AC_MSG_CHECKING([for Xenix])
+          AC_EGREP_CPP(yes,
+          [#if defined M_XENIX && !defined M_UNIX
+            yes
+          #endif],
+                       [AC_MSG_RESULT([yes]); XENIX=yes],
+                       [AC_MSG_RESULT([no]); XENIX=])
+
+ -- Macro: AC_YYTEXT_POINTER
+     'AC_DECL_YYTEXT'
+
+
+File: autoconf.info,  Node: Autoconf 1,  Next: Autoconf 2.13,  Prev: Obsolete Macros,  Up: Obsolete Constructs
+
+15.5 Upgrading From Version 1
+=============================
+
+Autoconf version 2 is mostly backward compatible with version 1.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 1.  So, depending on how
+sophisticated your 'configure.ac' files are, you might have to do some
+manual work in order to upgrade to version 2.  This chapter points out
+some problems to watch for when upgrading.  Also, perhaps your
+'configure' scripts could benefit from some of the new features in
+version 2; the changes are summarized in the file 'NEWS' in the Autoconf
+distribution.
+
+* Menu:
+
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in 'Makefile.in'
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+
+
+File: autoconf.info,  Node: Changed File Names,  Next: Changed Makefiles,  Prev: Autoconf 1,  Up: Autoconf 1
+
+15.5.1 Changed File Names
+-------------------------
+
+If you have an 'aclocal.m4' installed with Autoconf (as opposed to in a
+particular package's source directory), you must rename it to
+'acsite.m4'.  *Note autoconf Invocation::.
+
+   If you distribute 'install.sh' with your package, rename it to
+'install-sh' so 'make' builtin rules won't inadvertently create a file
+called 'install' from it.  'AC_PROG_INSTALL' looks for the script under
+both names, but it is best to use the new name.
+
+   If you were using 'config.h.top', 'config.h.bot', or 'acconfig.h',
+you still can, but you will have less clutter if you use the 'AH_'
+macros.  *Note Autoheader Macros::.
+
+
+File: autoconf.info,  Node: Changed Makefiles,  Next: Changed Macros,  Prev: Changed File Names,  Up: Autoconf 1
+
+15.5.2 Changed Makefiles
+------------------------
+
+Add '@CFLAGS@', '@CPPFLAGS@', and '@LDFLAGS@' in your 'Makefile.in'
+files, so they can take advantage of the values of those variables in
+the environment when 'configure' is run.  Doing this isn't necessary,
+but it's a convenience for users.
+
+   Also add '@configure_input@' in a comment to each input file for
+'AC_OUTPUT', so that the output files will contain a comment saying they
+were produced by 'configure'.  Automatically selecting the right comment
+syntax for all the kinds of files that people call 'AC_OUTPUT' on became
+too much work.
+
+   Add 'config.log' and 'config.cache' to the list of files you remove
+in 'distclean' targets.
+
+   If you have the following in 'Makefile.in':
+
+     prefix = /usr/local
+     exec_prefix = $(prefix)
+
+you must change it to:
+
+     prefix = @prefix@
+     exec_prefix = @exec_prefix@
+
+The old behavior of replacing those variables without '@' characters
+around them has been removed.
+
+
+File: autoconf.info,  Node: Changed Macros,  Next: Changed Results,  Prev: Changed Makefiles,  Up: Autoconf 1
+
+15.5.3 Changed Macros
+---------------------
+
+Many of the macros were renamed in Autoconf version 2.  You can still
+use the old names, but the new ones are clearer, and it's easier to find
+the documentation for them.  *Note Obsolete Macros::, for a table
+showing the new names for the old macros.  Use the 'autoupdate' program
+to convert your 'configure.ac' to using the new macro names.  *Note
+autoupdate Invocation::.
+
+   Some macros have been superseded by similar ones that do the job
+better, but are not call-compatible.  If you get warnings about calling
+obsolete macros while running 'autoconf', you may safely ignore them,
+but your 'configure' script will generally work better if you follow the
+advice it prints about what to replace the obsolete macros with.  In
+particular, the mechanism for reporting the results of tests has
+changed.  If you were using 'echo' or 'AC_VERBOSE' (perhaps via
+'AC_COMPILE_CHECK'), your 'configure' script's output will look better
+if you switch to 'AC_MSG_CHECKING' and 'AC_MSG_RESULT'.  *Note Printing
+Messages::.  Those macros work best in conjunction with cache variables.
+*Note Caching Results::.
+
+
+File: autoconf.info,  Node: Changed Results,  Next: Changed Macro Writing,  Prev: Changed Macros,  Up: Autoconf 1
+
+15.5.4 Changed Results
+----------------------
+
+If you were checking the results of previous tests by examining the
+shell variable 'DEFS', you need to switch to checking the values of the
+cache variables for those tests.  'DEFS' no longer exists while
+'configure' is running; it is only created when generating output files.
+This difference from version 1 is because properly quoting the contents
+of that variable turned out to be too cumbersome and inefficient to do
+every time 'AC_DEFINE' is called.  *Note Cache Variable Names::.
+
+   For example, here is a 'configure.ac' fragment written for Autoconf
+version 1:
+
+     AC_HAVE_FUNCS(syslog)
+     case "$DEFS" in
+     *-DHAVE_SYSLOG*) ;;
+     *) # syslog is not in the default libraries.  See if it's in some other.
+       saved_LIBS="$LIBS"
+       for lib in bsd socket inet; do
+         AC_CHECKING(for syslog in -l$lib)
+         LIBS="$saved_LIBS -l$lib"
+         AC_HAVE_FUNCS(syslog)
+         case "$DEFS" in
+         *-DHAVE_SYSLOG*) break ;;
+         *) ;;
+         esac
+         LIBS="$saved_LIBS"
+       done ;;
+     esac
+
+   Here is a way to write it for version 2:
+
+     AC_CHECK_FUNCS(syslog)
+     if test $ac_cv_func_syslog = no; then
+       # syslog is not in the default libraries.  See if it's in some other.
+       for lib in bsd socket inet; do
+         AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
+           LIBS="$LIBS -l$lib"; break])
+       done
+     fi
+
+   If you were working around bugs in 'AC_DEFINE_UNQUOTED' by adding
+backslashes before quotes, you need to remove them.  It now works
+predictably, and does not treat quotes (except back quotes) specially.
+*Note Setting Output Variables::.
+
+   All of the boolean shell variables set by Autoconf macros now use
+'yes' for the true value.  Most of them use 'no' for false, though for
+backward compatibility some use the empty string instead.  If you were
+relying on a shell variable being set to something like 1 or 't' for
+true, you need to change your tests.
+
+
+File: autoconf.info,  Node: Changed Macro Writing,  Prev: Changed Results,  Up: Autoconf 1
+
+15.5.5 Changed Macro Writing
+----------------------------
+
+When defining your own macros, you should now use 'AC_DEFUN' instead of
+'define'.  'AC_DEFUN' automatically calls 'AC_PROVIDE' and ensures that
+macros called via 'AC_REQUIRE' do not interrupt other macros, to prevent
+nested 'checking...' messages on the screen.  There's no actual harm in
+continuing to use the older way, but it's less convenient and
+attractive.  *Note Macro Definitions::.
+
+   You probably looked at the macros that came with Autoconf as a guide
+for how to do things.  It would be a good idea to take a look at the new
+versions of them, as the style is somewhat improved and they take
+advantage of some new features.
+
+   If you were doing tricky things with undocumented Autoconf internals
+(macros, variables, diversions), check whether you need to change
+anything to account for changes that have been made.  Perhaps you can
+even use an officially supported technique in version 2 instead of
+kludging.  Or perhaps not.
+
+   To speed up your locally written feature tests, add caching to them.
+See whether any of your tests are of general enough usefulness to
+encapsulate into macros that you can share.
+
+
+File: autoconf.info,  Node: Autoconf 2.13,  Prev: Autoconf 1,  Up: Obsolete Constructs
+
+15.6 Upgrading From Version 2.13
+================================
+
+The introduction of the previous section (*note Autoconf 1::) perfectly
+suits this section...
+
+     Autoconf version 2.50 is mostly backward compatible with version
+     2.13.  However, it introduces better ways to do some things, and
+     doesn't support some of the ugly things in version 2.13.  So,
+     depending on how sophisticated your 'configure.ac' files are, you
+     might have to do some manual work in order to upgrade to version
+     2.50.  This chapter points out some problems to watch for when
+     upgrading.  Also, perhaps your 'configure' scripts could benefit
+     from some of the new features in version 2.50; the changes are
+     summarized in the file 'NEWS' in the Autoconf distribution.
+
+* Menu:
+
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+
+
+File: autoconf.info,  Node: Changed Quotation,  Next: New Macros,  Prev: Autoconf 2.13,  Up: Autoconf 2.13
+
+15.6.1 Changed Quotation
+------------------------
+
+The most important changes are invisible to you: the implementation of
+most macros have completely changed.  This allowed more factorization of
+the code, better error messages, a higher uniformity of the user's
+interface etc.  Unfortunately, as a side effect, some construct which
+used to (miraculously) work might break starting with Autoconf 2.50.
+The most common culprit is bad quotation.
+
+   For instance, in the following example, the message is not properly
+quoted:
+
+     AC_INIT
+     AC_CHECK_HEADERS(foo.h,,
+     AC_MSG_ERROR(cannot find foo.h, bailing out))
+     AC_OUTPUT
+
+Autoconf 2.13 simply ignores it:
+
+     $ autoconf-2.13; ./configure --silent
+     creating cache ./config.cache
+     configure: error: cannot find foo.h
+     $
+
+while Autoconf 2.50 will produce a broken 'configure':
+
+     $ autoconf-2.50; ./configure --silent
+     configure: error: cannot find foo.h
+     ./configure: exit: bad non-numeric arg `bailing'
+     ./configure: exit: bad non-numeric arg `bailing'
+     $
+
+   The message needs to be quoted, and the 'AC_MSG_ERROR' invocation
+too!
+
+     AC_INIT
+     AC_CHECK_HEADERS(foo.h,,
+                      [AC_MSG_ERROR([cannot find foo.h, bailing out])])
+     AC_OUTPUT
+
+   Many many (and many more) Autoconf macros were lacking proper
+quotation, including no less than...  'AC_DEFUN' itself!
+
+     $ cat configure.in
+     AC_DEFUN([AC_PROG_INSTALL],
+     [# My own much better version
+     ])
+     AC_INIT
+     AC_PROG_INSTALL
+     AC_OUTPUT
+     $ autoconf-2.13
+     autoconf: Undefined macros:
+     ***BUG in Autoconf--please report*** AC_FD_MSG
+     ***BUG in Autoconf--please report*** AC_EPI
+     configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
+     configure.in:5:AC_PROG_INSTALL
+     $ autoconf-2.50
+     $
+
+
+File: autoconf.info,  Node: New Macros,  Prev: Changed Quotation,  Up: Autoconf 2.13
+
+15.6.2 New Macros
+-----------------
+
+Because Autoconf has been dormant for years, Automake provided
+Autoconf-like macros for a while.  Autoconf 2.50 now provides better
+versions of these macros, integrated in the 'AC_' namespace, instead of
+'AM_'.  But in order to ease the upgrading via 'autoupdate', bindings to
+such 'AM_' macros are provided.
+
+   Unfortunately Automake did not quote the name of these macros!
+Therefore, when 'm4' find in 'aclocal.m4' something like
+'AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)', 'AM_TYPE_PTRDIFF_T' is expanded,
+replaced with its Autoconf definition.
+
+   Fortunately Autoconf catches pre-'AC_INIT' expansions, and will
+complain, in its own words:
+
+     $ cat configure.in
+     AC_INIT
+     AM_TYPE_PTRDIFF_T
+     $ aclocal-1.4
+     $ autoconf
+     ./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
+     actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
+     ./aclocal.m4:17: the top level
+     $
+
+   Future versions of Automake will simply no longer define most of
+these macros, and will properly quote the names of the remaining macros.
+But you don't have to wait for it to happen to do the right thing right
+now: do not depend upon macros from Automake as it is simply not its job
+to provide macros (but the one it requires by itself):
+
+     $ cat configure.in
+     AC_INIT
+     AM_TYPE_PTRDIFF_T
+     $ rm aclocal.m4
+     $ autoupdate
+     autoupdate: `configure.in' is updated
+     $ cat configure.in
+     AC_INIT
+     AC_CHECK_TYPES([ptrdiff_t])
+     $ aclocal-1.4
+     $ autoconf
+     $
+
+
+File: autoconf.info,  Node: Questions,  Next: History,  Prev: Obsolete Constructs,  Up: Top
+
+16 Questions About Autoconf
+***************************
+
+Several questions about Autoconf come up occasionally.  Here some of
+them are addressed.
+
+* Menu:
+
+* Distributing::                Distributing 'configure' scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses 'configure' instead of Imake
+
+
+File: autoconf.info,  Node: Distributing,  Next: Why GNU m4,  Prev: Questions,  Up: Questions
+
+16.1 Distributing 'configure' Scripts
+=====================================
+
+     What are the restrictions on distributing 'configure'
+     scripts that Autoconf generates?  How does that affect my
+     programs that use them?
+
+   There are no restrictions on how the configuration scripts that
+Autoconf produces may be distributed or used.  In Autoconf version 1,
+they were covered by the GNU General Public License.  We still encourage
+software authors to distribute their work under terms like those of the
+GPL, but doing so is not required to use Autoconf.
+
+   Of the other files that might be used with 'configure', 'config.h.in'
+is under whatever copyright you use for your 'configure.ac'.
+'config.sub' and 'config.guess' have an exception to the GPL when they
+are used with an Autoconf-generated 'configure' script, which permits
+you to distribute them under the same terms as the rest of your package.
+'install-sh' is from the X Consortium and is not copyrighted.
+
+
+File: autoconf.info,  Node: Why GNU m4,  Next: Bootstrapping,  Prev: Distributing,  Up: Questions
+
+16.2 Why Require GNU M4?
+========================
+
+     Why does Autoconf require GNU M4?
+
+   Many M4 implementations have hard-coded limitations on the size and
+number of macros that Autoconf exceeds.  They also lack several builtin
+macros that it would be difficult to get along without in a
+sophisticated application like Autoconf, including:
+
+     builtin
+     indir
+     patsubst
+     __file__
+     __line__
+
+   Autoconf requires version 1.4 or above of GNU M4 because it uses
+frozen state files.
+
+   Since only software maintainers need to use Autoconf, and since GNU
+M4 is simple to configure and install, it seems reasonable to require
+GNU M4 to be installed also.  Many maintainers of GNU and other free
+software already have most of the GNU utilities installed, since they
+prefer them.
+
+
+File: autoconf.info,  Node: Bootstrapping,  Next: Why Not Imake,  Prev: Why GNU m4,  Up: Questions
+
+16.3 How Can I Bootstrap?
+=========================
+
+     If Autoconf requires GNU M4 and GNU M4 has an Autoconf
+     'configure' script, how do I bootstrap?  It seems like a chicken
+     and egg problem!
+
+   This is a misunderstanding.  Although GNU M4 does come with a
+'configure' script produced by Autoconf, Autoconf is not required in
+order to run the script and install GNU M4.  Autoconf is only required
+if you want to change the M4 'configure' script, which few people have
+to do (mainly its maintainer).
+
+
+File: autoconf.info,  Node: Why Not Imake,  Prev: Bootstrapping,  Up: Questions
+
+16.4 Why Not Imake?
+===================
+
+     Why not use Imake instead of 'configure' scripts?
+
+   Several people have written addressing this question, so I include
+adaptations of their explanations here.
+
+   The following answer is based on one written by Richard Pixley:
+
+     Autoconf generated scripts frequently work on machines that it has
+     never been set up to handle before.  That is, it does a good job of
+     inferring a configuration for a new system.  Imake cannot do this.
+
+     Imake uses a common database of host specific data.  For X11, this
+     makes sense because the distribution is made as a collection of
+     tools, by one central authority who has control over the database.
+
+     GNU tools are not released this way.  Each GNU tool has a
+     maintainer; these maintainers are scattered across the world.
+     Using a common database would be a maintenance nightmare.  Autoconf
+     may appear to be this kind of database, but in fact it is not.
+     Instead of listing host dependencies, it lists program
+     requirements.
+
+     If you view the GNU suite as a collection of native tools, then the
+     problems are similar.  But the GNU development tools can be
+     configured as cross tools in almost any host+target permutation.
+     All of these configurations can be installed concurrently.  They
+     can even be configured to share host independent files across
+     hosts.  Imake doesn't address these issues.
+
+     Imake templates are a form of standardization.  The GNU coding
+     standards address the same issues without necessarily imposing the
+     same restrictions.
+
+   Here is some further explanation, written by Per Bothner:
+
+     One of the advantages of Imake is that it easy to generate large
+     Makefiles using 'cpp''s '#include' and macro mechanisms.  However,
+     'cpp' is not programmable: it has limited conditional facilities,
+     and no looping.  And 'cpp' cannot inspect its environment.
+
+     All of these problems are solved by using 'sh' instead of 'cpp'.
+     The shell is fully programmable, has macro substitution, can
+     execute (or source) other shell scripts, and can inspect its
+     environment.
+
+   Paul Eggert elaborates more:
+
+     With Autoconf, installers need not assume that Imake itself is
+     already installed and working well.  This may not seem like much of
+     an advantage to people who are accustomed to Imake.  But on many
+     hosts Imake is not installed or the default installation is not
+     working well, and requiring Imake to install a package hinders the
+     acceptance of that package on those hosts.  For example, the Imake
+     template and configuration files might not be installed properly on
+     a host, or the Imake build procedure might wrongly assume that all
+     source files are in one big directory tree, or the Imake
+     configuration might assume one compiler whereas the package or the
+     installer needs to use another, or there might be a version
+     mismatch between the Imake expected by the package and the Imake
+     supported by the host.  These problems are much rarer with
+     Autoconf, where each package comes with its own independent
+     configuration processor.
+
+     Also, Imake often suffers from unexpected interactions between
+     'make' and the installer's C preprocessor.  The fundamental problem
+     here is that the C preprocessor was designed to preprocess C
+     programs, not 'Makefile's.  This is much less of a problem with
+     Autoconf, which uses the general-purpose preprocessor 'm4', and
+     where the package's author (rather than the installer) does the
+     preprocessing in a standard way.
+
+   Finally, Mark Eichin notes:
+
+     Imake isn't all that extensible, either.  In order to add new
+     features to Imake, you need to provide your own project template,
+     and duplicate most of the features of the existing one.  This means
+     that for a sophisticated project, using the vendor-provided Imake
+     templates fails to provide any leverage--since they don't cover
+     anything that your own project needs (unless it is an X11 program).
+
+     On the other side, though:
+
+     The one advantage that Imake has over 'configure': 'Imakefile's
+     tend to be much shorter (likewise, less redundant) than
+     'Makefile.in's.  There is a fix to this, however--at least for the
+     Kerberos V5 tree, we've modified things to call in common 'post.in'
+     and 'pre.in' 'Makefile' fragments for the entire tree.  This means
+     that a lot of common things don't have to be duplicated, even
+     though they normally are in 'configure' setups.
+
+
+File: autoconf.info,  Node: History,  Next: Environment Variable Index,  Prev: Questions,  Up: Top
+
+17 History of Autoconf
+**********************
+
+You may be wondering, Why was Autoconf originally written?  How did it
+get into its present form?  (Why does it look like gorilla spit?)  If
+you're not wondering, then this chapter contains no information useful
+to you, and you might as well skip it.  If you _are_ wondering, then let
+there be light...
+
+* Menu:
+
+* Genesis::                     Prehistory and naming of 'configure'
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+
+
+File: autoconf.info,  Node: Genesis,  Next: Exodus,  Prev: History,  Up: History
+
+17.1 Genesis
+============
+
+In June 1991 I was maintaining many of the GNU utilities for the Free
+Software Foundation.  As they were ported to more platforms and more
+programs were added, the number of '-D' options that users had to select
+in the 'Makefile' (around 20) became burdensome.  Especially for me--I
+had to test each new release on a bunch of different systems.  So I
+wrote a little shell script to guess some of the correct settings for
+the fileutils package, and released it as part of fileutils 2.0.  That
+'configure' script worked well enough that the next month I adapted it
+(by hand) to create similar 'configure' scripts for several other GNU
+utilities packages.  Brian Berliner also adapted one of my scripts for
+his CVS revision control system.
+
+   Later that summer, I learned that Richard Stallman and Richard Pixley
+were developing similar scripts to use in the GNU compiler tools; so I
+adapted my 'configure' scripts to support their evolving interface:
+using the file name 'Makefile.in' as the templates; adding '+srcdir',
+the first option (of many); and creating 'config.status' files.
+
+
+File: autoconf.info,  Node: Exodus,  Next: Leviticus,  Prev: Genesis,  Up: History
+
+17.2 Exodus
+===========
+
+As I got feedback from users, I incorporated many improvements, using
+Emacs to search and replace, cut and paste, similar changes in each of
+the scripts.  As I adapted more GNU utilities packages to use
+'configure' scripts, updating them all by hand became impractical.  Rich
+Murphey, the maintainer of the GNU graphics utilities, sent me mail
+saying that the 'configure' scripts were great, and asking if I had a
+tool for generating them that I could send him.  No, I thought, but I
+should!  So I started to work out how to generate them.  And the journey
+from the slavery of hand-written 'configure' scripts to the abundance
+and ease of Autoconf began.
+
+   Cygnus 'configure', which was being developed at around that time, is
+table driven; it is meant to deal mainly with a discrete number of
+system types with a small number of mainly unguessable features (such as
+details of the object file format).  The automatic configuration system
+that Brian Fox had developed for Bash takes a similar approach.  For
+general use, it seems to me a hopeless cause to try to maintain an
+up-to-date database of which features each variant of each operating
+system has.  It's easier and more reliable to check for most features on
+the fly--especially on hybrid systems that people have hacked on locally
+or that have patches from vendors installed.
+
+   I considered using an architecture similar to that of Cygnus
+'configure', where there is a single 'configure' script that reads
+pieces of 'configure.in' when run.  But I didn't want to have to
+distribute all of the feature tests with every package, so I settled on
+having a different 'configure' made from each 'configure.in' by a
+preprocessor.  That approach also offered more control and flexibility.
+
+   I looked briefly into using the Metaconfig package, by Larry Wall,
+Harlan Stenn, and Raphael Manfredi, but I decided not to for several
+reasons.  The 'Configure' scripts it produces are interactive, which I
+find quite inconvenient; I didn't like the ways it checked for some
+features (such as library functions); I didn't know that it was still
+being maintained, and the 'Configure' scripts I had seen didn't work on
+many modern systems (such as System V R4 and NeXT); it wasn't very
+flexible in what it could do in response to a feature's presence or
+absence; I found it confusing to learn; and it was too big and complex
+for my needs (I didn't realize then how much Autoconf would eventually
+have to grow).
+
+   I considered using Perl to generate my style of 'configure' scripts,
+but decided that M4 was better suited to the job of simple textual
+substitutions: it gets in the way less, because output is implicit.
+Plus, everyone already has it.  (Initially I didn't rely on the GNU
+extensions to M4.)  Also, some of my friends at the University of
+Maryland had recently been putting M4 front ends on several programs,
+including 'tvtwm', and I was interested in trying out a new language.
+
+
+File: autoconf.info,  Node: Leviticus,  Next: Numbers,  Prev: Exodus,  Up: History
+
+17.3 Leviticus
+==============
+
+Since my 'configure' scripts determine the system's capabilities
+automatically, with no interactive user intervention, I decided to call
+the program that generates them Autoconfig.  But with a version number
+tacked on, that name would be too long for old UNIX file systems, so I
+shortened it to Autoconf.
+
+   In the fall of 1991 I called together a group of fellow questers
+after the Holy Grail of portability (er, that is, alpha testers) to give
+me feedback as I encapsulated pieces of my handwritten scripts in M4
+macros and continued to add features and improve the techniques used in
+the checks.  Prominent among the testers were François Pinard, who came
+up with the idea of making an 'autoconf' shell script to run 'm4' and
+check for unresolved macro calls; Richard Pixley, who suggested running
+the compiler instead of searching the file system to find include files
+and symbols, for more accurate results; Karl Berry, who got Autoconf to
+configure TeX and added the macro index to the documentation; and Ian
+Lance Taylor, who added support for creating a C header file as an
+alternative to putting '-D' options in a 'Makefile', so he could use
+Autoconf for his UUCP package.  The alpha testers cheerfully adjusted
+their files again and again as the names and calling conventions of the
+Autoconf macros changed from release to release.  They all contributed
+many specific checks, great ideas, and bug fixes.
+
+
+File: autoconf.info,  Node: Numbers,  Next: Deuteronomy,  Prev: Leviticus,  Up: History
+
+17.4 Numbers
+============
+
+In July 1992, after months of alpha testing, I released Autoconf 1.0,
+and converted many GNU packages to use it.  I was surprised by how
+positive the reaction to it was.  More people started using it than I
+could keep track of, including people working on software that wasn't
+part of the GNU Project (such as TCL, FSP, and Kerberos V5).  Autoconf
+continued to improve rapidly, as many people using the 'configure'
+scripts reported problems they encountered.
+
+   Autoconf turned out to be a good torture test for M4 implementations.
+UNIX 'm4' started to dump core because of the length of the macros that
+Autoconf defined, and several bugs showed up in GNU 'm4' as well.
+Eventually, we realized that we needed to use some features that only
+GNU M4 has.  4.3BSD 'm4', in particular, has an impoverished set of
+builtin macros; the System V version is better, but still doesn't
+provide everything we need.
+
+   More development occurred as people put Autoconf under more stresses
+(and to uses I hadn't anticipated).  Karl Berry added checks for X11.
+david zuhn contributed C++ support.  François Pinard made it diagnose
+invalid arguments.  Jim Blandy bravely coerced it into configuring GNU
+Emacs, laying the groundwork for several later improvements.  Roland
+McGrath got it to configure the GNU C Library, wrote the 'autoheader'
+script to automate the creation of C header file templates, and added a
+'--verbose' option to 'configure'.  Noah Friedman added the
+'--autoconf-dir' option and 'AC_MACRODIR' environment variable.  (He
+also coined the term "autoconfiscate" to mean "adapt a software package
+to use Autoconf".)  Roland and Noah improved the quoting protection in
+'AC_DEFINE' and fixed many bugs, especially when I got sick of dealing
+with portability problems from February through June, 1993.
+
+
+File: autoconf.info,  Node: Deuteronomy,  Prev: Numbers,  Up: History
+
+17.5 Deuteronomy
+================
+
+A long wish list for major features had accumulated, and the effect of
+several years of patching by various people had left some residual
+cruft.  In April 1994, while working for Cygnus Support, I began a major
+revision of Autoconf.  I added most of the features of the Cygnus
+'configure' that Autoconf had lacked, largely by adapting the relevant
+parts of Cygnus 'configure' with the help of david zuhn and Ken Raeburn.
+These features include support for using 'config.sub', 'config.guess',
+'--host', and '--target'; making links to files; and running 'configure'
+scripts in subdirectories.  Adding these features enabled Ken to convert
+GNU 'as', and Rob Savoye to convert DejaGNU, to using Autoconf.
+
+   I added more features in response to other peoples' requests.  Many
+people had asked for 'configure' scripts to share the results of the
+checks between runs, because (particularly when configuring a large
+source tree, like Cygnus does) they were frustratingly slow.  Mike
+Haertel suggested adding site-specific initialization scripts.  People
+distributing software that had to unpack on MS-DOS asked for a way to
+override the '.in' extension on the file names, which produced file
+names like 'config.h.in' containing two dots.  Jim Avera did an
+extensive examination of the problems with quoting in 'AC_DEFINE' and
+'AC_SUBST'; his insights led to significant improvements.  Richard
+Stallman asked that compiler output be sent to 'config.log' instead of
+'/dev/null', to help people debug the Emacs 'configure' script.
+
+   I made some other changes because of my dissatisfaction with the
+quality of the program.  I made the messages showing results of the
+checks less ambiguous, always printing a result.  I regularized the
+names of the macros and cleaned up coding style inconsistencies.  I
+added some auxiliary utilities that I had developed to help convert
+source code packages to use Autoconf.  With the help of François Pinard,
+I made the macros not interrupt each others' messages.  (That feature
+revealed some performance bottlenecks in GNU 'm4', which he hastily
+corrected!)  I reorganized the documentation around problems people want
+to solve.  And I began a test suite, because experience had shown that
+Autoconf has a pronounced tendency to regress when we change it.
+
+   Again, several alpha testers gave invaluable feedback, especially
+François Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, and
+Mark Eichin.
+
+   Finally, version 2.0 was ready.  And there was much rejoicing.  (And
+I have free time again.  I think.  Yeah, right.)
+
+
+File: autoconf.info,  Node: Environment Variable Index,  Next: Output Variable Index,  Prev: History,  Up: Top
+
+Environment Variable Index
+**************************
+
+This is an alphabetical list of the environment variables that Autoconf
+checks.
+
+
+* Menu:
+
+* AC_MACRODIR:                           autoscan Invocation.  (line 54)
+* AC_MACRODIR <1>:                       autoconf Invocation.  (line 45)
+* AC_MACRODIR <2>:                       autoreconf Invocation.
+                                                               (line 77)
+* AC_MACRODIR <3>:                       autoheader Invocation.
+                                                               (line 62)
+* AC_MACRODIR <4>:                       autoupdate Invocation.
+                                                               (line 42)
+* CDPATH:                                Special Shell Variables.
+                                                               (line 13)
+* CONFIG_COMMANDS:                       Obsolete config.status Use.
+                                                               (line 11)
+* CONFIG_FILES:                          Obsolete config.status Use.
+                                                               (line 15)
+* CONFIG_HEADERS:                        Obsolete config.status Use.
+                                                               (line 20)
+* CONFIG_LINKS:                          Obsolete config.status Use.
+                                                               (line 25)
+* CONFIG_SHELL:                          config.status Invocation.
+                                                               (line 75)
+* CONFIG_SITE:                           Site Defaults.        (line 10)
+* CONFIG_STATUS:                         config.status Invocation.
+                                                               (line 79)
+* IFS:                                   Special Shell Variables.
+                                                               (line 45)
+* LANG:                                  Special Shell Variables.
+                                                               (line 59)
+* LANGUAGE:                              Special Shell Variables.
+                                                               (line 59)
+* LC_ALL:                                Special Shell Variables.
+                                                               (line 59)
+* LC_COLLATE:                            Special Shell Variables.
+                                                               (line 59)
+* LC_CTYPE:                              Special Shell Variables.
+                                                               (line 59)
+* LC_MESSAGES:                           Special Shell Variables.
+                                                               (line 59)
+* LC_NUMERIC:                            Special Shell Variables.
+                                                               (line 59)
+* LC_TIME:                               Special Shell Variables.
+                                                               (line 59)
+* NULLCMD:                               Special Shell Variables.
+                                                               (line 77)
+* PATH_SEPARATOR:                        Special Shell Variables.
+                                                               (line 88)
+* RANDOM:                                Special Shell Variables.
+                                                               (line 97)
+* SIMPLE_BACKUP_SUFFIX:                  autoupdate Invocation.
+                                                               (line 16)
+* status:                                Special Shell Variables.
+                                                               (line 84)
+* WARNINGS:                              autoconf Invocation.  (line 65)
+* WARNINGS <1>:                          autoheader Invocation.
+                                                               (line 78)
+
+
+File: autoconf.info,  Node: Output Variable Index,  Next: Preprocessor Symbol Index,  Prev: Environment Variable Index,  Up: Top
+
+Output Variable Index
+*********************
+
+This is an alphabetical list of the variables that Autoconf can
+substitute into files that it creates, typically one or more
+'Makefile's.  *Note Setting Output Variables::, for more information on
+how this is done.
+
+
+* Menu:
+
+* ALLOCA:                                Particular Functions.
+                                                              (line  10)
+* AWK:                                   Particular Programs. (line  10)
+* bindir:                                Installation Directory Variables.
+                                                              (line  12)
+* build:                                 Canonicalizing.      (line  26)
+* build_alias:                           Canonicalizing.      (line   9)
+* build_cpu:                             Canonicalizing.      (line  26)
+* build_os:                              Canonicalizing.      (line  26)
+* build_vendor:                          Canonicalizing.      (line  26)
+* CC:                                    C Compiler.          (line   7)
+* CC <1>:                                C Compiler.          (line  34)
+* CC <2>:                                C Compiler.          (line 156)
+* CC <3>:                                System Services.     (line  44)
+* CC <4>:                                UNIX Variants.       (line  18)
+* CFLAGS:                                Preset Output Variables.
+                                                              (line  15)
+* CFLAGS <1>:                            C Compiler.          (line   7)
+* configure_input:                       Preset Output Variables.
+                                                              (line  22)
+* CPP:                                   C Compiler.          (line  47)
+* CPPFLAGS:                              Preset Output Variables.
+                                                              (line  36)
+* cross_compiling:                       Specifying Names.    (line  26)
+* CXX:                                   C++ Compiler.        (line   7)
+* CXXCPP:                                C++ Compiler.        (line  31)
+* CXXFLAGS:                              Preset Output Variables.
+                                                              (line  43)
+* CXXFLAGS <1>:                          C++ Compiler.        (line   7)
+* datadir:                               Installation Directory Variables.
+                                                              (line  15)
+* DEFS:                                  Preset Output Variables.
+                                                              (line  50)
+* ECHO_C:                                Preset Output Variables.
+                                                              (line  60)
+* ECHO_N:                                Preset Output Variables.
+                                                              (line  60)
+* ECHO_T:                                Preset Output Variables.
+                                                              (line  60)
+* EGREP:                                 Particular Programs. (line  16)
+* exec_prefix:                           Installation Directory Variables.
+                                                              (line  19)
+* EXEEXT:                                Compilers and Preprocessors.
+                                                              (line   6)
+* EXEEXT <1>:                            Obsolete Macros.     (line 145)
+* F77:                                   Fortran 77 Compiler. (line   7)
+* FFLAGS:                                Preset Output Variables.
+                                                              (line  72)
+* FFLAGS <1>:                            Fortran 77 Compiler. (line   7)
+* FGREP:                                 Particular Programs. (line  20)
+* FLIBS:                                 Fortran 77 Compiler. (line  38)
+* GETGROUPS_LIBS:                        Particular Functions.
+                                                              (line  97)
+* GETLOADAVG_LIBS:                       Particular Functions.
+                                                              (line 103)
+* GREP:                                  Particular Programs. (line  24)
+* host:                                  Canonicalizing.      (line  34)
+* host_alias:                            Canonicalizing.      (line   9)
+* host_cpu:                              Canonicalizing.      (line  34)
+* host_os:                               Canonicalizing.      (line  34)
+* host_vendor:                           Canonicalizing.      (line  34)
+* includedir:                            Installation Directory Variables.
+                                                              (line  26)
+* infodir:                               Installation Directory Variables.
+                                                              (line  29)
+* INSTALL:                               Particular Programs. (line  28)
+* INSTALL_DATA:                          Particular Programs. (line  28)
+* INSTALL_PROGRAM:                       Particular Programs. (line  28)
+* INSTALL_SCRIPT:                        Particular Programs. (line  28)
+* KMEM_GROUP:                            Particular Functions.
+                                                              (line 103)
+* LDFLAGS:                               Preset Output Variables.
+                                                              (line  79)
+* LEX:                                   Particular Programs. (line  57)
+* LEXLIB:                                Particular Programs. (line  57)
+* LEX_OUTPUT_ROOT:                       Particular Programs. (line  57)
+* libdir:                                Installation Directory Variables.
+                                                              (line  32)
+* libexecdir:                            Installation Directory Variables.
+                                                              (line  35)
+* LIBOBJS:                               Particular Functions.
+                                                              (line 103)
+* LIBOBJS <1>:                           Particular Functions.
+                                                              (line 160)
+* LIBOBJS <2>:                           Particular Functions.
+                                                              (line 167)
+* LIBOBJS <3>:                           Generic Functions.   (line  44)
+* LIBOBJS <4>:                           Generic Functions.   (line  84)
+* LIBOBJS <5>:                           Particular Structures.
+                                                              (line  17)
+* LIBS:                                  Preset Output Variables.
+                                                              (line  87)
+* LIBS <1>:                              Obsolete Macros.     (line 408)
+* LIBS <2>:                              Obsolete Macros.     (line 515)
+* LN_S:                                  Particular Programs. (line  95)
+* localstatedir:                         Installation Directory Variables.
+                                                              (line  38)
+* mandir:                                Installation Directory Variables.
+                                                              (line  41)
+* NEED_SETGID:                           Particular Functions.
+                                                              (line 103)
+* OBJEXT:                                Compilers and Preprocessors.
+                                                              (line  10)
+* OBJEXT <1>:                            Obsolete Macros.     (line 300)
+* oldincludedir:                         Installation Directory Variables.
+                                                              (line  44)
+* POW_LIB:                               Particular Functions.
+                                                              (line 216)
+* prefix:                                Installation Directory Variables.
+                                                              (line  47)
+* program_transform_name:                Transforming Names.  (line  11)
+* RANLIB:                                Particular Programs. (line 114)
+* sbindir:                               Installation Directory Variables.
+                                                              (line  52)
+* SET_MAKE:                              Output.              (line  37)
+* sharedstatedir:                        Installation Directory Variables.
+                                                              (line  56)
+* srcdir:                                Preset Output Variables.
+                                                              (line  94)
+* subdirs:                               Subdirectories.      (line  12)
+* sysconfdir:                            Installation Directory Variables.
+                                                              (line  60)
+* target:                                Canonicalizing.      (line  46)
+* target_alias:                          Canonicalizing.      (line   9)
+* target_cpu:                            Canonicalizing.      (line  46)
+* target_os:                             Canonicalizing.      (line  46)
+* target_vendor:                         Canonicalizing.      (line  46)
+* top_srcdir:                            Preset Output Variables.
+                                                              (line  97)
+* X_CFLAGS:                              System Services.     (line  26)
+* X_EXTRA_LIBS:                          System Services.     (line  26)
+* X_LIBS:                                System Services.     (line  26)
+* X_PRE_LIBS:                            System Services.     (line  26)
+* YACC:                                  Particular Programs. (line 118)
+
+
+File: autoconf.info,  Node: Preprocessor Symbol Index,  Next: Autoconf Macro Index,  Prev: Output Variable Index,  Up: Top
+
+Preprocessor Symbol Index
+*************************
+
+This is an alphabetical list of the C preprocessor symbols that the
+Autoconf macros define.  To work with Autoconf, C source code needs to
+use these names in '#if' directives.
+
+
+* Menu:
+
+* _ALL_SOURCE:                           UNIX Variants.       (line  13)
+* _FILE_OFFSET_BITS:                     System Services.     (line  44)
+* _LARGEFILE_SOURCE:                     Particular Functions.
+                                                              (line  93)
+* _LARGE_FILES:                          System Services.     (line  44)
+* _MINIX:                                UNIX Variants.       (line  25)
+* _POSIX_1_SOURCE:                       UNIX Variants.       (line  25)
+* _POSIX_SOURCE:                         UNIX Variants.       (line  18)
+* _POSIX_SOURCE <1>:                     UNIX Variants.       (line  25)
+* _POSIX_VERSION:                        Particular Headers.  (line 130)
+* __CHAR_UNSIGNED__:                     C Compiler.          (line 120)
+* CLOSEDIR_VOID:                         Particular Functions.
+                                                              (line  58)
+* const:                                 C Compiler.          (line  73)
+* C_ALLOCA:                              Particular Functions.
+                                                              (line  10)
+* C_GETLOADAVG:                          Particular Functions.
+                                                              (line 103)
+* DGUX:                                  Particular Functions.
+                                                              (line 103)
+* DIRENT:                                Obsolete Macros.     (line 126)
+* F77_DUMMY_MAIN:                        Fortran 77 Compiler. (line  64)
+* F77_FUNC:                              Fortran 77 Compiler. (line 115)
+* F77_FUNC_:                             Fortran 77 Compiler. (line 115)
+* F77_MAIN:                              Fortran 77 Compiler. (line 101)
+* F77_NO_MINUS_C_MINUS_O:                Fortran 77 Compiler. (line  28)
+* GETGROUPS_T:                           Particular Types.    (line  10)
+* GETLODAVG_PRIVILEGED:                  Particular Functions.
+                                                              (line 103)
+* GETPGRP_VOID:                          Particular Functions.
+                                                              (line 136)
+* gid_t:                                 Particular Types.    (line  39)
+* GWINSZ_IN_SYS_IOCTL:                   Particular Headers.  (line 167)
+* HAVE_ALLOCA_H:                         Particular Functions.
+                                                              (line  10)
+* HAVE_CONFIG_H:                         Configuration Headers.
+                                                              (line  25)
+* HAVE_DECL_SYMBOL:                      Generic Declarations.
+                                                              (line  23)
+* HAVE_DIRENT_H:                         Particular Headers.  (line  10)
+* HAVE_DOPRNT:                           Particular Functions.
+                                                              (line 238)
+* HAVE_FUNCTION:                         Generic Functions.   (line  25)
+* HAVE_GETMNTENT:                        Particular Functions.
+                                                              (line 131)
+* HAVE_HEADER:                           Generic Headers.     (line  43)
+* HAVE_LONG_DOUBLE:                      C Compiler.          (line 124)
+* HAVE_LONG_FILE_NAMES:                  System Services.     (line  58)
+* HAVE_LSTAT_EMPTY_STRING_BUG:           Particular Functions.
+                                                              (line 196)
+* HAVE_MMAP:                             Particular Functions.
+                                                              (line 171)
+* HAVE_NDIR_H:                           Particular Headers.  (line  10)
+* HAVE_OBSTACK:                          Particular Functions.
+                                                              (line 176)
+* HAVE_RESTARTABLE_SYSCALLS:             Obsolete Macros.     (line 446)
+* HAVE_STAT_EMPTY_STRING_BUG:            Particular Functions.
+                                                              (line 196)
+* HAVE_STRCOLL:                          Particular Functions.
+                                                              (line 210)
+* HAVE_STRERROR_R:                       Particular Functions.
+                                                              (line 222)
+* HAVE_STRFTIME:                         Particular Functions.
+                                                              (line 230)
+* HAVE_STRINGIZE:                        C Compiler.          (line 130)
+* HAVE_STRUCT_STAT_ST_BLKSIZE:           Particular Structures.
+                                                              (line   9)
+* HAVE_STRUCT_STAT_ST_BLOCKS:            Particular Structures.
+                                                              (line  17)
+* HAVE_STRUCT_STAT_ST_RDEV:              Particular Structures.
+                                                              (line  23)
+* HAVE_ST_BLKSIZE:                       Particular Structures.
+                                                              (line   9)
+* HAVE_ST_BLOCKS:                        Particular Structures.
+                                                              (line  17)
+* HAVE_ST_RDEV:                          Particular Structures.
+                                                              (line  23)
+* HAVE_SYS_DIR_H:                        Particular Headers.  (line  10)
+* HAVE_SYS_NDIR_H:                       Particular Headers.  (line  10)
+* HAVE_SYS_WAIT_H:                       Particular Headers.  (line 112)
+* HAVE_TM_ZONE:                          Particular Structures.
+                                                              (line  36)
+* HAVE_TZNAME:                           Particular Structures.
+                                                              (line  36)
+* HAVE_UTIME_NULL:                       Particular Functions.
+                                                              (line 234)
+* HAVE_VFORK_H:                          Particular Functions.
+                                                              (line  71)
+* HAVE_VPRINTF:                          Particular Functions.
+                                                              (line 238)
+* HAVE_WAIT3:                            Obsolete Macros.     (line 166)
+* HAVE_WORKING_FORK:                     Particular Functions.
+                                                              (line  71)
+* HAVE_WORKING_STRERROR_R:               Particular Functions.
+                                                              (line 222)
+* HAVE_WORKING_VFORK:                    Particular Functions.
+                                                              (line  71)
+* inline:                                C Compiler.          (line 115)
+* INT_16_BITS:                           Obsolete Macros.     (line 217)
+* LONG_64_BITS:                          Obsolete Macros.     (line 268)
+* LSTAT_FOLLOWS_SLASHED_SYMLINK:         Particular Functions.
+                                                              (line 143)
+* MAJOR_IN_MKDEV:                        Particular Headers.  (line  46)
+* MAJOR_IN_SYSMACROS:                    Particular Headers.  (line  46)
+* mode_t:                                Particular Types.    (line  14)
+* NDIR:                                  Obsolete Macros.     (line 126)
+* NEED_MEMORY_H:                         Obsolete Macros.     (line 281)
+* NEED_SETGID:                           Particular Functions.
+                                                              (line 103)
+* NLIST_NAME_UNION:                      Particular Functions.
+                                                              (line 103)
+* NLIST_STRUCT:                          Particular Functions.
+                                                              (line 103)
+* NO_MINUS_C_MINUS_O:                    C Compiler.          (line  26)
+* off_t:                                 Particular Types.    (line  17)
+* PARAMS:                                C Compiler.          (line 137)
+* pid_t:                                 Particular Types.    (line  20)
+* PROTOTYPES:                            C Compiler.          (line 137)
+* RETSIGTYPE:                            Particular Types.    (line  23)
+* SELECT_TYPE_ARG1:                      Particular Functions.
+                                                              (line 180)
+* SELECT_TYPE_ARG234:                    Particular Functions.
+                                                              (line 180)
+* SELECT_TYPE_ARG5:                      Particular Functions.
+                                                              (line 180)
+* SETPGRP_VOID:                          Particular Functions.
+                                                              (line 188)
+* SETVBUF_REVERSED:                      Particular Functions.
+                                                              (line 205)
+* size_t:                                Particular Types.    (line  36)
+* STDC_HEADERS:                          Particular Headers.  (line  57)
+* SVR4:                                  Particular Functions.
+                                                              (line 103)
+* SYSDIR:                                Obsolete Macros.     (line 126)
+* SYSNDIR:                               Obsolete Macros.     (line 126)
+* SYS_SIGLIST_DECLARED:                  Particular Declarations.
+                                                              (line   9)
+* TIME_WITH_SYS_TIME:                    Particular Headers.  (line 146)
+* TM_IN_SYS_TIME:                        Particular Structures.
+                                                              (line  31)
+* uid_t:                                 Particular Types.    (line  39)
+* UMAX:                                  Particular Functions.
+                                                              (line 103)
+* UMAX4_3:                               Particular Functions.
+                                                              (line 103)
+* USG:                                   Obsolete Macros.     (line 482)
+* vfork:                                 Particular Functions.
+                                                              (line  71)
+* volatile:                              C Compiler.          (line  98)
+* WORDS_BIGENDIAN:                       C Compiler.          (line  68)
+* X_DISPLAY_MISSING:                     System Services.     (line  26)
+* YYTEXT_POINTER:                        Particular Programs. (line  57)
+
+
+File: autoconf.info,  Node: Autoconf Macro Index,  Next: M4 Macro Index,  Prev: Preprocessor Symbol Index,  Up: Top
+
+Autoconf Macro Index
+********************
+
+This is an alphabetical list of the Autoconf macros.  To make the list
+easier to use, the macros are listed without their preceding 'AC_'.
+
+
+* Menu:
+
+* AH_BOTTOM:                             Autoheader Macros.   (line  56)
+* AH_TEMPLATE:                           Autoheader Macros.   (line  32)
+* AH_TOP:                                Autoheader Macros.   (line  53)
+* AH_VERBATIM:                           Autoheader Macros.   (line  18)
+* AIX:                                   UNIX Variants.       (line  13)
+* ALLOCA:                                Obsolete Macros.     (line  20)
+* ARG_ARRAY:                             Obsolete Macros.     (line  23)
+* ARG_ENABLE:                            Package Options.     (line  40)
+* ARG_PROGRAM:                           Transforming Names.  (line  11)
+* ARG_VAR:                               Setting Output Variables.
+                                                              (line  57)
+* ARG_WITH:                              External Software.   (line  41)
+* AU_DEFUN:                              Obsoleting Macros.   (line  18)
+* BEFORE:                                Suggested Ordering.  (line  28)
+* BOTTOM:                                Autoheader Macros.   (line  56)
+* CACHE_CHECK:                           Caching Results.     (line  29)
+* CACHE_LOAD:                            Cache Checkpointing. (line  13)
+* CACHE_SAVE:                            Cache Checkpointing. (line  17)
+* CACHE_VAL:                             Caching Results.     (line  15)
+* CANONICAL_BUILD:                       Canonicalizing.      (line  26)
+* CANONICAL_HOST:                        Canonicalizing.      (line  34)
+* CANONICAL_SYSTEM:                      Obsolete Macros.     (line  29)
+* CANONICAL_TARGET:                      Canonicalizing.      (line  46)
+* CHAR_UNSIGNED:                         Obsolete Macros.     (line  39)
+* CHECKING:                              Obsolete Macros.     (line  89)
+* CHECK_DECL:                            Generic Declarations.
+                                                              (line  11)
+* CHECK_DECLS:                           Generic Declarations.
+                                                              (line  23)
+* CHECK_FILE:                            Files.               (line  13)
+* CHECK_FILES:                           Files.               (line  19)
+* CHECK_FUNC:                            Generic Functions.   (line  15)
+* CHECK_FUNCS:                           Generic Functions.   (line  25)
+* CHECK_HEADER:                          Generic Headers.     (line  13)
+* CHECK_HEADERS:                         Generic Headers.     (line  43)
+* CHECK_LIB:                             Libraries.           (line  11)
+* CHECK_MEMBER:                          Generic Structures.  (line  11)
+* CHECK_MEMBERS:                         Generic Structures.  (line  25)
+* CHECK_PROG:                            Generic Programs.    (line  23)
+* CHECK_PROGS:                           Generic Programs.    (line  33)
+* CHECK_SIZEOF:                          Generic Compiler Characteristics.
+                                                              (line   7)
+* CHECK_TOOL:                            Generic Programs.    (line  43)
+* CHECK_TOOLS:                           Generic Programs.    (line  54)
+* CHECK_TYPE:                            Generic Types.       (line  11)
+* CHECK_TYPE <1>:                        Obsolete Macros.     (line  42)
+* CHECK_TYPES:                           Generic Types.       (line  16)
+* COMPILE_CHECK:                         Obsolete Macros.     (line  93)
+* CONFIG_AUX_DIR:                        Input.               (line  29)
+* CONFIG_COMMANDS:                       Configuration Commands.
+                                                              (line  13)
+* CONFIG_FILES:                          Configuration Files. (line   9)
+* CONFIG_HEADERS:                        Configuration Headers.
+                                                              (line  25)
+* CONFIG_LINKS:                          Configuration Links. (line  12)
+* CONFIG_SRCDIR:                         Input.               (line  16)
+* CONFIG_SUBDIRS:                        Subdirectories.      (line  12)
+* CONST:                                 Obsolete Macros.     (line 100)
+* COPYRIGHT:                             Notices.             (line  21)
+* CROSS_CHECK:                           Obsolete Macros.     (line 103)
+* CYGWIN:                                Obsolete Macros.     (line 107)
+* C_BIGENDIAN:                           C Compiler.          (line  68)
+* C_CHAR_UNSIGNED:                       C Compiler.          (line 120)
+* C_CONST:                               C Compiler.          (line  73)
+* C_CROSS:                               Obsolete Macros.     (line  26)
+* C_INLINE:                              C Compiler.          (line 115)
+* C_LONG_DOUBLE:                         C Compiler.          (line 124)
+* C_PROTOTYPES:                          C Compiler.          (line 137)
+* C_STRINGIZE:                           C Compiler.          (line 130)
+* C_VOLATILE:                            C Compiler.          (line  98)
+* DECL_SYS_SIGLIST:                      Particular Declarations.
+                                                              (line   9)
+* DECL_YYTEXT:                           Obsolete Macros.     (line 123)
+* DEFINE:                                Defining Symbols.    (line  29)
+* DEFINE_UNQUOTED:                       Defining Symbols.    (line  45)
+* DEFUN:                                 Macro Definitions.   (line   6)
+* DEFUN <1>:                             Obsoleting Macros.   (line  18)
+* DIAGNOSE:                              Reporting Messages.  (line  11)
+* DIR_HEADER:                            Obsolete Macros.     (line 126)
+* DYNIX_SEQ:                             Obsolete Macros.     (line 137)
+* EGREP_CPP:                             Examining Declarations.
+                                                              (line  46)
+* EGREP_HEADER:                          Examining Declarations.
+                                                              (line  29)
+* EMXOS2:                                Obsolete Macros.     (line 150)
+* ENABLE:                                Package Options.     (line  57)
+* ERROR:                                 Obsolete Macros.     (line 154)
+* EXEEXT:                                Obsolete Macros.     (line 145)
+* F77_DUMMY_MAIN:                        Fortran 77 Compiler. (line  64)
+* F77_FUNC:                              Fortran 77 Compiler. (line 169)
+* F77_LIBRARY_LDFLAGS:                   Fortran 77 Compiler. (line  38)
+* F77_MAIN:                              Fortran 77 Compiler. (line 101)
+* F77_WRAPPERS:                          Fortran 77 Compiler. (line 115)
+* FATAL:                                 Reporting Messages.  (line  33)
+* FIND_X:                                Obsolete Macros.     (line 157)
+* FIND_XTRA:                             Obsolete Macros.     (line 160)
+* FUNC_ALLOCA:                           Particular Functions.
+                                                              (line  10)
+* FUNC_CHECK:                            Obsolete Macros.     (line 163)
+* FUNC_CHOWN:                            Particular Functions.
+                                                              (line  54)
+* FUNC_CLOSEDIR_VOID:                    Particular Functions.
+                                                              (line  58)
+* FUNC_ERROR_AT_LINE:                    Particular Functions.
+                                                              (line  63)
+* FUNC_FNMATCH:                          Particular Functions.
+                                                              (line  67)
+* FUNC_FORK:                             Particular Functions.
+                                                              (line  71)
+* FUNC_FSEEKO:                           Particular Functions.
+                                                              (line  93)
+* FUNC_GETGROUPS:                        Particular Functions.
+                                                              (line  97)
+* FUNC_GETLOADAVG:                       Particular Functions.
+                                                              (line 103)
+* FUNC_GETMNTENT:                        Particular Functions.
+                                                              (line 131)
+* FUNC_GETPGRP:                          Particular Functions.
+                                                              (line 136)
+* FUNC_LSTAT:                            Particular Functions.
+                                                              (line 196)
+* FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK:    Particular Functions.
+                                                              (line 143)
+* FUNC_MALLOC:                           Particular Functions.
+                                                              (line 156)
+* FUNC_MEMCMP:                           Particular Functions.
+                                                              (line 160)
+* FUNC_MKTIME:                           Particular Functions.
+                                                              (line 167)
+* FUNC_MMAP:                             Particular Functions.
+                                                              (line 171)
+* FUNC_OBSTACK:                          Particular Functions.
+                                                              (line 176)
+* FUNC_SELECT_ARGTYPES:                  Particular Functions.
+                                                              (line 180)
+* FUNC_SETPGRP:                          Particular Functions.
+                                                              (line 188)
+* FUNC_SETVBUF_REVERSED:                 Particular Functions.
+                                                              (line 205)
+* FUNC_STAT:                             Particular Functions.
+                                                              (line 196)
+* FUNC_STRCOLL:                          Particular Functions.
+                                                              (line 210)
+* FUNC_STRERROR_R:                       Particular Functions.
+                                                              (line 222)
+* FUNC_STRFTIME:                         Particular Functions.
+                                                              (line 230)
+* FUNC_STRTOD:                           Particular Functions.
+                                                              (line 216)
+* FUNC_UTIME_NULL:                       Particular Functions.
+                                                              (line 234)
+* FUNC_VPRINTF:                          Particular Functions.
+                                                              (line 238)
+* FUNC_WAIT3:                            Obsolete Macros.     (line 166)
+* GCC_TRADITIONAL:                       Obsolete Macros.     (line 175)
+* GETGROUPS_T:                           Obsolete Macros.     (line 178)
+* GETLOADAVG:                            Obsolete Macros.     (line 181)
+* HAVE_FUNCS:                            Obsolete Macros.     (line 184)
+* HAVE_HEADERS:                          Obsolete Macros.     (line 187)
+* HAVE_LIBRARY:                          Obsolete Macros.     (line 191)
+* HAVE_POUNDBANG:                        Obsolete Macros.     (line 198)
+* HEADER_CHECK:                          Obsolete Macros.     (line 201)
+* HEADER_DIRENT:                         Particular Headers.  (line  10)
+* HEADER_EGREP:                          Obsolete Macros.     (line 204)
+* HEADER_MAJOR:                          Particular Headers.  (line  46)
+* HEADER_STAT:                           Particular Headers.  (line  51)
+* HEADER_STDC:                           Particular Headers.  (line  57)
+* HEADER_SYS_WAIT:                       Particular Headers.  (line 112)
+* HEADER_TIME:                           Particular Headers.  (line 146)
+* HEADER_TIOCGWINSZ:                     Particular Headers.  (line 167)
+* HELP_STRING:                           Pretty Help Strings. (line  14)
+* INIT:                                  Input.               (line  10)
+* INIT <1>:                              Obsolete Macros.     (line 207)
+* INLINE:                                Obsolete Macros.     (line 214)
+* INT_16_BITS:                           Obsolete Macros.     (line 217)
+* IRIX_SUN:                              Obsolete Macros.     (line 221)
+* ISC_POSIX:                             UNIX Variants.       (line  18)
+* LANG_C:                                Obsolete Macros.     (line 235)
+* LANG_CPLUSPLUS:                        Obsolete Macros.     (line 238)
+* LANG_FORTRAN77:                        Obsolete Macros.     (line 241)
+* LANG_POP:                              Language Choice.     (line  37)
+* LANG_PUSH:                             Language Choice.     (line  32)
+* LANG_RESTORE:                          Obsolete Macros.     (line 244)
+* LANG_SAVE:                             Obsolete Macros.     (line 249)
+* LIBOBJ:                                Generic Functions.   (line  44)
+* LIBSOURCE:                             Generic Functions.   (line  52)
+* LIBSOURCES:                            Generic Functions.   (line  76)
+* LINK_FILES:                            Obsolete Macros.     (line 253)
+* LN_S:                                  Obsolete Macros.     (line 265)
+* LONG_64_BITS:                          Obsolete Macros.     (line 268)
+* LONG_DOUBLE:                           Obsolete Macros.     (line 272)
+* LONG_FILE_NAMES:                       Obsolete Macros.     (line 275)
+* MAJOR_HEADER:                          Obsolete Macros.     (line 278)
+* MEMORY_H:                              Obsolete Macros.     (line 281)
+* MINGW32:                               Obsolete Macros.     (line 287)
+* MINIX:                                 UNIX Variants.       (line  25)
+* MINUS_C_MINUS_O:                       Obsolete Macros.     (line 291)
+* MMAP:                                  Obsolete Macros.     (line 294)
+* MODE_T:                                Obsolete Macros.     (line 297)
+* MSG_CHECKING:                          Printing Messages.   (line  23)
+* MSG_ERROR:                             Printing Messages.   (line  54)
+* MSG_NOTICE:                            Printing Messages.   (line  44)
+* MSG_RESULT:                            Printing Messages.   (line  34)
+* MSG_WARN:                              Printing Messages.   (line  64)
+* OBJEXT:                                Obsolete Macros.     (line 300)
+* OBSOLETE:                              Obsolete Macros.     (line 306)
+* OFF_T:                                 Obsolete Macros.     (line 321)
+* OUTPUT:                                Output.              (line  12)
+* OUTPUT <1>:                            Obsolete Macros.     (line 324)
+* OUTPUT_COMMANDS:                       Obsolete Macros.     (line 346)
+* OUTPUT_COMMANDS_POST:                  Configuration Commands.
+                                                              (line  39)
+* OUTPUT_COMMANDS_PRE:                   Configuration Commands.
+                                                              (line  30)
+* PATH_PROG:                             Generic Programs.    (line  66)
+* PATH_PROGS:                            Generic Programs.    (line  71)
+* PATH_TOOL:                             Generic Programs.    (line  76)
+* PATH_X:                                System Services.     (line  10)
+* PATH_XTRA:                             System Services.     (line  26)
+* PID_T:                                 Obsolete Macros.     (line 375)
+* PREFIX:                                Obsolete Macros.     (line 378)
+* PREFIX_DEFAULT:                        Default Prefix.      (line  16)
+* PREFIX_PROGRAM:                        Default Prefix.      (line  25)
+* PREREQ:                                Notices.             (line  10)
+* PROGRAMS_CHECK:                        Obsolete Macros.     (line 381)
+* PROGRAMS_PATH:                         Obsolete Macros.     (line 384)
+* PROGRAM_CHECK:                         Obsolete Macros.     (line 387)
+* PROGRAM_EGREP:                         Obsolete Macros.     (line 390)
+* PROGRAM_PATH:                          Obsolete Macros.     (line 393)
+* PROG_AWK:                              Particular Programs. (line  10)
+* PROG_CC:                               C Compiler.          (line   7)
+* PROG_CC_C_O:                           C Compiler.          (line  26)
+* PROG_CC_STDC:                          C Compiler.          (line  34)
+* PROG_CPP:                              C Compiler.          (line  47)
+* PROG_CXX:                              C++ Compiler.        (line   7)
+* PROG_CXXCPP:                           C++ Compiler.        (line  31)
+* PROG_F77_C_O:                          Fortran 77 Compiler. (line  28)
+* PROG_FORTRAN:                          Fortran 77 Compiler. (line   7)
+* PROG_GCC_TRADITIONAL:                  C Compiler.          (line 156)
+* PROG_INSTALL:                          Particular Programs. (line  28)
+* PROG_LEX:                              Particular Programs. (line  57)
+* PROG_LN_S:                             Particular Programs. (line  95)
+* PROG_MAKE_SET:                         Output.              (line  37)
+* PROG_RANLIB:                           Particular Programs. (line 114)
+* PROG_YACC:                             Particular Programs. (line 118)
+* REMOTE_TAPE:                           Obsolete Macros.     (line 396)
+* REPLACE_FUNCS:                         Generic Functions.   (line  84)
+* REQUIRE:                               Prerequisite Macros. (line  17)
+* REQUIRE_CPP:                           Language Choice.     (line  50)
+* RESTARTABLE_SYSCALLS:                  Obsolete Macros.     (line 399)
+* RETSIGTYPE:                            Obsolete Macros.     (line 402)
+* REVISION:                              Notices.             (line  29)
+* RSH:                                   Obsolete Macros.     (line 405)
+* SCO_INTL:                              Obsolete Macros.     (line 408)
+* SEARCH_LIBS:                           Libraries.           (line  41)
+* SETVBUF_REVERSED:                      Obsolete Macros.     (line 416)
+* SET_MAKE:                              Obsolete Macros.     (line 419)
+* SIZEOF_TYPE:                           Obsolete Macros.     (line 422)
+* SIZE_T:                                Obsolete Macros.     (line 425)
+* STAT_MACROS_BROKEN:                    Particular Headers.  (line  51)
+* STAT_MACROS_BROKEN <1>:                Obsolete Macros.     (line 428)
+* STDC_HEADERS:                          Obsolete Macros.     (line 431)
+* STRCOLL:                               Obsolete Macros.     (line 434)
+* STRUCT_ST_BLKSIZE:                     Particular Structures.
+                                                              (line   9)
+* STRUCT_ST_BLOCKS:                      Particular Structures.
+                                                              (line  17)
+* STRUCT_ST_RDEV:                        Particular Structures.
+                                                              (line  23)
+* STRUCT_TIMEZONE:                       Particular Structures.
+                                                              (line  36)
+* STRUCT_TM:                             Particular Structures.
+                                                              (line  31)
+* ST_BLKSIZE:                            Obsolete Macros.     (line 437)
+* ST_BLOCKS:                             Obsolete Macros.     (line 440)
+* ST_RDEV:                               Obsolete Macros.     (line 443)
+* SUBST:                                 Setting Output Variables.
+                                                              (line  13)
+* SUBST_FILE:                            Setting Output Variables.
+                                                              (line  23)
+* SYS_INTERPRETER:                       System Services.     (line  37)
+* SYS_LARGEFILE:                         System Services.     (line  44)
+* SYS_LONG_FILE_NAMES:                   System Services.     (line  58)
+* SYS_POSIX_TERMIOS:                     System Services.     (line  62)
+* SYS_RESTARTABLE_SYSCALLS:              Obsolete Macros.     (line 446)
+* SYS_SIGLIST_DECLARED:                  Obsolete Macros.     (line 461)
+* TEMPLATE:                              Autoheader Macros.   (line  32)
+* TEST_CPP:                              Obsolete Macros.     (line 464)
+* TEST_PROGRAM:                          Obsolete Macros.     (line 467)
+* TIMEZONE:                              Obsolete Macros.     (line 470)
+* TIME_WITH_SYS_TIME:                    Obsolete Macros.     (line 473)
+* TOP:                                   Autoheader Macros.   (line  53)
+* TRY_COMPILE:                           Examining Syntax.    (line  14)
+* TRY_CPP:                               Examining Declarations.
+                                                              (line  11)
+* TRY_LINK:                              Examining Libraries. (line  33)
+* TRY_LINK_FUNC:                         Examining Libraries. (line  51)
+* TRY_RUN:                               Test Programs.       (line  11)
+* TYPE_GETGROUPS:                        Particular Types.    (line  10)
+* TYPE_MODE_T:                           Particular Types.    (line  14)
+* TYPE_OFF_T:                            Particular Types.    (line  17)
+* TYPE_PID_T:                            Particular Types.    (line  20)
+* TYPE_SIGNAL:                           Particular Types.    (line  23)
+* TYPE_SIZE_T:                           Particular Types.    (line  36)
+* TYPE_UID_T:                            Particular Types.    (line  39)
+* UID_T:                                 Obsolete Macros.     (line 476)
+* UNISTD_H:                              Obsolete Macros.     (line 479)
+* USG:                                   Obsolete Macros.     (line 482)
+* UTIME_NULL:                            Obsolete Macros.     (line 487)
+* VALIDATE_CACHED_SYSTEM_TUPLE:          Obsolete Macros.     (line 490)
+* VERBATIM:                              Autoheader Macros.   (line  18)
+* VERBOSE:                               Obsolete Macros.     (line 497)
+* VFORK:                                 Obsolete Macros.     (line 500)
+* VPRINTF:                               Obsolete Macros.     (line 503)
+* WAIT3:                                 Obsolete Macros.     (line 506)
+* WARN:                                  Obsolete Macros.     (line 509)
+* WARNING:                               Reporting Messages.  (line  29)
+* WITH:                                  External Software.   (line  67)
+* WORDS_BIGENDIAN:                       Obsolete Macros.     (line 512)
+* XENIX_DIR:                             Obsolete Macros.     (line 515)
+* YYTEXT_POINTER:                        Obsolete Macros.     (line 530)
+
+
+File: autoconf.info,  Node: M4 Macro Index,  Next: Concept Index,  Prev: Autoconf Macro Index,  Up: Top
+
+M4 Macro Index
+**************
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros.  To
+make the list easier to use, the macros are listed without their
+preceding 'm4_' or 'AS_'.
+
+
+* Menu:
+
+* defn:                                  Redefined M4 Macros.  (line 14)
+* defn <1>:                              Redefined M4 Macros.  (line 26)
+* pattern_allow:                         Forbidden Patterns.   (line 28)
+* pattern_forbid:                        Forbidden Patterns.   (line 15)
+* undefine:                              Redefined M4 Macros.  (line 18)
+
+
+File: autoconf.info,  Node: Concept Index,  Prev: M4 Macro Index,  Up: Top
+
+Concept Index
+*************
+
+This is an alphabetical list of the files, tools, and concepts
+introduced in this document.
+
+
+* Menu:
+
+* !:                                     Limitations of Builtins.
+                                                              (line  16)
+* "$@":                                  Shell Substitutions. (line  31)
+* $(COMMANDS):                           Shell Substitutions. (line 132)
+* ${VAR:-VALUE}:                         Shell Substitutions. (line  38)
+* ${VAR=EXPANDED-VALUE}:                 Shell Substitutions. (line  71)
+* ${VAR=LITERAL}:                        Shell Substitutions. (line  42)
+* /usr/xpg4/bin/sh on Solaris:           Shellology.          (line  43)
+* ::                                     Limitations of Builtins.
+                                                              (line 312)
+* @%:@:                                  Quadrigraphs.        (line   6)
+* @:>@:                                  Quadrigraphs.        (line   6)
+* @<:@:                                  Quadrigraphs.        (line   6)
+* @S|@:                                  Quadrigraphs.        (line   6)
+* 'COMMANDS':                            Shell Substitutions. (line 117)
+* acconfig.h:                            acconfig.h.          (line   6)
+* aclocal.m4:                            Making configure Scripts.
+                                                              (line   6)
+* Ash:                                   Shellology.          (line  13)
+* autoconf:                              autoconf Invocation. (line   6)
+* autoheader:                            autoheader Invocation.
+                                                              (line   6)
+* Automake:                              Automake.            (line  19)
+* autoreconf:                            autoreconf Invocation.
+                                                              (line   6)
+* autoscan:                              autoscan Invocation. (line   6)
+* autoupdate:                            autoupdate Invocation.
+                                                              (line   6)
+* awk:                                   Limitations of Usual Tools.
+                                                              (line  10)
+* Back trace:                            autoconf Invocation. (line  93)
+* Bash:                                  Shellology.          (line  37)
+* break:                                 Limitations of Builtins.
+                                                              (line  19)
+* Cache:                                 Caching Results.     (line   6)
+* Cache variable:                        Cache Variable Names.
+                                                              (line   6)
+* Cache, enabling:                       configure Invocation.
+                                                              (line  18)
+* case:                                  Limitations of Builtins.
+                                                              (line  22)
+* cat:                                   Limitations of Usual Tools.
+                                                              (line  53)
+* cmp:                                   Limitations of Usual Tools.
+                                                              (line  61)
+* Command Substitution:                  Shell Substitutions. (line 117)
+* config.h:                              Configuration Headers.
+                                                              (line   6)
+* config.h.bot:                          acconfig.h.          (line   6)
+* config.h.in:                           Header Templates.    (line   6)
+* config.h.top:                          acconfig.h.          (line   6)
+* config.status:                         config.status Invocation.
+                                                              (line   6)
+* Configuration Header:                  Configuration Headers.
+                                                              (line   6)
+* Configuration Header Template:         Header Templates.    (line   6)
+* configure:                             Making configure Scripts.
+                                                              (line   6)
+* configure <1>:                         Running configure scripts.
+                                                              (line   6)
+* configure.ac:                          Making configure Scripts.
+                                                              (line  27)
+* configure.in:                          Making configure Scripts.
+                                                              (line  27)
+* Copyright Notice:                      Notices.             (line  21)
+* cp:                                    Limitations of Usual Tools.
+                                                              (line  68)
+* Declaration, checking:                 Declarations.        (line   6)
+* diff:                                  Limitations of Usual Tools.
+                                                              (line  79)
+* dirname:                               Limitations of Usual Tools.
+                                                              (line  85)
+* dnl:                                   Macro Definitions.   (line  35)
+* dnl <1>:                               Coding Style.        (line  40)
+* echo:                                  Limitations of Builtins.
+                                                              (line  42)
+* egrep:                                 Limitations of Usual Tools.
+                                                              (line 112)
+* Endianness:                            C Compiler.          (line  68)
+* exit:                                  Limitations of Builtins.
+                                                              (line  69)
+* export:                                Limitations of Builtins.
+                                                              (line  94)
+* expr:                                  Limitations of Usual Tools.
+                                                              (line 126)
+* expr <1>:                              Limitations of Usual Tools.
+                                                              (line 151)
+* expr (|):                              Limitations of Usual Tools.
+                                                              (line 132)
+* false:                                 Limitations of Builtins.
+                                                              (line 120)
+* File, checking:                        Files.               (line   6)
+* for:                                   Limitations of Builtins.
+                                                              (line 124)
+* Function, checking:                    Particular Functions.
+                                                              (line   6)
+* grep:                                  Limitations of Usual Tools.
+                                                              (line 204)
+* Header, checking:                      Header Files.        (line   6)
+* if:                                    Limitations of Builtins.
+                                                              (line 146)
+* ifnames:                               ifnames Invocation.  (line   6)
+* Includes, default:                     Default Includes.    (line   6)
+* Instantiation:                         Output.              (line  12)
+* Language:                              Language Choice.     (line   6)
+* Library, checking:                     Libraries.           (line   6)
+* Libtool:                               Libtool.             (line  13)
+* Links:                                 Configuration Links. (line  12)
+* ln:                                    Limitations of Usual Tools.
+                                                              (line 216)
+* M4sugar:                               Programming in M4sugar.
+                                                              (line   6)
+* Macro invocation stack:                autoconf Invocation. (line  93)
+* Messages, from autoconf:               Reporting Messages.  (line   6)
+* Messages, from configure:              Printing Messages.   (line   6)
+* mv:                                    Limitations of Usual Tools.
+                                                              (line 228)
+* obstack:                               Particular Functions.
+                                                              (line 176)
+* POSIX termios headers:                 System Services.     (line  62)
+* Previous Variable:                     Setting Output Variables.
+                                                              (line  44)
+* Programs, checking:                    Alternative Programs.
+                                                              (line   6)
+* QNX 4.25:                              Systemology.         (line  11)
+* quadrigraphs:                          Quadrigraphs.        (line   6)
+* quotation:                             Autoconf Language.   (line   6)
+* quotation <1>:                         M4 Quotation.        (line   6)
+* Revision:                              Notices.             (line  29)
+* sed:                                   Limitations of Usual Tools.
+                                                              (line 239)
+* sed (t):                               Limitations of Usual Tools.
+                                                              (line 278)
+* set:                                   Limitations of Builtins.
+                                                              (line 175)
+* shift:                                 Limitations of Builtins.
+                                                              (line 186)
+* Structure, checking:                   Structures.          (line   6)
+* Symbolic links:                        Limitations of Usual Tools.
+                                                              (line 216)
+* termios POSIX headers:                 System Services.     (line  62)
+* test:                                  Limitations of Builtins.
+                                                              (line 191)
+* touch:                                 Limitations of Usual Tools.
+                                                              (line 338)
+* trap:                                  Limitations of Builtins.
+                                                              (line 272)
+* true:                                  Limitations of Builtins.
+                                                              (line 312)
+* undefined macro: _m4_divert_diversion: New Macros.          (line   6)
+* unset:                                 Limitations of Builtins.
+                                                              (line 323)
+* Variable, Precious:                    Setting Output Variables.
+                                                              (line  44)
+* Version:                               Notices.             (line  10)
+* VPATH:                                 Limitations of Make. (line  31)
+* Zsh:                                   Shellology.          (line  49)
+
+
+
+Tag Table:
+Node: Top1982
+Node: Introduction14243
+Ref: Introduction-Footnote-119088
+Ref: Introduction-Footnote-219169
+Ref: Introduction-Footnote-319269
+Ref: Introduction-Footnote-419383
+Node: The GNU build system19458
+Node: Automake20377
+Node: Libtool22803
+Node: Pointers24229
+Ref: Pointers-Footnote-125435
+Ref: Pointers-Footnote-225494
+Ref: Pointers-Footnote-325551
+Ref: Pointers-Footnote-425693
+Ref: Pointers-Footnote-525767
+Ref: Pointers-Footnote-625839
+Node: Making configure Scripts25914
+Node: Writing configure.ac28948
+Node: Shell Script Compiler30414
+Node: Autoconf Language32715
+Node: configure.ac Layout37347
+Node: autoscan Invocation38751
+Node: ifnames Invocation41504
+Node: autoconf Invocation42704
+Node: autoreconf Invocation49781
+Node: Setup53123
+Node: Notices54328
+Node: Input55964
+Node: Output58012
+Node: Configuration Actions59994
+Node: Configuration Files62899
+Node: Makefile Substitutions64365
+Node: Preset Output Variables66048
+Node: Installation Directory Variables70619
+Node: Build Directories74971
+Node: Automatic Remaking76624
+Node: Configuration Headers78779
+Node: Header Templates81482
+Node: autoheader Invocation82760
+Node: Autoheader Macros86228
+Node: Configuration Commands88431
+Node: Configuration Links90117
+Node: Subdirectories91489
+Node: Default Prefix93644
+Node: Existing Tests95041
+Node: Common Behavior96759
+Node: Standard Symbols97421
+Node: Default Includes98022
+Node: Alternative Programs99954
+Node: Particular Programs100640
+Node: Generic Programs106101
+Node: Files110010
+Node: Libraries110905
+Node: Library Functions113770
+Node: Function Portability114393
+Node: Particular Functions115398
+Node: Generic Functions125990
+Node: Header Files130235
+Node: Particular Headers130798
+Node: Generic Headers137767
+Node: Declarations139839
+Node: Particular Declarations140428
+Node: Generic Declarations140851
+Node: Structures143224
+Node: Particular Structures143831
+Node: Generic Structures145553
+Node: Types146797
+Node: Particular Types147317
+Node: Generic Types148487
+Node: Compilers and Preprocessors149859
+Node: Generic Compiler Characteristics150870
+Node: C Compiler151733
+Node: C++ Compiler159074
+Node: Fortran 77 Compiler161317
+Node: System Services169814
+Ref: System Services-Footnote-1172930
+Node: UNIX Variants173021
+Node: Writing Tests174203
+Node: Examining Declarations176135
+Node: Examining Syntax178635
+Node: Examining Libraries180083
+Node: Run Time183095
+Node: Test Programs184076
+Node: Guidelines186343
+Node: Test Functions187542
+Node: Systemology189098
+Ref: Systemology-Footnote-1189726
+Ref: Systemology-Footnote-2189764
+Node: Multiple Cases189832
+Node: Language Choice191089
+Node: Results193124
+Node: Defining Symbols193874
+Node: Setting Output Variables197130
+Node: Caching Results201321
+Node: Cache Variable Names205004
+Node: Cache Files206593
+Node: Cache Checkpointing208623
+Node: Printing Messages209954
+Node: Programming in M4213139
+Node: M4 Quotation213812
+Node: Active Characters214622
+Ref: Active Characters-Footnote-1216000
+Node: One Macro Call216022
+Node: Quotation and Nested Macros217584
+Node: Quadrigraphs220550
+Node: Quotation Rule Of Thumb221475
+Node: Programming in M4sugar224118
+Node: Redefined M4 Macros224626
+Node: Forbidden Patterns225596
+Node: Writing Autoconf Macros226961
+Node: Macro Definitions227762
+Node: Macro Names229570
+Node: Reporting Messages232171
+Node: Dependencies Between Macros233517
+Node: Prerequisite Macros234141
+Node: Suggested Ordering236922
+Node: Obsoleting Macros238441
+Node: Coding Style239564
+Node: Portable Shell246570
+Node: Shellology248656
+Node: Here-Documents251635
+Node: File Descriptors253597
+Node: File System Conventions255605
+Ref: File System Conventions-Footnote-1259725
+Node: Shell Substitutions259799
+Node: Assignments264708
+Node: Special Shell Variables266345
+Node: Limitations of Builtins270391
+Node: Limitations of Usual Tools282719
+Node: Limitations of Make295462
+Node: Manual Configuration296443
+Node: Specifying Names297272
+Ref: Specifying Names-Footnote-1300083
+Node: Canonicalizing300483
+Node: Using System Type302887
+Node: Site Configuration303936
+Node: External Software304769
+Node: Package Options308085
+Node: Pretty Help Strings310953
+Node: Site Details312932
+Node: Transforming Names314167
+Node: Transformation Options315315
+Node: Transformation Examples315819
+Node: Transformation Rules317541
+Node: Site Defaults319377
+Node: Running configure scripts323296
+Node: Basic Installation324313
+Node: Compilers and Options327161
+Node: Multiple Architectures327803
+Node: Installation Names328802
+Node: Optional Features330001
+Node: System Type330785
+Node: Sharing Defaults332311
+Node: Environment Variables332953
+Node: configure Invocation333639
+Node: config.status Invocation334771
+Node: Obsolete Constructs338596
+Node: Obsolete config.status Use339522
+Node: acconfig.h341321
+Node: autoupdate Invocation343337
+Node: Obsolete Macros345299
+Node: Autoconf 1362452
+Node: Changed File Names363518
+Node: Changed Makefiles364293
+Node: Changed Macros365386
+Node: Changed Results366642
+Node: Changed Macro Writing368753
+Node: Autoconf 2.13370028
+Node: Changed Quotation371037
+Node: New Macros372944
+Node: Questions374578
+Node: Distributing375102
+Node: Why GNU m4376173
+Node: Bootstrapping377071
+Node: Why Not Imake377687
+Node: History382392
+Node: Genesis383191
+Node: Exodus384387
+Node: Leviticus387438
+Node: Numbers388972
+Node: Deuteronomy390893
+Node: Environment Variable Index393565
+Node: Output Variable Index397608
+Node: Preprocessor Symbol Index407637
+Node: Autoconf Macro Index418644
+Node: M4 Macro Index441976
+Node: Concept Index442663
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
new file mode 100644
index 0000000..2728b2f
--- /dev/null
+++ b/doc/autoconf.texi
@@ -0,0 +1,11346 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename autoconf.info
+@settitle Autoconf
+
+@finalout
+@setchapternewpage odd
+@setcontentsaftertitlepage
+
+@include version.texi
+
+@c A simple macro for optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+
+@c I don't like the way URL are displayed in TeX with @uref.
+@ifhtml
+@macro href{url, title}
+@uref{\url\, \title\}
+@end macro
+@end ifhtml
+@ifnothtml
+@macro href{url, title}
+\title\@footnote{\title\, @url{\url\}.}
+@end macro
+@end ifnothtml
+
+
+@dircategory GNU admin
+@direntry
+* Autoconf: (autoconf).         Create source code configuration scripts
+@end direntry
+
+@dircategory Individual utilities
+@direntry
+* autoscan: (autoconf)autoscan Invocation.
+                                Semi-automatic @file{configure.ac} writing
+* ifnames: (autoconf)ifnames Invocation.
+                                Listing the conditionals in source code
+* autoconf: (autoconf)autoconf Invocation.
+                                How to create configuration scripts
+* autoreconf: (autoconf)autoreconf Invocation.
+                                Remaking multiple @code{configure} scripts
+* configure: (autoconf)configure Invocation.
+                                Configuring a package
+* config.status: (autoconf)config.status Invocation.
+                                Recreating a configuration
+@end direntry
+
+@ifinfo
+Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie.
+
+This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and an @code{m4} macro
+package.
+ 
+Copyright 2003-2022,2023	Thomas E. Dickey@*
+Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 Free
+Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+@end ifinfo
+
+@titlepage
+@title Autoconf
+@subtitle Creating Automatic Configuration Scripts
+@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION}
+@subtitle @value{UPDATED}
+@author David MacKenzie and Ben Elliston
+@c I think I've rewritten all of Noah and Roland's contributions by now.
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
+2001 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+@end titlepage
+
+@c Define an environment variable index.
+@defcodeindex ev
+@c Define an output variable index.
+@defcodeindex ov
+@c Define a CPP variable index.
+@defcodeindex cv
+@c Define an Autoconf macro index that @defmac doesn't write to.
+@defcodeindex ma
+@c Define an M4sugar macro index that @defmac doesn't write to.
+@defcodeindex ms
+
+@node Top, Introduction, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+
+@ifinfo
+This file documents the GNU Autoconf package for creating scripts to
+configure source code packages using templates and the GNU M4 macro
+package.  This is edition @value{EDITION}, for Autoconf version
+@value{VERSION}.
+
+@end ifinfo
+
+@c The master menu, created with texinfo-master-menu, goes here.
+
+@menu
+* Introduction::                Autoconf's purpose, strengths, and weaknesses
+* The GNU build system::        A set of tools for portable software packages
+* Making configure Scripts::    How to organize and produce Autoconf scripts
+* Setup::                       Initialization and output
+* Existing Tests::              Macros that check for particular features
+* Writing Tests::               How to write new feature checks
+* Results::                     What to do with results from feature checks
+* Programming in M4::           Layers on top of which Autoconf is written
+* Writing Autoconf Macros::     Adding new macros to Autoconf
+* Portable Shell::              Shell script portability pitfalls
+* Manual Configuration::        Selecting features that can't be guessed
+* Site Configuration::          Local defaults for @code{configure}
+* Running configure scripts::   How to use the Autoconf output
+* config.status Invocation::    Recreating a configuration
+* Obsolete Constructs::         Kept for backward compatibility
+* Questions::                   Questions about Autoconf, with answers
+* History::                     History of Autoconf
+* Environment Variable Index::  Index of environment variables used
+* Output Variable Index::       Index of variables set in output files
+* Preprocessor Symbol Index::   Index of C preprocessor symbols defined
+* Autoconf Macro Index::        Index of Autoconf macros
+* M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
+* Concept Index::               General index
+
+@detailmenu --- The Detailed Node Listing ---
+
+The GNU build system
+
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+
+Making @code{configure} Scripts
+
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic @file{configure.ac} writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple @code{configure} scripts
+
+Writing @file{configure.ac}
+
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+
+Initialization and Output Files
+
+* Notices::                     Copyright, version numbers in @code{configure}
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in @file{Makefile}s
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+
+Substitutions in Makefiles
+
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+
+Configuration Header Files
+
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+
+Existing Tests
+
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+
+Common Behavior
+
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+
+Alternative Programs
+
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+
+Library Functions
+
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+
+Header Files
+
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+
+Declarations
+
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+
+Structures
+
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+
+Types
+
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+
+Compilers and Preprocessors
+
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+
+Writing Tests
+
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+
+Checking Run Time Behavior
+
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+
+Results of Tests
+
+* Defining Symbols::            Defining C preprocessor symbols
+* Setting Output Variables::    Replacing variables in output files
+* Caching Results::             Speeding up subsequent @code{configure} runs
+* Printing Messages::           Notifying @code{configure} users
+
+Caching Results
+
+* Cache Variable Names::        Shell variables used in caches
+* Cache Files::                 Files @code{configure} uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
+
+Programming in M4
+
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+
+M4 Quotation
+
+* Active Characters::           Characters that change the behavior of m4
+* One Macro Call::              Quotation and one macro call
+* Quotation and Nested Macros::  Macros calling macros
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+
+Programming in M4sugar
+
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+
+Writing Autoconf Macros
+
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* Reporting Messages::          Notifying @code{autoconf} users
+* Dependencies Between Macros::  What to do when macros depend on other macros
+* Obsoleting Macros::           Warning about old ways of doing things
+* Coding Style::                Writing Autoconf macros @`a la Autoconf
+
+Dependencies Between Macros
+
+* Prerequisite Macros::         Ensuring required information
+* Suggested Ordering::          Warning about possible ordering problems
+
+Portable Shell Programming
+
+* Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
+* File Descriptors::            FDs and redirections
+* File System Conventions::     File- and pathnames
+* Shell Substitutions::         Variable and command expansions
+* Assignments::                 Varying side effects of assignments
+* Special Shell Variables::     Variables you should not change
+* Limitations of Builtins::     Portable use of not so portable /bin/sh
+* Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
+
+Manual Configuration
+
+* Specifying Names::            Specifying the system type
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+
+Site Configuration
+
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving @code{configure} local defaults
+
+Transforming Program Names When Installing
+
+* Transformation Options::      @code{configure} options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        @file{Makefile} uses of transforming names
+
+Running @code{configure} Scripts
+
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for @code{configure}
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how @code{configure} runs
+
+Obsolete Constructs
+
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in @file{config.h.in}
+* autoupdate Invocation::       Automatic update of @file{configure.ac}
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+
+Upgrading From Version 1
+
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in @file{Makefile.in}
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+
+Upgrading From Version 2.13
+
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+
+Questions About Autoconf
+
+* Distributing::                Distributing @code{configure} scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses @code{configure} instead of Imake
+
+History of Autoconf
+
+* Genesis::                     Prehistory and naming of @code{configure}
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+
+@end detailmenu
+@end menu
+
+@c ============================================================= Introduction.
+
+@node Introduction, The GNU build system, Top, Top
+@chapter Introduction
+
+@flushright
+A physicist, an engineer, and a computer scientist were discussing the
+nature of God.  ``Surely a Physicist,'' said the physicist, ``because
+early in the Creation, God made Light; and you know, Maxwell's
+equations, the dual nature of electromagnetic waves, the relativistic
+consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
+before making Light, God split the Chaos into Land and Water; it takes a
+hell of an engineer to handle that big amount of mud, and orderly
+separation of solids from liquids@dots{}'' The computer scientist
+shouted: ``And the Chaos, where do you think it was coming from, hmm?''
+
+---Anonymous
+@end flushright
+@c (via Franc,ois Pinard)
+
+Autoconf is a tool for producing shell scripts that automatically
+configure software source code packages to adapt to many kinds of
+@sc{unix}-like systems.  The configuration scripts produced by Autoconf
+are independent of Autoconf when they are run, so their users do not
+need to have Autoconf.
+
+The configuration scripts produced by Autoconf require no manual user
+intervention when run; they do not normally even need an argument
+specifying the system type.  Instead, they individually test for the
+presence of each feature that the software package they are for might need.
+(Before each check, they print a one-line message stating what they are
+checking for, so the user doesn't get too bored while waiting for the
+script to finish.)  As a result, they deal well with systems that are
+hybrids or customized from the more common @sc{unix} variants.  There is
+no need to maintain files that list the features supported by each
+release of each variant of @sc{unix}.
+
+For each software package that Autoconf is used with, it creates a
+configuration script from a template file that lists the system features
+that the package needs or can use.  After the shell code to recognize
+and respond to a system feature has been written, Autoconf allows it to
+be shared by many software packages that can use (or need) that feature.
+If it later turns out that the shell code needs adjustment for some
+reason, it needs to be changed in only one place; all of the
+configuration scripts can be regenerated automatically to take advantage
+of the updated code.
+
+The Metaconfig package is similar in purpose to Autoconf, but the
+scripts it produces require manual user intervention, which is quite
+inconvenient when configuring large source trees.  Unlike Metaconfig
+scripts, Autoconf scripts can support cross-compiling, if some care is
+taken in writing them.
+
+Autoconf does not solve all problems related to making portable software
+packages---for a more complete solution, it should be used in concert
+with other GNU build tools like Automake and Libtool.  These other tools
+take on jobs like the creation of a portable, recursive @file{Makefile}
+with all of the standard targets, linking of shared libraries, and so
+on.  @xref{The GNU build system}, for more information.
+
+Autoconf imposes some restrictions on the names of macros used with
+@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
+
+Autoconf requires @sc{gnu} M4 in order to generate the scripts.  It uses
+features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3,
+do not have.  You must use version 1.4 or later of @sc{gnu} M4.
+
+@xref{Autoconf 1}, for information about upgrading from version 1.
+@xref{History}, for the story of Autoconf's development.
+@xref{Questions}, for answers to some common questions about Autoconf.
+
+
+See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
+Autoconf web page} for up-to-date information, details on the mailing
+lists, pointers to a list of known bugs, etc.
+
+Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
+list}.
+
+Bug reports should be preferably submitted to the
+@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf,
+Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
+Autoconf Bugs mailing list}.  If possible, first check that your bug is
+not already solved in current development versions, and that it has not
+been reported yet.  Be sure to include all the needed information and a
+short @file{configure.ac} that demonstrates the problem.
+
+Autoconf's development tree is accessible via @sc{cvs}; see the Autoconf
+web page for details.  There is also a
+@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web
+interface to the Autoconf development tree}.  Patches relative to the
+current @sc{cvs} version can be sent for review to the
+@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
+
+Because of its mission, Autoconf includes only a set of often-used
+macros that have already demonstrated their usefulness.  Nevertheless,
+if you wish to share your macros, or find existing ones, see the
+@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
+Archive}, which is kindly run by @email{simons@@computer.org,
+Peter Simons}.
+
+
+@c ================================================= The GNU build system
+
+@node The GNU build system, Making configure Scripts, Introduction, Top
+@chapter The GNU build system
+
+Autoconf solves an important problem---reliable discovery of
+system-specific build and runtime information---but this is only one
+piece of the puzzle for the development of portable software.  To this
+end, the GNU project has developed a suite of integrated utilities to
+finish the job Autoconf started: the GNU build system, whose most
+important components are Autoconf, Automake, and Libtool.  In this
+chapter, we introduce you to those tools, point you to sources of more
+information, and try to convince you to use the entire GNU build system
+for your software.
+
+@menu
+* Automake::                    Escaping Makefile hell
+* Libtool::                     Building libraries portably
+* Pointers::                    More info on the GNU build system
+@end menu
+
+@node Automake, Libtool, The GNU build system, The GNU build system
+@section Automake
+
+The ubiquity of @code{make} means that a @code{Makefile} is almost the
+only viable way to distribute automatic build rules for software, but
+one quickly runs into @code{make}'s numerous limitations.  Its lack of
+support for automatic dependency tracking, recursive builds in
+subdirectories, reliable timestamps (e.g. for network filesystems), and
+so on, mean that developers must painfully (and often incorrectly)
+reinvent the wheel for each project.  Portability is non-trivial, thanks
+to the quirks of @code{make} on many systems.  On top of all this is the
+manual labor required to implement the many standard targets that users
+have come to expect (@code{make install}, @code{make distclean},
+@code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
+you also have to insert repetitive code in your @code{Makefile.in} to
+recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
+provided by @code{configure}.  Into this mess steps @dfn{Automake}.
+@cindex Automake
+
+Automake allows you to specify your build needs in a @code{Makefile.am}
+file with a vastly simpler and more powerful syntax than that of a plain
+@code{Makefile}, and then generates a portable @code{Makefile.in} for
+use with Autoconf.  For example, the @code{Makefile.am} to build and
+install a simple ``Hello world'' program might look like:
+
+@example
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c
+@end example
+
+@noindent
+The resulting @code{Makefile.in} (~400 lines) automatically supports all
+the standard targets, the substitutions provided by Autoconf, automatic
+dependency tracking, @code{VPATH} building, and so on.  @code{make} will
+build the @code{hello} program, and @code{make install} will install it
+in @file{/usr/local/bin} (or whatever prefix was given to
+@code{configure}, if not @file{/usr/local}).
+
+Automake may require that additional tools be present on the
+@emph{developer's} machine.  For example, the @code{Makefile.in} that
+the developer works with may not be portable (e.g. it might use special
+features of your compiler to automatically generate dependency
+information).  Running @code{make dist}, however, produces a
+@file{hello-1.0.tar.gz} package (or whatever the program/version is)
+with a @code{Makefile.in} that will work on any system.
+
+The benefits of Automake increase for larger packages (especially ones
+with subdirectories), but even for small programs the added convenience
+and portability can be substantial.  And that's not all@dots{}
+
+@node Libtool, Pointers, Automake, The GNU build system
+@section Libtool
+
+Very often, one wants to build not only programs, but libraries, so that
+other programs can benefit from the fruits of your labor.  Ideally, one
+would like to produce @emph{shared} (dynamically-linked) libraries,
+which can be used by multiple programs without duplication on disk or in
+memory and can be updated independently of the linked programs.
+Producing shared libraries portably, however, is the stuff of
+nightmares---each system has its own incompatible tools, compiler flags,
+and magic incantations.  Fortunately, GNU provides a solution:
+@dfn{Libtool}.
+@cindex Libtool
+
+Libtool handles all the requirements of building shared libraries for
+you, and at this time seems to be the @emph{only} way to do so with any
+portability.  It also handles many other headaches, such as: the
+interaction of @code{Makefile} rules with the variable suffixes of
+shared libraries, linking reliably to shared libraries before they are
+installed by the superuser, and supplying a consistent versioning system
+(so that different versions of a library can be installed or upgraded
+without breaking binary compatibility).  Although Libtool, like
+Autoconf, can be used on its own, it is most simply utilized in
+conjunction with Automake---there, Libtool is used automatically
+whenever shared libraries are needed, and you need not know its syntax.
+
+@node Pointers,  , Libtool, The GNU build system
+@section Pointers
+
+Developers who are used to the simplicity of @code{make} for small
+projects on a single system might be daunted at the prospect of learning
+to use Automake and Autoconf.  As your software is distributed to more
+and more users, however, you will otherwise quickly find yourself
+putting lots of effort into reinventing the services that the GNU build
+tools provide, and making the same mistakes that they once made and
+overcame.  (Besides, since you're already learning Autoconf, Automake
+will be a piece of cake.)
+
+There are a number of places that you can go to for more information on
+the GNU build tools.
+
+@itemize @minus
+
+@item Web
+
+The home pages for
+@href{http://www.gnu.org/software/autoconf/,Autoconf}, and
+@href{http://www.gnu.org/software/libtool/,Libtool}.
+
+@item Books
+
+The book @cite{GNU Autoconf, Automake and Libtool}@footnote{@cite{GNU
+Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston,
+T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.}
+describes the complete GNU build environment.  You can also find the
+entire book on-line at @href{http://sources.redhat.com/autobook/,``The
+Goat Book'' home page}.
+
+@item Tutorials and Examples
+
+The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
+maintains links to a number of Autoconf/Automake tutorials online, and
+also links to the @href{http://www.gnu.org/software/ac-archive/,
+Autoconf Macro Archive}.
+
+@end itemize
+
+@c ================================================= Making configure Scripts.
+
+@node Making configure Scripts, Setup, The GNU build system, Top
+@chapter Making @code{configure} Scripts
+@cindex @file{aclocal.m4}
+@cindex @code{configure}
+
+The configuration scripts that Autoconf produces are by convention
+called @code{configure}.  When run, @code{configure} creates several
+files, replacing configuration parameters in them with appropriate
+values.  The files that @code{configure} creates are:
+
+@itemize @minus
+@item
+one or more @file{Makefile} files, one in each subdirectory of the
+package (@pxref{Makefile Substitutions});
+
+@item
+optionally, a C header file, the name of which is configurable,
+containing @code{#define} directives (@pxref{Configuration Headers});
+
+@item
+a shell script called @file{config.status} that, when run, will recreate
+the files listed above (@pxref{config.status Invocation});
+
+@item
+an optional shell script normally called @file{config.cache}
+(created when using @samp{configure --config-cache}) that
+saves the results of running many of the tests (@pxref{Cache Files});
+
+@item
+a file called @file{config.log} containing any messages produced by
+compilers, to help debugging if @code{configure} makes a mistake.
+@end itemize
+
+@cindex @file{configure.in}
+@cindex @file{configure.ac}
+To create a @code{configure} script with Autoconf, you need to write an
+Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
+@code{autoconf} on it.  If you write your own feature tests to
+supplement those that come with Autoconf, you might also write files
+called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
+file to contain @code{#define} directives, you might also run
+@code{autoheader}, and you will distribute the generated file
+@file{config.h.in} with the package.
+
+Here is a diagram showing how the files that can be used in
+configuration are produced.  Programs that are executed are suffixed by
+@samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
+@code{autoconf} and @code{autoheader} also read the installed Autoconf
+macro files (by reading @file{autoconf.m4}).
+
+@noindent
+Files used in preparing a software package for distribution:
+@example
+your source files --> [autoscan*] --> [configure.scan] --> configure.ac
+
+@group
+configure.ac --.
+               |   .------> autoconf* -----> configure
+[aclocal.m4] --+---+
+               |   `-----> [autoheader*] --> [config.h.in]
+[acsite.m4] ---'
+@end group
+
+Makefile.in -------------------------------> Makefile.in
+@end example
+
+@noindent
+Files used in configuring a software package:
+@example
+@group
+                       .-------------> [config.cache]
+configure* ------------+-------------> config.log
+                       |
+[config.h.in] -.       v            .-> [config.h] -.
+               +--> config.status* -+               +--> make*
+Makefile.in ---'                    `-> Makefile ---'
+@end group
+@end example
+
+@menu
+* Writing configure.ac::        What to put in an Autoconf input file
+* autoscan Invocation::         Semi-automatic @file{configure.ac} writing
+* ifnames Invocation::          Listing the conditionals in source code
+* autoconf Invocation::         How to create configuration scripts
+* autoreconf Invocation::       Remaking multiple @code{configure} scripts
+@end menu
+
+@node Writing configure.ac, autoscan Invocation, Making configure Scripts, Making configure Scripts
+@section Writing @file{configure.ac}
+
+To produce a @code{configure} script for a software package, create a
+file called @file{configure.ac} that contains invocations of the
+Autoconf macros that test the system features your package needs or can
+use.  Autoconf macros already exist to check for many features; see
+@ref{Existing Tests}, for their descriptions.  For most other features,
+you can use Autoconf template macros to produce custom checks; see
+@ref{Writing Tests}, for information about them.  For especially tricky
+or specialized features, @file{configure.ac} might need to contain some
+hand-crafted shell commands; see @ref{Portable Shell}.  The
+@code{autoscan} program can give you a good start in writing
+@file{configure.ac} (@pxref{autoscan Invocation}, for more information).
+
+Previous versions of Autoconf promoted the name @file{configure.in},
+which is somewhat ambiguous (the tool needed to produce this file is not
+described by its extension), and introduces a slight confusion with
+@file{config.h.in} and so on (for which @samp{.in} means ``to be
+processed by @code{configure}'').  Using @file{configure.ac} is now
+preferred.
+
+@menu
+* Shell Script Compiler::       Autoconf as solution of a problem
+* Autoconf Language::           Programming in Autoconf
+* configure.ac Layout::         Standard organization of configure.ac
+@end menu
+
+@node Shell Script Compiler, Autoconf Language, Writing configure.ac, Writing configure.ac
+@subsection A Shell Script Compiler
+
+Just as for any other computer language, in order to properly program
+@file{configure.ac} in Autoconf you must understand @emph{what} problem
+the language tries to address and @emph{how} it does so.
+
+The problem Autoconf addresses is that the world is a mess.  After all,
+you are using Autoconf in order to have your package compile easily on
+all sorts of different systems, some of them being extremely hostile.
+Autoconf itself bears the price for these differences: @code{configure}
+must run on all those systems, and thus @code{configure} must limit itself
+to their lowest common denominator of features.
+
+Naturally, you might then think of shell scripts; who needs
+@code{autoconf}?  A set of properly written shell functions is enough to
+make it easy to write @code{configure} scripts by hand.  Sigh!
+Unfortunately, shell functions do not belong to the least common
+denominator; therefore, where you would like to define a function and
+use it ten times, you would instead need to copy its body ten times.
+
+So, what is really needed is some kind of compiler, @code{autoconf},
+that takes an Autoconf program, @file{configure.ac}, and transforms it
+into a portable shell script, @code{configure}.
+
+How does @code{autoconf} perform this task?
+
+There are two obvious possibilities: creating a brand new language or
+extending an existing one.  The former option is very attractive: all
+sorts of optimizations could easily be implemented in the compiler and
+many rigorous checks could be performed on the Autoconf program
+(e.g. rejecting any non-portable construct).  Alternatively, you can
+extend an existing language, such as the @code{sh} (Bourne shell)
+language.
+
+Autoconf does the latter: it is a layer on top of @code{sh}.  It was
+therefore most convenient to implement @code{autoconf} as a macro
+expander: a program that repeatedly performs @dfn{macro expansions} on
+text input, replacing macro calls with macro bodies and producing a pure
+@code{sh} script in the end.  Instead of implementing a dedicated
+Autoconf macro expander, it is natural to use an existing
+general-purpose macro language, such as M4, and implement the extensions
+as a set of M4 macros.
+
+
+@node Autoconf Language, configure.ac Layout, Shell Script Compiler, Writing configure.ac
+@subsection The Autoconf Language
+@cindex quotation
+
+The Autoconf language is very different from many other computer
+languages because it treats actual code the same as plain text.  Whereas
+in C, for instance, data and instructions have very different syntactic
+status, in Autoconf their status is rigorously the same.  Therefore, we
+need a means to distinguish literal strings from text to be expanded:
+quotation.
+
+When calling macros that take arguments, there must not be any blank
+space between the macro name and the open parenthesis.  Arguments should
+be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
+separated by commas.  Any leading spaces in arguments are ignored,
+unless they are quoted.  You may safely leave out the quotes when the
+argument is simple text, but @emph{always} quote complex arguments such
+as other macro calls.  This rule applies recursively for every macro
+call, including macros called from other macros.
+
+For instance:
+
+@example
+AC_CHECK_HEADER([stdio.h],
+                [AC_DEFINE([HAVE_STDIO_H])],
+                [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+is quoted properly.  You may safely simplify its quotation to:
+
+@example
+AC_CHECK_HEADER(stdio.h,
+                [AC_DEFINE(HAVE_STDIO_H)],
+                [AC_MSG_ERROR([Sorry, can't do anything for you])])
+@end example
+
+@noindent
+Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
+otherwise, its comma would have been interpreted as an argument separator.
+
+The following example is wrong and dangerous, as it is underquoted:
+
+@example
+AC_CHECK_HEADER(stdio.h,
+                AC_DEFINE(HAVE_STDIO_H),
+                AC_MSG_ERROR([Sorry, can't do anything for you]))
+@end example
+
+In other cases, you may have to use text that also resembles a macro
+call.  You must quote that text even when it is not passed as a macro
+argument:
+
+@example
+echo "Hard rock was here!  --[AC_DC]"
+@end example
+
+@noindent
+which will result in
+
+@example
+echo "Hard rock was here!  --AC_DC"
+@end example
+
+@noindent
+When you use the same text in a macro argument, you must therefore have
+an extra quotation level (since one is stripped away by the macro
+substitution).  In general, then, it is a good idea to @emph{use double
+quoting for all literal string arguments}:
+
+@example
+AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
+@end example
+
+You are now able to understand one of the constructs of Autoconf that
+has been continually misunderstood@dots{}  The rule of thumb is that
+@emph{whenever you expect macro expansion, expect quote expansion};
+i.e., expect one level of quotes to be lost.  For instance:
+
+@example
+AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
+@end example
+
+@noindent
+is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
+@samp{char b[10];} and will be expanded once, which results in
+@samp{char b10;}.  (There was an idiom common in Autoconf's past to
+address this issue via the M4 @code{changequote} primitive, but do not
+use it!)  Let's take a closer look: the author meant the first argument
+to be understood as a literal, and therefore it must be quoted twice:
+
+@example
+AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
+@end example
+
+@noindent
+Voil@`a, you actually produce @samp{char b[10];} this time!
+
+The careful reader will notice that, according to these guidelines, the
+``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
+lacking three pairs of quotes!  Nevertheless, for the sake of readability,
+double quotation of literals is used only where needed in this manual.
+
+Some macros take optional arguments, which this documentation represents
+as @ovar{arg} (not to be confused with the quote characters).  You may
+just leave them empty, or use @samp{[]} to make the emptiness of the
+argument explicit, or you may simply omit the trailing commas.  The
+three lines below are equivalent:
+
+@example
+AC_CHECK_HEADERS(stdio.h, [], [], [])
+AC_CHECK_HEADERS(stdio.h,,,)
+AC_CHECK_HEADERS(stdio.h)
+@end example
+
+It is best to put each macro call on its own line in
+@file{configure.ac}.  Most of the macros don't add extra newlines; they
+rely on the newline after the macro call to terminate the commands.
+This approach makes the generated @code{configure} script a little
+easier to read by not inserting lots of blank lines.  It is generally
+safe to set shell variables on the same line as a macro call, because
+the shell allows assignments without intervening newlines.
+
+You can include comments in @file{configure.ac} files by starting them
+with the @samp{#}.  For example, it is helpful to begin
+@file{configure.ac} files with a line like this:
+
+@example
+# Process this file with autoconf to produce a configure script.
+@end example
+
+@node configure.ac Layout,  , Autoconf Language, Writing configure.ac
+@subsection Standard @file{configure.ac} Layout
+
+The order in which @file{configure.ac} calls the Autoconf macros is not
+important, with a few exceptions.  Every @file{configure.ac} must
+contain a call to @code{AC_INIT} before the checks, and a call to
+@code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
+rely on other macros having been called first, because they check
+previously set values of some variables to decide what to do.  These
+macros are noted in the individual descriptions (@pxref{Existing
+Tests}), and they also warn you when @code{configure} is created if they
+are called out of order.
+
+To encourage consistency, here is a suggested order for calling the
+Autoconf macros.  Generally speaking, the things near the end of this
+list are those that could depend on things earlier in it.  For example,
+library functions could be affected by types and libraries.
+
+@display
+@group
+Autoconf requirements
+@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
+information on the package
+checks for programs
+checks for libraries
+checks for header files
+checks for types
+checks for structures
+checks for compiler characteristics
+checks for library functions
+checks for system services
+@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
+@code{AC_OUTPUT}
+@end group
+@end display
+
+
+@node autoscan Invocation, ifnames Invocation, Writing configure.ac, Making configure Scripts
+@section Using @code{autoscan} to Create @file{configure.ac}
+@cindex @code{autoscan}
+
+The @code{autoscan} program can help you create and/or maintain a
+@file{configure.ac} file for a software package.  @code{autoscan}
+examines source files in the directory tree rooted at a directory given
+as a command line argument, or the current directory if none is given.
+It searches the source files for common portability problems and creates
+a file @file{configure.scan} which is a preliminary @file{configure.ac}
+for that package, and checks a possibly existing @file{configure.ac} for
+completeness.
+
+When using @command{autoscan} to create a @file{configure.ac}, you
+should manually examine @file{configure.scan} before renaming it to
+@file{configure.ac}; it will probably need some adjustments.
+Occasionally, @code{autoscan} outputs a macro in the wrong order
+relative to another macro, so that @code{autoconf} produces a warning;
+you need to move such macros manually.  Also, if you want the package to
+use a configuration header file, you must add a call to
+@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
+also have to change or add some @code{#if} directives to your program in
+order to make it work with Autoconf (@pxref{ifnames Invocation}, for
+information about a program that can help with that job).
+
+When using @command{autoscan} to maintain a @file{configure.ac}, simply
+consider adding its suggestions.  The file @file{autoscan.log} will
+contain detailed information on why a macro is requested.
+
+@code{autoscan} uses several data files (installed along with Autoconf)
+to determine which macros to output when it finds particular symbols in
+a package's source files.  These data files all have the same format:
+each line consists of a symbol, whitespace, and the Autoconf macro to
+output if that symbol is encountered.  Lines starting with @samp{#} are
+comments.
+
+@code{autoscan} is only installed if you already have Perl installed.
+@code{autoscan} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Print the names of the files it examines and the potentially interesting
+symbols it finds in them.  This output can be voluminous.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+@end table
+
+@node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts
+@section Using @code{ifnames} to List Conditionals
+@cindex @code{ifnames}
+
+@code{ifnames} can help you write @file{configure.ac} for a software
+package.  It prints the identifiers that the package already uses in C
+preprocessor conditionals.  If a package has already been set up to have
+some portability, @code{ifnames} can thus help you figure out what its
+@code{configure} needs to check for.  It may help fill in some gaps in a
+@file{configure.ac} generated by @code{autoscan} (@pxref{autoscan
+Invocation}).
+
+@code{ifnames} scans all of the C source files named on the command line
+(or the standard input, if none are given) and writes to the standard
+output a sorted list of all the identifiers that appear in those files
+in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
+directives.  It prints each identifier on a line, followed by a
+space-separated list of the files in which that identifier occurs.
+
+@noindent
+@code{ifnames} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+@end table
+
+@node autoconf Invocation, autoreconf Invocation, ifnames Invocation, Making configure Scripts
+@section Using @code{autoconf} to Create @code{configure}
+@cindex @code{autoconf}
+
+To create @code{configure} from @file{configure.ac}, run the
+@code{autoconf} program with no arguments.  @code{autoconf} processes
+@file{configure.ac} with the @code{m4} macro processor, using the
+Autoconf macros.  If you give @code{autoconf} an argument, it reads that
+file instead of @file{configure.ac} and writes the configuration script
+to the standard output instead of to @code{configure}.  If you give
+@code{autoconf} the argument @option{-}, it reads from the standard
+input instead of @file{configure.ac} and writes the configuration script
+to the standard output.
+
+The Autoconf macros are defined in several files.  Some of the files are
+distributed with Autoconf; @code{autoconf} reads them first.  Then it
+looks for the optional file @file{acsite.m4} in the directory that
+contains the distributed Autoconf macro files, and for the optional file
+@file{aclocal.m4} in the current directory.  Those files can contain
+your site's or the package's own Autoconf macro definitions
+(@pxref{Writing Autoconf Macros}, for more information).  If a macro is defined
+in more than one of the files that @code{autoconf} reads, the last
+definition it reads overrides the earlier ones.
+
+@code{autoconf} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package file @file{aclocal.m4} in directory @var{dir}
+instead of in the current directory.
+
+@item --output=@var{file}
+@itemx -o @var{file}
+Save output (script or trace) to @var{file}.  The file @option{-} stands
+for the standard output.
+
+@item --warnings=@var{category}
+@itemx -W @var{category}
+@evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list).  @xref{Reporting Messages}, macro
+@code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
+values include:
+
+@table @samp
+@item all
+report all the warnings
+
+@item none
+report none
+
+@item error
+treats warnings as errors
+
+@item no-@var{category}
+disable warnings falling into @var{category}
+@end table
+
+Warnings about @samp{syntax} are enabled by default, and the environment
+variable @code{WARNINGS}, a comma separated list of categories, is
+honored. @command{autoconf -W @var{category}} will actually
+behave as if you had run:
+
+@example
+autoconf --warnings=syntax,$WARNINGS,@var{category}
+@end example
+
+@noindent
+If you want to disable @command{autoconf}'s defaults and @code{WARNINGS},
+but (for example) enable the warnings about obsolete constructs, you
+would use @option{-W none,obsolete}.
+
+@cindex Back trace
+@cindex Macro invocation stack
+@command{autoconf} displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}.  For instance,
+on this @file{configure.ac}:
+
+@example
+AC_DEFUN([INNER],
+[AC_TRY_RUN([true])])
+
+AC_DEFUN([OUTER],
+[INNER])
+
+AC_INIT
+OUTER
+@end example
+
+@noindent
+you get:
+
+@example
+$ autoconf -Wcross
+configure.ac:8: warning: AC_TRY_RUN called without default \
+to allow cross compiling
+$ autoconf -Wcross,error
+configure.ac:8: error: AC_TRY_RUN called without default \
+to allow cross compiling
+acgeneral.m4:3044: AC_TRY_RUN is expanded from...
+configure.ac:2: INNER is expanded from...
+configure.ac:5: OUTER is expanded from...
+configure.ac:8: the top level
+@end example
+
+@item --trace=@var{macro}[:@var{format}]
+@itemx -t @var{macro}[:@var{format}]
+Do not create the @code{configure} script, but list the calls to
+@var{macro} according to the @var{format}.  Multiple @option{--trace}
+arguments can be used to list several macros.  Multiple @option{--trace}
+arguments for a single macro are not cumulative; instead, you should
+just make @var{format} as long as needed.
+
+The @var{format} is a regular string, with newlines if desired, and
+several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
+below for details on the @var{format}.
+
+@item --initialization
+@itemx -i
+By default, @option{--trace} does not trace the initialization of the
+Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
+results in a noticeable speedup, but can be disabled by this option.
+@end table
+
+
+It is often necessary to check the content of a @file{configure.ac}
+file, but parsing it yourself is extremely fragile and error-prone.  It
+is suggested that you rely upon @option{--trace} to scan
+@file{configure.ac}.
+
+The @var{format} of @option{--trace} can use the following special
+escapes:
+
+@table @samp
+@item $$
+The character @samp{$}.
+
+@item $f
+The filename from which @var{macro} is called.
+
+@item $l
+The line number from which @var{macro} is called.
+
+@item $d
+The depth of the @var{macro} call.  This is an M4 technical detail that
+you probably don't want to know about.
+
+@item $n
+The name of the @var{macro}.
+
+@item $@var{num}
+The @var{num}th argument of the call to @var{macro}.
+
+@item $@@
+@itemx $@var{sep}@@
+@itemx $@{@var{separator}@}@@
+All the arguments passed to @var{macro}, separated by the character
+@var{sep} or the string @var{separator} (@samp{,} by default).  Each
+argument is quoted, i.e. enclosed in a pair of square brackets.
+
+@item $*
+@itemx $@var{sep}*
+@itemx $@{@var{separator}@}*
+As above, but the arguments are not quoted.
+
+@item $%
+@itemx $@var{sep}%
+@itemx $@{@var{separator}@}%
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is @samp{:}.
+
+The escape @samp{$%} produces single-line trace outputs (unless you put
+newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
+not.
+@end table
+
+For instance, to find the list of variables that are substituted, use:
+
+@example
+@group
+$ autoconf -t AC_SUBST
+configure.ac:2:AC_SUBST:ECHO_C
+configure.ac:2:AC_SUBST:ECHO_N
+configure.ac:2:AC_SUBST:ECHO_T
+@i{More traces deleted}
+@end group
+@end example
+
+@noindent
+The example below highlights the difference between @samp{$@@},
+@samp{$*}, and @strong{$%}.
+
+@example
+@group
+$ cat configure.ac
+AC_DEFINE(This, is, [an
+[example]])
+$ autoconf -t 'AC_DEFINE:@@: $@@
+*: $*
+$: $%'
+@@: [This],[is],[an
+[example]]
+*: This,is,an
+[example]
+$: This:is:an [example]
+@end group
+@end example
+
+@noindent
+The @var{format} gives you a lot of freedom:
+
+@example
+@group
+$ autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'
+$ac_subst@{"ECHO_C"@} = "configure.ac:2";
+$ac_subst@{"ECHO_N"@} = "configure.ac:2";
+$ac_subst@{"ECHO_T"@} = "configure.ac:2";
+@i{More traces deleted}
+@end group
+@end example
+
+@noindent
+A long @var{separator} can be used to improve the readability of complex
+structures, and to ease its parsing (for instance when no single
+character is suitable as a separator)):
+
+@example
+@group
+$ autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'
+AUTOCONF|:::::|autoconf|:::::|$missing_dir
+@i{More traces deleted}
+@end group
+@end example
+
+@node autoreconf Invocation,  , autoconf Invocation, Making configure Scripts
+@section Using @code{autoreconf} to Update @code{configure} Scripts
+@cindex @code{autoreconf}
+
+If you have a lot of Autoconf-generated @code{configure} scripts, the
+@code{autoreconf} program can save you some work.  It runs
+@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to
+remake the Autoconf @code{configure} scripts and configuration header
+templates in the directory tree rooted at the current directory.  By
+default, it only remakes those files that are older than their
+@file{configure.ac} or (if present) @file{aclocal.m4}.  Since
+@code{autoheader} does not change the timestamp of its output file if
+the file wouldn't be changing, this is not necessarily the minimum
+amount of work.  If you install a new version of Autoconf, you can make
+@code{autoreconf} remake @emph{all} of the files by giving it the
+@option{--force} option.
+
+If you give @code{autoreconf} the @option{--autoconf-dir=@var{dir}} or
+@option{--localdir=@var{dir}} options, it passes them down to
+@code{autoconf} and @code{autoheader} (with relative paths adjusted
+properly).
+
+@code{autoreconf} does not support having, in the same directory tree,
+both directories that are parts of a larger package (sharing
+@file{aclocal.m4} and @file{acconfig.h}) and directories that are
+independent packages (each with their own @file{aclocal.m4} and
+@file{acconfig.h}).  It assumes that they are all part of the same
+package if you use @option{--localdir}, or that each directory is a
+separate package if you don't use it.  This restriction may be removed
+in the future.
+
+@xref{Automatic Remaking}, for @file{Makefile} rules to automatically
+remake @code{configure} scripts when their source files change.  That
+method handles the timestamps of configuration header templates
+properly, but does not pass @option{--autoconf-dir=@var{dir}} or
+@option{--localdir=@var{dir}}.
+
+@noindent
+@code{autoreconf} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+Print the name of each directory where @code{autoreconf} runs
+@code{autoconf} (and @code{autoheader}, if appropriate).
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --force
+@itemx -f
+Remake even @file{configure} scripts and configuration headers that are
+newer than their input files (@file{configure.ac} and, if present,
+@file{aclocal.m4}).
+
+@item --install
+@itemx -i
+Copy missing auxiliary files.  This option is similar to the option
+@code{--add-missing} in other tools.
+
+@item --symlink
+@itemx -s
+Instead of copying missing auxiliary files, install symbolic links.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Have @code{autoconf} and @code{autoheader} look for the package files
+@file{aclocal.m4} and (@code{autoheader} only) @file{acconfig.h} (but
+not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
+@var{dir} instead of in the directory containing each @file{configure.ac}.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --m4dir=@var{dir}
+@itemx -M @var{dir}
+Specify location of additional macro files (@file{m4} by default).
+@end table
+
+
+@c ========================================= Initialization and Output Files.
+
+@node Setup, Existing Tests, Making configure Scripts, Top
+@chapter Initialization and Output Files
+
+Autoconf-generated @code{configure} scripts need some information about
+how to initialize, such as how to find the package's source files; and
+about the output files to produce.  The following sections describe
+initialization and the creation of output files.
+
+@menu
+* Notices::                     Copyright, version numbers in @code{configure}
+* Input::                       Where Autoconf should find files
+* Output::                      Outputting results from the configuration
+* Configuration Actions::       Preparing the output based on results
+* Configuration Files::         Creating output files
+* Makefile Substitutions::      Using output variables in @file{Makefile}s
+* Configuration Headers::       Creating a configuration header file
+* Configuration Commands::      Running arbitrary instantiation commands
+* Configuration Links::         Links depending from the configuration
+* Subdirectories::              Configuring independent packages together
+* Default Prefix::              Changing the default installation prefix
+@end menu
+
+@node Notices, Input, Setup, Setup
+@section Notices in @code{configure}
+
+The following macros manage version numbers for @code{configure}
+scripts.  Using them is optional.
+
+@c FIXME: AC_PREREQ should not be here, but where should it go?
+@defmac AC_PREREQ (@var{version})
+@maindex PREREQ
+@cindex Version
+Ensure that a recent enough version of Autoconf is being used.  If the
+version of Autoconf being used to create @code{configure} is earlier
+than @var{version}, print an error message to the standard error output
+and do not create @code{configure}.  For example:
+
+@example
+AC_PREREQ(@value{VERSION})
+@end example
+
+This macro is the only macro that may be used before @code{AC_INIT}, but
+for consistency, you are invited not to do so.
+@end defmac
+
+@defmac AC_COPYRIGHT (@var{copyright-notice})
+@maindex COPYRIGHT
+@cindex Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the Autoconf macros, parts of your @code{configure} are covered by the
+@var{copyright-notice}.
+
+The @var{copyright-notice} will show up in both the head of
+@code{configure} and in @samp{configure --version}.
+@end defmac
+
+
+@defmac AC_REVISION (@var{revision-info})
+@maindex REVISION
+@cindex Revision
+Copy revision stamp @var{revision-info} into the @code{configure}
+script, with any dollar signs or double-quotes removed.  This macro lets
+you put a revision stamp from @file{configure.ac} into @code{configure}
+without @sc{rcs} or @code{cvs} changing it when you check in
+@code{configure}.  That way, you can determine easily which revision of
+@file{configure.ac} a particular @code{configure} corresponds to.
+
+For example, this line in @file{configure.ac}:
+
+@c The asis prevents RCS from changing the example in the manual.
+@example
+AC_REVISION($@asis{Revision: 1.30 }$)
+@end example
+
+@noindent
+produces this in @code{configure}:
+
+@example
+#! /bin/sh
+# From configure.ac Revision: 1.30
+@end example
+@end defmac
+
+
+@node Input, Output, Notices, Setup
+@section Finding @code{configure} Input
+
+Every @code{configure} script must call @code{AC_INIT} before doing
+anything else.  The only other required macro is @code{AC_OUTPUT}
+(@pxref{Output}).
+
+@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report-address})
+@maindex INIT
+Process any command-line arguments and perform various initializations
+and verifications.  Set the name of the @var{package} and its
+@var{version}.  The optional argument @var{bug-report-address} should be
+the email to which users should send bug reports.
+@end defmac
+
+@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
+@maindex CONFIG_SRCDIR
+@var{unique-file-in-source-dir} is some file that is in the package's
+source directory; @code{configure} checks for this file's existence to
+make sure that the directory that it is told contains the source code in
+fact does.  Occasionally people accidentally specify the wrong directory
+with @option{--srcdir}; this is a safety check.  @xref{configure
+Invocation}, for more information.
+@end defmac
+
+
+@c FIXME: Remove definitively once --install explained.
+@c
+@c Small packages may store all their macros in @code{aclocal.m4}.  As the
+@c set of macros grows, or for maintenance reasons, a maintainer may prefer
+@c to split the macros in several files.  In this case, Autoconf must be
+@c told which files to load, and in which order.
+@c
+@c @defmac AC_INCLUDE (@var{file}@dots{})
+@c @maindex INCLUDE
+@c @c FIXME: There is no longer shell globbing.
+@c Read the macro definitions that appear in the listed files.  A list of
+@c space-separated filenames or shell globbing patterns is expected.  The
+@c files will be read in the order they're listed.
+@c
+@c Because the order of definition of macros is important (only the last
+@c definition of a macro is used), beware that it is @code{AC_INIT} that
+@c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
+@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
+@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
+@c the latter case, non-macro lines from included files may end up in the
+@c @file{configure} script, whereas in the former case, they'd be discarded
+@c just like any text that appear before @code{AC_INIT}.
+@c @end defmac
+
+Packages that do manual configuration or use the @code{install} program
+might need to tell @code{configure} where to find some other shell
+scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
+it looks are correct for most cases.
+
+@defmac AC_CONFIG_AUX_DIR (@var{dir})
+@maindex CONFIG_AUX_DIR
+Use the auxiliary build tools (e.g., @file{install-sh},
+@file{config.sub}, @file{config.guess}, Cygnus @code{configure},
+Automake and Libtool scripts etc.) that are in directory @var{dir}.
+These are auxiliary files used in configuration.  @var{dir} can be
+either absolute or relative to @file{@var{srcdir}}.  The default is
+@file{@var{srcdir}} or @file{@var{srcdir}/..} or
+@file{@var{srcdir}/../..}, whichever is the first that contains
+@file{install-sh}.  The other files are not checked for, so that using
+@code{AC_PROG_INSTALL} does not automatically require distributing the
+other auxiliary files.  It checks for @file{install.sh} also, but that
+name is obsolete because some @command{make} have a rule that creates
+@file{install} from it if there is no @file{Makefile}.
+@end defmac
+
+
+@node Output, Configuration Actions, Input, Setup
+@section Outputting Files
+
+Every Autoconf-generated @code{configure} script must finish by calling
+@code{AC_OUTPUT}.  It is the macro that generates @file{config.status},
+which will create the @file{Makefile}s and any other files resulting
+from configuration.  The only other required macro is @code{AC_INIT}
+(@pxref{Input}).
+
+@defmac AC_OUTPUT
+@maindex OUTPUT
+@cindex Instantiation
+Generate @file{config.status} and launch it.  Call this macro once, at
+the end of @file{configure.ac}.
+
+@file{config.status} will take all the configuration actions: all the
+output files (see @ref{Configuration Files}, macro
+@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
+macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
+Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
+@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
+to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
+are honored.
+@end defmac
+
+Historically, the usage of @code{AC_OUTPUT} was somewhat different.
+@xref{Obsolete Macros}, for a description of the arguments that
+@code{AC_OUTPUT} used to support.
+
+
+If you run @code{make} on subdirectories, you should run it using the
+@code{make} variable @code{MAKE}.  Most versions of @code{make} set
+@code{MAKE} to the name of the @code{make} program plus any options it
+was given.  (But many do not include in it the values of any variables
+set on the command line, so those are not passed on automatically.)
+Some old versions of @code{make} do not set this variable.  The
+following macro allows you to use it even with those versions.
+
+@defmac AC_PROG_MAKE_SET
+@maindex PROG_MAKE_SET
+@ovindex SET_MAKE
+If @code{make} predefines the variable @code{MAKE}, define output
+variable @code{SET_MAKE} to be empty.  Otherwise, define @code{SET_MAKE}
+to contain @samp{MAKE=make}.  Calls @code{AC_SUBST} for @code{SET_MAKE}.
+@end defmac
+
+To use this macro, place a line like this in each @file{Makefile.in}
+that runs @code{MAKE} on other directories:
+
+@example
+@@SET_MAKE@@
+@end example
+
+
+
+@node Configuration Actions, Configuration Files, Output, Setup
+@section Taking Configuration Actions
+
+@file{configure} is designed so that it appears to do everything itself,
+but there is actually a hidden slave: @file{config.status}.
+@file{configure} is in charge of examining your system, but it is
+@file{config.status} that actually takes the proper actions based on the
+results of @file{configure}.  The most typical task of
+@file{config.status} is to @emph{instantiate} files.
+
+This section describes the common behavior of the four standard
+instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
+@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}.  They all
+have this prototype:
+
+@c Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
+@c awful.
+@example
+AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
+@end example
+
+@noindent
+where the arguments are:
+
+@table @var
+@item @var{tag}@dots{}
+A whitespace-separated list of tags, which are typically the names of
+the files to instantiate.
+
+@item commands
+Shell commands output literally into @file{config.status}, and
+associated with a tag that the user can use to tell @file{config.status}
+which the commands to run.  The commands are run each time a @var{tag}
+request is given to @file{config.status}; typically, each time the file
+@file{@var{tag}} is created.
+
+@item init-cmds
+Shell commands output @emph{unquoted} near the beginning of
+@file{config.status}, and executed each time @file{config.status} runs
+(regardless of the tag).  Because they are unquoted, for example,
+@samp{$var} will be output as the value of @code{var}.  @var{init-cmds}
+is typically used by @file{configure} to give @file{config.status} some
+variables it needs to run the @var{commands}.
+@end table
+
+All these macros can be called multiple times, with different
+@var{tag}s, of course!
+
+You are encouraged to use literals as @var{tags}.  In particular, you
+should avoid
+
+@example
+@dots{} && my_foos="$my_foos fooo"
+@dots{} && my_foos="$my_foos foooo"
+AC_CONFIG_FOOS($my_foos)
+@end example
+
+@noindent
+and use this instead:
+
+@example
+@dots{} && AC_CONFIG_FOOS(fooo)
+@dots{} && AC_CONFIG_FOOS(foooo)
+@end example
+
+The macro @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
+specials @var{tag}s: they may have the form @samp{@var{output}} or
+@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
+from its templates, @var{inputs} if specified, defaulting to
+@samp{@var{output}.in}.
+
+For instance
+@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for
+the creation of @file{Makefile} that will be the expansion of the
+output variables in the concatenation of @file{boiler/top.mk} and
+@file{boiler/bot.mk}.
+
+The special value @samp{-} might be used to denote the standard output
+when used in @var{output}, or the standard input when used in the
+@var{inputs}.  You most probably don't need to use this in
+@file{configure.ac}, but it is convenient when using the command line
+interface of @file{./config.status}, see @ref{config.status Invocation},
+for more details.
+
+The @var{inputs} may be absolute or relative filenames.  In the latter
+case they are first looked for in the build tree, and then in the source
+tree.
+
+
+@node Configuration Files, Makefile Substitutions, Configuration Actions, Setup
+@section Creating Configuration Files
+
+Be sure to read the previous section, @ref{Configuration Actions}.
+
+@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_FILES
+Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
+file (by default @file{@var{file}.in}), substituting the output variable
+values.
+@c Before we used to have this feature, which was later rejected
+@c because it complicates the write of Makefiles:
+@c If the file would be unchanged, it is left untouched, to preserve
+@c timestamp.
+This macro is one of the instantiating macros, see @ref{Configuration
+Actions}.  @xref{Makefile Substitutions}, for more information on using
+output variables.  @xref{Setting Output Variables}, for more information
+on creating them.  This macro creates the directory that the file is in
+if it doesn't exist.  Usually, @file{Makefile}s are created this way,
+but other files, such as @file{.gdbinit}, can be specified as well.
+
+Typical calls to @code{AC_CONFIG_FILES} look like this:
+
+@example
+AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile)
+AC_CONFIG_FILES(autoconf, chmod +x autoconf)
+@end example
+
+You can override an input file name by appending to @var{file} a
+colon-separated list of input files.  Examples:
+
+@example
+AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk
+                lib/Makefile:boiler/lib.mk)
+@end example
+
+@noindent
+Doing this allows you to keep your file names acceptable to MS-DOS, or
+to prepend and/or append boilerplate to the file.
+@end defmac
+
+
+
+@node Makefile Substitutions, Configuration Headers, Configuration Files, Setup
+@section Substitutions in Makefiles
+
+Each subdirectory in a distribution that contains something to be
+compiled or installed should come with a file @file{Makefile.in}, from
+which @code{configure} will create a @file{Makefile} in that directory.
+To create a @file{Makefile}, @code{configure} performs a simple variable
+substitution, replacing occurrences of @samp{@@@var{variable}@@} in
+@file{Makefile.in} with the value that @code{configure} has determined
+for that variable.  Variables that are substituted into output files in
+this way are called @dfn{output variables}.  They are ordinary shell
+variables that are set in @code{configure}.  To make @code{configure}
+substitute a particular variable into the output files, the macro
+@code{AC_SUBST} must be called with that variable name as an argument.
+Any occurrences of @samp{@@@var{variable}@@} for other variables are
+left unchanged.  @xref{Setting Output Variables}, for more information
+on creating output variables with @code{AC_SUBST}.
+
+A software package that uses a @code{configure} script should be
+distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
+way, the user has to properly configure the package for the local system
+before compiling it.
+
+@xref{Makefile Conventions,, Makefile Conventions, standards, The
+GNU Coding Standards}, for more information on what to put in
+@file{Makefile}s.
+
+@menu
+* Preset Output Variables::     Output variables that are always set
+* Installation Directory Variables::  Other preset output variables
+* Build Directories::           Supporting multiple concurrent compiles
+* Automatic Remaking::          Makefile rules for configuring
+@end menu
+
+@node Preset Output Variables, Installation Directory Variables, Makefile Substitutions, Makefile Substitutions
+@subsection Preset Output Variables
+
+Some output variables are preset by the Autoconf macros.  Some of the
+Autoconf macros set additional output variables, which are mentioned in
+the descriptions for those macros.  @xref{Output Variable Index}, for a
+complete list of output variables.  @xref{Installation Directory
+Variables}, for the list of the preset ones related to installation
+directories.  Below are listed the other preset ones.  They all are
+precious variables (@pxref{Setting Output Variables},
+@code{AC_ARG_VAR}).
+
+@c Just say no to ASCII sorting!  We're humans, not computers.
+@c These variables are listed as they would be in a dictionary:
+@c actor
+@c Actress
+@c actress
+
+@defvar CFLAGS
+@ovindex CFLAGS
+Debugging and optimization options for the C compiler.  If it is not set
+in the environment when @code{configure} runs, the default value is set
+when you call @code{AC_PROG_CC} (or empty if you don't).  @code{configure}
+uses this variable when compiling programs to test for C features.
+@end defvar
+
+@defvar configure_input
+@ovindex configure_input
+A comment saying that the file was generated automatically by
+@code{configure} and giving the name of the input file.
+@code{AC_OUTPUT} adds a comment line containing this variable to the top
+of every @file{Makefile} it creates.  For other files, you should
+reference this variable in a comment at the top of each input file.  For
+example, an input shell script should begin like this:
+
+@example
+#! /bin/sh
+# @@configure_input@@
+@end example
+
+@noindent
+The presence of that line also reminds people editing the file that it
+needs to be processed by @code{configure} in order to be used.
+@end defvar
+
+@defvar CPPFLAGS
+@ovindex CPPFLAGS
+Header file search directory (@option{-I@var{dir}}) and any other
+miscellaneous options for the C and C++ preprocessors and compilers.  If
+it is not set in the environment when @code{configure} runs, the default
+value is empty.  @code{configure} uses this variable when compiling or
+preprocessing programs to test for C and C++ features.
+@end defvar
+
+@defvar CXXFLAGS
+@ovindex CXXFLAGS
+Debugging and optimization options for the C++ compiler.  If it is not
+set in the environment when @code{configure} runs, the default value is
+set when you call @code{AC_PROG_CXX} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+C++ features.
+@end defvar
+
+@defvar DEFS
+@ovindex DEFS
+@option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
+is called, @code{configure} replaces @samp{@@DEFS@@} with
+@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
+variable is not defined while @code{configure} is performing its tests,
+only when creating the output files.  @xref{Setting Output Variables}, for
+how to check the results of previous tests.
+@end defvar
+
+@defvar ECHO_C
+@defvarx ECHO_N
+@defvarx ECHO_T
+@ovindex ECHO_C
+@ovindex ECHO_N
+@ovindex ECHO_T
+How does one suppress the trailing newline from @code{echo} for
+question-answer message pairs?  These variables provide a way:
+
+@example
+echo $ECHO_N "And the winner is... $ECHO_C"
+sleep 100000000000
+echo "$@{ECHO_T@}dead."
+@end example
+
+@noindent
+Some old and uncommon @code{echo} implementations offer no means to
+achieve this, in which case @code{ECHO_T} is set to tab.  You might not
+want to use it.
+@end defvar
+
+@defvar FFLAGS
+@ovindex FFLAGS
+Debugging and optimization options for the Fortran 77 compiler.  If it
+is not set in the environment when @code{configure} runs, the default
+value is set when you call @code{AC_PROG_F77} (or empty if you don't).
+@code{configure} uses this variable when compiling programs to test for
+Fortran 77 features.
+@end defvar
+
+@defvar LDFLAGS
+@ovindex LDFLAGS
+Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
+options for the linker.  Don't use this variable to pass library names
+(@option{-l}) to the linker, use @code{LIBS} instead.  If it is not set
+in the environment when @code{configure} runs, the default value is empty.
+@code{configure} uses this variable when linking programs to test for
+C, C++ and Fortran 77 features.
+@end defvar
+
+@defvar LIBS
+@ovindex LIBS
+@option{-l} options to pass to the linker.  The default value is empty,
+but some Autoconf macros may prepend extra libraries to this variable if
+those libraries are found and provide necessary functions, see
+@ref{Libraries}.  @code{configure} uses this variable when linking
+programs to test for C, C++ and Fortran 77 features.
+@end defvar
+
+@defvar srcdir
+@ovindex srcdir
+The directory that contains the source code for that @file{Makefile}.
+@end defvar
+
+@defvar top_srcdir
+@ovindex top_srcdir
+The top-level source code directory for the package.  In the top-level
+directory, this is the same as @code{srcdir}.
+@end defvar
+
+@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions
+@subsection Installation Directory Variables
+
+The following variables specify the directories where the package will
+be installed, see @ref{Directory Variables,, Variables for Installation
+Directories, standards, The GNU Coding Standards}, for more information.
+See the end of this section for details on when and how to use these
+variables.
+
+@defvar bindir
+@ovindex bindir
+The directory for installing executables that users run.
+@end defvar
+
+@defvar datadir
+@ovindex datadir
+The directory for installing read-only architecture-independent data.
+@end defvar
+
+@defvar exec_prefix
+@ovindex exec_prefix
+The installation prefix for architecture-dependent files.  By default
+it's the same as @var{prefix}.  You should avoid installing anything
+directly to @var{exec_prefix}.  However, the default value for
+directories containing architecture-dependent files should be relative
+to @var{exec_prefix}.
+@end defvar
+
+@defvar includedir
+@ovindex includedir
+The directory for installing C header files.
+@end defvar
+
+@defvar infodir
+@ovindex infodir
+The directory for installing documentation in Info format.
+@end defvar
+
+@defvar libdir
+@ovindex libdir
+The directory for installing object code libraries.
+@end defvar
+
+@defvar libexecdir
+@ovindex libexecdir
+The directory for installing executables that other programs run.
+@end defvar
+
+@defvar localstatedir
+@ovindex localstatedir
+The directory for installing modifiable single-machine data.
+@end defvar
+
+@defvar mandir
+@ovindex mandir
+The top-level directory for installing documentation in man format.
+@end defvar
+
+@defvar oldincludedir
+@ovindex oldincludedir
+The directory for installing C header files for non-gcc compilers.
+@end defvar
+
+@defvar prefix
+@ovindex prefix
+The common installation prefix for all files. If @var{exec_prefix}
+is defined to a different value, @var{prefix} is used only for
+architecture-independent files.
+@end defvar
+
+@defvar sbindir
+@ovindex sbindir
+The directory for installing executables that system
+administrators run.
+@end defvar
+
+@defvar sharedstatedir
+@ovindex sharedstatedir
+The directory for installing modifiable architecture-independent data.
+@end defvar
+
+@defvar sysconfdir
+@ovindex sysconfdir
+The directory for installing read-only single-machine data.
+@end defvar
+
+
+Most of these variables have values that rely on @code{prefix} or
+@code{exec_prefix}.  It is on purpose that the directory output
+variables keep them unexpanded: typically @samp{@@datadir@@} will be
+replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
+
+This behavior is mandated by the @sc{gnu} coding standards, so that when
+the user runs:
+
+@table @samp
+@item make
+she can still specify a different prefix from the one specified to
+@command{configure}, in which case, if needed, the package shall hard
+code dependencies to her late desires.
+
+@item make install
+she can specify a different installation location, in which case the
+package @emph{must} still depend on the location which was compiled in
+(i.e., never recompile when @samp{make install} is run).  This is an
+extremely important feature, as many people may decide to install all
+the files of a package grouped together, and then install links from
+the final locations to there.
+@end table
+
+In order to support these features, it is essential that @code{datadir}
+remains being defined as @samp{$@{prefix@}/share} to depend upon the
+current value of @code{prefix}.
+
+A corollary is that you should not use these variables but in Makefiles.
+For instance, instead of trying to evaluate @code{datadir} in
+@file{configure} and hardcoding it in Makefiles using
+e.g. @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
+@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
+
+Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
+@code{datadir} and friends in your shell scripts and other files, rather
+let @command{make} manage their replacement.  For instance Autoconf
+ships templates of its shell scripts ending with @samp{.sh}, and uses
+this Makefile snippet:
+
+@example
+.sh:
+        rm -f $@@ $@@.tmp
+        sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp
+        chmod +x $@@.tmp
+        mv $@@.tmp $@@
+@end example
+
+Three things are noteworthy:
+
+@table @samp
+@item @@datadir\@@
+The backslash prevents @command{configure} from replacing
+@samp{@@datadir@@} in the sed expression itself.
+
+@item $(pkgdatadir)
+Don't use @samp{@@pkgdatadir@@}!  Use the matching makefile variable
+instead.
+
+@item ,
+Don't use @samp{/} in the sed expression(s) since most probably the
+variables you use, such as @samp{$(pkgdatadir)}, will contain
+some.
+@end table
+
+
+@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions
+@subsection Build Directories
+
+You can support compiling a software package for several architectures
+simultaneously from the same copy of the source code.  The object files
+for each architecture are kept in their own directory.
+
+To support doing this, @code{make} uses the @code{VPATH} variable to
+find the files that are in the source directory.  @sc{gnu} @code{make}
+and most other recent @code{make} programs can do this.  Older
+@code{make} programs do not support @code{VPATH}; when using them, the
+source code must be in the same directory as the object files.
+
+To support @code{VPATH}, each @file{Makefile.in} should contain two
+lines that look like:
+
+@example
+srcdir = @@srcdir@@
+VPATH = @@srcdir@@
+@end example
+
+Do not set @code{VPATH} to the value of another variable, for example
+@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
+variable substitutions on the value of @code{VPATH}.
+
+@code{configure} substitutes in the correct value for @code{srcdir} when
+it produces @file{Makefile}.
+
+Do not use the @code{make} variable @code{$<}, which expands to the
+file name of the file in the source directory (found with @code{VPATH}),
+except in implicit rules.  (An implicit rule is one such as @samp{.c.o},
+which tells how to create a @file{.o} file from a @file{.c} file.)  Some
+versions of @code{make} do not set @code{$<} in explicit rules; they
+expand it to an empty value.
+
+Instead, @file{Makefile} command lines should always refer to source
+files by prefixing them with @samp{$(srcdir)/}.  For example:
+
+@example
+time.info: time.texinfo
+        $(MAKEINFO) $(srcdir)/time.texinfo
+@end example
+
+@node Automatic Remaking,  , Build Directories, Makefile Substitutions
+@subsection Automatic Remaking
+
+You can put rules like the following in the top-level @file{Makefile.in}
+for a package to automatically update the configuration information when
+you change the configuration files.  This example includes all of the
+optional files, such as @file{aclocal.m4} and those related to
+configuration header files.  Omit from the @file{Makefile.in} rules for
+any of these files that your package does not use.
+
+The @samp{$(srcdir)/} prefix is included because of limitations in the
+@code{VPATH} mechanism.
+
+The @file{stamp-} files are necessary because the timestamps of
+@file{config.h.in} and @file{config.h} will not be changed if remaking
+them does not change their contents.  This feature avoids unnecessary
+recompilation.  You should include the file @file{stamp-h.in} your
+package's distribution, so @command{make} will consider
+@file{config.h.in} up to date.  Don't use @command{touch}
+(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
+@command{date} would cause needless differences, hence @sc{cvs}
+conflicts etc.).
+
+@example
+@group
+$(srcdir)/configure: configure.ac aclocal.m4
+        cd $(srcdir) && autoconf
+
+# autoheader might not change config.h.in, so touch a stamp file.
+$(srcdir)/config.h.in: stamp-h.in
+$(srcdir)/stamp-h.in: configure.ac aclocal.m4
+        cd $(srcdir) && autoheader
+        echo timestamp > $(srcdir)/stamp-h.in
+
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        ./config.status
+
+Makefile: Makefile.in config.status
+        ./config.status
+
+config.status: configure
+        ./config.status --recheck
+@end group
+@end example
+
+@noindent
+(Be careful if you copy these lines directly into your Makefile, as you
+will need to convert the indented lines to start with the tab character.)
+
+In addition, you should use @samp{AC_CONFIG_FILES(stamp-h, echo
+timestamp > stamp-h)} so @file{config.status} will ensure that
+@file{config.h} is considered up to date.  @xref{Output}, for more
+information about @code{AC_OUTPUT}.
+
+@xref{config.status Invocation}, for more examples of handling
+configuration-related dependencies.
+
+@node Configuration Headers, Configuration Commands, Makefile Substitutions, Setup
+@section Configuration Header Files
+@cindex Configuration Header
+@cindex @file{config.h}
+
+When a package tests more than a few C preprocessor symbols, the command
+lines to pass @option{-D} options to the compiler can get quite long.
+This causes two problems.  One is that the @code{make} output is hard to
+visually scan for errors.  More seriously, the command lines can exceed
+the length limits of some operating systems.  As an alternative to
+passing @option{-D} options to the compiler, @code{configure} scripts can
+create a C header file containing @samp{#define} directives.  The
+@code{AC_CONFIG_HEADERS} macro selects this kind of output.  It should
+be called right after @code{AC_INIT}.
+
+The package should @samp{#include} the configuration header file before
+any other header files, to prevent inconsistencies in declarations (for
+example, if it redefines @code{const}).  Use @samp{#include <config.h>}
+instead of @samp{#include "config.h"}, and pass the C compiler a
+@option{-I.} option (or @option{-I..}; whichever directory contains
+@file{config.h}).  That way, even if the source directory is configured
+itself (perhaps to make a distribution), other build directories can
+also be configured without finding the @file{config.h} from the source
+directory.
+
+@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_HEADERS
+@cvindex HAVE_CONFIG_H
+This macro is one of the instantiating macros, see @ref{Configuration
+Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
+whitespace-separated list @var{header} containing C preprocessor
+@code{#define} statements, and replace @samp{@@DEFS@@} in generated
+files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
+The usual name for @var{header} is @file{config.h}.
+
+If @var{header} already exists and its contents are identical to what
+@code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
+some changes in configuration without needlessly causing object files
+that depend on the header file to be recompiled.
+
+Usually the input file is named @file{@var{header}.in}; however, you can
+override the input file name by appending to @var{header}, a
+colon-separated list of input files.  Examples:
+
+@example
+AC_CONFIG_HEADERS(config.h:config.hin)
+AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post)
+@end example
+
+@noindent
+Doing this allows you to keep your file names acceptable to MS-DOS, or
+to prepend and/or append boilerplate to the file.
+@end defmac
+
+@xref{Configuration Actions}, for more details on @var{header}.
+
+@menu
+* Header Templates::            Input for the configuration headers
+* autoheader Invocation::       How to create configuration templates
+* Autoheader Macros::           How to specify CPP templates
+@end menu
+
+@node Header Templates, autoheader Invocation, Configuration Headers, Configuration Headers
+@subsection Configuration Header Templates
+@cindex Configuration Header Template
+@cindex @file{config.h.in}
+
+Your distribution should contain a template file that looks as you want
+the final header file to look, including comments, with @code{#undef}
+statements which are used as hooks.  For example, suppose your
+@file{configure.ac} makes these calls:
+
+@example
+AC_CONFIG_HEADERS(conf.h)
+AC_CHECK_HEADERS(unistd.h)
+@end example
+
+@noindent
+Then you could have code like the following in @file{conf.h.in}.  On
+systems that have @file{unistd.h}, @code{configure} will @samp{#define}
+@samp{HAVE_UNISTD_H} to 1.  On other systems, the whole line will be
+commented out (in case the system predefines that symbol).
+
+@example
+@group
+/* Define as 1 if you have unistd.h.  */
+#undef HAVE_UNISTD_H
+@end group
+@end example
+
+You can then decode the configuration header using the preprocessor
+directives:
+
+@example
+@group
+#include <conf.h>
+
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#else
+/* We are in trouble. */
+#endif
+@end group
+@end example
+
+The use of old form templates, with @samp{#define} instead of
+@samp{#undef} is strongly discouraged.
+
+Since it is a tedious task to keep a template header up to date, you may
+use @code{autoheader} to generate it, see @ref{autoheader Invocation}.
+
+
+@node autoheader Invocation, Autoheader Macros, Header Templates, Configuration Headers
+@subsection Using @code{autoheader} to Create @file{config.h.in}
+@cindex @code{autoheader}
+
+The @command{autoheader} program can create a template file of C
+@samp{#define} statements for @code{configure} to use.  If
+@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
+@command{autoheader} creates @file{@var{file}.in}; if multiple file
+arguments are given, the first one is used.  Otherwise,
+@command{autoheader} creates @file{config.h.in}.
+
+In order to do its job, @command{autoheader} needs you to document all
+of the symbols that you might use; i.e., there must be at least one
+@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third
+argument for each symbol (@pxref{Defining Symbols}).  An additional
+constraint is that the first argument of @code{AC_DEFINE} must be a
+literal.  Note that all symbols defined by Autoconf's built-in tests are
+already documented properly; you only need to document those that you
+define yourself.
+
+You might wonder why @command{autoheader} is needed: after all, why
+would @command{configure} need to ``patch'' a @file{config.h.in} to
+produce a @file{config.h} instead of just creating @file{config.h} from
+scratch?  Well, when everything rocks, the answer is just that we are
+wasting our time maintaining @command{autoheader}: generating
+@file{config.h} directly is all that is needed.  When things go wrong,
+however, you'll be thankful for the existence of @command{autoheader}.
+
+The fact that the symbols are documented is important in order to
+@emph{check} that @file{config.h} makes sense.  The fact that there is a
+well defined list of symbols that should be @code{#define}'d (or not) is
+also important for people who are porting packages to environments where
+@command{configure} cannot be run: they just have to @emph{fill in the
+blanks}.
+
+But let's come back to the point: @command{autoheader}'s invocation@dots{}
+
+If you give @command{autoheader} an argument, it uses that file instead
+of @file{configure.ac} and writes the header file to the standard output
+instead of to @file{config.h.in}.  If you give @command{autoheader} an
+argument of @option{-}, it reads the standard input instead of
+@file{configure.ac} and writes the header file to the standard output.
+
+@code{autoheader} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but
+not @file{@var{file}.top} and @file{@var{file}.bot}) in directory
+@var{dir} instead of in the current directory.
+
+@item --warnings=@var{category}
+@itemx -W @var{category}
+@evindex WARNINGS
+Report the warnings related to @var{category} (which can actually be a
+comma separated list). Current categories include:
+
+@table @samp
+@item obsolete
+report the uses of obsolete constructs
+
+@item all
+report all the warnings
+
+@item none
+report none
+
+@item error
+treats warnings as errors
+
+@item no-@var{category}
+disable warnings falling into @var{category}
+@end table
+
+@end table
+
+
+
+@node Autoheader Macros,  , autoheader Invocation, Configuration Headers
+@subsection Autoheader Macros
+
+@code{autoheader} scans @file{configure.ac} and figures out which C
+preprocessor symbols it might define.  It knows how to generate
+templates for symbols defined by @code{AC_CHECK_HEADERS},
+@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
+symbol, you must define a template for it.  If there are missing
+templates, @code{autoheader} fails with an error message.
+
+The simplest way to create a template for a @var{symbol} is to supply
+the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
+@ref{Defining Symbols}.  You may also use one of the following macros.
+
+@defmac AH_VERBATIM (@var{key}, @var{template})
+@maindex AH_VERBATIM
+@maindex VERBATIM
+Tell @code{autoheader} to include the @var{template} as-is in the header
+template file.  This @var{template} is associated with the @var{key},
+which is used to sort all the different templates and guarantee their
+uniqueness.  It should be the symbol that can be @code{AC_DEFINE}'d.
+
+For example:
+
+@example
+AH_VERBATIM([_GNU_SOURCE],
+[/* Enable GNU extensions on systems that have them.  */
+#ifndef _GNU_SOURCE
+# define _GNU_SOURCE
+#endif])
+@end example
+@end defmac
+
+
+@defmac AH_TEMPLATE (@var{key}, @var{description})
+@maindex AH_TEMPLATE
+@maindex TEMPLATE
+Tell @code{autoheader} to generate a template for @var{key}.  This macro
+generates standard templates just like @code{AC_DEFINE} when a
+@var{description} is given.
+
+For example:
+
+@example
+AH_TEMPLATE([CRAY_STACKSEG_END],
+            [Define to one of _getb67, GETB67, getb67
+             for Cray-2 and Cray-YMP systems.  This
+             function is required for alloca.c support
+             on those systems.])
+@end example
+
+@noindent
+will generate the following template, with the description properly
+justified.
+
+@example
+/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
+   Cray-YMP systems. This function is required for alloca.c
+   support on those systems. */
+#undef CRAY_STACKSEG_END
+@end example
+@end defmac
+
+
+@defmac AH_TOP (@var{text})
+@maindex AH_TOP
+@maindex TOP
+Include @var{text} at the top of the header template file.
+@end defmac
+
+
+@defmac AH_BOTTOM (@var{text})
+@maindex AH_BOTTOM
+@maindex BOTTOM
+Include @var{text} at the bottom of the header template file.
+@end defmac
+
+
+@node Configuration Commands, Configuration Links, Configuration Headers, Setup
+@section Running Arbitrary Configuration Commands
+
+You execute arbitrary commands either before, during and after
+@file{config.status} is run.  The three following macros accumulate the
+commands to run when they are called multiple times.
+@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
+@code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details.
+
+@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_COMMANDS
+Specify additional shell commands to run at the end of
+@file{config.status}, and shell commands to initialize any variables
+from @code{configure}.  Associate the commands to the @var{tag}.  Since
+typically the @var{cmds} create a file, @var{tag} should naturally be
+the name of that file.  This macro is one of the instantiating macros,
+see @ref{Configuration Actions}.
+
+Here is an unrealistic example:
+@example
+fubar=42
+AC_CONFIG_COMMANDS(fubar,
+                   [echo this is extra $fubar, and so on.],
+                   [fubar=$fubar])
+@end example
+
+Here is a better one:
+@example
+AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp])
+@end example
+@end defmac
+
+@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
+@maindex OUTPUT_COMMANDS_PRE
+Execute the @var{cmds} right before creating @file{config.status}.  A
+typical use is computing values derived from variables built during the
+execution of @code{configure}:
+
+@example
+AC_CONFIG_COMMANDS_PRE(
+[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
+AC_SUBST(LTLIBOBJS)])
+@end example
+@end defmac
+
+@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
+@maindex OUTPUT_COMMANDS_POST
+Execute the @var{cmds} right after creating @file{config.status}.
+@end defmac
+
+
+
+
+@node Configuration Links, Subdirectories, Configuration Commands, Setup
+@section Creating Configuration Links
+
+You may find it convenient to create links whose destinations depend upon
+results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
+creation of relative symbolic links can be delicate when the package is
+built in another directory than its sources.
+
+@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
+@maindex CONFIG_LINKS
+@cindex Links
+Make @code{AC_OUTPUT} link each of the existing files @var{source} to
+the corresponding link name @var{dest}.  Makes a symbolic link if
+possible, otherwise a hard link.  The @var{dest} and @var{source} names
+should be relative to the top level source or build directory.  This
+macro is one of the instantiating macros, see @ref{Configuration
+Actions}.
+
+For example, this call:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+
+@noindent
+creates in the current directory @file{host.h} as a link to
+@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
+link to @file{@var{srcdir}/config/$obj_format.h}.
+
+The tempting value @samp{.} for @var{dest} is invalid: it makes it
+impossible for @samp{config.status} to guess the links to establish.
+
+One can then run:
+@example
+./config.status host.h object.h
+@end example
+@noindent
+to create the links.
+@end defmac
+
+
+
+@node Subdirectories, Default Prefix, Configuration Links, Setup
+@section Configuring Other Packages in Subdirectories
+
+In most situations, calling @code{AC_OUTPUT} is sufficient to produce
+@file{Makefile}s in subdirectories.  However, @code{configure} scripts
+that control more than one independent package can use
+@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other
+packages in subdirectories.
+
+@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
+@maindex CONFIG_SUBDIRS
+@ovindex subdirs
+Make @code{AC_OUTPUT} run @code{configure} in each subdirectory
+@var{dir} in the given whitespace-separated list.  Each @var{dir} should
+be a literal, i.e., please do not use:
+
+@example
+if test "$package_foo_enabled" = yes; then
+  $my_subdirs="$my_subdirs foo"
+fi
+AC_CONFIG_SUBDIRS($my_subdirs)
+@end example
+
+@noindent
+because this prevents @samp{./configure --help=recursive} from
+displaying the options of the package @code{foo}.  Rather, you should
+write:
+
+@example
+if test "$package_foo_enabled" = yes then;
+  AC_CONFIG_SUBDIRS(foo)
+fi
+@end example
+
+If a given @var{dir} is not found, no error is reported, so a
+@code{configure} script can configure whichever parts of a large source
+tree are present.  If a given @var{dir} contains @code{configure.gnu},
+it is run instead of @code{configure}. This is for packages that might
+use a non-autoconf script @code{Configure}, which can't be called
+through a wrapper @code{configure} since it would be the same file on
+case-insensitive filesystems. Likewise, if a @var{dir} contains
+@file{configure.ac} but no @code{configure}, the Cygnus @code{configure}
+script found by @code{AC_CONFIG_AUX_DIR} is used.
+
+The subdirectory @code{configure} scripts are given the same command
+line options that were given to this @code{configure} script, with minor
+changes if needed (e.g., to adjust a relative path for the cache file or
+source directory).  This macro also sets the output variable
+@code{subdirs} to the list of directories @samp{@var{dir} @dots{}}.
+@file{Makefile} rules can use this variable to determine which
+subdirectories to recurse into.  This macro may be called multiple
+times.
+@end defmac
+
+@node Default Prefix,  , Subdirectories, Setup
+@section Default Prefix
+
+By default, @code{configure} sets the prefix for files it installs to
+@file{/usr/local}.  The user of @code{configure} can select a different
+prefix using the @option{--prefix} and @option{--exec-prefix} options.
+There are two ways to change the default: when creating
+@code{configure}, and when running it.
+
+Some software packages might want to install in a directory besides
+@file{/usr/local} by default.  To accomplish that, use the
+@code{AC_PREFIX_DEFAULT} macro.
+
+@defmac AC_PREFIX_DEFAULT (@var{prefix})
+@maindex PREFIX_DEFAULT
+Set the default installation prefix to @var{prefix} instead of
+@file{/usr/local}.
+@end defmac
+
+It may be convenient for users to have @code{configure} guess the
+installation prefix from the location of a related program that they
+have already installed.  If you wish to do that, you can call
+@code{AC_PREFIX_PROGRAM}.
+
+@defmac AC_PREFIX_PROGRAM (@var{program})
+@maindex PREFIX_PROGRAM
+If the user did not specify an installation prefix (using the
+@option{--prefix} option), guess a value for it by looking for
+@var{program} in @code{PATH}, the way the shell does.  If @var{program}
+is found, set the prefix to the parent of the directory containing
+@var{program}; otherwise leave the prefix specified in
+@file{Makefile.in} unchanged.  For example, if @var{program} is
+@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc},
+set the prefix to @file{/usr/local/gnu}.
+@end defmac
+
+
+
+@c ======================================================== Existing tests
+
+@node Existing Tests, Writing Tests, Setup, Top
+@chapter Existing Tests
+
+These macros test for particular system features that packages might
+need or want to use.  If you need to test for a kind of feature that
+none of these macros check for, you can probably do it by calling
+primitive test macros with appropriate arguments (@pxref{Writing
+Tests}).
+
+These tests print messages telling the user which feature they're
+checking for, and what they find.  They cache their results for future
+@code{configure} runs (@pxref{Caching Results}).
+
+Some of these macros set output variables.  @xref{Makefile
+Substitutions}, for how to get their values.  The phrase ``define
+@var{name}'' is used below as a shorthand to mean ``define C
+preprocessor symbol @var{name} to the value 1''.  @xref{Defining
+Symbols}, for how to get those symbol definitions into your program.
+
+@menu
+* Common Behavior::             Macros' standard schemes
+* Alternative Programs::        Selecting between alternative programs
+* Files::                       Checking for the existence of files
+* Libraries::                   Library archives that might be missing
+* Library Functions::           C library functions that might be missing
+* Header Files::                Header files that might be missing
+* Declarations::                Declarations that may be missing
+* Structures::                  Structures or members that might be missing
+* Types::                       Types that might be missing
+* Compilers and Preprocessors::  Checking for compiling programs
+* System Services::             Operating system services
+* UNIX Variants::               Special kludges for specific UNIX variants
+@end menu
+
+@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests
+@section Common Behavior
+
+Much effort has been expended to make Autoconf easy to learn.  The most
+obvious way to reach this goal is simply to enforce standard interfaces
+and behaviors, avoiding exceptions as much as possible.  Because of
+history and inertia, unfortunately, there are still too many exceptions
+in Autoconf; nevertheless, this section describes some of the common
+rules.
+
+@menu
+* Standard Symbols::            Symbols defined by the macros
+* Default Includes::            Includes used by the generic macros
+@end menu
+
+@node Standard Symbols, Default Includes, Common Behavior, Common Behavior
+@subsection Standard Symbols
+
+All the generic macros that @code{AC_DEFINE} a symbol as a result of
+their test transform their @var{argument}s to a standard alphabet.
+First, @var{argument} is converted to upper case and any asterisks
+(@samp{*}) are each converted to @samp{P}.  Any remaining characters
+that are not alphanumeric are converted to underscores.
+
+For instance,
+
+@example
+AC_CHECK_TYPES(struct $Expensive*)
+@end example
+
+@noindent
+will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check succeeds.
+
+
+@node Default Includes,  , Standard Symbols, Common Behavior
+@subsection Default Includes
+@cindex Includes, default
+
+Several tests depend upon a set of header files.  Since these headers
+are not universally available, tests actually have to provide a set of
+protected includes, such as:
+
+@example
+@group
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+#  include <sys/time.h>
+# else
+#  include <time.h>
+# endif
+#endif
+@end group
+@end example
+
+@noindent
+Unless you know exactly what you are doing, you should avoid using
+unconditional includes, and check the existence of the headers you
+include beforehand (@pxref{Header Files}).
+
+Most generic macros provide the following default set of includes:
+
+@example
+@group
+#include <stdio.h>
+#if HAVE_SYS_TYPES_H
+# include <sys/types.h>
+#endif
+#if HAVE_SYS_STAT_H
+# include <sys/stat.h>
+#endif
+#if STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# if HAVE_STDLIB_H
+#  include <stdlib.h>
+# endif
+#endif
+#if HAVE_STRING_H
+# if !STDC_HEADERS && HAVE_MEMORY_H
+#  include <memory.h>
+# endif
+# include <string.h>
+#endif
+#if HAVE_STRINGS_H
+# include <strings.h>
+#endif
+#if HAVE_INTTYPES_H
+# include <inttypes.h>
+#else
+# if HAVE_STDINT_H
+#  include <stdint.h>
+# endif
+#endif
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#endif
+@end group
+@end example
+
+If the default includes are used, then Autoconf will automatically check
+for the presence of these headers and their compatibility, i.e., you
+don't need to run @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h}
+etc.
+
+These headers are checked for in the same order as they are included.
+For instance, on some systems @file{string.h} and @file{strings.h} both
+exist, but conflict.  Then @code{HAVE_STRING_H} will be defined, but
+@code{HAVE_STRINGS_H} won't.
+
+@node Alternative Programs, Files, Common Behavior, Existing Tests
+@section Alternative Programs
+@cindex Programs, checking
+
+These macros check for the presence or behavior of particular programs.
+They are used to choose between several alternative programs and to
+decide what to do once one has been chosen.  If there is no macro
+specifically defined to check for a program you need, and you don't need
+to check for any special properties of it, then you can use one of the
+general program-check macros.
+
+@menu
+* Particular Programs::         Special handling to find certain programs
+* Generic Programs::            How to find other programs
+@end menu
+
+@node Particular Programs, Generic Programs, Alternative Programs, Alternative Programs
+@subsection Particular Program Checks
+
+These macros check for particular programs---whether they exist, and
+in some cases whether they support certain features.
+
+@defmac AC_PROG_AWK
+@maindex PROG_AWK
+@ovindex AWK
+Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that
+order, and set output variable @code{AWK} to the first one that is found.
+It tries @code{mawk} first because that is reported to be the
+fastest implementation.
+@end defmac
+
+
+@defmac AC_PROG_EGREP
+@ovindex EGREP
+Check for @code{grep -E}, @code{egrep} in that
+order, and set output variable @code{EGREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_FGREP
+@ovindex FGREP
+Check for @code{grep -F}, @code{fgrep} in that
+order, and set output variable @code{FGREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_GREP
+@ovindex GREP
+Check for @code{grep}, @code{ggrep} in that
+order, and set output variable @code{GREP} to the first one that is found.
+@end defmac
+
+
+@defmac AC_PROG_INSTALL
+@maindex PROG_INSTALL
+@ovindex INSTALL
+@ovindex INSTALL_PROGRAM
+@ovindex INSTALL_DATA
+@ovindex INSTALL_SCRIPT
+Set output variable @code{INSTALL} to the path of a @sc{bsd} compatible
+@code{install} program, if one is found in the current @code{PATH}.
+Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
+checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
+default directories) to determine @var{dir} (@pxref{Output}).  Also set
+the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
+@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
+
+This macro screens out various instances of @code{install} known not to
+work.  It prefers to find a C program rather than a shell script, for
+speed.  Instead of @file{install-sh}, it can also use @file{install.sh},
+but that name is obsolete because some @code{make} programs have a rule
+that creates @file{install} from it if there is no @file{Makefile}.
+
+Autoconf comes with a copy of @file{install-sh} that you can use.  If
+you use @code{AC_PROG_INSTALL}, you must include either
+@file{install-sh} or @file{install.sh} in your distribution, or
+@code{configure} will produce an error message saying it can't find
+them---even if the system you're on has a good @code{install} program.
+This check is a safety measure to prevent you from accidentally leaving
+that file out, which would prevent your package from installing on
+systems that don't have a @sc{bsd}-compatible @code{install} program.
+
+If you need to use your own installation program because it has features
+not found in standard @code{install} programs, there is no reason to use
+@code{AC_PROG_INSTALL}; just put the file name of your program into your
+@file{Makefile.in} files.
+@end defmac
+
+@defmac AC_PROG_LEX
+@maindex PROG_LEX
+@ovindex LEX
+@ovindex LEXLIB
+@cvindex YYTEXT_POINTER
+@ovindex LEX_OUTPUT_ROOT
+If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
+and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
+place.  Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
+@option{-ll}.
+
+Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
+of a @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
+the base of the file name that the lexer generates; usually
+@file{lex.yy}, but sometimes something else.  These results vary
+according to whether @code{lex} or @code{flex} is being used.
+
+You are encouraged to use Flex in your sources, since it is both more
+pleasant to use than plain Lex and the C source it produces is portable.
+In order to ensure portability, however, you must either provide a
+function @code{yywrap} or, if you don't use it (e.g., your scanner has
+no @samp{#include}-like feature), simply include a @samp{%noyywrap}
+statement in the scanner's source.  Once this done, the scanner is
+portable (unless @emph{you} felt free to use nonportable constructs) and
+does not depend on any library.  In this case, and in this case only, it
+is suggested that you use this Autoconf snippet:
+
+@example
+AC_PROG_LEX
+if test "$LEX" != flex; then
+  LEX="$SHELL $missing_dir/missing flex"
+  AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
+  AC_SUBST(LEXLIB, '')
+fi
+@end example
+
+The shell script @command{missing} can be found in the Automake
+distribution.
+
+To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
+(indirectly) this macro twice, which will cause an annoying but benign
+``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
+of Automake will fix this issue, meanwhile, just ignore this message.
+@end defmac
+
+@defmac AC_PROG_LN_S
+@maindex PROG_LN_S
+@ovindex LN_S
+If @samp{ln -s} works on the current file system (the operating system
+and file system support symbolic links), set the output variable
+@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
+@code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}.
+
+If you make a link a directory other than the current directory, its
+meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
+create links using @samp{$(LN_S)}, either find out which form is used
+and adjust the arguments, or always invoke @code{ln} in the directory
+where the link is to be created.
+
+In other words, it does not work to do:
+@example
+$(LN_S) foo /x/bar
+@end example
+
+Instead, do:
+
+@example
+(cd /x && $(LN_S) foo bar)
+@end example
+@end defmac
+
+@defmac AC_PROG_RANLIB
+@maindex PROG_RANLIB
+@ovindex RANLIB
+Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
+is found, and otherwise to @samp{:} (do nothing).
+@end defmac
+
+@defmac AC_PROG_YACC
+@maindex PROG_YACC
+@ovindex YACC
+If @code{byacc} is found, set @code{YACC} to @samp{byacc}.
+Otherwise, if @code{bison} is found,
+set output variable @code{YACC} to @samp{bison -y}.
+Finally, if neither @code{byacc} or @code{bison} is found,
+set @code{YACC} to @samp{yacc}.
+@end defmac
+
+@node Generic Programs,  , Particular Programs, Alternative Programs
+@subsection Generic Program and File Checks
+
+These macros are used to find programs not covered by the ``particular''
+test macros.  If you need to check the behavior of a program as well as
+find out whether it is present, you have to write your own test for it
+(@pxref{Writing Tests}).  By default, these macros use the environment
+variable @code{PATH}.  If you need to check for a program that might not
+be in the user's @code{PATH}, you can pass a modified path to use
+instead, like this:
+
+@example
+AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd,
+  $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc)
+@end example
+
+You are strongly encouraged to declare the @var{variable} passed to
+@code{AC_CHECK_PROG} etc. as precious, @xref{Setting Output Variables},
+@code{AC_ARG_VAR}, for more details.
+
+@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path},  @ovar{reject})
+@maindex CHECK_PROG
+Check whether program @var{prog-to-check-for} exists in @code{PATH}.  If
+it is found, set @var{variable} to @var{value-if-found}, otherwise to
+@var{value-if-not-found}, if given.  Always pass over @var{reject} (an
+absolute file name) even if it is the first found in the search path; in
+that case, set @var{variable} using the absolute file name of the
+@var{prog-to-check-for} found that is not @var{reject}.  If
+@var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
+@var{variable}.
+@end defmac
+
+@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_PROGS
+Check for each program in the whitespace-separated list
+@var{progs-to-check-for} exists on the @code{PATH}.  If it is found, set
+@var{variable} to the name of that program.  Otherwise, continue
+checking the next program in the list.  If none of the programs in the
+list are found, set @var{variable} to @var{value-if-not-found}; if
+@var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed.  Calls @code{AC_SUBST} for @var{variable}.
+@end defmac
+
+@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_TOOL
+Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
+with a prefix of the host type as determined by
+@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
+For example, if the user runs @samp{configure --host=i386-gnu}, then
+this call:
+@example
+AC_CHECK_TOOL(RANLIB, ranlib, :)
+@end example
+@noindent
+sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
+@code{PATH}, or otherwise to @samp{ranlib} if that program exists in
+@code{PATH}, or to @samp{:} if neither program exists.
+@end defmac
+
+@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex CHECK_TOOLS
+Like @code{AC_CHECK_TOOL}, each of the tools in the list @var{progs-to-check-for} are
+checked with a prefix of the host type as determined by @code{AC_CANONICAL_HOST},
+followed by a dash (@pxref{Canonicalizing}). If none of the tools can be found with a
+prefix, then the first one without a prefix is used. If a tool is found, set
+@var{variable} to the name of that program. If none of the tools in the
+list are found, set @var{variable} to @var{value-if-not-found}; if
+@var{value-if-not-found} is not specified, the value of @var{variable}
+is not changed.  Calls @code{AC_SUBST} for @var{variable}.
+@end defmac
+
+@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_PROG
+Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
+path of @var{prog-to-check-for} if found.
+@end defmac
+
+@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_PROGS
+Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
+are found, set @var{variable} to the entire path of the program
+found.
+@end defmac
+
+@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
+@maindex PATH_TOOL
+Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire
+path of the program if it is found.
+@end defmac
+
+
+@node Files, Libraries, Alternative Programs, Existing Tests
+@section Files
+@cindex File, checking
+
+You might also need to check for the existence of files.  Before using
+these macros, ask yourself whether a run time test might not be a better
+solution.  Be aware that, like most Autoconf macros, they test a feature
+of the host machine, and therefore, they die when cross-compiling.
+
+@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FILE
+Check whether file @var{file} exists on the native system.  If it is
+found, execute @var{action-if-found}, otherwise do
+@var{action-if-not-found}, if given.
+@end defmac
+
+@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FILES
+Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
+Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
+for each file found.
+@end defmac
+
+
+@node Libraries, Library Functions, Files, Existing Tests
+@section Library Files
+@cindex Library, checking
+
+The following macros check for the presence of certain C, C++ or Fortran
+77 library archive files.
+
+@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex CHECK_LIB
+Depending on the current language(@pxref{Language Choice}), try to
+ensure that the C, C++, or Fortran 77 function @var{function} is
+available by checking whether a test program can be linked with the
+library @var{library} to get the function.  @var{library} is the base
+name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
+the @var{library} argument.
+
+@var{action-if-found} is a list of shell commands to run if the link
+with the library succeeds; @var{action-if-not-found} is a list of shell
+commands to run if the link fails.  If @var{action-if-found} is not
+specified, the default action will prepend @option{-l@var{library}} to
+@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
+capitals). This macro is intended to support building of @code{LIBS} in
+a right-to-left (least-dependent to most-dependent) fashion such that
+library dependencies are satisfied as a natural side-effect of
+consecutive tests. Some linkers are very sensitive to library ordering
+so the order in which @code{LIBS} is generated is important to reliable
+detection of libraries.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g. @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
+that @var{library} is present, because linking the test program will
+always fail with unresolved symbols. The @var{other-libraries} argument
+should be limited to cases where it is desirable to test for one library
+in the presence of another that is not already in @code{LIBS}.
+@end defmac
+
+
+@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex SEARCH_LIBS
+Search for a library defining @var{function} if it's not already
+available.  This equates to calling @code{AC_TRY_LINK_FUNC} first
+with no libraries, then for each library listed in @var{search-libs}.
+
+Add @option{-l@var{library}} to @code{LIBS} for the first library found
+to contain @var{function}, and run @var{action-if-found}.  If the
+function is not found, run @var{action-if-not-found}.
+
+If linking with @var{library} results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the @var{other-libraries} argument, separated by spaces:
+e.g. @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
+that @var{function} is present, because linking the test program will
+always fail with unresolved symbols.
+@end defmac
+
+
+
+@node Library Functions, Header Files, Libraries, Existing Tests
+@section Library Functions
+
+The following macros check for particular C library functions.
+If there is no macro specifically defined to check for a function you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general function-check macros.
+
+@menu
+* Function Portability::        Pitfalls with usual functions
+* Particular Functions::        Special handling to find certain functions
+* Generic Functions::           How to find other functions
+@end menu
+
+@node Function Portability, Particular Functions, Library Functions, Library Functions
+@subsection Portability of Classical Functions
+
+Most usual functions can either be missing, or be buggy, or be limited
+on some architectures.  This section tries to make an inventory of these
+portability issues.  By definition, this list will always require
+additions, please help us keeping it as complete as possible
+
+@table @code
+
+@item unlink
+The @sc{posix} spec says that @code{unlink} causes the given files to be
+removed only after there are no more open file handles for it.  Not all
+OS's support this behaviour though.  So even on systems that provide
+@code{unlink}, you cannot portably assume it is OK to call it on files
+that are open.  For example, on Windows 9x and ME, such a call would fail;
+on DOS it could even lead to file system corruption, as the file might end
+up being written to after the OS has removed it.
+
+@end table
+
+
+@node Particular Functions, Generic Functions, Function Portability, Library Functions
+@subsection Particular Function Checks
+@cindex Function, checking
+
+These macros check for particular C functions---whether they exist, and
+in some cases how they respond when given certain arguments.
+
+@defmac AC_FUNC_ALLOCA
+@maindex FUNC_ALLOCA
+@cvindex C_ALLOCA
+@cvindex HAVE_ALLOCA_H
+@ovindex ALLOCA
+Check how to get @code{alloca}.  Tries to get a builtin version by
+checking for @file{alloca.h} or the predefined C preprocessor macros
+@code{__GNUC__} and @code{_AIX}.  If this macro finds @file{alloca.h},
+it defines @code{HAVE_ALLOCA_H}.
+
+If those attempts fail, it looks for the function in the standard C
+library.  If any of those methods succeed, it defines
+@code{HAVE_ALLOCA}.  Otherwise, it sets the output variable
+@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so
+programs can periodically call @samp{alloca(0)} to garbage collect).
+This variable is separate from @code{LIBOBJS} so multiple programs can
+share the value of @code{ALLOCA} without needing to create an actual
+library, in case only some of them use the code in @code{LIBOBJS}.
+
+This macro does not try to get @code{alloca} from the System V R3
+@file{libPW} or the System V R4 @file{libucb} because those libraries
+contain some incompatible functions that cause trouble.  Some versions
+do not even contain @code{alloca} or contain a buggy version.  If you
+still want to use their @code{alloca}, use @code{ar} to extract
+@file{alloca.o} from them instead of compiling @file{alloca.c}.
+
+Source files that use @code{alloca} should start with a piece of code
+like the following, to declare it properly.  In some versions of AIX,
+the declaration of @code{alloca} must precede everything else except for
+comments and preprocessor directives.  The @code{#pragma} directive is
+indented so that pre-@sc{ansi} C compilers will ignore it, rather than
+choke on it.
+
+@example
+@group
+/* AIX requires this to be the first thing in the file.  */
+#ifndef __GNUC__
+# if HAVE_ALLOCA_H
+#  include <alloca.h>
+# else
+#  ifdef _AIX
+ #pragma alloca
+#  else
+#   ifndef alloca /* predefined by HP cc +Olibcalls */
+char *alloca ();
+#   endif
+#  endif
+# endif
+#endif
+@end group
+@end example
+@end defmac
+
+@defmac AC_FUNC_CHOWN
+@maindex FUNC_CHOWN
+If the @code{chown} function is available and works (in particular, it
+should accept @option{-1} for @code{uid} and @code{gid}), define
+@code{HAVE_CHOWN}.
+@end defmac
+
+
+@defmac AC_FUNC_CLOSEDIR_VOID
+@maindex FUNC_CLOSEDIR_VOID
+@cvindex CLOSEDIR_VOID
+If the @code{closedir} function does not return a meaningful value,
+define @code{CLOSEDIR_VOID}.  Otherwise, callers ought to check its
+return value for an error indicator.
+@end defmac
+
+@defmac AC_FUNC_ERROR_AT_LINE
+@maindex FUNC_ERROR_AT_LINE
+If the @code{error_at_line} function is not found, require an
+@code{AC_LIBOBJ} replacement of @samp{error}.
+@end defmac
+
+@defmac AC_FUNC_FNMATCH
+@maindex FUNC_FNMATCH
+If the @code{fnmatch} function is available and works (unlike the one on
+Solaris 2.4), define @code{HAVE_FNMATCH}.
+@end defmac
+
+@defmac AC_FUNC_FORK
+@maindex FUNC_FORK
+@cvindex HAVE_VFORK_H
+@cvindex HAVE_WORKING_FORK
+@cvindex HAVE_WORKING_VFORK
+@cvindex vfork
+This macro checks for the @code{fork} and @code{vfork} functions. If a
+working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
+checks whether @code{fork} is just a stub by trying to run it.
+
+If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
+@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
+define @code{vfork} to be @code{fork} for backward compatibility with
+previous versions of @command{autoconf}. This macro checks for several known
+errors in implementations of @code{vfork} and considers the system to not
+have a working @code{vfork} if it detects any of them. It is not considered
+to be an implementation error if a child's invocation of @code{signal}
+modifies the parent's signal handler, since child processes rarely change
+their signal handlers.
+
+Since this macro defines @code{vfork} only for backward compatibility with
+previous versions of @command{autoconf} you're encouraged to define it
+yourself in new code:
+@example
+@group
+#if !HAVE_WORKING_VFORK
+# define vfork fork
+#endif
+@end group
+@end example
+@end defmac
+
+@defmac AC_FUNC_FSEEKO
+@maindex FUNC_FSEEKO
+@cvindex _LARGEFILE_SOURCE
+If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
+Define @code{_LARGEFILE_SOURCE} if necessary.
+@end defmac
+
+@defmac AC_FUNC_GETGROUPS
+@maindex FUNC_GETGROUPS
+@ovindex GETGROUPS_LIBS
+If the @code{getgroups} function is available and works (unlike on
+Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
+@code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
+needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
+@end defmac
+
+@defmac AC_FUNC_GETLOADAVG
+@maindex FUNC_GETLOADAVG
+@cvindex SVR4
+@cvindex DGUX
+@cvindex UMAX
+@cvindex UMAX4_3
+@cvindex NLIST_STRUCT
+@cvindex NLIST_NAME_UNION
+@cvindex GETLODAVG_PRIVILEGED
+@cvindex NEED_SETGID
+@cvindex C_GETLOADAVG
+@ovindex LIBOBJS
+@ovindex NEED_SETGID
+@ovindex KMEM_GROUP
+@ovindex GETLOADAVG_LIBS
+Check how to get the system load averages.  If the system has the
+@code{getloadavg} function, define @code{HAVE_GETLOADAVG}, and set
+@code{GETLOADAVG_LIBS} to any libraries needed to get that function.
+Also add @code{GETLOADAVG_LIBS} to @code{LIBS}.
+
+Otherwise, require an @code{AC_LIBOBJ} replacement (@file{getloadavg.c})
+of @samp{getloadavg}, and possibly define several other C preprocessor
+macros and output variables:
+
+@enumerate
+@item
+Define @code{C_GETLOADAVG}.
+
+@item
+Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
+those systems.
+
+@item
+If @file{nlist.h} is found, define @code{NLIST_STRUCT}.
+
+@item
+If @samp{struct nlist} has an @samp{n_un.n_name} member, define
+@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}.  The obsolete symbol
+@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
+
+@item
+Programs may need to be installed setgid (or setuid) for
+@code{getloadavg} to work.  In this case, define
+@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
+to @samp{true} (and otherwise to @samp{false}), and set
+@code{KMEM_GROUP} to the name of the group that should own the installed
+program.
+@end enumerate
+@end defmac
+
+@defmac AC_FUNC_GETMNTENT
+@maindex FUNC_GETMNTENT
+@cvindex HAVE_GETMNTENT
+Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
+libraries, for Irix 4, PTX, and Unixware, respectively.  Then, if
+@code{getmntent} is available, define @code{HAVE_GETMNTENT}.
+@end defmac
+
+@defmac AC_FUNC_GETPGRP
+@maindex FUNC_GETPGRP
+@cvindex GETPGRP_VOID
+If @code{getpgrp} takes no argument (the @sc{posix.1} version), define
+@code{GETPGRP_VOID}.  Otherwise, it is the @sc{bsd} version, which takes
+a process ID as an argument.  This macro does not check whether
+@code{getpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
+@end defmac
+
+@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+@maindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
+If @file{link} is a symbolic link, then @code{lstat} should treat
+@file{link/} the same as @file{link/.}.  However, many older
+@code{lstat} implementations incorrectly ignore trailing slashes.
+
+It is safe to assume that if @code{lstat} incorrectly ignores
+trailing slashes, then other symbolic-link-aware functions like
+@code{unlink} and @code{unlink} also incorrectly ignore trailing slashes.
+
+If @code{lstat} behaves properly, define
+@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
+@code{AC_LIBOBJ} replacement of @code{lstat}.
+@end defmac
+
+@defmac AC_FUNC_MALLOC
+@maindex FUNC_MALLOC
+If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid
+pointer), define @code{HAVE_MALLOC}.
+@end defmac
+
+@defmac AC_FUNC_MEMCMP
+@maindex FUNC_MEMCMP
+@ovindex LIBOBJS
+If the @code{memcmp} function is not available, or does not work on
+8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
+bytes or more and with at least one buffer not starting on a 4-byte
+boundary (such as the one on NeXT x86 OpenStep), require an
+@code{AC_LIBOBJ} replacement for @samp{memcmp}.
+@end defmac
+
+@defmac AC_FUNC_MKTIME
+@maindex FUNC_MKTIME
+@ovindex LIBOBJS
+If the @code{mktime} function is not available, or does not work
+correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
+@end defmac
+
+@defmac AC_FUNC_MMAP
+@maindex FUNC_MMAP
+@cvindex HAVE_MMAP
+If the @code{mmap} function exists and works correctly, define
+@code{HAVE_MMAP}.  Only checks private fixed mapping of already-mapped
+memory.
+@end defmac
+
+@defmac AC_FUNC_OBSTACK
+@maindex FUNC_OBSTACK
+@cvindex HAVE_OBSTACK
+@cindex obstack
+If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
+@code{AC_LIBOBJ} replacement for @samp{obstack}.
+@end defmac
+
+@defmac AC_FUNC_SELECT_ARGTYPES
+@maindex FUNC_SELECT_ARGTYPES
+@cvindex SELECT_TYPE_ARG1
+@cvindex SELECT_TYPE_ARG234
+@cvindex SELECT_TYPE_ARG5
+Determines the correct type to be passed for each of the
+@code{select} function's arguments, and defines those types
+in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
+@code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
+to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
+and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
+@end defmac
+
+@defmac AC_FUNC_SETPGRP
+@maindex FUNC_SETPGRP
+@cvindex SETPGRP_VOID
+If @code{setpgrp} takes no argument (the @sc{posix.1} version), define
+@code{SETPGRP_VOID}.  Otherwise, it is the @sc{bsd} version, which takes
+two process IDs as arguments.  This macro does not check whether
+@code{setpgrp} exists at all; if you need to work in that situation,
+first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
+@end defmac
+
+@defmac AC_FUNC_STAT
+@defmacx AC_FUNC_LSTAT
+@maindex FUNC_STAT
+@maindex FUNC_LSTAT
+@cvindex HAVE_STAT_EMPTY_STRING_BUG
+@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
+Determine whether @code{stat} or @code{lstat} have the bug that it
+succeeds when given the zero-length file name argument.  The @code{stat}
+and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
+this.
+
+If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
+@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
+replacement of it.
+@end defmac
+
+@defmac AC_FUNC_SETVBUF_REVERSED
+@maindex FUNC_SETVBUF_REVERSED
+@cvindex SETVBUF_REVERSED
+If @code{setvbuf} takes the buffering type as its second argument and
+the buffer pointer as the third, instead of the other way around, define
+@code{SETVBUF_REVERSED}.
+@end defmac
+
+@defmac AC_FUNC_STRCOLL
+@maindex FUNC_STRCOLL
+@cvindex HAVE_STRCOLL
+If the @code{strcoll} function exists and works correctly, define
+@code{HAVE_STRCOLL}.  This does a bit more than
+@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
+definitions of @code{strcoll} that should not be used.
+@end defmac
+
+@defmac AC_FUNC_STRTOD
+@maindex FUNC_STRTOD
+@ovindex POW_LIB
+If the @code{strtod} function does not exist or doesn't work correctly,
+ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}.  In this case,
+because @file{strtod.c} is likely to need @samp{pow}, set the output
+variable @code{POW_LIB} to the extra library needed.
+@end defmac
+
+@defmac AC_FUNC_STRERROR_R
+@maindex FUNC_STRERROR_R
+@cvindex HAVE_STRERROR_R
+@cvindex HAVE_WORKING_STRERROR_R
+If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}.  If
+its implementation correctly returns a @code{char *}, define
+@code{HAVE_WORKING_STRERROR_R}.  On at least DEC UNIX 4.0[A-D] and HP-UX
+B.10.20, @code{strerror_r} returns @code{int}.  Actually, this tests
+only whether it returns a scalar or an array, but that should be enough.
+This is used by the common @file{error.c}.
+@end defmac
+
+@defmac AC_FUNC_STRFTIME
+@maindex FUNC_STRFTIME
+@cvindex HAVE_STRFTIME
+Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}.
+Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
+@end defmac
+
+@defmac AC_FUNC_UTIME_NULL
+@maindex FUNC_UTIME_NULL
+@cvindex HAVE_UTIME_NULL
+If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
+the present, define @code{HAVE_UTIME_NULL}.
+@end defmac
+
+@defmac AC_FUNC_VPRINTF
+@maindex FUNC_VPRINTF
+@cvindex HAVE_VPRINTF
+@cvindex HAVE_DOPRNT
+If @code{vprintf} is found, define @code{HAVE_VPRINTF}.  Otherwise, if
+@code{_doprnt} is found, define @code{HAVE_DOPRNT}.  (If @code{vprintf}
+is available, you may assume that @code{vfprintf} and @code{vsprintf}
+are also available.)
+@end defmac
+
+@node Generic Functions,  , Particular Functions, Library Functions
+@subsection Generic Function Checks
+
+These macros are used to find functions not covered by the ``particular''
+test macros.  If the functions might be in libraries other than the
+default C library, first call @code{AC_CHECK_LIB} for those libraries.
+If you need to check the behavior of a function as well as find out
+whether it is present, you have to write your own test for
+it (@pxref{Writing Tests}).
+
+@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FUNC
+If C function @var{function} is available, run shell commands
+@var{action-if-found}, otherwise @var{action-if-not-found}.  If you just
+want to define a symbol if the function is available, consider using
+@code{AC_CHECK_FUNCS} instead.  This macro checks for functions with C
+linkage even when @code{AC_LANG(C++)} has been called, since C is more
+standardized than C++.  (@pxref{Language Choice}, for more information
+about selecting the language for checks.)
+@end defmac
+
+@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex CHECK_FUNCS
+@cvindex HAVE_@var{function}
+For each @var{function} in the whitespace-separated argument list,
+define @code{HAVE_@var{function}} (in all capitals) if it is available.
+If @var{action-if-found} is given, it is additional shell code to
+execute when one of the functions is found.  You can give it a value of
+@samp{break} to break out of the loop on the first match.  If
+@var{action-if-not-found} is given, it is executed when one of the
+functions is not found.
+@end defmac
+
+Autoconf follows a philosophy that was formed over the years by those
+who have struggled for portability: isolate the portability issues in
+specific files, and then program as if you were in a @sc{posix}
+environment.  Some functions may be missing or unfixable, and your
+package must be ready to replace them.
+
+Use the first three of the following macros to specify a function to be
+replaced, and the last one (@code{AC_REPLACE_FUNCS}) to check for and
+replace the function if needed.
+
+@defmac AC_LIBOBJ (@var{function})
+@maindex LIBOBJ
+@ovindex LIBOBJS
+Specify that @samp{@var{function}.c} must be included in the executables
+to replace a missing or broken implementation of @var{function}.
+
+Technically, it adds @samp{@var{function}.$ac_objext} to the output
+variable @code{LIBOBJS} and calls @code{AC_LIBSOURCE} for
+@samp{@var{function}.c}.  You should not directly change @code{LIBOBJS},
+since this is not traceable.
+@end defmac
+
+@defmac AC_LIBSOURCE (@var{file})
+@maindex LIBSOURCE
+Specify that @var{file} might be needed to compile the project.  If you
+need to know what files might be needed by a @file{configure.ac}, you
+should trace @code{AC_LIBSOURCE}.  @var{file} must be a literal.
+
+This macro is called automatically from @code{AC_LIBOBJ}, but you must
+call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}.  In
+that case, since shell variables cannot be traced statically, you must
+pass to @code{AC_LIBSOURCE} any possible files that the shell variable
+might cause @code{AC_LIBOBJ} to need.  For example, if you want to pass
+a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
+@code{"foo"} or @code{"bar"}, you should do:
+
+@example
+AC_LIBSOURCE(foo.c)
+AC_LIBSOURCE(bar.c)
+AC_LIBOBJ($foo_or_bar)
+@end example
+
+@noindent
+There is usually a way to avoid this, however, and you are encouraged to
+simply call @code{AC_LIBOBJ} with literal arguments.
+
+Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
+slightly different semantics: the old macro took the function name,
+e.g. @code{foo}, as its argument rather than the file name.
+@end defmac
+
+@defmac AC_LIBSOURCES (@var{files})
+@maindex LIBSOURCES
+Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
+comma-separated M4 list.  Thus, the above example might be rewritten:
+
+@example
+AC_LIBSOURCES([foo.c, bar.c])
+AC_LIBOBJ($foo_or_bar)
+@end example
+@end defmac
+
+@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
+@maindex REPLACE_FUNCS
+@ovindex LIBOBJS
+Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
+@var{action-if-not-found}.  You can declare your replacement function by
+enclosing the prototype in @samp{#if !HAVE_@var{function}}.  If the
+system has the function, it probably declares it in a header file you
+should be including, so you shouldn't redeclare it lest your declaration
+conflict.
+@end defmac
+
+@node Header Files, Declarations, Library Functions, Existing Tests
+@section Header Files
+@cindex Header, checking
+
+The following macros check for the presence of certain C header files.
+If there is no macro specifically defined to check for a header file you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general header-file check macros.
+
+@menu
+* Particular Headers::          Special handling to find certain headers
+* Generic Headers::             How to find other headers
+@end menu
+
+@node Particular Headers, Generic Headers, Header Files, Header Files
+@subsection Particular Header Checks
+
+These macros check for particular system header files---whether they
+exist, and in some cases whether they declare certain symbols.
+
+@defmac AC_HEADER_DIRENT
+@maindex HEADER_DIRENT
+@cvindex HAVE_DIRENT_H
+@cvindex HAVE_NDIR_H
+@cvindex HAVE_SYS_DIR_H
+@cvindex HAVE_SYS_NDIR_H
+Check for the following header files.  For the first one that is
+found and defines @samp{DIR}, define the listed C preprocessor macro:
+
+@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
+@item @file{dirent.h}   @tab @code{HAVE_DIRENT_H}
+@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
+@item @file{sys/dir.h}  @tab @code{HAVE_SYS_DIR_H}
+@item @file{ndir.h}     @tab @code{HAVE_NDIR_H}
+@end multitable
+
+The directory-library declarations in your source code should look
+something like the following:
+
+@example
+@group
+#if HAVE_DIRENT_H
+# include <dirent.h>
+# define NAMLEN(dirent) strlen((dirent)->d_name)
+#else
+# define dirent direct
+# define NAMLEN(dirent) (dirent)->d_namlen
+# if HAVE_SYS_NDIR_H
+#  include <sys/ndir.h>
+# endif
+# if HAVE_SYS_DIR_H
+#  include <sys/dir.h>
+# endif
+# if HAVE_NDIR_H
+#  include <ndir.h>
+# endif
+#endif
+@end group
+@end example
+
+Using the above declarations, the program would declare variables to be
+of type @code{struct dirent}, not @code{struct direct}, and would access
+the length of a directory entry name by passing a pointer to a
+@code{struct dirent} to the @code{NAMLEN} macro.
+
+This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
+@end defmac
+
+@defmac AC_HEADER_MAJOR
+@maindex HEADER_MAJOR
+@cvindex MAJOR_IN_MKDEV
+@cvindex MAJOR_IN_SYSMACROS
+If @file{sys/types.h} does not define @code{major}, @code{minor}, and
+@code{makedev}, but @file{sys/mkdev.h} does, define
+@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
+@code{MAJOR_IN_SYSMACROS}.
+@end defmac
+
+
+@defmac AC_HEADER_STAT
+@maindex HEADER_STAT
+@maindex STAT_MACROS_BROKEN
+If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in
+@file{sys/stat.h} do not work properly (returning false positives),
+define @code{STAT_MACROS_BROKEN}.  This is the case on Tektronix UTekV,
+Amdahl UTS and Motorola System V/88.
+@end defmac
+
+
+@defmac AC_HEADER_STDC
+@maindex HEADER_STDC
+@cvindex STDC_HEADERS
+Define @code{STDC_HEADERS} if the system has @sc{ansi} C header files.
+Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
+@file{string.h}, and @file{float.h}; if the system has those, it
+probably has the rest of the @sc{ansi} C header files.  This macro also
+checks whether @file{string.h} declares @code{memchr} (and thus
+presumably the other @code{mem} functions), whether @file{stdlib.h}
+declare @code{free} (and thus presumably @code{malloc} and other related
+functions), and whether the @file{ctype.h} macros work on characters
+with the high bit set, as @sc{ansi} C requires.
+
+Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
+the system has @sc{ansi}-compliant header files (and probably C library
+functions) because many systems that have GCC do not have @sc{ansi} C
+header files.
+
+On systems without @sc{ansi} C headers, there is so much variation that
+it is probably easier to declare the functions you use than to figure
+out exactly what the system header files declare.  Some systems contain
+a mix of functions @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but
+lack @samp{memmove}; some define the @sc{bsd} functions as macros in
+@file{string.h} or @file{strings.h}; some have only the @sc{bsd}
+functions but @file{string.h}; some declare the memory functions in
+@file{memory.h}, some in @file{string.h}; etc.  It is probably
+sufficient to check for one string function and one memory function; if
+the library has the @sc{ansi} versions of those then it probably has
+most of the others.  If you put the following in @file{configure.ac}:
+
+@example
+AC_HEADER_STDC
+AC_CHECK_FUNCS(strchr memcpy)
+@end example
+
+@noindent
+then, in your code, you can put declarations like this:
+
+@example
+@group
+#if STDC_HEADERS
+# include <string.h>
+#else
+# if !HAVE_STRCHR
+#  define strchr index
+#  define strrchr rindex
+# endif
+char *strchr (), *strrchr ();
+# if !HAVE_MEMCPY
+#  define memcpy(d, s, n) bcopy ((s), (d), (n))
+#  define memmove(d, s, n) bcopy ((s), (d), (n))
+# endif
+#endif
+@end group
+@end example
+
+@noindent
+If you use a function like @code{memchr}, @code{memset}, @code{strtok},
+or @code{strspn}, which have no @sc{bsd} equivalent, then macros won't
+suffice; you must provide an implementation of each function.  An easy
+way to incorporate your implementations only when needed (since the ones
+in system C libraries may be hand optimized) is to, taking @code{memchr}
+for example, put it in @file{memchr.c} and use
+@samp{AC_REPLACE_FUNCS(memchr)}.
+@end defmac
+
+@defmac AC_HEADER_SYS_WAIT
+@maindex HEADER_SYS_WAIT
+@cvindex HAVE_SYS_WAIT_H
+If @file{sys/wait.h} exists and is compatible with @sc{posix.1}, define
+@code{HAVE_SYS_WAIT_H}.  Incompatibility can occur if @file{sys/wait.h}
+does not exist, or if it uses the old @sc{bsd} @code{union wait} instead
+of @code{int} to store a status value.  If @file{sys/wait.h} is not
+@sc{posix.1} compatible, then instead of including it, define the
+@sc{posix.1} macros with their usual interpretations.  Here is an
+example:
+
+@example
+@group
+#include <sys/types.h>
+#if HAVE_SYS_WAIT_H
+# include <sys/wait.h>
+#endif
+#ifndef WEXITSTATUS
+# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
+#endif
+#ifndef WIFEXITED
+# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
+#endif
+@end group
+@end example
+@end defmac
+
+@cvindex _POSIX_VERSION
+@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
+@sc{posix.1} systems.  If there is no @file{unistd.h}, it is definitely
+not a @sc{posix.1} system.  However, some non-@sc{posix.1} systems do
+have @file{unistd.h}.
+
+The way to check if the system supports @sc{posix.1} is:
+
+@example
+@group
+#if HAVE_UNISTD_H
+# include <sys/types.h>
+# include <unistd.h>
+#endif
+
+#ifdef _POSIX_VERSION
+/* Code for POSIX.1 systems.  */
+#endif
+@end group
+@end example
+
+@defmac AC_HEADER_TIME
+@maindex HEADER_TIME
+@cvindex TIME_WITH_SYS_TIME
+If a program may include both @file{time.h} and @file{sys/time.h},
+define @code{TIME_WITH_SYS_TIME}.  On some older systems,
+@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
+protected against multiple inclusion, so programs should not explicitly
+include both files.  This macro is useful in programs that use, for
+example, @code{struct timeval} or @code{struct timezone} as well as
+@code{struct tm}.  It is best used in conjunction with
+@code{HAVE_SYS_TIME_H}, which can be checked for using
+@code{AC_CHECK_HEADERS(sys/time.h)}.
+
+@example
+@group
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+#  include <sys/time.h>
+# else
+#  include <time.h>
+# endif
+#endif
+@end group
+@end example
+@end defmac
+
+
+@defmac AC_HEADER_TIOCGWINSZ
+@maindex HEADER_TIOCGWINSZ
+@cvindex GWINSZ_IN_SYS_IOCTL
+@c FIXME: I need clarifications from Jim.
+If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
+define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
+found in @file{<termios.h>}.
+
+Use:
+
+@example
+@group
+#if HAVE_TERMIOS_H
+# include <termios.h>
+#endif
+
+#if GWINSZ_IN_SYS_IOCTL
+# include <sys/ioctl.h>
+#endif
+@end group
+@end example
+@end defmac
+
+@node Generic Headers,  , Particular Headers, Header Files
+@subsection Generic Header Checks
+
+These macros are used to find system header files not covered by the
+``particular'' test macros.  If you need to check the contents of a header
+as well as find out whether it is present, you have to write your own
+test for it (@pxref{Writing Tests}).
+
+@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_HEADER
+If the system header file @var{header-file} is usable, execute shell
+commands @var{action-if-found}, otherwise execute
+@var{action-if-not-found}.  If you just want to define a symbol if the
+header file is available, consider using @code{AC_CHECK_HEADERS}
+instead.
+
+The meaning of ``usable'' depends upon the content of @var{includes}:
+
+@table @asis
+@item if @var{includes} is empty
+check whether
+
+@example
+@var{header-file}
+@end example
+
+@noindent
+can be @emph{preprocessed} without error.
+
+@item if @var{include} is set
+Check whether
+
+@example
+@var{includes}
+#include <@var{header-file}>
+@end example
+
+@noindent
+can be @emph{compiled} without error.  You may use
+@code{AC_CHECK_HEADER} (and @code{AC_CHECK_HEADERS}) to check whether
+two headers are compatible.
+@end table
+
+You may pass any kind of dummy content for @var{includes}, such as a
+single space, a comment, to check whether @var{header-file} compiles
+with success.
+@end defmac
+
+@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_HEADERS
+@cvindex HAVE_@var{header}
+For each given system header file @var{header-file} in the
+whitespace-separated argument list that exists, define
+@code{HAVE_@var{header-file}} (in all capitals).  If @var{action-if-found}
+is given, it is additional shell code to execute when one of the header
+files is found.  You can give it a value of @samp{break} to break out of
+the loop on the first match.  If @var{action-if-not-found} is given, it
+is executed when one of the header files is not found.
+
+Be sure to read the documentation of @code{AC_CHECK_HEADER} to
+understand the influence of @var{includes}.
+@end defmac
+
+@node Declarations, Structures, Header Files, Existing Tests
+@section Declarations
+@cindex Declaration, checking
+
+The following macros check for the declaration of variables and
+functions.  If there is no macro specifically defined to check for a
+symbol you need, then you can use the general macros (@pxref{Generic
+Declarations}) or, for more complex tests, you may use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
+
+@menu
+* Particular Declarations::     Macros to check for certain declarations
+* Generic Declarations::        How to find other declarations
+@end menu
+
+@node Particular Declarations, Generic Declarations, Declarations, Declarations
+@subsection Particular Declaration Checks
+
+The following macros check for certain declarations.
+
+@defmac AC_DECL_SYS_SIGLIST
+@maindex DECL_SYS_SIGLIST
+@cvindex SYS_SIGLIST_DECLARED
+Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist}
+is declared in a system header file, either @file{signal.h} or
+@file{unistd.h}.
+@end defmac
+
+@node Generic Declarations,  , Particular Declarations, Declarations
+@subsection Generic Declaration Checks
+
+These macros are used to find declarations not covered by the ``particular''
+test macros.
+
+@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_DECL
+If @var{symbol} (a function or a variable) is not declared in
+@var{includes} and a declaration is needed, run the shell commands
+@var{action-if-not-found}, otherwise @var{action-if-found}.  If no
+@var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+This macro actually tests whether it is valid to use @var{symbol} as an
+r-value, not if it is really declared, because it is much safer to avoid
+introducing extra declarations when they are not needed.
+@end defmac
+
+@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_DECLS
+@cvindex HAVE_DECL_@var{symbol}
+For each of the @var{symbols} (@emph{comma}-separated list), define
+@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
+@var{symbol} is declared, otherwise to @samp{0}.  If
+@var{action-if-not-found} is given, it is additional shell code to
+execute when one of the function declarations is needed, otherwise
+@var{action-if-found} is executed.
+
+This macro uses an m4 list as first argument:
+@example
+AC_CHECK_DECLS(strdup)
+AC_CHECK_DECLS([strlen])
+AC_CHECK_DECLS([malloc, realloc, calloc, free])
+@end example
+
+Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
+declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
+of leaving @code{HAVE_DECL_@var{symbol}} undeclared.  When you are
+@emph{sure} that the check was performed, use
+@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
+
+@example
+#if !HAVE_DECL_SYMBOL
+extern char *symbol;
+#endif
+@end example
+
+@noindent
+If the test may have not been performed, however, because it is safer
+@emph{not} to declare a symbol than to use a declaration that conflicts
+with the system's one, you should use:
+
+@example
+#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
+char *malloc (size_t *s);
+#endif
+@end example
+
+@noindent
+You fall into the second category only in extreme situations: either
+your files may be used without being configured, or they are used during
+the configuration.  In most cases the traditional approach is enough.
+@end defmac
+
+
+@node Structures, Types, Declarations, Existing Tests
+@section Structures
+@cindex Structure, checking
+
+The following macros check for the presence of certain members in C
+structures.  If there is no macro specifically defined to check for a
+member you need, then you can use the general structure-member macro
+(@pxref{Generic Structures}) or, for more complex tests, you may use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
+
+@menu
+* Particular Structures::       Macros to check for certain structure members
+* Generic Structures::          How to find other structure members
+@end menu
+
+@node Particular Structures, Generic Structures, Structures, Structures
+@subsection Particular Structure Checks
+
+The following macros check for certain structures or structure members.
+
+@defmac AC_STRUCT_ST_BLKSIZE
+@maindex STRUCT_ST_BLKSIZE
+@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
+@cvindex HAVE_ST_BLKSIZE
+If @code{struct stat} contains an @code{st_blksize} member, define
+@code{HAVE_STRUCT_STAT_ST_BLKSIZE}.  The former name,
+@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
+the future.  This macro is obsoleted, and should be replaced by
+
+@example
+AC_CHECK_MEMBERS([struct stat.st_blksize])
+@end example
+@end defmac
+
+@defmac AC_STRUCT_ST_BLOCKS
+@maindex STRUCT_ST_BLOCKS
+@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
+@cvindex HAVE_ST_BLOCKS
+@ovindex LIBOBJS
+If @code{struct stat} contains an @code{st_blocks} member, define
+@code{HAVE_STRUCT STAT_ST_BLOCKS}.  Otherwise, require an
+@code{AC_LIBOBJ} replacement of @samp{fileblocks}.  The former name,
+@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
+future.
+@end defmac
+
+@defmac AC_STRUCT_ST_RDEV
+@maindex STRUCT_ST_RDEV
+@cvindex HAVE_ST_RDEV
+@cvindex HAVE_STRUCT_STAT_ST_RDEV
+If @code{struct stat} contains an @code{st_rdev} member, define
+@code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
+@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
+in the future.  Actually, even the new macro is obsolete, and should be
+replaced by:
+@example
+AC_CHECK_MEMBERS([struct stat.st_rdev])
+@end example
+@end defmac
+
+@defmac AC_STRUCT_TM
+@maindex STRUCT_TM
+@cvindex TM_IN_SYS_TIME
+If @file{time.h} does not define @code{struct tm}, define
+@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
+had better define @code{struct tm}.
+@end defmac
+
+@defmac AC_STRUCT_TIMEZONE
+@maindex STRUCT_TIMEZONE
+@cvindex HAVE_TM_ZONE
+@cvindex HAVE_TZNAME
+Figure out how to get the current timezone.  If @code{struct tm} has a
+@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
+obsoleted @code{HAVE_TM_ZONE}).  Otherwise, if the external array
+@code{tzname} is found, define @code{HAVE_TZNAME}.
+@end defmac
+
+@node Generic Structures,  , Particular Structures, Structures
+@subsection Generic Structure Checks
+
+These macros are used to find structure members not covered by the
+``particular'' test macros.
+
+@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_MEMBER
+Check whether @var{member} is a member of the aggregate @var{aggregate}.
+If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).
+
+@example
+AC_CHECK_MEMBER(struct passwd.pw_gecos,,
+                [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
+                [#include <pwd.h>])
+@end example
+
+You can use this macro for sub-members:
+
+@example
+AC_CHECK_MEMBER(struct top.middle.bot)
+@end example
+@end defmac
+
+@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_MEMBERS
+Check for the existence of each @samp{@var{aggregate}.@var{member}} of
+@var{members} using the previous macro.  When @var{member} belongs to
+@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
+capitals, with spaces and dots replaced by underscores).
+
+This macro uses m4 lists:
+@example
+AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
+@end example
+@end defmac
+
+
+@node Types, Compilers and Preprocessors, Structures, Existing Tests
+@section Types
+
+The following macros check for C types, either builtin or typedefs.  If
+there is no macro specifically defined to check for a type you need, and
+you don't need to check for any special properties of it, then you can
+use a general type-check macro.
+
+@menu
+* Particular Types::            Special handling to find certain types
+* Generic Types::               How to find other types
+@end menu
+
+@node Particular Types, Generic Types, Types, Types
+@subsection Particular Type Checks
+
+These macros check for particular C types in @file{sys/types.h},
+@file{stdlib.h} and others, if they exist.
+
+@defmac AC_TYPE_GETGROUPS
+@maindex TYPE_GETGROUPS
+@cvindex GETGROUPS_T
+Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
+is the base type of the array argument to @code{getgroups}.
+@end defmac
+
+@defmac AC_TYPE_MODE_T
+@maindex TYPE_MODE_T
+@cvindex mode_t
+Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
+@end defmac
+
+@defmac AC_TYPE_OFF_T
+@maindex TYPE_OFF_T
+@cvindex off_t
+Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
+@end defmac
+
+@defmac AC_TYPE_PID_T
+@maindex TYPE_PID_T
+@cvindex pid_t
+Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
+@end defmac
+
+@defmac AC_TYPE_SIGNAL
+@maindex TYPE_SIGNAL
+@cvindex RETSIGTYPE
+If @file{signal.h} declares @code{signal} as returning a pointer to a
+function returning @code{void}, define @code{RETSIGTYPE} to be
+@code{void}; otherwise, define it to be @code{int}.
+
+Define signal handlers as returning type @code{RETSIGTYPE}:
+
+@example
+@group
+RETSIGTYPE
+hup_handler ()
+@{
+@dots{}
+@}
+@end group
+@end example
+@end defmac
+
+@defmac AC_TYPE_SIZE_T
+@maindex TYPE_SIZE_T
+@cvindex size_t
+Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
+@end defmac
+
+@defmac AC_TYPE_UID_T
+@maindex TYPE_UID_T
+@cvindex uid_t
+@cvindex gid_t
+If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
+@code{gid_t} to be @code{int}.
+@end defmac
+
+@node Generic Types,  , Particular Types, Types
+@subsection Generic Type Checks
+
+These macros are used to check for types not covered by the ``particular''
+test macros.
+
+@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_TYPE
+Check whether @var{type} is defined.  It may be a compiler builtin type
+or defined by the @ovar{includes} (@pxref{Default Includes}).
+@end defmac
+
+
+@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes})
+@maindex CHECK_TYPES
+For each @var{type} of the @var{types} that is defined, define
+@code{HAVE_@var{type}} (in all capitals).  If no @var{includes} are
+specified, the default includes are used (@pxref{Default Includes}).  If
+@var{action-if-found} is given, it is additional shell code to execute
+when one of the types is found.  If @var{action-if-not-found} is given,
+it is executed when one of the types is not found.
+
+This macro uses m4 lists:
+@example
+AC_CHECK_TYPES(ptrdiff_t)
+AC_CHECK_TYPES([unsigned long long, uintmax_t])
+@end example
+
+@end defmac
+
+Autoconf, up to 2.13, used to provide to another version of
+@code{AC_CHECK_TYPE}, broken by design.  In order to keep backward
+compatibility, a simple heuristics, quite safe but not totally, is
+implemented.  In case of doubt, read the documentation of the former
+@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
+
+
+@node Compilers and Preprocessors, System Services, Types, Existing Tests
+@section Compilers and Preprocessors
+
+@ovindex EXEEXT
+All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
+@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
+the output of the compiler, typically to the empty string if Unix and
+@samp{.exe} if Win32 or OS/2.
+
+@ovindex OBJEXT
+They also define the output variable @code{OBJEXT} based on the
+output of the compiler, after .c files have been excluded, typically
+to @samp{o} if Unix, @samp{obj} if Win32.
+
+If the compiler being used does not produce executables, they fail.  If
+the executables can't be run, and cross-compilation is not enabled, they
+fail too.  @xref{Manual Configuration}, for more on support for cross
+compiling.
+
+@menu
+* Generic Compiler Characteristics::  Language independent tests
+* C Compiler::                  Checking its characteristics
+* C++ Compiler::                Likewise
+* Fortran 77 Compiler::         Likewise
+@end menu
+
+@node Generic Compiler Characteristics, C Compiler, Compilers and Preprocessors, Compilers and Preprocessors
+@subsection Generic Compiler Characteristics
+
+@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @ovar{includes})
+@maindex CHECK_SIZEOF
+Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
+size in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
+of 0.  If no @var{includes} are specified, the default includes are used
+(@pxref{Default Includes}).  If you provide @var{include}, make sure to
+include @file{stdio.h} which is required for this macro to run.
+
+This macro now works even when cross-compiling.  The @var{unused}
+argument was used when cross-compiling.
+
+For example, the call
+
+@example
+AC_CHECK_SIZEOF(int *)
+@end example
+
+@noindent
+defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
+@end defmac
+
+
+@node C Compiler, C++ Compiler, Generic Compiler Characteristics, Compilers and Preprocessors
+@subsection C Compiler Characteristics
+
+@defmac AC_PROG_CC (@ovar{compiler-search-list})
+@maindex PROG_CC
+@ovindex CC
+@ovindex CFLAGS
+Determine a C compiler to use.  If @code{CC} is not already set in the
+environment, check for @code{gcc} and @code{cc}, then for other C
+compilers.  Set output variable @code{CC} to the name of the compiler
+found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C compilers to
+search for.  This just gives the user an opportunity to specify an
+alternative search list for the C compiler.  For example, if you didn't
+like the default order, then you could invoke @code{AC_PROG_CC} like
+this:
+
+@example
+AC_PROG_CC(cl egcs gcc cc)
+@end example
+
+If using the @sc{gnu} C compiler, set shell variable @code{GCC} to
+@samp{yes}.  If output variable @code{CFLAGS} was not already set, set
+it to @option{-g -O2} for the @sc{gnu} C compiler (@option{-O2} on systems
+where GCC does not accept @option{-g}), or @option{-g} for other compilers.
+@end defmac
+
+@defmac AC_PROG_CC_C_O
+@maindex PROG_CC_C_O
+@cvindex NO_MINUS_C_MINUS_O
+If the C compiler does not accept the @option{-c} and @option{-o} options
+simultaneously, define @code{NO_MINUS_C_MINUS_O}.  This macro actually
+tests both the compiler found by @code{AC_PROG_CC}, and, if different,
+the first @code{cc} in the path.  The test fails if one fails.  This
+macro was created for @sc{gnu} Make to choose the default C compilation
+rule.
+@end defmac
+
+@defmac AC_PROG_CC_STDC
+@maindex PROG_CC_STDC
+@ovindex CC
+If the C compiler is not in @sc{ansi} C mode by default, try to add an
+option to output variable @code{CC} to make it so.  This macro tries
+various options that select @sc{ansi} C on some system or another.  It
+considers the compiler to be in @sc{ansi} C mode if it handles function
+prototypes correctly.
+
+If you use this macro, you should check after calling it whether the C
+compiler has been set to accept @sc{ansi} C; if not, the shell variable
+@code{ac_cv_prog_cc_stdc} is set to @samp{no}.  If you wrote your source
+code in @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by
+using the program @code{ansi2knr}, which comes with Automake.
+@end defmac
+
+
+@defmac AC_PROG_CPP
+@maindex PROG_CPP
+@ovindex CPP
+Set output variable @code{CPP} to a command that runs the
+C preprocessor.  If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
+It is only portable to run @code{CPP} on files with a @file{.c}
+extension.
+
+If the current language is C (@pxref{Language Choice}), many of the
+specific test macros use the value of @code{CPP} indirectly by calling
+@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or
+@code{AC_EGREP_CPP}.
+
+Some preprocessors don't indicate missing include files by the error
+status.  For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.
+@end defmac
+
+
+The following macros check for C compiler or machine architecture
+features.  To check for characteristics not listed here, use
+@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN}
+(@pxref{Run Time})
+
+@defmac AC_C_BIGENDIAN
+@maindex C_BIGENDIAN
+@cvindex WORDS_BIGENDIAN
+@cindex Endianness
+If words are stored with the most significant byte first (like Motorola
+and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}.
+@end defmac
+
+
+@defmac AC_C_CONST
+@maindex C_CONST
+@cvindex const
+If the C compiler does not fully support the @sc{ansi} C qualifier
+@code{const}, define @code{const} to be empty.  Some C compilers that do
+not define @code{__STDC__} do support @code{const}; some compilers that
+define @code{__STDC__} do not completely support @code{const}.  Programs
+can simply use @code{const} as if every C compiler supported it; for
+those that don't, the @file{Makefile} or configuration header file will
+define it as empty.
+
+Occasionally installers use a C++ compiler to compile C code, typically
+because they lack a C compiler.  This causes problems with @code{const},
+because C and C++ treat @code{const} differently.  For example:
+
+@example
+const int foo;
+@end example
+
+@noindent
+is valid in C but not in C++.  These differences unfortunately cannot be
+papered over by defining @code{const} to be empty.
+
+If @code{autoconf} detects this situation, it leaves @code{const} alone,
+as this generally yields better results in practice.  However, using a
+C++ compiler to compile C code is not recommended or supported, and
+installers who run into trouble in this area should get a C compiler
+like GCC to compile their C code.
+@end defmac
+
+@defmac AC_C_VOLATILE
+@maindex C_VOLATILE
+@cvindex volatile
+If the C compiler does not understand the keyword @code{volatile},
+define @code{volatile} to be empty.  Programs can simply use
+@code{volatile} as if every C compiler supported it; for those that do
+not, the @file{Makefile} or configuration header will define it as
+empty.
+
+If the correctness of your program depends on the semantics of
+@code{volatile}, simply defining it to be empty does, in a sense, break
+your code.  However, given that the compiler does not support
+@code{volatile}, you are at its mercy anyway.  At least your
+program will compile, when it wouldn't before.
+
+In general, the @code{volatile} keyword is a feature of @sc{ansi} C, so
+you might expect that @code{volatile} is available only when
+@code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
+support volatile, but does not defined @code{__STDC__}.
+@end defmac
+
+@defmac AC_C_INLINE
+@maindex C_INLINE
+@cvindex inline
+If the C compiler supports the keyword @code{inline}, do nothing.
+Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
+if it accepts one of those, otherwise define @code{inline} to be empty.
+@end defmac
+
+@defmac AC_C_CHAR_UNSIGNED
+@maindex C_CHAR_UNSIGNED
+@cvindex __CHAR_UNSIGNED__
+If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
+unless the C compiler predefines it.
+@end defmac
+
+@defmac AC_C_LONG_DOUBLE
+@maindex C_LONG_DOUBLE
+@cvindex HAVE_LONG_DOUBLE
+If the C compiler supports the @code{long double} type, define
+@code{HAVE_LONG_DOUBLE}.  Some C compilers that do not define
+@code{__STDC__} do support the @code{long double} type; some compilers
+that define @code{__STDC__} do not support @code{long double}.
+@end defmac
+
+@defmac AC_C_STRINGIZE
+@maindex C_STRINGIZE
+@cvindex HAVE_STRINGIZE
+If the C preprocessor supports the stringizing operator, define
+@code{HAVE_STRINGIZE}.  The stringizing operator is @samp{#} and is
+found in macros such as this:
+
+@example
+#define x(y) #y
+@end example
+@end defmac
+
+@defmac AC_C_PROTOTYPES
+@maindex C_PROTOTYPES
+@cvindex PROTOTYPES
+@cvindex PARAMS
+Check to see if function prototypes are understood by the compiler.  If
+so, define @samp{PROTOTYPES}.  In the case the compiler does not handle
+prototypes, you should use @code{ansi2knr}, which comes with the
+Automake distribution, to unprotoize function definitions.  For
+function prototypes, you should first define @code{PARAMS}:
+
+@example
+#ifndef PARAMS
+# if PROTOTYPES
+#  define PARAMS(protos) protos
+# else /* no PROTOTYPES */
+#  define PARAMS(protos) ()
+# endif /* no PROTOTYPES */
+#endif
+@end example
+
+@noindent
+then use it this way:
+
+@example
+size_t my_strlen PARAMS ((const char *));
+@end example
+@end defmac
+
+@defmac AC_PROG_GCC_TRADITIONAL
+@maindex PROG_GCC_TRADITIONAL
+@ovindex CC
+Add @option{-traditional} to output variable @code{CC} if using the
+@sc{gnu} C compiler and @code{ioctl} does not work properly without
+@option{-traditional}.  That usually happens when the fixed header files
+have not been installed on an old system.  Since recent versions of the
+@sc{gnu} C compiler fix the header files automatically when installed,
+this is becoming a less prevalent problem.
+@end defmac
+
+
+@node C++ Compiler, Fortran 77 Compiler, C Compiler, Compilers and Preprocessors
+@subsection C++ Compiler Characteristics
+
+
+@defmac AC_PROG_CXX (@ovar{compiler-search-list})
+@maindex PROG_CXX
+@ovindex CXX
+@ovindex CXXFLAGS
+Determine a C++ compiler to use.  Check if the environment variable
+@code{CXX} or @code{CCC} (in that order) is set; if so, then set output
+variable @code{CXX} to its value.
+
+Otherwise, if the macro is invoked without an argument, then search for
+a C++ compiler under the likely names (first @code{g++} and @code{c++}
+then other names).  If none of those checks succeed, then as a last
+resort set @code{CXX} to @code{g++}.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C++ compilers to
+search for.  This just gives the user an opportunity to specify an
+alternative search list for the C++ compiler.  For example, if you
+didn't like the default order, then you could invoke @code{AC_PROG_CXX}
+like this:
+
+@example
+AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
+@end example
+
+If using the @sc{gnu} C++ compiler, set shell variable @code{GXX} to
+@samp{yes}.  If output variable @code{CXXFLAGS} was not already set, set
+it to @option{-g -O2} for the @sc{gnu} C++ compiler (@option{-O2} on
+systems where G++ does not accept @option{-g}), or @option{-g} for other
+compilers.
+@end defmac
+
+@defmac AC_PROG_CXXCPP
+@maindex PROG_CXXCPP
+@ovindex CXXCPP
+Set output variable @code{CXXCPP} to a command that runs the C++
+preprocessor.  If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
+It is only portable to run @code{CXXCPP} on files with a @file{.c},
+@file{.C}, or @file{.cc} extension.
+
+If the current language is C++ (@pxref{Language Choice}), many of the
+specific test macros use the value of @code{CXXCPP} indirectly by
+calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER},
+@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}.
+
+Some preprocessors don't indicate missing include files by the error
+status.  For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.  However,
+it is not known whether such broken preprocessors exist for C++.
+@end defmac
+
+
+
+@node Fortran 77 Compiler,  , C++ Compiler, Compilers and Preprocessors
+@subsection Fortran 77 Compiler Characteristics
+
+@defmac AC_PROG_F77 (@ovar{compiler-search-list})
+@maindex PROG_FORTRAN
+@ovindex F77
+@ovindex FFLAGS
+Determine a Fortran 77 compiler to use.  If @code{F77} is not already
+set in the environment, then check for @code{g77} and @code{f77}, and
+then some other names.  Set the output variable @code{F77} to the name
+of the compiler found.
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of Fortran 77
+compilers to search for.  This just gives the user an opportunity to
+specify an alternative search list for the Fortran 77 compiler.  For
+example, if you didn't like the default order, then you could invoke
+@code{AC_PROG_F77} like this:
+
+@example
+AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)
+@end example
+
+If using @code{g77} (the @sc{gnu} Fortran 77 compiler), then
+@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
+If the output variable @code{FFLAGS} was not already set in the
+environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
+where @code{g77} does not accept @option{-g}).  Otherwise, set
+@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
+@end defmac
+
+@defmac AC_PROG_F77_C_O
+@maindex PROG_F77_C_O
+@cvindex F77_NO_MINUS_C_MINUS_O
+Test if the Fortran 77 compiler accepts the options @option{-c} and
+@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it
+does not.
+@end defmac
+
+
+The following macros check for Fortran 77 compiler characteristics.  To
+check for characteristics not listed here, use @code{AC_TRY_COMPILE}
+(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}),
+making sure to first set the current language to Fortran 77
+@code{AC_LANG(Fortran 77)} (@pxref{Language Choice}).
+
+
+@defmac AC_F77_LIBRARY_LDFLAGS
+@maindex F77_LIBRARY_LDFLAGS
+@ovindex FLIBS
+Determine the linker flags (e.g. @option{-L} and @option{-l}) for the
+@dfn{Fortran 77 intrinsic and run-time libraries} that are required to
+successfully link a Fortran 77 program or shared library.  The output
+variable @code{FLIBS} is set to these flags.
+
+This macro is intended to be used in those situations when it is
+necessary to mix, e.g. C++ and Fortran 77 source code into a single
+program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
+automake, GNU Automake}).
+
+For example, if object files from a C++ and Fortran 77 compiler must be
+linked together, then the C++ compiler/linker must be used for linking
+(since special C++-ish things need to happen at link time like calling
+global constructors, instantiating templates, enabling exception
+support, etc.).
+
+However, the Fortran 77 intrinsic and run-time libraries must be linked
+in as well, but the C++ compiler/linker doesn't know by default how to
+add these Fortran 77 libraries.  Hence, the macro
+@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77
+libraries.
+
+The macro @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} will probably
+also be necessary to link C/C++ with Fortran; see below.
+@end defmac
+
+
+@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex F77_DUMMY_MAIN
+@cvindex F77_DUMMY_MAIN
+With many compilers, the Fortran libraries detected by
+@code{AC_F77_LIBRARY_LDFLAGS} provide their own @code{main} entry
+function that initializes things like Fortran I/O, and which then calls
+a user-provided entry function named e.g. @code{MAIN__} to run the
+user's program.  The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN}
+macro figures out how to deal with this interaction.
+
+When using Fortran for purely numerical functions (no I/O, etcetera),
+users often prefer to provide their own @code{main} and skip the Fortran
+library initializations.  In this case, however, one may still need to
+provide a dummy @code{MAIN__} routine in order to prevent linking errors
+on some systems.  @code{AC_F77_DUMMY_MAIN} detects whether any such
+routine is @emph{required} for linking, and what its name is; the shell
+variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no
+solution was found, and @code{none} when no such dummy main is needed.
+
+By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the
+name of this routine (e.g. @code{MAIN__}) @emph{if} it is required.
+@ovar{action-if-not-found} defaults to exiting with an error.
+
+In order to link with Fortran routines, the user's C/C++ program should
+then include the following code to define the dummy main if it is
+needed:
+
+@example
+#ifdef F77_DUMMY_MAIN
+#  ifdef __cplusplus
+     extern "C"
+#  endif
+   int F77_DUMMY_MAIN() @{ return 1; @}
+#endif
+@end example
+
+Note that @code{AC_F77_DUMMY_MAIN} is called automatically from
+@code{AC_F77_WRAPPERS}; there is generally no need to call it explicitly
+unless one wants to change the default actions.
+@end defmac
+
+@defmac AC_F77_MAIN
+@maindex F77_MAIN
+@cvindex F77_MAIN
+As discussed above for @code{AC_F77_DUMMY_MAIN}, many Fortran libraries
+allow you to provide an entry point called e.g. @code{MAIN__} instead of
+the usual @code{main}, which is then called by a @code{main} function in
+the Fortran libraries that initializes things like Fortran I/O.  The
+@code{AC_F77_MAIN} macro detects whether it is @emph{possible} to
+utilize such an alternate main function, and defines @code{F77_MAIN} to
+the name of the function.  (If no alternate main function name is found,
+@code{F77_MAIN} is simply defined to @code{main}.)
+
+Thus, when calling Fortran routines from C that perform things like I/O,
+one should use this macro and name the "main" function @code{F77_MAIN}
+instead of @code{main}.
+@end defmac
+
+@defmac AC_F77_WRAPPERS
+@maindex F77_WRAPPERS
+@cvindex F77_FUNC
+@cvindex F77_FUNC_
+Defines C macros @code{F77_FUNC(name,NAME)} and
+@code{F77_FUNC_(name,NAME)} to properly mangle the names of C/C++
+identifiers, and identifiers with underscores, respectively, so that
+they match the name-mangling scheme used by the Fortran 77 compiler.
+
+Fortran 77 is case-insensitive, and in order to achieve this the Fortran
+77 compiler converts all identifiers into a canonical case and format.
+To call a Fortran 77 subroutine from C or to write a C function that is
+callable from Fortran 77, the C program must explicitly use identifiers
+in the format expected by the Fortran 77 compiler.  In order to do this,
+one simply wraps all C identifiers in one of the macros provided by
+@code{AC_F77_WRAPPERS}.  For example, suppose you have the following
+Fortran 77 subroutine:
+
+@example
+      subroutine foobar(x,y)
+      double precision x, y
+      y = 3.14159 * x
+      return
+      end
+@end example
+
+You would then declare its prototype in C or C++ as:
+
+@example
+#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
+#ifdef __cplusplus
+extern "C"  /* prevent C++ name mangling */
+#endif
+void FOOBAR_F77(double *x, double *y);
+@end example
+
+Note that we pass both the lowercase and uppercase versions of the
+function name to @code{F77_FUNC} so that it can select the right one.
+Note also that all parameters to Fortran 77 routines are passed as
+pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, GNU
+Automake}).
+
+Although Autoconf tries to be intelligent about detecting the
+name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77
+compilers that it doesn't support yet.  In this case, the above code
+will generate a compile-time error, but some other behavior
+(e.g. disabling Fortran-related features) can be induced by checking
+whether the @code{F77_FUNC} macro is defined.
+
+Now, to call that routine from a C program, we would do something like:
+
+@example
+@{
+    double x = 2.7183, y;
+    FOOBAR_F77(&x, &y);
+@}
+@end example
+
+If the Fortran 77 identifier contains an underscore
+(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of
+@code{F77_FUNC} (with the same arguments).  This is because some Fortran
+77 compilers mangle names differently if they contain an underscore.
+@end defmac
+
+@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
+@maindex F77_FUNC
+Given an identifier @var{name}, set the shell variable @var{shellvar} to
+hold the mangled version @var{name} according to the rules of the
+Fortran 77 linker (see also @code{AC_F77_WRAPPERS}).  @var{shellvar} is
+optional; if it is not supplied, the shell variable will be simply
+@var{name}.  The purpose of this macro is to give the caller a way to
+access the name-mangling information other than through the C
+preprocessor as above; for example, to call Fortran routines from some
+language other than C/C++.
+@end defmac
+
+@node System Services, UNIX Variants, Compilers and Preprocessors, Existing Tests
+@section System Services
+
+The following macros check for operating system services or capabilities.
+
+@defmac AC_PATH_X
+@maindex PATH_X
+Try to locate the X Window System include files and libraries.  If the
+user gave the command line options @option{--x-includes=@var{dir}} and
+@option{--x-libraries=@var{dir}}, use those directories.  If either or
+both were not given, get the missing values by running @code{xmkmf} on a
+trivial @file{Imakefile} and examining the @file{Makefile} that it
+produces.  If that fails (such as if @code{xmkmf} is not present), look
+for them in several directories where they often reside.  If either
+method is successful, set the shell variables @code{x_includes} and
+@code{x_libraries} to their locations, unless they are in directories
+the compiler searches by default.
+
+If both methods fail, or the user gave the command line option
+@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
+otherwise set it to the empty string.
+@end defmac
+
+@defmac AC_PATH_XTRA
+@maindex PATH_XTRA
+@ovindex X_CFLAGS
+@ovindex X_LIBS
+@ovindex X_EXTRA_LIBS
+@ovindex X_PRE_LIBS
+@cvindex X_DISPLAY_MISSING
+An enhanced version of @code{AC_PATH_X}.  It adds the C compiler flags
+that X needs to output variable @code{X_CFLAGS}, and the X linker flags
+to @code{X_LIBS}.  Define @code{X_DISPLAY_MISSING} if X is not
+available.
+
+This macro also checks for special libraries that some systems need in
+order to compile X programs.  It adds any that the system needs to
+output variable @code{X_EXTRA_LIBS}.  And it checks for special X11R6
+libraries that need to be linked with before @option{-lX11}, and adds
+any found to the output variable @code{X_PRE_LIBS}.
+
+@c This is an incomplete kludge.  Make a real way to do it.
+@c If you need to check for other X functions or libraries yourself, then
+@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
+@c @code{LIBS} temporarily, like this: (FIXME - add example)
+@end defmac
+
+@defmac AC_SYS_INTERPRETER
+@maindex SYS_INTERPRETER
+Check whether the system supports starting scripts with a line of the
+form @samp{#! /bin/csh} to select the interpreter to use for the script.
+After running this macro, shell code in @code{configure.ac} can check
+the shell variable @code{interpval}; it will be set to @samp{yes}
+if the system supports @samp{#!}, @samp{no} if not.
+@end defmac
+
+@defmac AC_SYS_LARGEFILE
+@maindex SYS_LARGEFILE
+@cvindex _FILE_OFFSET_BITS
+@cvindex _LARGE_FILES
+@ovindex CC
+Arrange for
+@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html,
+large-file support}.  On some hosts, one must use special compiler
+options to build programs that can access large files.  Append any such
+options to the output variable @code{CC}.  Define
+@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
+
+Large-file support can be disabled by configuring with the
+@option{--disable-largefile} option.
+
+If you use this macro, check that your program works even when
+@code{off_t} is longer than @code{long}, since this is common when
+large-file support is enabled.  For example, it is not correct to print
+an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
+(long) X)}.
+@end defmac
+
+@defmac AC_SYS_LONG_FILE_NAMES
+@maindex SYS_LONG_FILE_NAMES
+@cvindex HAVE_LONG_FILE_NAMES
+If the system supports file names longer than 14 characters, define
+@code{HAVE_LONG_FILE_NAMES}.
+@end defmac
+
+@defmac AC_SYS_POSIX_TERMIOS
+@maindex SYS_POSIX_TERMIOS
+@cindex POSIX termios headers
+@cindex termios POSIX headers
+Check to see if POSIX termios headers and functions are available on the
+system.  If so, set the shell variable @code{am_cv_sys_posix_termios} to
+@samp{yes}.  If not, set the variable to @samp{no}.
+@end defmac
+
+@node UNIX Variants,  , System Services, Existing Tests
+@section UNIX Variants
+
+The following macros check for certain operating systems that need
+special treatment for some programs, due to exceptional oddities in
+their header files or libraries.  These macros are warts; they will be
+replaced by a more systematic approach, based on the functions they make
+available or the environments they provide.
+
+@defmac AC_AIX
+@maindex AIX
+@cvindex _ALL_SOURCE
+If on AIX, define @code{_ALL_SOURCE}.  Allows the use of some @sc{bsd}
+functions.  Should be called before any macros that run the C compiler.
+@end defmac
+
+@defmac AC_ISC_POSIX
+@maindex ISC_POSIX
+@cvindex _POSIX_SOURCE
+@ovindex CC
+If on a POSIXized ISC @sc{unix}, define @code{_POSIX_SOURCE} and add
+@option{-posix} (for the @sc{gnu} C compiler) or @option{-Xp} (for other C
+compilers) to output variable @code{CC}.  This allows the use of
+@sc{posix} facilities.  Must be called after @code{AC_PROG_CC} and
+before any other macros that run the C compiler.
+@end defmac
+
+@defmac AC_MINIX
+@maindex MINIX
+@cvindex _MINIX
+@cvindex _POSIX_SOURCE
+@cvindex _POSIX_1_SOURCE
+If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
+@code{_POSIX_1_SOURCE} to be 2.  This allows the use of @sc{posix}
+facilities.  Should be called before any macros that run the C compiler.
+@end defmac
+
+
+
+
+@c ========================================================= Writing Tests
+
+@node Writing Tests, Results, Existing Tests, Top
+@chapter Writing Tests
+
+If the existing feature tests don't do something you need, you have to
+write new ones.  These macros are the building blocks.  They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+This chapter contains some suggestions and some of the reasons why the
+existing tests are written the way they are.  You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones.  If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand the assumptions behind them, which
+might help you figure out how to best solve the problem.
+
+These macros check the output of the C compiler system.  They do
+not cache the results of their tests for future use (@pxref{Caching
+Results}), because they don't know enough about the information they are
+checking for to generate a cache variable name.  They also do not print
+any messages, for the same reason.  The checks for particular kinds of C
+features call these macros and do cache their results and print messages
+about what they're checking for.
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+@xref{Writing Autoconf Macros}, for how to do that.
+
+@menu
+* Examining Declarations::      Detecting header files and declarations
+* Examining Syntax::            Detecting language syntax features
+* Examining Libraries::         Detecting functions and global variables
+* Run Time::                    Testing for run-time features
+* Systemology::                 A zoology of operating systems
+* Multiple Cases::              Tests for several possible values
+* Language Choice::             Selecting which language to use for testing
+@end menu
+
+@node Examining Declarations, Examining Syntax, Writing Tests, Writing Tests
+@section Examining Declarations
+
+The macro @code{AC_TRY_CPP} is used to check whether particular header
+files exist.  You can check for one at a time, or more than one if you
+need several header files to all exist for some purpose.
+
+@defmac AC_TRY_CPP (@var{includes}, @ovar{action-if-true}, @ovar{action-if-false})
+@maindex TRY_CPP
+@var{includes} is C or C++ @code{#include} statements and declarations,
+on which shell variable, back quote, and backslash substitutions are
+performed.  (Actually, it can be any C program, but other statements are
+probably not useful.)  If the preprocessor produces no error messages
+while processing it, run shell commands @var{action-if-true}.  Otherwise
+run shell commands @var{action-if-false}.
+
+This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
+@option{-g}, @option{-O}, etc. are not valid options to many C
+preprocessors.
+@end defmac
+
+Here is how to find out whether a header file contains a particular
+declaration, such as a typedef, a structure, a structure member, or a
+function.  Use @code{AC_EGREP_HEADER} instead of running @code{grep}
+directly on the header file; on some systems the symbol might be defined
+in another header file that the file you are checking @samp{#include}s.
+
+@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
+@maindex EGREP_HEADER
+If the output of running the preprocessor on the system header file
+@var{header-file} matches the @code{egrep} regular expression
+@var{pattern}, execute shell commands @var{action-if-found}, otherwise
+execute @var{action-if-not-found}.
+@end defmac
+
+To check for C preprocessor symbols, either defined by header files or
+predefined by the C preprocessor, use @code{AC_EGREP_CPP}.  Here is an
+example of the latter:
+
+@example
+AC_EGREP_CPP(yes,
+[#ifdef _AIX
+  yes
+#endif
+], is_aix=yes, is_aix=no)
+@end example
+
+@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex EGREP_CPP
+@var{program} is the text of a C or C++ program, on which shell
+variable, back quote, and backslash substitutions are performed.  If the
+output of running the preprocessor on @var{program} matches the
+@code{egrep} regular expression @var{pattern}, execute shell commands
+@var{action-if-found}, otherwise execute @var{action-if-not-found}.
+
+This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
+on which language is current, @pxref{Language Choice}), if it hasn't
+been called already.
+@end defmac
+
+@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests
+@section Examining Syntax
+
+To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
+as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to
+try to compile a small program that uses that feature.  You can also use
+it to check for structures and structure members that are not present on
+all systems.
+
+@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_COMPILE
+Create a C, C++ or Fortran 77 test program (depending on which language
+is current, @pxref{Language Choice}), to see whether a function whose
+body consists of @var{function-body} can be compiled.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} will be ignored if
+the currently selected language is Fortran 77).  This macro also uses
+@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
+selected language, as well as @code{CPPFLAGS}, when compiling.  If
+Fortran 77 is the currently selected language then @code{FFLAGS} will be
+used when compiling.
+
+If the file compiles successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+
+This macro does not try to link; use @code{AC_TRY_LINK} if you need to
+do that (@pxref{Examining Libraries}).
+@end defmac
+
+@node Examining Libraries, Run Time, Examining Syntax, Writing Tests
+@section Examining Libraries
+
+To check for a library, a function, or a global variable, Autoconf
+@code{configure} scripts try to compile and link a small program that
+uses it.  This is unlike Metaconfig, which by default uses @code{nm}
+or @code{ar} on the C library to try to figure out which functions are
+available.  Trying to link with the function is usually a more reliable
+approach because it avoids dealing with the variations in the options
+and output formats of @code{nm} and @code{ar} and in the location of the
+standard libraries.  It also allows configuring for cross-compilation or
+checking a function's runtime behavior if needed.  On the other hand, it
+can be slower than scanning the libraries once.
+
+A few systems have linkers that do not return a failure exit status when
+there are unresolved functions in the link.  This bug makes the
+configuration scripts produced by Autoconf unusable on those systems.
+However, some of them can be given options that make the exit status
+correct.  This is a problem that Autoconf does not currently handle
+automatically.  If users encounter this problem, they might be able to
+solve it by setting @code{LDFLAGS} in the environment to pass whatever
+options the linker needs (for example, @option{-Wl,-dn} on @sc{mips
+risc/os}).
+
+@code{AC_TRY_LINK} is used to compile test programs to test for
+functions and global variables.  It is also used by @code{AC_CHECK_LIB}
+to check for libraries (@pxref{Libraries}), by adding the library being
+checked for to @code{LIBS} temporarily and trying to link a small
+program.
+
+@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_LINK
+Depending on the current language (@pxref{Language Choice}), create a
+test program to see whether a function whose body consists of
+@var{function-body} can be compiled and linked.
+
+For C and C++, @var{includes} is any @code{#include} statements needed
+by the code in @var{function-body} (@var{includes} will be ignored if
+the currently selected language is Fortran 77).  This macro also uses
+@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
+selected language, as well as @code{CPPFLAGS}, when compiling.  If
+Fortran 77 is the currently selected language then @code{FFLAGS} will be
+used when compiling.  However, both @code{LDFLAGS} and @code{LIBS} will
+be used during linking in all cases.
+
+If the file compiles and links successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+@end defmac
+
+@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@maindex TRY_LINK_FUNC
+Depending on the current language (@pxref{Language Choice}), create a
+test program to see whether a program whose body consists of
+a prototype of and a call to @var{function} can be compiled and linked.
+
+If the file compiles and links successfully, run shell commands
+@var{action-if-found}, otherwise run @var{action-if-not-found}.
+@end defmac
+
+
+
+@node Run Time, Systemology, Examining Libraries, Writing Tests
+@section Checking Run Time Behavior
+
+Sometimes you need to find out how a system performs at run time, such
+as whether a given function has a certain capability or bug.  If you
+can, make such checks when your program runs instead of when it is
+configured.  You can check for things like the machine's endianness when
+your program initializes itself.
+
+If you really need to test for a run-time behavior while configuring,
+you can write a test program to determine the result, and compile and
+run it using @code{AC_TRY_RUN}.  Avoid running test programs if
+possible, because this prevents people from configuring your package for
+cross-compiling.
+
+@menu
+* Test Programs::               Running test programs
+* Guidelines::                  General rules for writing test programs
+* Test Functions::              Avoiding pitfalls in test programs
+@end menu
+
+@node Test Programs, Guidelines, Run Time, Run Time
+@subsection Running Test Programs
+
+Use the following macro if you need to test run-time behavior of the
+system while configuring.
+
+@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
+@maindex TRY_RUN
+@var{program} is the text of a C program, on which shell variable and
+back quote substitutions are performed.  If it compiles and links
+successfully and returns an exit status of 0 when executed, run shell
+commands @var{action-if-true}.  Otherwise, run shell commands
+@var{action-if-false}; the exit status of the program is available in
+the shell variable @samp{$?}.  This macro uses @code{CFLAGS} or
+@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when
+compiling.
+
+If the C compiler being used does not produce executables that run on
+the system where @code{configure} is being run, then the test program is
+not run.  If the optional shell commands @var{action-if-cross-compiling}
+are given, they are run instead.  Otherwise, @code{configure} prints
+an error message and exits.
+@end defmac
+
+Try to provide a pessimistic default value to use when cross-compiling
+makes run-time tests impossible.  You do this by passing the optional
+last argument to @code{AC_TRY_RUN}.  @code{autoconf} prints a warning
+message when creating @code{configure} each time it encounters a call to
+@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument
+given.  You may ignore the warning, though users will not be able to
+configure your package for cross-compiling.  A few of the macros
+distributed with Autoconf produce this warning message.
+
+To configure for cross-compiling you can also choose a value for those
+parameters based on the canonical system name (@pxref{Manual
+Configuration}).  Alternatively, set up a test results cache file with
+the correct values for the host system (@pxref{Caching Results}).
+
+To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call @code{AC_PROG_CC} before running them.  Then, if the shell
+variable @code{cross_compiling} is set to @samp{yes}, use an alternate
+method to get the results instead of calling the macros.
+
+
+@node Guidelines, Test Functions, Test Programs, Run Time
+@subsection Guidelines for Test Programs
+
+Test programs should not write anything to the standard output.  They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status.  Test programs should @code{exit}, not @code{return}, from
+@code{main}, because on some systems (old Suns, at least) the argument
+to @code{return} in @code{main} is ignored.
+
+Test programs can use @code{#if} or @code{#ifdef} to check the values of
+preprocessor macros defined by tests that have already run.  For
+example, if you call @code{AC_HEADER_STDC}, then later on in
+@file{configure.ac} you can have a test program that includes an
+@sc{ansi} C header file conditionally:
+
+@example
+@group
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+@end group
+@end example
+
+If a test program needs to use or create a data file, give it a name
+that starts with @file{conftest}, such as @file{conftest.data}.  The
+@code{configure} script cleans up by running @samp{rm -rf conftest*}
+after running test programs and if the script is interrupted.
+
+@node Test Functions,  , Guidelines, Run Time
+@subsection Test Functions
+
+Function declarations in test programs should have a prototype
+conditionalized for C++.  In practice, though, test programs rarely need
+functions that take arguments.
+
+@example
+#ifdef __cplusplus
+foo (int i)
+#else
+foo (i) int i;
+#endif
+@end example
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires @samp{extern "C"} prototypes.  Make sure to not
+include any header files containing clashing prototypes.
+
+@example
+#ifdef __cplusplus
+extern "C" void *malloc (size_t);
+#else
+char *malloc ();
+#endif
+@end example
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function.  You can do this by calling it in another function that is
+never invoked.  You can't do it by putting it after a call to
+@code{exit}, because GCC version 2 knows that @code{exit} never returns
+and optimizes out any code that follows it in the same block.
+
+If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes.  GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, @code{memcpy}.  To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as @code{char}).
+
+@node Systemology, Multiple Cases, Run Time, Writing Tests
+@section Systemology
+
+This section aims at presenting some systems and pointers to
+documentation.  It may help you addressing particular problems reported
+by users.
+
+@table @asis
+@item @sc{qnx 4.25}
+@cindex @sc{qnx 4.25}
+@c FIXME: Please, if you feel like writing something more precise,
+@c it'd be great.  In particular, I can't understand the difference with
+@c QNX Neutrino.
+@sc{qnx} is a realtime operating system running on Intel architecture
+meant to be scalable from the small embedded systems to hundred
+processor super-computer.  It claims to be @sc{posix} certified. More
+information is available on the @href{www.qnx.com, @sc{qnx} home page},
+including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx}
+man pages}.
+@end table
+
+
+@node Multiple Cases, Language Choice, Systemology, Writing Tests
+@section Multiple Cases
+
+Some operations are accomplished in several possible ways, depending on
+the @sc{unix} variant.  Checking for them essentially requires a ``case
+statement''.  Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+Here is an example that uses the shell variable @code{fstype} to keep
+track of whether the remaining cases need to be checked.
+
+@example
+@group
+AC_MSG_CHECKING([how to get file system type])
+fstype=no
+# The order of these tests is important.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>],
+           [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>],
+             [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+fi
+if test $fstype = no; then
+  AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>],
+             [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+fi
+# (more cases omitted here)
+AC_MSG_RESULT([$fstype])
+@end group
+@end example
+
+@node Language Choice,  , Multiple Cases, Writing Tests
+@section Language Choice
+@cindex Language
+
+Autoconf-generated @code{configure} scripts check for the C compiler and
+its features by default.  Packages that use other programming languages
+(maybe more than one, e.g. C and C++) need to test features of the
+compilers for the respective languages.  The following macros determine
+which programming language is used in the subsequent tests in
+@file{configure.ac}.
+
+@defmac AC_LANG (@var{language})
+Do compilation tests using the compiler, preprocessor and file
+extensions for the specified @var{language}.
+
+Supported languages are:
+
+@table @samp
+@item C
+Do compilation tests using @code{CC} and @code{CPP} and use extension
+@file{.c} for test programs.
+
+@item C++
+Do compilation tests using @code{CXX} and @code{CXXCPP} and use
+extension @file{.C} for test programs.
+
+@item Fortran 77
+Do compilation tests using @code{F77} and use extension @file{.f} for
+test programs.
+@end table
+@end defmac
+
+@defmac AC_LANG_PUSH (@var{language})
+@maindex LANG_PUSH
+Remember the current language (as set by @code{AC_LANG}) on a stack, and
+then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
+in macros that need to temporarily switch to a particular language.
+@end defmac
+
+@defmac AC_LANG_POP (@ovar{language})
+@maindex LANG_POP
+Select the language that is saved on the top of the stack, as set by
+@code{AC_LANG_PUSH}, and remove it from the stack.
+
+If given, @var{language} specifies the language we just @emph{quit}.  It
+is a good idea to specify it when it's known (which should be the
+case@dots{}), since Autoconf will detect inconsistencies.
+
+@example
+AC_LANG_PUSH(Fortran 77)
+# Perform some tests on Fortran 77.
+# ...
+AC_LANG_POP(Fortran 77)
+@end example
+@end defmac
+
+@defmac AC_REQUIRE_CPP
+@maindex REQUIRE_CPP
+Ensure that whichever preprocessor would currently be used for tests has
+been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
+argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
+depending on which language is current.
+@end defmac
+
+
+
+@c ====================================================== Results of Tests.
+
+@node Results, Programming in M4, Writing Tests, Top
+@chapter Results of Tests
+
+Once @code{configure} has determined whether a feature exists, what can
+it do to record that information?  There are four sorts of things it can
+do: define a C preprocessor symbol, set a variable in the output files,
+save the result in a cache file for future @code{configure} runs, and
+print a message letting the user know the result of the test.
+
+@menu
+* Defining Symbols::            Defining C preprocessor symbols
+* Setting Output Variables::    Replacing variables in output files
+* Caching Results::             Speeding up subsequent @code{configure} runs
+* Printing Messages::           Notifying @code{configure} users
+@end menu
+
+@node Defining Symbols, Setting Output Variables, Results, Results
+@section Defining C Preprocessor Symbols
+
+A common action to take in response to a feature test is to define a C
+preprocessor symbol indicating the results of the test.  That is done by
+calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
+
+By default, @code{AC_OUTPUT} places the symbols defined by these macros
+into the output variable @code{DEFS}, which contains an option
+@option{-D@var{symbol}=@var{value}} for each symbol defined.  Unlike in
+Autoconf version 1, there is no variable @code{DEFS} defined while
+@code{configure} is running.  To check whether Autoconf macros have
+already defined a certain C preprocessor symbol, test the value of the
+appropriate cache variable, as in this example:
+
+@example
+AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
+if test "$ac_cv_func_vprintf" != yes; then
+  AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
+fi
+@end example
+
+If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
+@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
+correct values into @code{#define} statements in a template file.
+@xref{Configuration Headers}, for more information about this kind of
+output.
+
+@defmac AC_DEFINE (@var{variable}, @ovar{value}, @ovar{description})
+@maindex DEFINE
+Define C preprocessor variable @var{variable}.  If @var{value} is given,
+set @var{variable} to that value (verbatim), otherwise set it to 1.
+@var{value} should not contain literal newlines, and if you are not
+using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
+characters, as @code{make} tends to eat them.  To use a shell variable
+(which you need to do in order to define a value containing the M4 quote
+characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
+@var{description} is only useful if you are using
+@code{AC_CONFIG_HEADERS}.  In this case, @var{description} is put into
+the generated @file{config.h.in} as the comment before the macro define.
+The following example defines the C preprocessor variable
+@code{EQUATION} to be the string constant @samp{"$a > $b"}:
+
+@example
+AC_DEFINE(EQUATION, "$a > $b")
+@end example
+@end defmac
+
+@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description})
+@maindex DEFINE_UNQUOTED
+Like @code{AC_DEFINE}, but three shell expansions are
+performed---once---on @var{variable} and @var{value}: variable expansion
+(@samp{$}), command substitution (@samp{`}), and backslash escaping
+(@samp{\}).  Single and double quote characters in the value have no
+special meaning.  Use this macro instead of @code{AC_DEFINE} when
+@var{variable} or @var{value} is a shell variable.  Examples:
+
+@example
+AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
+AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
+AC_DEFINE_UNQUOTED($ac_tr_hdr)
+@end example
+@end defmac
+
+Due to the syntactical bizarreness of the Bourne shell, do not use
+semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @code{configure} script.  Use either spaces or
+newlines.  That is, do this:
+
+@example
+AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
+@end example
+
+@noindent
+or this:
+
+@example
+AC_CHECK_HEADER(elf.h,
+ [AC_DEFINE(SVR4)
+  LIBS="$LIBS -lelf"])
+@end example
+
+@noindent
+instead of this:
+
+@example
+AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
+@end example
+
+@node Setting Output Variables, Caching Results, Defining Symbols, Results
+@section Setting Output Variables
+
+Another way to record the results of tests is to set @dfn{output
+variables}, which are shell variables whose values are substituted into
+files that @code{configure} outputs.  The two macros below create new
+output variables.  @xref{Preset Output Variables}, for a list of output
+variables that are always available.
+
+@defmac AC_SUBST (@var{variable}, @ovar{value})
+@maindex SUBST
+Create an output variable from a shell variable.  Make @code{AC_OUTPUT}
+substitute the variable @var{variable} into output files (typically one
+or more @file{Makefile}s).  This means that @code{AC_OUTPUT} will
+replace instances of @samp{@@@var{variable}@@} in input files with the
+value that the shell variable @var{variable} has when @code{AC_OUTPUT}
+is called.  This value of @var{variable} should not contain literal
+newlines.
+
+If @var{value} is given, in addition assign it to @samp{variable}.
+@end defmac
+
+@defmac AC_SUBST_FILE (@var{variable})
+@maindex SUBST_FILE
+Another way to create an output variable from a shell variable.  Make
+@code{AC_OUTPUT} insert (without substitutions) the contents of the file
+named by shell variable @var{variable} into output files.  This means
+that @code{AC_OUTPUT} will replace instances of
+@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
+with the contents of the file that the shell variable @var{variable}
+names when @code{AC_OUTPUT} is called.  Set the variable to
+@file{/dev/null} for cases that do not have a file to insert.
+
+This macro is useful for inserting @file{Makefile} fragments containing
+special dependencies or other @code{make} directives for particular host
+or target types into @file{Makefile}s.  For example, @file{configure.ac}
+could contain:
+
+@example
+AC_SUBST_FILE(host_frag)
+host_frag=$srcdir/conf/sun4.mh
+@end example
+
+@noindent
+and then a @file{Makefile.in} could contain:
+
+@example
+@@host_frag@@
+@end example
+@end defmac
+
+@cindex Previous Variable
+@cindex Variable, Precious
+Running @command{configure} in different environments can be extremely
+dangerous.  If for instance the user runs @samp{CC=bizarre-cc
+./configure}, then the cache, @file{config.h} and many other output
+files will depend upon @command{bizarre-cc} being the C compiler.  If
+for some reason the user runs @command{/configure} again, or if it is
+run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
+and @pxref{config.status Invocation}), then the configuration can be
+inconsistent, composed of results depending upon two different
+compilers.
+
+Such variables are named @dfn{precious variables}, and can be declared
+as such by @code{AC_ARG_VAR}.
+
+@defmac AC_ARG_VAR (@var{variable}, @var{description})
+@maindex ARG_VAR
+Declare @var{variable} is a precious variable, and include its
+@var{description} in the variable section of @samp{./configure --help}.
+
+Being precious means that
+@itemize @minus
+@item
+@var{variable} is @code{AC_SUBST}'d.
+
+@item
+@var{variable} is kept in the cache including if it was not specified on
+the @samp{./configure} command line.  Indeed, while @command{configure}
+can notice the definition of @code{CC} in @samp{./configure
+CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
+./configure}, which, unfortunately, is what most users do.
+
+@item
+@var{variable} is checked for consistency between two
+@command{configure} runs.  For instance:
+
+@example
+$ ./configure --silent --config-cache
+$ CC=cc ./configure --silent --config-cache
+configure: error: `CC' was not set in the previous run
+configure: error: changes in the environment can compromise \
+the build
+configure: error: run `make distclean' and/or \
+`rm config.cache' and start over
+@end example
+
+@noindent
+and similarly if the variable is unset, or if its content is changed.
+
+
+@item
+@var{variable} is kept during automatic reconfiguration
+(@pxref{config.status Invocation}) as if it had been passed as a command
+line argument, including when no cache is used:
+
+@example
+$ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent
+$ ./config.status --recheck
+running /bin/sh ./configure undeclared_var=raboof --silent \
+  CC=/usr/bin/cc  --no-create --no-recursion
+@end example
+@end itemize
+@end defmac
+
+
+@node Caching Results, Printing Messages, Setting Output Variables, Results
+@section Caching Results
+@cindex Cache
+
+To avoid checking for the same features repeatedly in various
+@code{configure} scripts (or in repeated runs of one script),
+@code{configure} can optionally save the results of many checks in a
+@dfn{cache file} (@pxref{Cache Files}).  If a @code{configure} script
+runs with caching enabled and finds a cache file, it reads the results
+of previous runs from the cache and avoids rerunning those checks.  As a
+result, @code{configure} can then run much faster than if it had to
+perform all of the checks every time.
+
+@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_VAL
+Ensure that the results of the check identified by @var{cache-id} are
+available.  If the results of the check were in the cache file that was
+read, and @code{configure} was not given the @option{--quiet} or
+@option{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands @var{commands-to-set-it}.  If
+the shell commands are run to determine the value, the value will be
+saved in the cache file just before @code{configure} creates its output
+files.  @xref{Cache Variable Names}, for how to choose the name of the
+@var{cache-id} variable.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
+
+@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
+@maindex CACHE_CHECK
+A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
+messages.  This macro provides a convenient shorthand for the most
+common way to use these macros.  It calls @code{AC_MSG_CHECKING} for
+@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
+@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
+
+The @var{commands-to-set-it} @emph{must have no side effects} except for
+setting the variable @var{cache-id}, see below.
+@end defmac
+
+It is very common to find buggy macros using @code{AC_CACHE_VAL} or
+@code{AC_CACHE_CHECK}, because people are tempted to call
+@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
+@emph{follows} the call to @code{AC_CACHE_VAL} should call
+@code{AC_DEFINE}, by examining the value of the cache variable.  For
+instance, the following macro is broken:
+
+@example
+@group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+                [ac_cv_shell_true_works=no
+                 true && ac_cv_shell_true_works=yes
+                 if test $ac_cv_shell_true_works = yes; then
+                   AC_DEFINE([TRUE_WORKS], 1
+                             [Define if `true(1)' works properly.])
+                 fi])
+])
+@end group
+@end example
+
+@noindent
+This fails if the cache is enabled: the second time this macro is run,
+@code{TRUE_WORKS} @emph{will not be defined}.  The proper implementation
+is:
+
+@example
+@group
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+                [ac_cv_shell_true_works=no
+                 true && ac_cv_shell_true_works=yes])
+ if test $ac_cv_shell_true_works = yes; then
+   AC_DEFINE([TRUE_WORKS], 1
+             [Define if `true(1)' works properly.])
+ fi
+])
+@end group
+@end example
+
+Also, @var{commands-to-set-it} should not print any messages, for
+example with @code{AC_MSG_CHECKING}; do that before calling
+@code{AC_CACHE_VAL}, so the messages are printed regardless of whether
+the results of the check are retrieved from the cache or determined by
+running the shell commands.
+
+@menu
+* Cache Variable Names::        Shell variables used in caches
+* Cache Files::                 Files @code{configure} uses for caching
+* Cache Checkpointing::         Loading and saving the cache file
+@end menu
+
+@node Cache Variable Names, Cache Files, Caching Results, Caching Results
+@subsection Cache Variable Names
+@cindex Cache variable
+
+The names of cache variables should have the following format:
+
+@example
+@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
+@end example
+
+@noindent
+for example, @samp{ac_cv_header_stat_broken} or
+@samp{ac_cv_prog_gcc_traditional}.  The parts of the variable name are:
+
+@table @asis
+@item @var{package-prefix}
+An abbreviation for your package or organization; the same prefix you
+begin local Autoconf macros with, except lowercase by convention.
+For cache values used by the distributed Autoconf macros, this value is
+@samp{ac}.
+
+@item @code{_cv_}
+Indicates that this shell variable is a cache value. This string
+@emph{must} be present in the variable name, including the leading
+underscore.
+
+@item @var{value-type}
+A convention for classifying cache values, to produce a rational naming
+system.  The values used in Autoconf are listed in @ref{Macro Names}.
+
+@item @var{specific-value}
+Which member of the class of cache values this test applies to.
+For example, which function (@samp{alloca}), program (@samp{gcc}), or
+output variable (@samp{INSTALL}).
+
+@item @var{additional-options}
+Any particular behavior of the specific member that this test applies to.
+For example, @samp{broken} or @samp{set}.  This part of the name may
+be omitted if it does not apply.
+@end table
+
+The values assigned to cache variables may not contain newlines.
+Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
+names of files or functions; so this is not an important restriction.
+
+@node Cache Files, Cache Checkpointing, Cache Variable Names, Caching Results
+@subsection Cache Files
+
+A cache file is a shell script that caches the results of configure
+tests run on one system so they can be shared between configure scripts
+and configure runs.  It is not useful on other systems.  If its contents
+are invalid for some reason, the user may delete or edit it.
+
+By default, @code{configure} uses no cache file (technically, it uses
+@option{--cache-file=/dev/null}), to avoid problems caused by accidental
+use of stale cache files.
+
+To enable caching, @code{configure} accepts @option{--config-cache} (or
+@option{-C}) to cache results in the file @file{config.cache}.
+Alternatively, @option{--cache-file=@var{file}} specifies that
+@var{file} be the cache file.  The cache file is created if it does not
+exist already.  When @code{configure} calls @code{configure} scripts in
+subdirectories, it uses the @option{--cache-file} argument so that they
+share the same cache.  @xref{Subdirectories}, for information on
+configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
+
+@file{config.status} only pays attention to the cache file if it is
+given the @option{--recheck} option, which makes it rerun
+@code{configure}.
+
+It is wrong to try to distribute cache files for particular system types.
+There is too much room for error in doing that, and too much
+administrative overhead in maintaining them.  For any features that
+can't be guessed automatically, use the standard method of the canonical
+system type and linking files (@pxref{Manual Configuration}).
+
+The site initialization script can specify a site-wide cache file to
+use, instead of the usual per-program cache.  In this case, the cache
+file will gradually accumulate information whenever someone runs a new
+@code{configure} script.  (Running @code{configure} merges the new cache
+results with the existing cache file.)  This may cause problems,
+however, if the system configuration (e.g. the installed libraries or
+compilers) changes and the stale cache file is not deleted.
+
+@node Cache Checkpointing,  , Cache Files, Caching Results
+@subsection Cache Checkpointing
+
+If your configure script, or a macro called from configure.ac, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using @code{AC_CACHE_SAVE}.  Doing so will
+reduce the amount of time it takes to re-run the configure script with
+(hopefully) the error that caused the previous abort corrected.
+
+@c FIXME: Do we really want to document this guy?
+@defmac AC_CACHE_LOAD
+@maindex CACHE_LOAD
+Loads values from existing cache file, or creates a new cache file if a
+cache file is not found.  Called automatically from @code{AC_INIT}.
+@end defmac
+
+@defmac AC_CACHE_SAVE
+@maindex CACHE_SAVE
+Flushes all cached values to the cache file.  Called automatically from
+@code{AC_OUTPUT}, but it can be quite useful to call
+@code{AC_CACHE_SAVE} at key points in configure.ac.
+@end defmac
+
+For instance:
+
+@example
+@r{ @dots{} AC_INIT, etc. @dots{}}
+@group
+# Checks for programs.
+AC_PROG_CC
+AC_PROG_GCC_TRADITIONAL
+@r{ @dots{} more program checks @dots{}}
+AC_CACHE_SAVE
+@end group
+
+@group
+# Checks for libraries.
+AC_CHECK_LIB(nsl, gethostbyname)
+AC_CHECK_LIB(socket, connect)
+@r{ @dots{} more lib checks @dots{}}
+AC_CACHE_SAVE
+@end group
+
+@group
+# Might abort...
+AM_PATH_GTK(1.0.2,, (exit 1); exit)
+AM_PATH_GTKMM(0.9.5,, (exit 1); exit)
+@end group
+@r{ @dots{} AC_OUTPUT, etc. @dots{}}
+@end example
+
+@node Printing Messages,  , Caching Results, Results
+@section Printing Messages
+@cindex Messages, from @code{configure}
+
+@code{configure} scripts need to give users running them several kinds
+of information.  The following macros print messages in ways appropriate
+for each kind.  The arguments to all of them get enclosed in shell
+double quotes, so the shell performs variable and back-quote
+substitution on them.
+
+These macros are all wrappers around the @code{echo} shell command.
+@code{configure} scripts should rarely need to run @code{echo} directly
+to print messages for the user.  Using these macros makes it easy to
+change how and when each kind of message is printed; such changes need
+only be made to the macro definitions and all of the callers will change
+automatically.
+
+To diagnose static issues, i.e., when @code{autoconf} is run, see
+@ref{Reporting Messages}.
+
+@defmac AC_MSG_CHECKING (@var{feature-description})
+@maindex MSG_CHECKING
+Notify the user that @code{configure} is checking for a particular
+feature.  This macro prints a message that starts with @samp{checking }
+and ends with @samp{...} and no newline.  It must be followed by a call
+to @code{AC_MSG_RESULT} to print the result of the check and the
+newline.  The @var{feature-description} should be something like
+@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
+c89}.
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@defmac AC_MSG_RESULT (@var{result-description})
+@maindex MSG_RESULT
+Notify the user of the results of a check.  @var{result-description} is
+almost always the value of the cache variable for the check, typically
+@samp{yes}, @samp{no}, or a file name.  This macro should follow a call
+to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
+the completion of the message printed by the call to
+@code{AC_MSG_CHECKING}.
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@defmac AC_MSG_NOTICE (@var{message})
+@maindex MSG_NOTICE
+Deliver the @var{message} to the user. It is useful mainly to print a
+general description of the overall purpose of a group of feature checks,
+e.g.,
+
+@example
+AC_MSG_NOTICE([checking if stack overflow is detectable])
+@end example
+
+This macro prints nothing if @code{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+@end defmac
+
+@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
+@maindex MSG_ERROR
+Notify the user of an error that prevents @code{configure} from
+completing.  This macro prints an error message to the standard error
+output and exits @code{configure} with @var{exit-status} (1 by default).
+@var{error-description} should be something like @samp{invalid value
+$HOME for \$HOME}.
+
+The @var{error-description} should start with a lower-case letter, and
+``cannot'' is preferred to ``can't''.
+@end defmac
+
+@defmac AC_MSG_WARN (@var{problem-description})
+@maindex MSG_WARN
+Notify the @code{configure} user of a possible problem.  This macro
+prints the message to the standard error output; @code{configure}
+continues running afterward, so macros that call @code{AC_MSG_WARN} should
+provide a default (back-up) behavior for the situations they warn about.
+@var{problem-description} should be something like @samp{ln -s seems to
+make hard links}.
+@end defmac
+
+
+
+@c ====================================================== Programming in M4.
+
+@node Programming in M4, Writing Autoconf Macros, Results, Top
+@chapter Programming in M4
+
+Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
+convenient macros for pure M4 programming, and @dfn{M4sh}, which
+provides macros dedicated to shell script generation.
+
+As of this version of Autoconf, these two layers are still experimental,
+and their interface might change in the future.  As a matter of fact,
+@emph{anything that is not documented must not be used}.
+
+@menu
+* M4 Quotation::                Protecting macros from unwanted expansion
+* Programming in M4sugar::      Convenient pure M4 macros
+@end menu
+
+@node M4 Quotation, Programming in M4sugar, Programming in M4, Programming in M4
+@section M4 Quotation
+@cindex quotation
+
+@c FIXME: Grmph, yet another quoting myth: quotation has *never*
+@c prevented `expansion' of $1.  Unless it refers to the expansion
+@c of the value of $1?  Anyway, we need a rewrite here@dots{}
+
+The most common brokenness of existing macros is an improper quotation.
+This section, which users of Autoconf can skip, but which macro writers
+@emph{must} read, first justifies the quotation scheme that was chosen
+for Autoconf and then ends with a rule of thumb.  Understanding the
+former helps one to follow the latter.
+
+@menu
+* Active Characters::           Characters that change the behavior of m4
+* One Macro Call::              Quotation and one macro call
+* Quotation and Nested Macros::  Macros calling macros
+* Quadrigraphs::                Another way to escape special characters
+* Quotation Rule Of Thumb::     One parenthesis, one quote
+@end menu
+
+@node Active Characters, One Macro Call, M4 Quotation, M4 Quotation
+@subsection Active Characters
+
+To fully understand where proper quotation is important, you first need
+to know what are the special characters in Autoconf: @samp{#} introduces
+a comment inside which no macro expansion is performed, @samp{,}
+separates arguments, @samp{[} and @samp{]} are the quotes themselves,
+and finally @samp{(} and @samp{)} (which @code{m4} tries to match by
+pairs).
+
+In order to understand the delicate case of macro calls, we first have
+to present some obvious failures.  Below they are ``obvious-ified'',
+although you find them in real life, they are usually in disguise.
+
+Comments, introduced by a hash and running up to the newline, are opaque
+tokens to the top level: active characters are turned off, and there is
+no macro expansion:
+
+@example
+# define([def], ine)
+@result{}# define([def], ine)
+@end example
+
+Each time there can be a macro expansion, there is a quotation
+expansion; i.e., one level of quotes is stripped:
+
+@example
+int tab[10];
+@result{}int tab10;
+[int tab[10];]
+@result{}int tab[10];
+@end example
+
+Without this in mind, the reader will try hopelessly to use her macro
+@code{array}:
+
+@example
+define([array], [int tab[10];])
+array
+@result{}int tab10;
+[array]
+@result{}array
+@end example
+
+@noindent
+How can you correctly output the intended results@footnote{Using
+@code{defn}.}?
+
+
+@node One Macro Call, Quotation and Nested Macros, Active Characters, M4 Quotation
+@subsection One Macro Call
+
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
+
+@example
+define([car], [$1])
+@end example
+
+@noindent
+The two pairs of quotes above are not part of the arguments of
+@code{define}; rather, they are understood by the top level when it
+tries to find the arguments of @code{define}.  Therefore, it is
+equivalent to write:
+
+@example
+define(car, $1)
+@end example
+
+@noindent
+But, while it is acceptable for a @file{configure.ac} to avoid unneeded
+quotes, it is bad practice for Autoconf macros which must both be more
+robust and also advocate perfect style.
+
+At the top level, there are only two possible quotings: either you
+quote or you don't:
+
+@example
+car(foo, bar, baz)
+@result{}foo
+[car(foo, bar, baz)]
+@result{}car(foo, bar, baz)
+@end example
+
+Let's pay attention to the special characters:
+
+@example
+car(#)
+@error{}EOF in argument list
+@end example
+
+The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
+
+@example
+car([#)]
+@end example
+
+@noindent
+Proper quotation, of course, fixes the problem:
+
+@example
+car([#])
+@result{}#
+@end example
+
+The reader will easily understand the following examples:
+
+@example
+car(foo, bar)
+@result{}foo
+car([foo, bar])
+@result{}foo, bar
+car((foo, bar))
+@result{}(foo, bar)
+car([(foo], [bar)])
+@result{}(foo
+car([], [])
+@result{}
+car([[]], [[]])
+@result{}[]
+@end example
+
+With this in mind, we can explore the cases where macros invoke
+macros@dots{}
+
+
+@node Quotation and Nested Macros, Quadrigraphs, One Macro Call, M4 Quotation
+@subsection Quotation and Nested Macros
+
+The examples below use the following macros:
+
+@example
+define([car], [$1])
+define([active], [ACT, IVE])
+define([array], [int tab[10]])
+@end example
+
+Each additional embedded macro call introduces other possible
+interesting quotations:
+
+@example
+car(active)
+@result{}ACT
+car([active])
+@result{}ACT, IVE
+car([[active]])
+@result{}active
+@end example
+
+In the first case, the top level looks for the arguments of @code{car},
+and finds @samp{active}.  Because @code{m4} evaluates its arguments
+before applying the macro, @samp{active} is expanded, which results in:
+
+@example
+car(ACT, IVE)
+@result{}ACT
+@end example
+
+@noindent
+In the second case, the top level gives @samp{active} as first and only
+argument of @code{car}, which results in:
+
+@example
+active
+@result{}ACT, IVE
+@end example
+
+@noindent
+i.e., the argument is evaluated @emph{after} the macro that invokes it.
+In the third case, @code{car} receives @samp{[active]}, which results in:
+
+@example
+[active]
+@result{}active
+@end example
+
+@noindent
+exactly as we already saw above.
+
+The example above, applied to a more realistic example, gives:
+
+@example
+car(int tab[10];)
+@result{}int tab10;
+car([int tab[10];])
+@result{}int tab10;
+car([[int tab[10];]])
+@result{}int tab[10];
+@end example
+
+@noindent
+Huh?  The first case is easily understood, but why is the second wrong,
+and the third right?  To understand that, you must know that after
+@code{m4} expands a macro, the resulting text is immediately subjected
+to macro expansion and quote removal.  This means that the quote removal
+occurs twice---first before the argument is passed to the @code{car}
+macro, and second after the @code{car} macro expands to the first
+argument.
+
+As the author of the Autoconf macro @code{car}, you then consider it to
+be incorrect that your users have to double-quote the arguments of
+@code{car}, so you ``fix'' your macro.  Let's call it @code{qar} for
+quoted car:
+
+@example
+define([qar], [[$1]])
+@end example
+
+@noindent
+and check that @code{qar} is properly fixed:
+
+@example
+qar([int tab[10];])
+@result{}int tab[10];
+@end example
+
+@noindent
+Ahhh!  That's much better.
+
+But note what you've done: now that the arguments are literal strings,
+if the user wants to use the results of expansions as arguments, she has
+to use an @emph{unquoted} macro call:
+
+@example
+qar(active)
+@result{}ACT
+@end example
+
+@noindent
+where she wanted to reproduce what she used to do with @code{car}:
+
+@example
+car([active])
+@result{}ACT, IVE
+@end example
+
+@noindent
+Worse yet: she wants to use a macro that produces a set of @code{cpp}
+macros:
+
+@example
+define([my_includes], [#include <stdio.h>])
+car([my_includes])
+@result{}#include <stdio.h>
+qar(my_includes)
+@error{}EOF in argument list
+@end example
+
+This macro, @code{qar}, because it double quotes its arguments, forces
+its users to leave their macro calls unquoted, which is dangerous.
+Commas and other active symbols are interpreted by @code{m4} before
+they are given to the macro, often not in the way the users expect.
+Also, because @code{qar} behaves differently from the other macros,
+it's an exception that should be avoided in Autoconf.
+
+
+@node Quadrigraphs, Quotation Rule Of Thumb, Quotation and Nested Macros, M4 Quotation
+@subsection Quadrigraphs
+@cindex quadrigraphs
+@cindex @samp{@@<:@@}
+@cindex @samp{@@:>@@}
+@cindex @samp{@@S|@@}
+@cindex @samp{@@%:@@}
+
+When writing an autoconf macro you may occasionally need to generate
+special characters that are difficult to express with the standard
+autoconf quoting rules.  For example, you may need to output the regular
+expression @samp{[^[]}, which matches any character other than @samp{[}.
+This expression contains unbalanced brackets so it cannot be put easily
+into an M4 macro.
+
+You can work around this problem by using one of the following
+@dfn{quadrigraphs}:
+
+@table @samp
+@item @@<:@@
+@samp{[}
+@item @@:>@@
+@samp{]}
+@item @@S|@@
+@samp{$}
+@item @@%:@@
+@samp{#}
+@end table
+
+Quadrigraphs are replaced at a late stage of the translation process,
+after @command{m4} is run, so they do not get in the way of M4 quoting.
+For example, the string @samp{[^@@<:@@]}, if properly quoted, will
+appear as @samp{[^[]} in the @code{configure} script.
+
+
+@node Quotation Rule Of Thumb,  , Quadrigraphs, M4 Quotation
+@subsection Quotation Rule Of Thumb
+
+To conclude, the quotation rule of thumb is:
+
+@center @emph{One pair of quotes per pair of parentheses.}
+
+Never over-quote, never under-quote, in particular in the definition of
+macros.  In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), properly quote
+@emph{the arguments}!
+
+It is common to read Autoconf programs with snippets like:
+
+@example
+AC_TRY_LINK(
+changequote(<<, >>)dnl
+<<#include <time.h>
+#ifndef tzname /* For SGI.  */
+extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+#endif>>,
+changequote([, ])dnl
+[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
+@end example
+
+@noindent
+which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
+double quoting, so you just need:
+
+@example
+AC_TRY_LINK(
+[#include <time.h>
+#ifndef tzname /* For SGI.  */
+extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+#endif],
+            [atoi (*tzname);],
+            [ac_cv_var_tzname=yes],
+            [ac_cv_var_tzname=no])
+@end example
+
+@noindent
+The M4-fluent reader will note that these two examples are rigorously
+equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
+and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
+quotes are not part of the arguments!
+
+Simplified, the example above is just doing this:
+
+@example
+changequote(<<, >>)dnl
+<<[]>>
+changequote([, ])dnl
+@end example
+
+@noindent
+instead of simply:
+
+@example
+[[]]
+@end example
+
+
+With macros that do not double quote their arguments (which is the
+rule), double-quote the (risky) literals:
+
+@example
+AC_LINK_IFELSE([AC_LANG_PROGRAM(
+[[#include <time.h>
+#ifndef tzname /* For SGI.  */
+extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
+#endif]],
+                                [atoi (*tzname);])],
+               [ac_cv_var_tzname=yes],
+               [ac_cv_var_tzname=no])
+@end example
+
+See @xref{Quadrigraphs}, for what to do if you run into a hopeless case
+where quoting does not suffice.
+
+When you create a @code{configure} script using newly written macros,
+examine it carefully to check whether you need to add more quotes in
+your macros.  If one or more words have disappeared in the @code{m4}
+output, you need more quotes.  When in doubt, quote.
+
+However, it's also possible to put on too many layers of quotes.  If
+this happens, the resulting @code{configure} script will contain
+unexpanded macros.  The @code{autoconf} program checks for this problem
+by doing @samp{grep AC_ configure}.
+
+
+@node Programming in M4sugar,  , M4 Quotation, Programming in M4
+@section Programming in M4sugar
+
+@cindex M4sugar
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros.  M4sugar introduces additional generic macros.  Its name was
+coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
+M4sugar''.
+
+@menu
+* Redefined M4 Macros::         M4 builtins changed in M4sugar
+* Forbidden Patterns::          Catching unexpanded macros
+@end menu
+
+@node Redefined M4 Macros, Forbidden Patterns, Programming in M4sugar, Programming in M4sugar
+@subsection Redefined M4 Macros
+
+All the M4 native macros are moved in the @samp{m4_} pseudo-namespace,
+e.g., M4sugar renames @code{define} as @code{m4_define} etc.  There is
+one exception: @code{dnl} kept its original name, and no @code{m4_dnl}
+is defined.
+
+M4sugar redefines some M4 macros, and made them slightly incompatible
+with their native equivalent.
+
+@defmac m4_defn (@var{macro})
+@msindex defn
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  See @code{m4_undefine}.
+@end defmac
+
+@defmac m4_undefine (@var{macro})
+@msindex undefine
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  Use
+
+@example
+m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
+@end example
+
+@noindent
+to recover the behavior of the builtin.
+@end defmac
+
+@defmac m4_popdef (@var{macro})
+@msindex defn
+Contrary to the M4 builtin, this macro fails if @var{macro} is not
+defined.  See @code{m4_undefine}.
+@end defmac
+
+@node Forbidden Patterns,  , Redefined M4 Macros, Programming in M4sugar
+@subsection Forbidden Patterns
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output.  For
+instance, if an Autoconf @file{configure} script includes tokens such as
+@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
+wrong (typically a macro was not evaluated because of over quotation).
+
+M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
+
+@defmac m4_pattern_forbid (@var{pattern})
+@msindex pattern_forbid
+Declare no token matching @var{pattern} must be found in the output.
+Comments are not checked; this can be a problem if, for instance, you
+have some macro left unexpanded after an @samp{#include}.  No consensus
+is currently found in the Autoconf community, as some people consider it
+should be valid to name macros in comments (which doesn't makes sense to
+the author of this documentation, as @samp{#}-comments should document
+the output, not the input, documented vy @samp{dnl}-comments).
+@end defmac
+
+Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to @samp{$m4_flags}.
+
+@defmac m4_pattern_allow (@var{pattern})
+@msindex pattern_allow
+Any token matching @var{pattern} is allowed, including if it matches an
+@code{m4_pattern_forbid} pattern.
+@end defmac
+
+@c=================================================== Writing Autoconf Macros.
+
+@node Writing Autoconf Macros, Portable Shell, Programming in M4, Top
+@chapter Writing Autoconf Macros
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
+
+@menu
+* Macro Definitions::           Basic format of an Autoconf macro
+* Macro Names::                 What to call your new macros
+* Reporting Messages::          Notifying @code{autoconf} users
+* Dependencies Between Macros::  What to do when macros depend on other macros
+* Obsoleting Macros::           Warning about old ways of doing things
+* Coding Style::                Writing Autoconf macros @`a la Autoconf
+@end menu
+
+@node Macro Definitions, Macro Names, Writing Autoconf Macros, Writing Autoconf Macros
+@section Macro Definitions
+
+@maindex DEFUN
+Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
+similar to the M4 builtin @code{define} macro.  In addition to defining
+a macro, @code{AC_DEFUN} adds to it some code that is used to constrain
+the order in which macros are called (@pxref{Prerequisite Macros}).
+
+An Autoconf macro definition looks like this:
+
+@example
+AC_DEFUN(@var{macro-name}, @var{macro-body})
+@end example
+
+You can refer to any arguments passed to the macro as @samp{$1},
+@samp{$2}, etc.  @xref{Definitions,, How to define new macros, m4.info,
+GNU m4}, for more complete information on writing M4 macros.
+
+Be sure to properly quote both the @var{macro-body} @emph{and} the
+@var{macro-name} to avoid any problems if the macro happens to have
+been previously defined.
+
+Each macro should have a header comment that gives its prototype, and a
+brief description.  When arguments have default values, display them in
+the prototype.  For example:
+
+@example
+# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+# --------------------------------------
+define([AC_MSG_ERROR],
+[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
+@end example
+
+Comments about the macro should be left in the header comment.  Most
+other comments will make their way into @file{configure}, so just keep
+using @samp{#} to introduce comments.
+
+@cindex @code{dnl}
+If you have some very special comments about pure M4 code, comments
+that make no sense in @file{configure} and in the header comment, then
+use the builtin @code{dnl}: it causes @code{m4} to discard the text
+through the next newline.
+
+Keep in mind that @code{dnl} is rarely needed to introduce comments;
+@code{dnl} is more useful to get rid of the newlines following macros
+that produce no output, such as @code{AC_REQUIRE}.
+
+
+@node Macro Names, Reporting Messages, Macro Definitions, Writing Autoconf Macros
+@section Macro Names
+
+All of the Autoconf macros have all-uppercase names starting with
+@samp{AC_} to prevent them from accidentally conflicting with other
+text.  All shell variables that they use for internal purposes have
+mostly-lowercase names starting with @samp{ac_}.  To ensure that your
+macros don't conflict with present or future Autoconf macros, you should
+prefix your own macro names and any shell variables they use with some
+other sequence.  Possibilities include your initials, or an abbreviation
+for the name of your organization or software package.
+
+Most of the Autoconf macros' names follow a structured naming convention
+that indicates the kind of feature check by the name.  The macro names
+consist of several words, separated by underscores, going from most
+general to most specific.  The names of their cache variables use the
+same convention (@pxref{Cache Variable Names}, for more information on
+them).
+
+The first word of the name after @samp{AC_} usually tells the category
+of feature being tested.  Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write.  They are also used for cache variables, in all-lowercase.  Use
+them where applicable; where they're not, invent your own categories.
+
+@table @code
+@item C
+C language builtin features.
+@item DECL
+Declarations of C variables in header files.
+@item FUNC
+Functions in libraries.
+@item GROUP
+@sc{unix} group owners of files.
+@item HEADER
+Header files.
+@item LIB
+C libraries.
+@item PATH
+The full path names to files, including programs.
+@item PROG
+The base names of programs.
+@item MEMBER
+Members of aggregates.
+@item SYS
+Operating system features.
+@item TYPE
+C builtin or declared types.
+@item VAR
+C variables in libraries.
+@end table
+
+After the category comes the name of the particular feature being
+tested.  Any further words in the macro name indicate particular aspects
+of the feature.  For example, @code{AC_FUNC_UTIME_NULL} checks the
+behavior of the @code{utime} function when called with a @code{NULL}
+pointer.
+
+An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with @samp{_AC_}.
+Additionally, a macro that is an internal subroutine of another macro
+should have a name that starts with an underscore and the name of that
+other macro, followed by one or more words saying what the internal
+macro does.  For example, @code{AC_PATH_X} has internal macros
+@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
+
+@node Reporting Messages, Dependencies Between Macros, Macro Names, Writing Autoconf Macros
+@section Reporting Messages
+@cindex Messages, from @code{autoconf}
+
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros.  For dynamic issues, i.e.,
+when @code{configure} is run, see @ref{Printing Messages}.
+
+@defmac AC_DIAGNOSE (@var{category}, @var{message})
+@maindex DIAGNOSE
+Report @var{message} as a warning (or as an error if requested by the
+user) if it falls into the @var{category}.  You are encouraged to use
+standard categories, which currently include:
+
+@table @samp
+@item all
+messages that don't fall into one of the following category.  Use of an
+empty @var{category} is equivalent.
+
+@item cross
+related to cross compilation issues.
+
+@item obsolete
+use of an obsolete construct.
+
+@item syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
+@end table
+@end defmac
+
+@defmac AC_WARNING (@var{message})
+@maindex WARNING
+Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
+strongly encouraged to use a finer grained category.
+@end defmac
+
+@defmac AC_FATAL (@var{message})
+@maindex FATAL
+Report a severe error @var{message}, and have @code{autoconf} die.
+@end defmac
+
+When the user runs @samp{autoconf -W error}, warnings from
+@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
+@ref{autoconf Invocation}.
+
+@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Autoconf Macros
+@section Dependencies Between Macros
+
+Some Autoconf macros depend on other macros having been called first in
+order to work correctly.  Autoconf provides a way to ensure that certain
+macros are called if needed and a way to warn the user if macros are
+called in an order that might cause incorrect operation.
+
+@menu
+* Prerequisite Macros::         Ensuring required information
+* Suggested Ordering::          Warning about possible ordering problems
+@end menu
+
+@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, Dependencies Between Macros
+@subsection Prerequisite Macros
+
+A macro that you write might need to use values that have previously
+been computed by other macros.  For example, @code{AC_DECL_YYTEXT}
+examines the output of @code{flex} or @code{lex}, so it depends on
+@code{AC_PROG_LEX} having been called first to set the shell variable
+@code{LEX}.
+
+Rather than forcing the user of the macros to keep track of the
+dependencies between them, you can use the @code{AC_REQUIRE} macro to do
+it automatically.  @code{AC_REQUIRE} can ensure that a macro is only
+called if it is needed, and only called once.
+
+@defmac AC_REQUIRE (@var{macro-name})
+@maindex REQUIRE
+If the M4 macro @var{macro-name} has not already been called, call it
+(without any arguments).  Make sure to quote @var{macro-name} with
+square brackets.  @var{macro-name} must have been defined using
+@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
+
+@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
+must not be called from the top level.
+@end defmac
+
+@code{AC_REQUIRE} is often misunderstood.  It really implements
+dependencies between macros in the sense that if one macro depends upon
+another, the latter will be expanded @emph{before} the body of the
+former.  In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
+body of @code{FOO}.  For instance, this definition of macros:
+
+@example
+@group
+AC_DEFUN([TRAVOLTA],
+[test "$body_temparature_in_celsius" -gt "38" &&
+  dance_floor=occupied])
+AC_DEFUN([NEWTON_JOHN],
+[test "$hair_style" = "curly" &&
+  dance_floor=occupied])
+@end group
+
+@group
+AC_DEFUN([RESERVE_DANCE_FLOOR],
+[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+  AC_REQUIRE([TRAVOLTA])
+  AC_REQUIRE([NEWTON_JOHN])
+fi])
+@end group
+@end example
+
+@noindent
+with this @file{configure.ac}
+
+@example
+AC_INIT
+RESERVE_DANCE_FLOOR
+if test "$dance_floor" = occupied; then
+  AC_MSG_ERROR([cannot pick up here, let's move])
+fi
+@end example
+
+@noindent
+will not leave you with a better chance to meet a kindred soul at
+other times than Saturday night since it expands into:
+
+@example
+@group
+test "$body_temperature_in_Celsius" -gt "38" &&
+  dance_floor=occupied
+test "$hair_style" = "curly" &&
+  dance_floor=occupied
+fi
+if date | grep '^Sat.*pm' >/dev/null 2>&1; then
+
+
+fi
+@end group
+@end example
+
+This behavior was chosen on purpose: (i) it prevents messages in
+required macros from interrupting the messages in the requiring macros;
+(ii) it avoids bad surprises when shell conditionals are used, as in:
+
+@example
+@group
+if @dots{}; then
+  AC_REQUIRE([SOME_CHECK])
+fi
+@dots{}
+SOME_CHECK
+@end group
+@end example
+
+
+You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
+macro.  You can use @code{dnl} to avoid the empty lines they leave.
+
+@node Suggested Ordering,  , Prerequisite Macros, Dependencies Between Macros
+@subsection Suggested Ordering
+
+Some macros should be run before another macro if both are called, but
+neither @emph{requires} that the other be called.  For example, a macro
+that changes the behavior of the C compiler should be called before any
+macros that run the C compiler.  Many of these dependencies are noted in
+the documentation.
+
+Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
+with this kind of dependency appear out of order in a
+@file{configure.ac} file.  The warning occurs when creating
+@code{configure} from @file{configure.ac}, not when running
+@code{configure}.
+
+For example, @code{AC_PROG_CPP} checks whether the C compiler
+can run the C preprocessor when given the @option{-E} option.  It should
+therefore be called after any macros that change which C compiler is
+being used, such as @code{AC_PROG_CC}.  So @code{AC_PROG_CC} contains:
+
+@example
+AC_BEFORE([$0], [AC_PROG_CPP])dnl
+@end example
+
+@noindent
+This warns the user if a call to @code{AC_PROG_CPP} has already occurred
+when @code{AC_PROG_CC} is called.
+
+@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
+@maindex BEFORE
+Make @code{m4} print a warning message to the standard error output if
+@var{called-macro-name} has already been called.  @var{this-macro-name}
+should be the name of the macro that is calling @code{AC_BEFORE}.  The
+macro @var{called-macro-name} must have been defined using
+@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
+that it has been called.
+@end defmac
+
+@node Obsoleting Macros, Coding Style, Dependencies Between Macros, Writing Autoconf Macros
+@section Obsoleting Macros
+
+Configuration and portability technology has evolved over the years.
+Often better ways of solving a particular problem are developed, or
+ad-hoc approaches are systematized.  This process has occurred in many
+parts of Autoconf.  One result is that some of the macros are now
+considered @dfn{obsolete}; they still work, but are no longer considered
+the best thing to do, hence they should be replaced with more modern
+macros.  Ideally, @code{autoupdate} should substitute the old macro calls
+with their modern implementation.
+
+Autoconf provides a simple means to obsolete a macro.
+
+@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
+@maindex DEFUN
+@maindex AU_DEFUN
+Define @var{old-macro} as @var{implementation}.  The only difference
+with @code{AC_DEFUN} is that the user will be warned that
+@var{old-macro} is now obsolete.
+
+If she then uses @code{autoupdate}, the call to @var{old-macro} will be
+replaced by the modern @var{implementation}.  The additional
+@var{message} is then printed.
+@end defmac
+
+@node Coding Style,  , Obsoleting Macros, Writing Autoconf Macros
+@section Coding Style
+
+The Autoconf macros follow a strict coding style.  You are encouraged to
+follow this style, especially if you intend to distribute your macro,
+either by contributing it to Autoconf itself, or via other means.
+
+The first requirement is to pay great attention to the quotation, for
+more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
+
+Do not try to invent new interfaces.  It is likely that there is a macro
+in Autoconf that resembles the macro you are defining: try to stick to
+this existing interface (order of arguments, default values, etc.).  We
+@emph{are} conscious that some of these interfaces are not perfect;
+nevertheless, when harmless, homogeneity should be preferred over
+creativity.
+
+Be careful about clashes both between M4 symbols and between shell
+variables.
+
+If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
+you are unlikely to generate conflicts.  Nevertheless, when you need to
+set a special value, @emph{avoid using a regular macro name}; rather,
+use an ``impossible'' name.  For instance, up to version 2.13, the macro
+@code{AC_SUBST} used to remember what @var{symbol}s were already defined
+by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
+But since there is a macro named @code{AC_SUBST_FILE}, it was just
+impossible to @samp{AC_SUBST(FILE)}!  In this case,
+@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
+have been used (yes, with the parentheses)@dots{}or better yet, high-level
+macros such as @code{AC_EXPAND_ONCE}.
+
+No Autoconf macro should ever enter the user-variable name space; i.e.,
+except for the variables that are the actual result of running the
+macro, all shell variables should start with @code{ac_}.  In
+addition, small macros or any macro that is likely to be embedded in
+other macros should be careful not to use obvious names.
+
+@cindex @code{dnl}
+Do not use @code{dnl} to introduce comments: most of the comments you
+are likely to write are either header comments which are not output
+anyway, or comments that should make their way into @file{configure}.
+There are exceptional cases where you do want to comment special M4
+constructs, in which case @code{dnl} is right, but keep in mind that it
+is unlikely.
+
+M4 ignores the leading spaces before each argument, use this feature to
+indent in such a way that arguments are (more or less) aligned with the
+opening parenthesis of the macro being called.  For instance, instead of
+
+@example
+AC_CACHE_CHECK(for EMX OS/2 environment,
+ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
+[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
+@end example
+
+@noindent
+write
+
+@example
+AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+                   [ac_cv_emxos2=yes],
+                   [ac_cv_emxos2=no])])
+@end example
+
+@noindent
+or even
+
+@example
+AC_CACHE_CHECK([for EMX OS/2 environment],
+               [ac_cv_emxos2],
+               [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
+                                                   [return __EMX__;])],
+                                  [ac_cv_emxos2=yes],
+                                  [ac_cv_emxos2=no])])
+@end example
+
+When using @code{AC_TRY_RUN} or any macro that cannot work when
+cross-compiling, provide a pessimistic value (typically @samp{no}).
+
+Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly.  For instance,
+instead of:
+
+@example
+patsubst([$1], [$"])
+@end example
+
+@noindent
+use
+
+@example
+patsubst([$1], [$""])
+@end example
+
+@noindent
+so that Emacsen do not open a endless ``string'' at the first quote.
+For the same reasons, avoid:
+
+@example
+test $[#] != 0
+@end example
+
+@noindent
+and use:
+
+@example
+test $[@@%:@@] != 0
+@end example
+
+@noindent
+Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
+breaking the bracket-matching highlighting from Emacsen.  Note the
+preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc.  Do
+not escape when it is unneeded.  Common examples of useless quotation
+are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
+etc.  If you add portability issues to the picture, you'll prefer
+@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
+better than hacking Autoconf @code{:-)}.
+
+When using @command{sed}, don't use @option{-e} except for indenting
+purpose.  With the @code{s} command, the preferred separator is @samp{/}
+unless @samp{/} itself is used in the command, in which case you should
+use @samp{,}.
+
+@xref{Macro Definitions}, for details on how to define a macro.  If a
+macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
+object of an @code{AC_REQUIRE} directive, then use @code{define}.  In
+case of doubt, use @code{AC_DEFUN}.  All the @code{AC_REQUIRE}
+statements should be at the beginning of the macro, @code{dnl}'ed.
+
+You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty.  It provides
+both a simpler and a more predictable interface to the user, and saves
+room for further arguments.
+
+Unless the macro is short, try to leave the closing @samp{])} at the
+beginning of a line, followed by a comment that repeats the name of the
+macro being defined.  This introduces an additional newline in
+@code{configure}; normally, that is not a problem, but if you want to
+remove it you can use @samp{[]dnl} on the last line.  You can similarly
+use @samp{[]dnl} after a macro call to remove its newline.  @samp{[]dnl}
+is recommended instead of @samp{dnl} to ensure that M4 does not
+interpret the @samp{dnl} as being attached to the preceding text or
+macro output.  For example, instead of:
+
+@example
+AC_DEFUN([AC_PATH_X],
+[AC_MSG_CHECKING([for X])
+AC_REQUIRE_CPP()
+@r{# @dots{}omitted@dots{}}
+  AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi])
+@end example
+
+@noindent
+you would write:
+
+@example
+AC_DEFUN([AC_PATH_X],
+[AC_REQUIRE_CPP()[]dnl
+AC_MSG_CHECKING([for X])
+@r{# @dots{}omitted@dots{}}
+  AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
+fi[]dnl
+])# AC_PATH_X
+@end example
+
+If the macro is long, try to split it into logical chunks.  Typically,
+macros that check for a bug in a function and prepare its
+@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
+this setup.  Do not hesitate to introduce auxiliary macros to factor
+your code.
+
+In order to highlight the recommended coding style, here is a macro
+written the old way:
+
+@example
+dnl Check for EMX on OS/2.
+dnl _AC_EMXOS2
+AC_DEFUN(_AC_EMXOS2,
+[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
+ac_cv_emxos2=yes, ac_cv_emxos2=no)])
+test "$ac_cv_emxos2" = yes && EMXOS2=yes])
+@end example
+
+@noindent
+and the new way:
+
+@example
+# _AC_EMXOS2
+# ----------
+# Check for EMX on OS/2.
+define([_AC_EMXOS2],
+[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
+[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
+                   [ac_cv_emxos2=yes],
+                   [ac_cv_emxos2=no])])
+test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
+])# _AC_EMXOS2
+@end example
+
+
+
+
+@c ============================================= Portable Shell Programming
+
+@node Portable Shell, Manual Configuration, Writing Autoconf Macros, Top
+@chapter Portable Shell Programming
+
+When writing your own checks, there are some shell-script programming
+techniques you should avoid in order to make your code portable.  The
+Bourne shell and upward-compatible shells like the Korn shell and Bash
+have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after @sc{unix} version 7, circa
+1977.  You should not use shell functions, aliases, negated character
+classes, or other features that are not found in all Bourne-compatible
+shells; restrict yourself to the lowest common denominator.  Even
+@code{unset} is not supported by all shells!  Also, include a space
+after the exclamation point in interpreter specifications, like this:
+
+@example
+#! /usr/bin/perl
+@end example
+
+@noindent
+If you omit the space before the path, then 4.2@sc{bsd} based systems
+(such as Sequent DYNIX) will ignore the line, because they interpret
+@samp{#! /} as a 4-byte magic number.
+
+The set of external programs you should run in a @code{configure} script
+is fairly small.  @xref{Utilities in Makefiles,, Utilities in
+Makefiles, standards, GNU Coding Standards}, for the list.  This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
+
+Some of these external utilities have a portable subset of features; see
+@ref{Limitations of Usual Tools}.
+
+@menu
+* Shellology::                  A zoology of shells
+* Here-Documents::              Quirks and tricks
+* File Descriptors::            FDs and redirections
+* File System Conventions::     File- and pathnames
+* Shell Substitutions::         Variable and command expansions
+* Assignments::                 Varying side effects of assignments
+* Special Shell Variables::     Variables you should not change
+* Limitations of Builtins::     Portable use of not so portable /bin/sh
+* Limitations of Usual Tools::  Portable use of portable tools
+* Limitations of Make::         Portable Makefiles
+@end menu
+
+@node Shellology, Here-Documents, Portable Shell, Portable Shell
+@section Shellology
+
+There are several families of shells, most prominently the Bourne
+family and the C shell family which are deeply incompatible.  If you
+want to write portable shell scripts, avoid members of the C shell
+family.
+
+Below we describe some of the members of the Bourne shell family.
+
+@table @asis
+@item Ash
+@cindex Ash
+@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
+light-weight Bourne-compatible shell.  Ash 0.2 has some bugs that are
+fixed in the 0.3.x series, but portable shell scripts should workaround
+them, since version 0.2 is still shipped with many @sc{gnu}/Linux
+distributions.
+
+To be compatible with Ash 0.2:
+
+@itemize @minus
+@item
+don't use @samp{$?} after expanding empty or unset variables:
+
+@example
+foo=
+false
+$foo
+echo "Don't use it: $?"
+@end example
+
+@item
+don't use command substitution within variable expansion:
+
+@example
+cat $@{FOO=`bar`@}
+@end example
+
+@item
+beware that single builtin substitutions are not performed by a sub
+shell, hence their effect applies to the current shell!  @xref{Shell
+Substitutions}, item ``Command Substitution''.
+@end itemize
+
+@item Bash
+@cindex Bash
+To detect whether you are running @command{bash}, test if
+@code{BASH_VERSION} is set.  To disable its extensions and require
+@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
+Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
+details.
+
+@item @command{/usr/xpg4/bin/sh} on Solaris
+@cindex @command{/usr/xpg4/bin/sh} on Solaris
+The @sc{posix}-compliant Bourne shell on a Solaris system is
+@command{/usr/xpg4/bin/sh} and is part of an extra optional package.
+There is no extra charge for this package, but it is also not part of a
+minimal OS install and therefore some folks may not have it.
+
+@item Zsh
+@cindex Zsh
+To detect whether you are running @command{zsh}, test if
+@code{ZSH_VERSION} is set.  By default @command{zsh} is @emph{not}
+compatible with the Bourne shell: you have to run @samp{emulate sh} and
+set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
+zsh, The Z Shell Manual}, for details.
+
+Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
+@end table
+
+The following discussion between Russ Allbery and Robert Lipe is worth
+reading:
+
+@noindent
+Russ Allbery:
+
+@quotation
+The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell
+leads to a permanent deadlock.  Vendors don't want to break user's
+existent shell scripts, and there are some corner cases in the Bourne
+shell that are not completely compatible with a @sc{posix} shell.  Thus,
+vendors who have taken this route will @emph{never} (OK@dots{}``never say
+never'') replace the Bourne shell (as @command{/bin/sh}) with a
+@sc{posix} shell.
+@end quotation
+
+@noindent
+Robert Lipe:
+
+@quotation
+This is exactly the problem.  While most (at least most System V's) do
+have a bourne shell that accepts shell functions most vendor
+@command{/bin/sh} programs are not the @sc{posix} shell.
+
+So while most modern systems do have a shell _somewhere_ that meets the
+@sc{posix} standard, the challenge is to find it.
+@end quotation
+
+@node Here-Documents, File Descriptors, Shellology, Portable Shell
+@section Here-Documents
+
+Don't rely on @samp{\} being preserved just because it has no special
+meaning together with the next symbol.  in the native @command{/bin/sh}
+on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
+unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
+use @samp{\\} to get @samp{\}.
+
+With OpenBSD 2.7's @command{/bin/sh}
+
+@example
+@group
+$ cat <<EOF
+> \" \\
+> EOF
+" \
+@end group
+@end example
+
+@noindent
+and with Bash:
+
+@example
+@group
+bash-2.04$ cat <<EOF
+> \" \\
+> EOF
+\" \
+@end group
+@end example
+
+
+Many older shells (including the Bourne shell) implement here-documents
+inefficiently.  Users can generally speed things up by using a faster
+shell, e.g., by using the command @samp{bash ./configure} rather than
+plain @samp{./configure}.
+
+Some shells can be extremely inefficient when there are a lot of
+here-documents inside a single statement.  For instance if your
+@file{configure.ac} includes something like:
+
+@example
+@group
+if <cross_compiling>; then
+  assume this and that
+else
+  check this
+  check that
+  check something else
+  @dots{}
+  on and on forever
+  @dots{}
+fi
+@end group
+@end example
+
+A shell parses the whole @code{if}/@code{fi} construct, creating
+temporary files for each here document in it.  Some shells create links
+for such here-documents on every @code{fork}, so that the clean-up code
+they had installed correctly removes them.  It is creating the links
+that the shell can take forever.
+
+Moving the tests out of the @code{if}/@code{fi}, or creating multiple
+@code{if}/@code{fi} constructs, would improve the performance
+significantly.  Anyway, this kind of construct is not exactly the
+typical use of Autoconf.  In fact, it's even not recommended, because M4
+macros can't look into shell conditionals, so we may fail to expand a
+macro when it was expanded before in a conditional path, and the
+condition turned out to be false at run-time, and we end up not
+executing the macro at all.
+
+@node File Descriptors, File System Conventions, Here-Documents, Portable Shell
+@section File Descriptors
+
+Some file descriptors shall not be used, since some systems, admittedly
+arcane, use them for special purpose:
+
+@table @asis
+@item 3
+some systems may open it to @samp{/dev/tty}.
+
+@item 4
+used on the Kubota Titan.
+@end table
+
+Don't redirect several times the same file descriptor, as you are doomed
+to failure under Ultrix.
+
+@example
+ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
+UWS V4.4 (Rev. 11)
+$ eval 'echo matter >fullness' >void
+illegal io
+$ eval '(echo matter >fullness)' >void
+illegal io
+$ (eval '(echo matter >fullness)') >void
+Ambiguous output redirect.
+@end example
+
+@noindent
+In each case the expected result is of course @file{fullness} containing
+@samp{matter} and @file{void} being empty.
+
+Don't try to redirect the standard error of a command substitution: it
+must be done @emph{inside} the command substitution: when running
+@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
+escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
+
+It is worth noting that Zsh (but not Ash nor Bash) makes it possible
+in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
+
+Most shells, if not all (including Bash, Zsh, Ash), output traces on
+stderr, even for sub-shells.  This might result in undesired content
+if you meant to capture the standard-error output of the inner command:
+
+@example
+$ ash -x -c '(eval "echo foo >&2") 2>stderr'
+$ cat stderr
++ eval echo foo >&2
++ echo foo
+foo
+$ bash -x -c '(eval "echo foo >&2") 2>stderr'
+$ cat stderr
++ eval 'echo foo >&2'
+++ echo foo
+foo
+$ zsh -x -c '(eval "echo foo >&2") 2>stderr'
+@i{# Traces on startup files deleted here.}
+$ cat stderr
++zsh:1> eval echo foo >&2
++zsh:1> echo foo
+foo
+@end example
+
+@noindent
+You'll appreciate the various levels of detail@dots{}
+
+One workaround is to grep out uninteresting lines, hoping not to remove
+good ones@dots{}
+
+@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell
+@section File System Conventions
+
+While @command{autoconf} and friends will usually be run on some Unix
+variety, it can and will be used on other systems, most notably @sc{dos}
+variants.  This impacts several assumptions regarding file and
+path names.
+
+@noindent
+For example, the following code:
+
+@example
+case $foo_dir in
+  /*) # Absolute
+     ;;
+  *)
+     foo_dir=$dots$foo_dir ;;
+esac
+@end example
+
+@noindent
+will fail to properly detect absolute paths on those systems, because
+they can use a drivespec, and will usually use a backslash as directory
+separator.  The canonical way to check for absolute paths is:
+
+@example
+case $foo_dir in
+  [\\/]* | ?:[\\/]* ) # Absolute
+     ;;
+  *)
+     foo_dir=$dots$foo_dir ;;
+esac
+@end example
+
+@noindent
+Make sure you quote the brackets if appropriate and keep the backslash as
+first character (@pxref{Limitations of Builtins}).
+
+Also, because the colon is used as part of a drivespec, these systems don't
+use it as path separator.  When creating or accessing paths, use
+@code{$ac_path_separator} instead (or the @code{PATH_SEPARATOR} output
+variable).  @command{autoconf} sets this to the appropriate value (@samp{:}
+or @samp{;}) when it starts up.
+
+File names need extra care as well.  While @sc{dos}-based environments
+that are Unixy enough to run @command{autoconf} (such as DJGPP) will
+usually be able to handle long file names properly, there are still
+limitations that can seriously break packages.  Several of these issues
+can be easily detected by the
+@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
+package.
+
+A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
+indicate where they apply: @sc{sfn} means the issues are only relevant to
+plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn}
+identifies problems that exist even under Windows.
+
+@table @asis
+@item No multiple dots (@sc{sfn})
+@sc{dos} cannot handle multiple dots in filenames.  This is an especially
+important thing to remember when building a portable configure script,
+as @command{autoconf} uses a .in suffix for template files.
+
+This is perfectly OK on Unices:
+
+@example
+AC_CONFIG_HEADER(config.h)
+AC_CONFIG_FILES([source.c foo.bar])
+AC_OUTPUT
+@end example
+
+@noindent
+but it causes problems on @sc{dos}, as it requires @samp{config.h.in},
+@samp{source.c.in} and @samp{foo.bar.in}.  To make your package more portable
+to @sc{dos}-based environments, you should use this instead:
+
+@example
+AC_CONFIG_HEADER(config.h:config.hin)
+AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
+AC_OUTPUT
+@end example
+
+@item No leading dot (@sc{sfn})
+@sc{dos} cannot handle filenames that start with a dot.  This is usually
+not a very important issue for @command{autoconf}.
+
+@item Case insensitivity (@sc{lfn})
+@sc{dos} is case insensitive, so you cannot, for example, have both a
+file called @samp{INSTALL} and a directory called @samp{install}.  This
+also affects @command{make}; if there's a file called @samp{INSTALL} in
+the directory, @command{make install} will do nothing (unless the
+@samp{install} target is marked as PHONY).
+
+@item The 8+3 limit (@sc{sfn})
+Because the @sc{dos} file system only stores the first 8 characters of
+the filename and the first 3 of the extension, those must be unique.
+That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
+@file{foobar-prettybird.c} all resolve to the same filename
+(@file{FOOBAR-P.C}).  The same goes for @file{foo.bar} and
+@file{foo.bartender}.
+
+Note: This is not usually a problem under Windows, as it uses numeric
+tails in the short version of filenames to make them unique.  However, a
+registry setting can turn this behaviour off.  While this makes it
+possible to share file trees containing long file names between @sc{sfn}
+and @sc{lfn} environments, it also means the above problem applies there
+as well.
+
+@item Invalid characters
+Some characters are invalid in @sc{dos} filenames, and should therefore
+be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
+@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
+In a @sc{sfn} environment, other characters are also invalid.  These
+include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
+@end table
+
+@node Shell Substitutions, Assignments, File System Conventions, Portable Shell
+@section Shell Substitutions
+
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and backquoted expressions, in particular
+on the right-hand side of assignments and in the argument of @code{case}.
+For instance, the following code:
+
+@example
+case "$given_srcdir" in
+.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+*)  top_srcdir="$dots$given_srcdir" ;;
+esac
+@end example
+
+@noindent
+is more readable when written as:
+
+@example
+case $given_srcdir in
+.)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
+*)  top_srcdir=$dots$given_srcdir ;;
+esac
+@end example
+
+@noindent
+and in fact it is even @emph{more} portable: in the first case of the
+first attempt, the computation of @code{top_srcdir} is not portable,
+since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
+Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
+the same way.  There is just no portable way to use double-quoted
+strings inside double-quoted backquoted expressions (pfew!).
+
+@table @code
+@item $@@
+@cindex @samp{"$@@"}
+One of the most famous shell-portability issues is related to
+@samp{"$@@"}: when there are no positional arguments, it is supposed to
+be equivalent to nothing.  But some shells, for instance under Digital
+Unix 4.0 and 5.0, will then replace it with an empty argument.  To be
+portable, use @samp{$@{1+"$@@"@}}.
+
+@item $@{@var{var}:-@var{value}@}
+@cindex $@{@var{var}:-@var{value}@}
+Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the
+colon for any shell substitution, and complain and die.
+
+@item $@{@var{var}=@var{literal}@}
+@cindex $@{@var{var}=@var{literal}@}
+Be sure to quote:
+
+@example
+: $@{var='Some words'@}
+@end example
+
+@noindent
+otherwise some shells, such as on Digital Unix V 5.0, will die because
+of a ``bad substitution''.
+
+Solaris' @command{/bin/sh} has a frightening bug in its interpretation
+of this.  Imagine you need set a variable to a string containing
+@samp{@}}.  This @samp{@}} character confuses Solaris' @command{/bin/sh}
+when the affected variable was already set.  This bug can be exercised
+by running:
+
+@example
+$ unset foo
+$ foo=$@{foo='@}'@}
+$ echo $foo
+@}
+$ foo=$@{foo='@}'   # no error; this hints to what the bug is
+$ echo $foo
+@}
+$ foo=$@{foo='@}'@}
+$ echo $foo
+@}@}
+ ^ ugh!
+@end example
+
+It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
+though it is enclosed in single quotes.  The problem doesn't happen
+using double quotes.
+
+@item $@{@var{var}=@var{expanded-value}@}
+@cindex $@{@var{var}=@var{expanded-value}@}
+On Ultrix,
+running
+
+@example
+default="yu,yaa"
+: $@{var="$default"@}
+@end example
+
+@noindent
+will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
+each char will be set. You won't observe the phenomenon using a simple
+@samp{echo $var} since apparently the shell resets the 8th bit when it
+expands $var.  Here are two means to make this shell confess its sins:
+
+@example
+$ cat -v <<EOF
+$var
+EOF
+@end example
+
+@noindent
+and
+
+@example
+$ set | grep '^var=' | cat -v
+@end example
+
+One classic incarnation of this bug is:
+
+@example
+default="a b c"
+: $@{list="$default"@}
+for c in $list; do
+  echo $c
+done
+@end example
+
+@noindent
+You'll get @samp{a b c} on a single line.  Why?  Because there are no
+spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
+bit set, hence no IFS splitting is performed!!!
+
+One piece of good news is that Ultrix works fine with @samp{:
+$@{list=$default@}}; i.e., if you @emph{don't} quote.  The bad news is
+then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of
+@var{default}!
+
+The portable way out consists in using a double assignment, to switch
+the 8th bit twice on Ultrix:
+
+@example
+list=$@{list="$default"@}
+@end example
+
+@noindent
+@dots{}but beware of the @samp{@}} bug from Solaris (see above).  For safety,
+use:
+
+@example
+test "$@{var+set@}" = set || var=@var{@{value@}}
+@end example
+
+
+@item `@var{commands}`
+@cindex `@var{commands}`
+@cindex Command Substitution
+While in general it makes no sense, do not substitute a single builtin
+with side effects as Ash 0.2, trying to optimize, does not fork a
+sub-shell to perform the command.
+
+For instance, if you wanted to check that @command{cd} is silent, do not
+use @samp{test -z "`cd /`"} because the following can happen:
+
+@example
+$ pwd
+/tmp
+$ test -n "`cd /`" && pwd
+/
+@end example
+
+@noindent
+The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
+
+
+@item $(@var{commands})
+@cindex $(@var{commands})
+This construct is meant to replace @samp{`@var{commands}`}; they can be
+nested while this is impossible to do portably with back quotes.
+Unfortunately it is not yet widely supported.  Most notably, even recent
+releases of Solaris don't support it:
+
+@example
+$ showrev -c /bin/sh | grep version
+Command version: SunOS 5.8 Generic 109324-02 February 2001
+$ echo $(echo blah)
+syntax error: `(' unexpected
+@end example
+
+@noindent
+nor does @sc{irix} 6.5's Bourne shell:
+@example
+$ uname -a
+IRIX firebird-image 6.5 07151432 IP22
+$ echo $(echo blah)
+$(echo blah)
+@end example
+@end table
+
+
+@node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell
+@section Assignments
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
+gives @samp{1} with sh on Solaris, but @samp{2} with Bash.  You must use
+@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
+
+Don't rely on the exit status of an assignment: Ash 0.2 does not change
+the status and propagates that of the last statement:
+
+@example
+$ false || foo=bar; echo $?
+1
+$ false || foo=`:`; echo $?
+0
+@end example
+
+@noindent
+and to make things even worse, @sc{qnx 4.25} just sets the exit status
+to 0 in any case:
+
+@example
+$ foo=`exit 1`; echo $?
+0
+@end example
+
+To assign default values, follow this algorithm:
+
+@enumerate
+@item
+If the default value is a literal and does not contain any closing
+brace, use:
+
+@example
+: $@{var='my literal'@}
+@end example
+
+@item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will never be IFS-split (i.e., it's not a
+list), then use:
+
+@example
+: $@{var="$default"@}
+@end example
+
+@item
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will be IFS-split (i.e., it's a list),
+then use:
+
+@example
+var=$@{var="$default"@}
+@end example
+
+@item
+If the default value contains a closing brace, then use:
+
+@example
+test "$@{var+set@}" = set || var='$@{indirection@}'
+@end example
+@end enumerate
+
+In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
+doubt, just use the latter.  @xref{Shell Substitutions}, items
+@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
+for the rationale.
+
+
+@node Special Shell Variables, Limitations of Builtins, Assignments, Portable Shell
+@section Special Shell Variables
+
+Some shell variables should not be used, since they can have a deep
+influence on the behavior of the shell.  In order to recover a sane
+behavior from the shell, some variables should be unset, but
+@command{unset} is not portable (@pxref{Limitations of Builtins}) and a
+fallback value is needed.  We list these values below.
+
+@c Alphabetical order, case insensitive, `A' before `a'.
+@table @code
+@item CDPATH
+@evindex CDPATH
+When this variable is set @code{cd} is verbose, so idioms such as
+@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path
+twice.
+
+@c FIXME: Which shells?  How do they behave?
+Setting @code{CDPATH} to the empty value is not enough for most shells.
+A simple colon is enough except for @code{zsh}, which prefers a leading
+dot:
+
+@example
+zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo)
+/tmp/foo
+zsh-3.1.6 % (CDPATH=:. cd foo)
+/tmp/foo
+zsh-3.1.6 % (CDPATH=.: cd foo)
+zsh-3.1.6 %
+@end example
+
+@noindent
+(of course we could just @code{unset} @code{CDPATH}, since it also
+behaves properly if set to the empty string).
+
+Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
+same behavior:
+
+@example
+bash-2.02 % (CDPATH=:. cd foo)
+bash-2.02 % (CDPATH=.: cd foo)
+/tmp/foo
+@end example
+
+Therefore, a portable solution to neutralize @samp{CDPATH} is
+
+@example
+CDPATH=$@{ZSH_VERSION+.@}:
+@end example
+
+@noindent
+Note that since @command{zsh} supports @command{unset}, you may unset
+@samp{CDPATH} using @samp{:} as a fallback, see
+@ref{Limitations of Builtins}.
+
+@item IFS
+@evindex IFS
+Don't set the first character of @code{IFS} to backslash.  Indeed,
+Bourne shells use the first character (backslash) when joining the
+components in @samp{"$@@"} and some shells then re-interpret (!) the
+backslash escapes, so you can end up with backspace and other strange
+characters.
+
+@item LANG
+@itemx LC_ALL
+@itemx LC_TIME
+@itemx LC_CTYPE
+@itemx LANGUAGE
+@itemx LC_COLLATE
+@itemx LC_NUMERIC
+@itemx LC_MESSAGES
+@evindex LANG
+@evindex LC_ALL
+@evindex LC_TIME
+@evindex LC_CTYPE
+@evindex LANGUAGE
+@evindex LC_COLLATE
+@evindex LC_NUMERIC
+@evindex LC_MESSAGES
+
+These must not be set unconditionally because not all systems understand
+e.g. @samp{LANG=C} (notably SCO).  Fixing @env{LC_MESSAGES} prevents
+Solaris @command{sh} from translating var values in @code{set}!  Non-C
+@env{LC_CTYPE} values break the ctype check.  Fixing @env{LC_COLLATE}
+makes scripts more portable in some cases.  For example, it causes the
+regular expression @samp{[a-z]} to match only lower-case letters on
+@sc{ascii} platforms.  However, @samp{[a-z]} does not work in general
+even when @env{LC_COLLATE} is fixed; for example, it does not work for
+@sc{ebcdic} platforms.  For maximum portability, you should use regular
+expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list
+characters explicitly instead of relying on ranges.
+
+@emph{If} one of these variables is set, you should try to unset it,
+using @samp{C} as a fall back value. see @ref{Limitations of Builtins},
+builtin @command{unset}, for more details.
+
+@item NULLCMD
+@evindex NULLCMD
+When executing the command @samp{>foo}, @command{zsh} executes
+@samp{$NULLCMD >foo}.  The Bourne shell considers @code{NULLCMD} is
+@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
+sets @code{NULLCMD} to @samp{cat}.  If you forgot to set @code{NULLCMD},
+your script might be suspended waiting for data on its standard input.
+
+@item status
+@evindex status
+This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
+hence read-only.  Do not use it.
+
+@item PATH_SEPARATOR
+@evindex PATH_SEPARATOR
+On DJGPP systems, the @code{PATH_SEPARATOR} variable can be set to
+either @samp{:} or @samp{;} to control the path separator @command{bash}
+uses to set up certain environment variables (such as
+@code{PATH}). Since this only works inside bash, you want autoconf to
+detect the regular @sc{dos} path separator @samp{;}, so it can be safely
+substituted in files that may not support @samp{;} as path separator. So
+either unset this variable or set it to @samp{;}.
+
+@item RANDOM
+@evindex RANDOM
+Many shells provide @code{RANDOM}, a variable that returns a different
+integer when used.  Most of the time, its value does not change when it
+is not used, but on @sc{irix 6.5} the value changes all the time.  This
+can be observed by using @command{set}.
+@end table
+
+
+@node Limitations of Builtins, Limitations of Usual Tools, Special Shell Variables, Portable Shell
+@section Limitations of Shell Builtins
+
+No, no, we are serious: some shells do have limitations! :)
+
+You should always keep in mind that any built-in or command may support
+options, and therefore have a very different behavior with arguments
+starting with a dash.  For instance, the innocent @samp{echo "$word"}
+can give unexpected results when @code{word} starts with a dash.  It is
+often possible to avoid this problem using @samp{echo "x$word"}, taking
+the @samp{x} into account later in the pipe.
+
+@table @asis
+@item @command{!}
+@cindex @command{!}
+You can't use @command{!}, you'll have to rewrite your code.
+
+
+@item @command{break}
+@c ------------------
+@cindex @command{break}
+The use of @samp{break 2}, etcetera, is safe.
+
+
+@item @command{case}
+@c -----------------
+@cindex @command{case}
+You don't need to quote the argument; no splitting is performed.
+
+You don't need the final @samp{;;}, but you should use it.
+
+Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
+handle backslashes in character classes:
+
+@example
+bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
+bash-2.02$
+@end example
+
+@noindent
+This is extremely unfortunate, since you are likely to use this code to
+handle @sc{unix} or @sc{ms-dos} absolute paths.  To work around this
+bug, always put the backslash first:
+
+@example
+bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
+OK
+bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
+OK
+@end example
+
+
+@item @command{echo}
+@c -----------------
+@cindex @command{echo}
+The simple @code{echo} is probably the most surprising source of
+portability troubles.  It is not possible to use @samp{echo} portably
+unless both options and escape sequences are omitted.  New applications
+which are not aiming at portability should use @samp{printf} instead of
+@samp{echo}.
+
+Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
+etc. for a means to simulate @option{-c}.
+
+Do not use backslashes in the arguments, as there is no consensus on
+their handling.  On @samp{echo '\n' | wc -l}, the @command{sh} of
+Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris'
+@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.
+Please note that the problem is truly @command{echo}: all the shells
+understand @samp{'\n'} as the string composed of a backslash and an
+@samp{n}.
+
+Because of these problems, do not pass a string containing arbitrary
+characters to @command{echo}.  For example, @samp{echo "$foo"} is safe
+if you know that @var{foo}'s value cannot contain backslashes and cannot
+start with @samp{-}, but otherwise you should use a here-document like
+this:
+
+@example
+cat <<EOF
+$foo
+EOF
+@end example
+
+
+@item @command{exit}
+@c -----------------
+@cindex @command{exit}
+The default value of @command{exit} is supposed to be @code{$?};
+unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
+perform @samp{exit 0}.
+
+@example
+bash-2.04$ foo=`exit 1` || echo fail
+fail
+bash-2.04$ foo=`(exit 1)` || echo fail
+fail
+bash-2.04$ foo=`(exit 1); exit` || echo fail
+bash-2.04$
+@end example
+
+Using @samp{exit $?} restores the expected behavior.
+
+Some shell scripts, such as those generated by @command{autoconf}, use a
+trap to clean up before exiting.  If the last shell command exited with
+nonzero status, the trap also exits with nonzero status so that the
+invoker can tell that an error occurred.
+
+Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
+trap ignores the @code{exit} command's status.  In these shells, a trap
+cannot determine whether it was invoked by plain @code{exit} or by
+@code{exit 1}.  Instead of calling @code{exit} directly, use the
+@code{AC_MSG_ERROR} macro that has a workaround for this problem.
+
+
+@item @command{export}
+@c -------------------
+@cindex @command{export}
+The builtin @command{export} dubs @dfn{environment variable} a shell
+variable.  Each update of exported variables corresponds to an update of
+the environment variables.  Conversely, each environment variable
+received by the shell when it is launched should be imported as a shell
+variable marked as exported.
+
+Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5
+and DU 4.0, forget to @command{export} the environment variables they
+receive.  As a result, two variables are coexisting: the environment
+variable and the shell variable.  The following code demonstrates this
+failure:
+
+@example
+#! /bin/sh
+echo $FOO
+FOO=bar
+echo $FOO
+exec /bin/sh $0
+@end example
+
+@noindent
+when run with @samp{FOO=foo} in the environment, these shells will print
+alternately @samp{foo} and @samp{bar}, although it should only print
+@samp{foo} and then a sequence of @samp{bar}s.
+
+Therefore you should @command{export} again each environment variable
+that you update.
+
+
+@item @command{false}
+@c ------------------
+@cindex @command{false}
+Don't expect @command{false} to exit with status 1: in the native Bourne
+shell of Solaris 8, it exits with status 255.
+
+
+@item @command{for}
+@c ----------------
+@cindex @command{for}
+To loop over positional arguments, use:
+
+@example
+for arg
+do
+  echo "$arg"
+done
+@end example
+
+@noindent
+You may @emph{not} leave the @code{do} on the same line as @code{for},
+since some shells improperly grok:
+
+@example
+for arg; do
+  echo "$arg"
+done
+@end example
+
+If you want to explicitly refer to the positional arguments, given the
+@samp{$@@} bug (@pxref{Shell Substitutions}), use:
+
+@example
+for arg in $@{1+"$@@"@}; do
+  echo "$arg"
+done
+@end example
+
+@item @command{if}
+@c ---------------
+@cindex @command{if}
+Using @samp{!} is not portable.  Instead of:
+
+@example
+if ! cmp -s file file.new; then
+  mv file.new file
+fi
+@end example
+
+@noindent
+use:
+
+@example
+if cmp -s file file.new; then :; else
+  mv file.new file
+fi
+@end example
+
+There are shells that do not reset the exit status from an @command{if}:
+
+@example
+$ if (exit 42); then true; fi; echo $?
+42
+@end example
+
+@noindent
+whereas a proper shell should have printed @samp{0}.  This is especially
+bad in Makefiles since it produces false failures.  This is why properly
+written Makefiles, such as Automake's, have such hairy constructs:
+
+@example
+if test -f "$file"; then
+  install "$file" "$dest"
+else
+  :
+fi
+@end example
+
+
+@item @command{set}
+@c ----------------
+@cindex @command{set}
+This builtin faces the usual problem with arguments starting with a
+dash.  Modern shells such as Bash or Zsh understand @option{--} to specify
+the end of the options (any argument after @option{--} is a parameters,
+even @samp{-x} for instance), but most shells simply stop the option
+processing as soon as a non-option argument is found.  Therefore, use
+@samp{dummy} or simply @samp{x} to end the option processing, and use
+@command{shift} to pop it out:
+
+@example
+set x $my_list; shift
+@end example
+
+@item @command{shift}
+@c ------------------
+@cindex @command{shift}
+Not only is @command{shift}ing a bad idea when there is nothing left to
+shift, but in addition it is not portable: the shell of @sc{mips
+risc/os} 4.52 refuses to do it.
+
+@item @command{test}
+@c -----------------
+@cindex @command{test}
+The @code{test} program is the way to perform many file and string
+tests.  It is often invoked by the alternate name @samp{[}, but using
+that name in Autoconf code is asking for trouble since it is an M4 quote
+character.
+
+If you need to make multiple checks using @code{test}, combine them with
+the shell operators @samp{&&} and @samp{||} instead of using the
+@code{test} operators @option{-a} and @option{-o}.  On System V, the
+precedence of @option{-a} and @option{-o} is wrong relative to the unary
+operators; consequently, @sc{posix} does not specify them, so using them
+is nonportable.  If you combine @samp{&&} and @samp{||} in the same
+statement, keep in mind that they have equal precedence.
+
+You may use @samp{!} with @command{test}, but not with @command{if}:
+@samp{test ! -r foo || exit 1}.
+
+@item @command{test} (files)
+@c -------------------------
+To enable @code{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the build system instead of
+the host system.  But occasionally you may find it necessary to check
+whether some arbitrary file exists.  To do so, use @samp{test -f} or
+@samp{test -r}.  Do not use @samp{test -x}, because @sc{4.3bsd} does not
+have it.  Do not use @samp{test -e} either, because Solaris 2.5 does not
+have it.
+
+@item @command{test} (strings)
+@c ---------------------------
+Avoid @samp{test "@var{string}"}, in particular if @var{string} might
+start with a dash, since @code{test} might interpret its argument as an
+option (e.g., @samp{@var{string} = "-n"}).
+
+Contrary to a common belief, @samp{test -n @var{string}} and @samp{test
+-z @var{string}} @strong{are} portable, nevertheless many shells (such
+as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
+bizarre precedence and may be confused if @var{string} looks like an
+operator:
+
+@example
+$ test -n =
+test: argument expected
+@end example
+
+If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
+"x@var{string}" != x} instead.
+
+It is frequent to find variations of the following idiom:
+
+@example
+test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
+  @var{action}
+@end example
+
+@noindent
+to take an action when a token matches a given pattern.  Such constructs
+should always be avoided by using:
+
+@example
+echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
+  @var{action}
+@end example
+
+@noindent
+Use @code{case} where possible since it is faster, being a shell builtin:
+
+
+@example
+case $ac_feature in
+  *[!-a-zA-Z0-9_]*) @var{action};;
+esac
+@end example
+
+Alas, negated character classes are probably not portable, although no
+shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]}
+(when in interactive mode, @command{zsh} is confused by the
+@samp{[!@dots{}]} syntax and looks for an event in its history because of
+@samp{!}).  Many shells do not support the alternative syntax
+@samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
+
+One solution can be:
+
+@example
+expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+  @var{action}
+@end example
+
+@noindent
+or better yet
+
+@example
+expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+  @var{action}
+@end example
+
+@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
+"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
+@samp{@var{foo}} contains backslashes.
+
+
+@item @command{trap}
+@c -----------------
+@cindex @command{trap}
+It is safe to trap at least the signals 1, 2, 13 and 15.  You can also
+trap 0, i.e., have the @command{trap} run when the script ends (either via an
+explicit @command{exit}, or the end of the script).
+
+Although @sc{posix} is not absolutely clear on this point, it is widely
+admitted that when entering the trap @samp{$?} should be set to the exit
+status of the last command run before the trap.  The ambiguity can be
+summarized as: ``when the trap is launched by an @command{exit}, what is
+the @emph{last} command run: that before @command{exit}, or
+@command{exit} itself?''
+
+Bash considers @command{exit} to be the last command, while Zsh and
+Solaris 8 @command{sh} consider that when the trap is run it is
+@emph{still} in the @command{exit}, hence it is the previous exit status
+that the trap receives:
+
+@example
+$ cat trap.sh
+trap 'echo $?' 0
+(exit 42); exit 0
+$ zsh trap.sh
+42
+$ bash trap.sh
+0
+@end example
+
+The portable solution is then simple: when you want to @samp{exit 42},
+run @samp{(exit 42); exit 42}, the first @command{exit} being used to
+set the exit status to 42 for Zsh, and the second to trigger the trap
+and pass 42 as exit status for Bash.
+
+The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0
+by empty lines if the code is inside @command{trap}.
+
+@example
+$ trap 'false
+
+echo $?' 0
+$ exit
+0
+@end example
+
+@noindent
+Fortunately, this bug only affects @command{trap}.
+
+@item @command{true}
+@c -----------------
+@cindex @command{true}
+@cindex @command{:}
+Don't worry: as far as we know @command{true} is portable.
+Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
+portable shell community tends to prefer using @command{:}.  This has a
+funny side effect: when asked whether @command{false} is more portable
+than @command{true} Alexandre Oliva answered:
+
+@quotation
+In a sense, yes, because if it doesn't exist, the shell will produce an
+exit status of failure, which is correct for @command{false}, but not
+for @command{true}.
+@end quotation
+
+
+@item @command{unset}
+@c ------------------
+@cindex @command{unset}
+You cannot assume the support of @command{unset}, nevertheless, because
+it is extremely useful to disable embarrassing variables such as
+@code{CDPATH} or @code{LANG}, you can test for its existence and use
+it @emph{provided} you give a neutralizing value when @command{unset} is
+not supported:
+
+@example
+if (unset FOO) >/dev/null 2>&1; then
+  unset=unset
+else
+  unset=false
+fi
+$unset CDPATH || CDPATH=:
+@end example
+
+@xref{Special Shell Variables}, for some neutralizing values. Also, see
+@ref{Limitations of Builtins}, documentation of @command{export}, for
+the case of environment variables.
+@end table
+
+@node Limitations of Usual Tools, Limitations of Make, Limitations of Builtins, Portable Shell
+@section Limitations of Usual Tools
+
+The small set of tools you can expect to find on any machine can still
+include some limitations you should be aware of.
+
+@table @asis
+@item @command{awk}
+@c ----------------
+@cindex @command{awk}
+Don't leave white spaces before the parentheses in user functions calls,
+@sc{gnu} awk will reject it:
+
+@example
+$ gawk 'function die () @{ print "Aaaaarg!"  @}
+        BEGIN @{ die () @}'
+gawk: cmd. line:2:         BEGIN @{ die () @}
+gawk: cmd. line:2:                      ^ parse error
+$ gawk 'function die () @{ print "Aaaaarg!"  @}
+        BEGIN @{ die() @}'
+Aaaaarg!
+@end example
+
+If you want your program to be deterministic, don't depend on @code{for}
+on arrays:
+
+@example
+$ cat for.awk
+END @{
+  arr["foo"] = 1
+  arr["bar"] = 1
+  for (i in arr)
+    print i
+@}
+$ gawk -f for.awk </dev/null
+foo
+bar
+$ nawk -f for.awk </dev/null
+bar
+foo
+@end example
+
+Some AWK, such as HPUX 11.0's native one, have regex engines fragile to
+inner anchors:
+
+@example
+$ echo xfoo | $AWK '/foo|^bar/ @{ print @}'
+$ echo bar | $AWK '/foo|^bar/ @{ print @}'
+bar
+$ echo xfoo | $AWK '/^bar|foo/ @{ print @}'
+xfoo
+$ echo bar | $AWK '/^bar|foo/ @{ print @}'
+bar
+@end example
+
+@noindent
+Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
+or use a simple test to reject such AWK.
+
+
+@item @command{cat}
+@c ----------------
+@cindex @command{cat}
+Don't rely on any option.  The option @option{-v}, which displays
+non-printing characters, @emph{seems} portable, though.
+
+
+@item @command{cc}
+@c ---------------
+When a compilation such as @samp{cc foo.c -o foo} fails, some compilers
+(such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}.
+
+
+@item @command{cmp}
+@c ----------------
+@cindex @command{cmp}
+@command{cmp} performs a raw data comparison of two files, while
+@command{diff} compares two text files.  Therefore, if you might compare
+DOS files, even if only checking whether two files are different, use
+@command{diff} to avoid spurious differences due to differences of
+newline encoding.
+
+
+@item @command{cp}
+@c ---------------
+@cindex @command{cp}
+@c This is thanks to Ian.
+SunOS @command{cp} does not support @option{-f}, although its
+@command{mv} does.  It's possible to deduce why @command{mv} and
+@command{cp} are different with respect to @option{-f}.  @command{mv}
+prompts by default before overwriting a read-only file.  @command{cp}
+does not.  Therefore, @command{mv} requires a @option{-f} option, but
+@command{cp} does not.  @command{mv} and @command{cp} behave differently
+with respect to read-only files because the simplest form of
+@command{cp} cannot overwrite a read-only file, but the simplest form of
+@command{mv} can.  This is because @command{cp} opens the target for
+write access, whereas @command{mv} simply calls @code{link} (or, in
+newer systems, @code{rename}).
+@c Ian said: ``I don't think -p or -r are portable''!!! How can you live
+@c without -r???
+
+
+@item @command{diff}
+@c -----------------
+@cindex @command{diff}
+Option @option{-u} is nonportable.
+
+Some implementations, such as Tru64's, fail when comparing to
+@file{/dev/null}.  Use an empty file instead.
+
+@item @command{dirname}
+@c --------------------
+@cindex @command{dirname}
+Not all hosts have @command{dirname}, but it is reasonably easy to
+emulate, e.g.:
+
+@example
+dir=`expr "x$file" : 'x\(.*\)/[^/]*' \|
+          '.'      : '.'
+@end example
+
+@noindent
+But there are a few subtilities, e.g., under UN*X, should @samp{//1}
+give @samp{/}?  Paul Eggert answers:
+
+@quotation
+No, under some older flavors of Unix, leading @samp{//} is a special
+path name: it refers to a ``super-root'' and is used to access other
+machines' files.  Leading @samp{///}, @samp{////}, etc. are equivalent
+to @samp{/}; but leading @samp{//} is special.  I think this tradition
+started with Apollo Domain/OS, an OS that is still in use on some older
+hosts.
+
+POSIX.2 allows but does not require the special treatment for @samp{//}.
+It says that the behavior of dirname on path names of the form
+@samp{//([^/]+/*)?}  is implementation defined.  In these cases, GNU
+@command{dirname} returns @samp{/}, but it's more portable to return
+@samp{//} as this works even on those older flavors of Unix.
+
+I have heard rumors that this special treatment of @samp{//} may be
+dropped in future versions of POSIX, but for now it's still the
+standard.
+@end quotation
+
+
+@item @command{egrep}
+@c ------------------
+@cindex @command{egrep}
+The empty alternative is not portable, use @samp{?} instead. For
+instance with Digital Unix v5.0:
+
+@example
+> printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
+|foo
+> printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
+bar|
+> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
+foo
+|bar
+@end example
+
+@command{egrep} also suffers the limitations of @command{grep}.
+
+
+@item @command{expr}
+@c -----------------
+@cindex @command{expr}
+No @command{expr} keyword starts with @samp{x}, so use @samp{expr
+x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
+misinterpreting @var{word}.
+
+Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
+
+@item @command{expr} (@samp{|})
+@cindex @command{expr} (@samp{|})
+You can use @samp{|}.  Although @sc{posix} does require that @samp{expr
+''} return the empty string, it does not specify the result when you
+@samp{|} together the empty string (or zero) with the empty string.  For
+example:
+
+@example
+expr '' \| ''
+@end example
+
+@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this
+case, but traditional Unix returns @samp{0} (Solaris is one such
+example).  In the latest @sc{posix} draft, the specification has been
+changed to match traditional Unix's behavior (which is bizarre, but it's
+too late to fix this).  Please note that the same problem does arise
+when the empty string results from a computation, as in:
+
+@example
+expr bar : foo \| foo : bar
+@end example
+
+@noindent
+Avoid this portability problem by avoiding the empty string.
+
+
+@item @command{expr} (@samp{:})
+@c ----------------------------
+@cindex @command{expr}
+Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
+not supported on Solaris.
+
+The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a :
+b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string.
+In practice, it outputs the empty string on most platforms, but portable
+scripts should not assume this.  For instance, the @sc{qnx} 4.25 native
+@command{expr} returns @samp{0}.
+
+You may believe that one means to get a uniform behavior would be to use
+the empty string as a default value:
+
+@example
+expr a : b \| ''
+@end example
+
+@noindent
+unfortunately this behaves exactly as the original expression, see the
+@samp{@command{expr} (@samp{:})} entry for more information.
+
+Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and
+Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
+@command{expr} to fail if the matched substring is longer than 120
+bytes.  In this case, you might want to fall back on @samp{echo|sed} if
+@command{expr} fails.
+
+Don't leave, there is some more!
+
+The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to
+the empty string, has a funny behavior in its exit status: it's always 1
+when parentheses are used!
+
+@example
+$ val=`expr 'a' : 'a'`; echo "$?: $val"
+0: 1
+$ val=`expr 'a' : 'b'`; echo "$?: $val"
+1: 0
+
+$ val=`expr 'a' : '\(a\)'`; echo "?: $val"
+1: a
+$ val=`expr 'a' : '\(b\)'`; echo "?: $val"
+1: 0
+@end example
+
+@noindent
+In practice this can be a big problem if you are ready to catch failures
+of @command{expr} programs with some other method (such as using
+@command{sed}), since you may get twice the result.  For instance
+
+@example
+$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'
+@end example
+
+@noindent
+will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25.  A
+simple work around consists in testing @command{expr} and use a variable
+set to @command{expr} or to @command{false} according to the result.
+
+
+@item @command{find}
+@c -----------------
+The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1,
+NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it.
+
+
+@item @command{grep}
+@c -----------------
+@cindex @command{grep}
+Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
+System V does not suppress output, only error messages.  Instead,
+redirect the standard output and standard error (in case the file
+doesn't exist) of @code{grep} to @file{/dev/null}.  Check the exit
+status of @code{grep} to determine whether it found a match.
+
+Don't use multiple regexps with @option{-e}, as some @code{grep} will only
+honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1).  Anyway,
+Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{}  Instead, use
+alternation and @code{egrep}.
+
+
+@item @command{ln}
+@c ---------------
+@cindex @command{ln}
+@cindex Symbolic links
+Don't rely on @command{ln} having a @option{-f} option.  Symbolic links
+are not available on old systems, use @samp{ln} as a fall back.
+
+For versions of the DJGPP before 2.04, @command{ln} emulates soft links
+for executables by generating a stub that in turn calls the real
+program.  This feature also works with nonexistent files like in the
+Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
+which will attempt to call @file{file.exe} if run. But this feature only
+works for executables, so @samp{cp -p} is used instead for these
+systems.  DJGPP versions 2.04 and later have full symlink support.
+
+
+@item @command{mv}
+@c ---------------
+@cindex @command{mv}
+The only portable options are @option{-f} and @option{-i}.
+
+Moving individual files between file systems is portable (it was in V6),
+but it is not always atomic: when doing @samp{mv new existing}, there's
+a critical section where neither the old nor the new version of
+@file{existing} actually exists.
+
+Moving directories across mount points is not portable, use @command{cp}
+and @command{rm}.
+
+
+@item @command{sed}
+@c ----------------
+@cindex @command{sed}
+Patterns should not include the separator (unless escaped), even as part
+of a character class.  In conformance with @sc{posix}, the Cray
+@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
+
+Sed scripts should not use branch labels longer than 8 characters and
+should not contain comments.
+
+Don't include extra @samp{;}, as some @command{sed}, such as NetBSD
+1.4.2's, try to interpret the second as a command:
+
+@example
+$ echo a | sed 's/x/x/;;s/x/x/'
+sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
+@end example
+
+Input should have reasonably long lines, since some @command{sed} have
+an input buffer limited to 4000 bytes.
+
+Alternation, @samp{\|}, is common but not portable.
+@c FIXME: I know Solaris is guilty, but I don't remember how.
+Anchors (@samp{^} and @samp{$}) inside groups are not portable.
+
+Nested groups are extremely portable, but there is at least one
+@command{sed} (System V/68 Base Operating System R3V7.1) that does not
+support it.
+
+Of course the option @option{-e} is portable, but it is not needed.  No
+valid Sed program can start with a dash, so it does not help
+disambiguating.  Its sole usefulness is helping enforcing indenting as
+in:
+
+@example
+sed -e @var{instruction-1} \
+    -e @var{instruction-2}
+@end example
+
+@noindent
+as opposed to
+
+@example
+sed @var{instruction-1};@var{instruction-2}
+@end example
+
+Contrary to yet another urban legend, you may portably use @samp{&} in
+the replacement part of the @code{s} command to mean ``what was
+matched''.
+
+
+@item @command{sed} (@samp{t})
+@c ---------------------------
+@cindex @command{sed} (@samp{t})
+Some old systems have @command{sed} that ``forget'' to reset their
+@samp{t} flag when starting a new cycle.  For instance on @sc{mips
+risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed}
+script (the line numbers are not actual part of the texts):
+
+@example
+s/keep me/kept/g  # a
+t end             # b
+s/.*/deleted/g    # c
+: end             # d
+@end example
+
+@noindent
+on
+
+@example
+delete me         # 1
+delete me         # 2
+keep me           # 3
+delete me         # 4
+@end example
+
+@noindent
+you get
+
+@example
+deleted
+delete me
+kept
+deleted
+@end example
+
+@noindent
+instead of
+
+@example
+deleted
+deleted
+kept
+deleted
+@end example
+
+Why? When processing 1, a matches, therefore sets the t flag, b jumps to
+d, and the output is produced.  When processing line 2, the t flag is
+still set (this is the bug).  Line a fails to match, but @command{sed}
+is not supposed to clear the t flag when a substitution fails.  Line b
+sees that the flag is set, therefore it clears it, and jumps to d, hence
+you get @samp{delete me} instead of @samp{deleted}.  When processing 3 t
+is clear, a matches, so the flag is set, hence b clears the flags and
+jumps.  Finally, since the flag is clear, 4 is processed properly.
+
+There are two things one should remind about @samp{t} in @command{sed}.
+Firstly, always remember that @samp{t} jumps if @emph{some} substitution
+succeeded, not only the immediately preceding substitution, therefore,
+always use a fake @samp{t clear; : clear} to reset the t flag where
+indeed.
+
+Secondly, you cannot rely on @command{sed} to clear the flag at each new
+cycle.
+
+One portable implementation of the script above is:
+
+@example
+t clear
+: clear
+s/keep me/kept/g
+t end
+s/.*/deleted/g
+: end
+@end example
+
+@item @command{touch}
+@c ------------------
+@cindex @command{touch}
+On some old @sc{bsd} systems, @command{touch} or any command that
+results in an empty file does not update the timestamps, so use a
+command like @code{echo} as a workaround.
+
+GNU @command{touch} 3.16r (and presumably all before that) fails to work
+on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume.
+
+@end table
+
+
+@node Limitations of Make,  , Limitations of Usual Tools, Portable Shell
+@section Limitations of Make
+
+Make itself suffers a great number of limitations, only a few of which
+being listed here.  First of all, remember that since commands are
+executed by the shell, all its weaknesses are inherited@dots{}
+
+@table @asis
+@item Leading underscore in macro names
+Some Make don't support leading underscores in macro names, such as on
+NEWS-OS 4.2R.
+
+@example
+$ cat Makefile
+_am_include = #
+_am_quote =
+all:; @@echo this is test
+
+% make
+Make: Must be a separator on rules line 2.  Stop.
+
+$ cat Makefile2
+am_include = #
+am_quote =
+all:; @@echo this is test
+
+$ make -f Makefile2
+this is test
+@end example
+
+@item @code{VPATH}
+@cindex @code{VPATH}
+Don't use it!  For instance any assignment to @code{VPATH} causes Sun
+@command{make} to only execute the first set of double-colon rules.
+@end table
+
+
+
+
+@c ================================================== Manual Configuration
+
+@node Manual Configuration, Site Configuration, Portable Shell, Top
+@chapter Manual Configuration
+
+A few kinds of features can't be guessed automatically by running test
+programs.  For example, the details of the object-file format, or
+special options that need to be passed to the compiler or linker.  You
+can check for such features using ad-hoc means, such as having
+@code{configure} check the output of the @code{uname} program, or
+looking for libraries that are unique to particular systems.  However,
+Autoconf provides a uniform method for handling unguessable features.
+
+@menu
+* Specifying Names::            Specifying the system type
+* Canonicalizing::              Getting the canonical system type
+* Using System Type::           What to do with the system type
+@end menu
+
+@node Specifying Names, Canonicalizing, Manual Configuration, Manual Configuration
+@section Specifying the System Type
+
+Like other @sc{gnu} @code{configure} scripts, Autoconf-generated
+@code{configure} scripts can make decisions based on a canonical name
+for the system type, which has the form:
+@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
+@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
+
+@code{configure} can usually guess the canonical name for the type of
+system it's running on.  To do so it runs a script called
+@code{config.guess}, which infers the name using the @code{uname}
+command or symbols predefined by the C preprocessor.
+
+Alternately, the user can specify the system type with command line
+arguments to @code{configure}.  Doing so is necessary when
+cross-compiling.  In the most complex case of cross-compiling, three
+system types are involved.  The options to specify them are@footnote{For
+backward compatibility, @code{configure} will accept a system type as an
+option by itself.  Such an option will override the defaults for build,
+host and target system types.  The following configure statement will
+configure a cross toolchain that will run on NetBSD/alpha but generate
+code for GNU Hurd/sparc, which is also the build platform.
+
+@example
+./configure --host=alpha-netbsd sparc-gnu
+@end example
+}:
+
+@table @option
+@item --build=@var{build-type}
+the type of system on which the package is being configured and
+compiled.
+
+@item --host=@var{host-type}
+@ovindex cross_compiling
+the type of system on which the package will run.
+
+@item --target=@var{target-type}
+the type of system for which any compiler tools in the package will
+produce code (rarely needed).  By default, it is the same as host.
+@end table
+
+They all default to the result of running @code{config.guess}, unless
+you specify either @option{--build} or @option{--host}.  In this case, the
+default becomes the system type you specified.  If you specify both, and
+they're different, @code{configure} will enter cross compilation mode,
+so it won't run any tests that require execution.
+
+Hint: if you mean to override the result of @code{config.guess}, prefer
+@option{--build} over @option{--host}.  In the future, @option{--host} will
+not override the name of the build system type.  Also, if you specify
+@option{--host}, but not @option{--build}, when @code{configure} performs
+the first compiler test it will try to run an executable produced by the
+compiler.  If the execution fails, it will enter cross-compilation mode.
+Note, however, that it won't guess the build-system type, since this may
+require running test programs.  Moreover, by the time the compiler test
+is performed, it may be too late to modify the build-system type: other
+tests may have already been performed.  Therefore, whenever you specify
+@code{--host}, be sure to specify @code{--build} too.
+
+@example
+./configure --build=i686-pc-linux-gnu --host=m68k-coff
+@end example
+
+@noindent
+will enter cross-compilation mode, but @code{configure} will fail if it
+can't run the code generated by the specified compiler if you configure
+as follows:
+
+@example
+./configure CC=m68k-coff-gcc
+@end example
+
+@code{configure} recognizes short aliases for many system types; for
+example, @samp{decstation} can be used instead of
+@samp{mips-dec-ultrix4.2}.  @code{configure} runs a script called
+@code{config.sub} to canonicalize system type aliases.
+
+
+
+@node Canonicalizing, Using System Type, Specifying Names, Manual Configuration
+@section Getting the Canonical System Type
+
+The following macros make the system type available to @code{configure}
+scripts.
+
+@ovindex build_alias
+@ovindex host_alias
+@ovindex target_alias
+
+The variables @samp{build_alias}, @samp{host_alias}, and
+@samp{target_alias} are always exactly the arguments of @option{--build},
+@option{--host}, and @option{--target}; in particular, they are left empty
+if the user did not use them, even if the corresponding
+@code{AC_CANONICAL} macro was run.  Any configure script may use these
+variables anywhere.  These are the variables that should be used when in
+interaction with the user.
+
+If you need to recognize some special environments based on their system
+type, run the following macros to get canonical system names.  These
+variables are not set before the macro call.
+
+If you use these macros, you must distribute @code{config.guess} and
+@code{config.sub} along with your source code.  @xref{Output}, for
+information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
+to control in which directory @code{configure} looks for those scripts.
+
+
+@defmac AC_CANONICAL_BUILD
+@maindex CANONICAL_BUILD
+@ovindex build
+@ovindex build_cpu
+@ovindex build_vendor
+@ovindex build_os
+Compute the canonical build-system type variable, @code{build}, and its
+three individual parts @code{build_cpu}, @code{build_vendor}, and
+@code{build_os}.
+
+If @option{--build} was specified, then @code{build} is the
+canonicalization of @code{build_alias} by @command{config.sub},
+otherwise it is determined by the shell script @code{config.guess}.
+@end defmac
+
+@defmac AC_CANONICAL_HOST
+@maindex CANONICAL_HOST
+@ovindex host
+@ovindex host_cpu
+@ovindex host_vendor
+@ovindex host_os
+Compute the canonical host-system type variable, @code{host}, and its
+three individual parts @code{host_cpu}, @code{host_vendor}, and
+@code{host_os}.
+
+If @option{--host} was specified, then @code{host} is the
+canonicalization of @code{host_alias} by @command{config.sub},
+otherwise it defaults to @code{build}.
+
+For temporary backward-compatibility, when @option{--host} is specified
+by @option{--build} isn't, the build system will be assumed to be the
+same as @option{--host}, and @samp{build_alias} will be set to that
+value.  Eventually, this historically incorrect behavior will go away.
+
+@end defmac
+
+@defmac AC_CANONICAL_TARGET
+@maindex CANONICAL_TARGET
+@ovindex target
+@ovindex target_cpu
+@ovindex target_vendor
+@ovindex target_os
+Compute the canonical target-system type variable, @code{target}, and its
+three individual parts @code{target_cpu}, @code{target_vendor}, and
+@code{target_os}.
+
+If @option{--target} was specified, then @code{target} is the
+canonicalization of @code{target_alias} by @command{config.sub},
+otherwise it defaults to @code{host}.
+@end defmac
+
+
+@node Using System Type,  , Canonicalizing, Manual Configuration
+@section Using the System Type
+
+How do you use a canonical system type?  Usually, you use it in one or
+more @code{case} statements in @file{configure.ac} to select
+system-specific C files.  Then, using @code{AC_CONFIG_LINKS}, link those
+files which have names based on the system name, to generic names, such
+as @file{host.h} or @file{target.c} (@pxref{Configuration Links}).  The
+@code{case} statement patterns can use shell wild cards to group several
+cases together, like in this fragment:
+
+@example
+case "$target" in
+i386-*-mach* | i386-*-gnu*)
+             obj_format=aout emulation=mach bfd_gas=yes ;;
+i960-*-bout) obj_format=bout ;;
+esac
+@end example
+
+@noindent
+and in @file{configure.ac}, use:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+
+You can also use the host system type to find cross-compilation tools.
+@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL}
+macro which does that.
+
+
+@c ===================================================== Site Configuration.
+
+@node Site Configuration, Running configure scripts, Manual Configuration, Top
+@chapter Site Configuration
+
+@code{configure} scripts support several kinds of local configuration
+decisions.  There are ways for users to specify where external software
+packages are, include or exclude optional features, install programs
+under modified names, and set default values for @code{configure}
+options.
+
+@menu
+* External Software::           Working with other optional software
+* Package Options::             Selecting optional features
+* Pretty Help Strings::         Formatting help string
+* Site Details::                Configuring site details
+* Transforming Names::          Changing program names when installing
+* Site Defaults::               Giving @code{configure} local defaults
+@end menu
+
+@node External Software, Package Options, Site Configuration, Site Configuration
+@section Working With External Software
+
+Some packages require, or can optionally use, other software packages
+that are already installed.  The user can give @code{configure}
+command line options to specify which such external software to use.
+The options have one of these forms:
+
+@example
+--with-@var{package}=@ovar{arg}
+--without-@var{package}
+@end example
+
+For example, @option{--with-gnu-ld} means work with the @sc{gnu} linker
+instead of some other linker.  @option{--with-x} means work with The X
+Window System.
+
+The user can give an argument by following the package name with
+@samp{=} and the argument.  Giving an argument of @samp{no} is for
+packages that are used by default; it says to @emph{not} use the
+package.  An argument that is neither @samp{yes} nor @samp{no} could
+include a name or number of a version of the other package, to specify
+more precisely which other package this program is supposed to work
+with.  If no argument is given, it defaults to @samp{yes}.
+@option{--without-@var{package}} is equivalent to
+@option{--with-@var{package}=no}.
+
+@code{configure} scripts do not complain about
+@option{--with-@var{package}} options that they do not support.  This
+behavior permits configuring a source tree containing multiple packages
+with a top-level @code{configure} script when the packages support
+different options, without spurious error messages about options that
+some of the packages support.  An unfortunate side effect is that option
+spelling errors are not diagnosed.  No better approach to this problem
+has been suggested so far.
+
+For each external software package that may be used, @file{configure.ac}
+should call @code{AC_ARG_WITH} to detect whether the @code{configure}
+user asked to use it.  Whether each package is used or not by default,
+and which arguments are valid, is up to you.
+
+@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
+@maindex ARG_WITH
+If the user gave @code{configure} the option @option{--with-@var{package}}
+or @option{--without-@var{package}}, run shell commands
+@var{action-if-given}.  If neither option was given, run shell commands
+@var{action-if-not-given}.  The name @var{package} indicates another
+software package that this program should work with.  It should consist
+only of alphanumeric characters and dashes.
+
+The option's argument is available to the shell commands
+@var{action-if-given} in the shell variable @code{withval}, which is
+actually just the value of the shell variable @code{with_@var{package}},
+with any @option{-} characters changed into @samp{_}.  You may use that
+variable instead, if you wish.
+
+The argument @var{help-string} is a description of the option that
+looks like this:
+@example
+  --with-readline         support fancy command line editing
+@end example
+
+@noindent
+@var{help-string} may be more than one line long, if more detail is
+needed.  Just make sure the columns line up in @samp{configure --help}.
+Avoid tabs in the help string.  You'll need to enclose it in @samp{[}
+and @samp{]} in order to produce the leading spaces.
+
+You should format your @var{help-string} with the macro
+@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
+@end defmac
+
+@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
+@maindex WITH
+This is an obsolete version of @code{AC_ARG_WITH} that does not
+support providing a help string.
+@end defmac
+
+@node Package Options, Pretty Help Strings, External Software, Site Configuration
+@section Choosing Package Options
+
+If a software package has optional compile-time features, the user can
+give @code{configure} command line options to specify whether to
+compile them.  The options have one of these forms:
+
+@example
+--enable-@var{feature}=@ovar{arg}
+--disable-@var{feature}
+@end example
+
+These options allow users to choose which optional features to build and
+install.  @option{--enable-@var{feature}} options should never make a
+feature behave differently or cause one feature to replace another.
+They should only cause parts of the program to be built rather than left
+out.
+
+The user can give an argument by following the feature name with
+@samp{=} and the argument.  Giving an argument of @samp{no} requests
+that the feature @emph{not} be made available.  A feature with an
+argument looks like @option{--enable-debug=stabs}.  If no argument is
+given, it defaults to @samp{yes}.  @option{--disable-@var{feature}} is
+equivalent to @option{--enable-@var{feature}=no}.
+
+@code{configure} scripts do not complain about
+@option{--enable-@var{feature}} options that they do not support.
+This behavior permits configuring a source tree containing multiple
+packages with a top-level @code{configure} script when the packages
+support different options, without spurious error messages about options
+that some of the packages support.
+An unfortunate side effect is that option spelling errors are not diagnosed.
+No better approach to this problem has been suggested so far.
+
+For each optional feature, @file{configure.ac} should call
+@code{AC_ARG_ENABLE} to detect whether the @code{configure} user asked
+to include it.  Whether each feature is included or not by default, and
+which arguments are valid, is up to you.
+
+@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
+@maindex ARG_ENABLE
+If the user gave @code{configure} the option
+@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
+shell commands @var{action-if-given}.  If neither option was given, run
+shell commands @var{action-if-not-given}.  The name @var{feature}
+indicates an optional user-level facility.  It should consist only of
+alphanumeric characters and dashes.
+
+The option's argument is available to the shell commands
+@var{action-if-given} in the shell variable @code{enableval}, which is
+actually just the value of the shell variable
+@code{enable_@var{feature}}, with any @option{-} characters changed into
+@samp{_}.  You may use that variable instead, if you wish.  The
+@var{help-string} argument is like that of @code{AC_ARG_WITH}
+(@pxref{External Software}).
+
+You should format your @var{help-string} with the macro
+@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
+@end defmac
+
+@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
+@maindex ENABLE
+This is an obsolete version of @code{AC_ARG_ENABLE} that does not
+support providing a help string.
+@end defmac
+
+
+@node Pretty Help Strings, Site Details, Package Options, Site Configuration
+@section Making Your Help Strings Look Pretty
+
+Properly formatting the @samp{help strings} which are used in
+@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
+(@pxref{Package Options}) can be challenging.  Specifically, you want
+your own @samp{help strings} to line up in the appropriate columns of
+@samp{configure --help} just like the standard Autoconf @samp{help
+strings} do.  This is the purpose of the @code{AC_HELP_STRING} macro.
+
+@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
+@maindex HELP_STRING
+
+Expands into an help string that looks pretty when the user executes
+@samp{configure --help}.  It is typically used in @code{AC_ARG_WITH}
+(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
+Options}).  The following example will make this clearer.
+
+@example
+AC_DEFUN(TEST_MACRO,
+[AC_ARG_WITH(foo,
+             AC_HELP_STRING([--with-foo],
+                            [use foo (default is NO)]),
+             ac_cv_use_foo=$withval, ac_cv_use_foo=no),
+AC_CACHE_CHECK(whether to use foo,
+               ac_cv_use_foo, ac_cv_use_foo=no)])
+@end example
+
+Please note that the call to @code{AC_HELP_STRING} is @strong{unquoted}.
+Then the last few lines of @samp{configure --help} will appear like
+this:
+
+@example
+--enable and --with options recognized:
+  --with-foo              use foo (default is NO)
+@end example
+
+The @code{AC_HELP_STRING} macro is particularly helpful when the
+@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
+arguments, as shown in the following example.
+
+@example
+AC_DEFUN(MY_ARG_WITH,
+[AC_ARG_WITH([$1],
+             AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
+             ac_cv_use_$1=$withval, ac_cv_use_$1=no),
+AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
+@end example
+@end defmac
+
+
+@node Site Details, Transforming Names, Pretty Help Strings, Site Configuration
+@section Configuring Site Details
+
+Some software packages require complex site-specific information.  Some
+examples are host names to use for certain services, company names, and
+email addresses to contact.  Since some configuration scripts generated
+by Metaconfig ask for such information interactively, people sometimes
+wonder how to get that information in Autoconf-generated configuration
+scripts, which aren't interactive.
+
+Such site configuration information should be put in a file that is
+edited @emph{only by users}, not by programs.  The location of the file
+can either be based on the @code{prefix} variable, or be a standard
+location such as the user's home directory.  It could even be specified
+by an environment variable.  The programs should examine that file at
+run time, rather than at compile time.  Run time configuration is more
+convenient for users and makes the configuration process simpler than
+getting the information while configuring.  @xref{Directory Variables,,
+Variables for Installation Directories, standards, GNU Coding
+Standards}, for more information on where to put data files.
+
+@node Transforming Names, Site Defaults, Site Details, Site Configuration
+@section Transforming Program Names When Installing
+
+Autoconf supports changing the names of programs when installing them.
+In order to use these transformations, @file{configure.ac} must call the
+macro @code{AC_ARG_PROGRAM}.
+
+@defmac AC_ARG_PROGRAM
+@maindex ARG_PROGRAM
+@ovindex program_transform_name
+Place in output variable @code{program_transform_name} a sequence of
+@code{sed} commands for changing the names of installed programs.
+
+If any of the options described below are given to @code{configure},
+program names are transformed accordingly.  Otherwise, if
+@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
+is given that differs from the host type (specified with @option{--host}),
+the target type followed by a dash is used as a prefix.  Otherwise, no
+program name transformation is done.
+@end defmac
+
+@menu
+* Transformation Options::      @code{configure} options to transform names
+* Transformation Examples::     Sample uses of transforming names
+* Transformation Rules::        @file{Makefile} uses of transforming names
+@end menu
+
+@node Transformation Options, Transformation Examples, Transforming Names, Transforming Names
+@subsection Transformation Options
+
+You can specify name transformations by giving @code{configure} these
+command line options:
+
+@table @option
+@item --program-prefix=@var{prefix}
+prepend @var{prefix} to the names;
+
+@item --program-suffix=@var{suffix}
+append @var{suffix} to the names;
+
+@item --program-transform-name=@var{expression}
+perform @code{sed} substitution @var{expression} on the names.
+@end table
+
+@node Transformation Examples, Transformation Rules, Transformation Options, Transforming Names
+@subsection Transformation Examples
+
+These transformations are useful with programs that can be part of a
+cross-compilation development environment.  For example, a
+cross-assembler running on a Sun 4 configured with
+@option{--target=i960-vxworks} is normally installed as
+@file{i960-vxworks-as}, rather than @file{as}, which could be confused
+with a native Sun 4 assembler.
+
+You can force a program name to begin with @file{g}, if you don't want
+@sc{gnu} programs installed on your system to shadow other programs with
+the same name.  For example, if you configure @sc{gnu} @code{diff} with
+@option{--program-prefix=g}, then when you run @samp{make install} it is
+installed as @file{/usr/local/bin/gdiff}.
+
+As a more sophisticated example, you could use
+
+@example
+--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
+@end example
+@noindent
+
+to prepend @samp{g} to most of the program names in a source tree,
+excepting those like @code{gdb} that already have one and those like
+@code{less} and @code{lesskey} that aren't @sc{gnu} programs.  (That is
+assuming that you have a source tree containing those programs that is
+set up to use this feature.)
+
+One way to install multiple versions of some programs simultaneously is
+to append a version number to the name of one or both.  For example, if
+you want to keep Autoconf version 1 around for awhile, you can configure
+Autoconf version 2 using @option{--program-suffix=2} to install the
+programs as @file{/usr/local/bin/autoconf2},
+@file{/usr/local/bin/autoheader2}, etc.  Nevertheless, pay attention
+that only the binaries are renamed, therefore you'd have problems with
+the library files which might overlap.
+
+@node Transformation Rules,  , Transformation Examples, Transforming Names
+@subsection Transformation Rules
+
+Here is how to use the variable @code{program_transform_name} in a
+@file{Makefile.in}:
+
+@example
+transform = @@program_transform_name@@
+install: all
+        $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \
+                                               sed '$(transform)'`
+
+uninstall:
+        rm -f $(bindir)/`echo myprog | sed '$(transform)'`
+@end example
+
+@noindent
+If you have more than one program to install, you can do it in a loop:
+
+@example
+PROGRAMS = cp ls rm
+install:
+        for p in $(PROGRAMS); do \
+          $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p | \
+                                              sed '$(transform)'`; \
+        done
+
+uninstall:
+        for p in $(PROGRAMS); do \
+          rm -f $(bindir)/`echo $$p | sed '$(transform)'`; \
+        done
+@end example
+
+It is guaranteed that @code{program_transform_name} is never empty, and
+that there are no useless separators.  Therefore you may safely embed
+@code{program_transform_name} within a sed program using @samp{;}:
+
+@example
+transform = @@program_transform_name@@
+transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
+@end example
+
+Whether to do the transformations on documentation files (Texinfo or
+@code{man}) is a tricky question; there seems to be no perfect answer,
+due to the several reasons for name transforming.  Documentation is not
+usually particular to a specific architecture, and Texinfo files do not
+conflict with system documentation.  But they might conflict with
+earlier versions of the same files, and @code{man} pages sometimes do
+conflict with system documentation.  As a compromise, it is probably
+best to do name transformations on @code{man} pages but not on Texinfo
+manuals.
+
+@node Site Defaults,  , Transforming Names, Site Configuration
+@section Setting Site Defaults
+
+Autoconf-generated @code{configure} scripts allow your site to provide
+default values for some configuration values.  You do this by creating
+site- and system-wide initialization files.
+
+@evindex CONFIG_SITE
+If the environment variable @code{CONFIG_SITE} is set, @code{configure}
+uses its value as the name of a shell script to read.  Otherwise, it
+reads the shell script @file{@var{prefix}/share/config.site} if it exists,
+then @file{@var{prefix}/etc/config.site} if it exists.  Thus,
+settings in machine-specific files override those in machine-independent
+ones in case of conflict.
+
+Site files can be arbitrary shell scripts, but only certain kinds of
+code are really appropriate to be in them.  Because @code{configure}
+reads any cache file after it has read any site files, a site file can
+define a default cache file to be shared between all Autoconf-generated
+@code{configure} scripts run on that system (@pxref{Cache Files}).  If
+you set a default cache file in a site file, it is a good idea to also
+set the output variable @code{CC} in that site file, because the cache
+file is only valid for a particular compiler, but many systems have
+several available.
+
+You can examine or override the value set by a command line option to
+@code{configure} in a site file; options set shell variables that have
+the same names as the options, with any dashes turned into underscores.
+The exceptions are that @option{--without-} and @option{--disable-} options
+are like giving the corresponding @option{--with-} or @option{--enable-}
+option and the value @samp{no}.  Thus, @option{--cache-file=localcache}
+sets the variable @code{cache_file} to the value @samp{localcache};
+@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
+@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
+variable @code{prefix} to the value @samp{/usr}; etc.
+
+Site files are also good places to set default values for other output
+variables, such as @code{CFLAGS}, if you need to give them non-default
+values: anything you would normally do, repetitively, on the command
+line.  If you use non-default values for @var{prefix} or
+@var{exec_prefix} (wherever you locate the site file), you can set them
+in the site file if you specify it with the @code{CONFIG_SITE}
+environment variable.
+
+You can set some cache values in the site file itself.  Doing this is
+useful if you are cross-compiling, so it is impossible to check features
+that require running a test program.  You could ``prime the cache'' by
+setting those values correctly for that system in
+@file{@var{prefix}/etc/config.site}.  To find out the names of the cache
+variables you need to set, look for shell variables with @samp{_cv_} in
+their names in the affected @code{configure} scripts, or in the Autoconf
+M4 source code for those macros.
+
+The cache file is careful to not override any variables set in the site
+files.  Similarly, you should not override command-line options in the
+site files.  Your code should check that variables such as @code{prefix}
+and @code{cache_file} have their default values (as set near the top of
+@code{configure}) before changing them.
+
+Here is a sample file @file{/usr/share/local/gnu/share/config.site}.  The
+command @samp{configure --prefix=/usr/share/local/gnu} would read this
+file (if @code{CONFIG_SITE} is not set to a different file).
+
+@example
+# config.site for configure
+#
+# Change some defaults.
+test "$prefix" = NONE && prefix=/usr/share/local/gnu
+test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
+test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
+test "$localstatedir" = '$prefix/var' && localstatedir=/var
+
+# Give Autoconf 2.x generated configure scripts a shared default
+# cache file for feature test results, architecture-specific.
+if test "$cache_file" = /dev/null; then
+  cache_file="$prefix/var/config.cache"
+  # A cache file is only valid for one C compiler.
+  CC=gcc
+fi
+@end example
+
+
+@c ============================================== Running configure Scripts.
+
+@node Running configure scripts, config.status Invocation, Site Configuration, Top
+@chapter Running @code{configure} Scripts
+@cindex @code{configure}
+
+Below are instructions on how to configure a package that uses a
+@code{configure} script, suitable for inclusion as an @file{INSTALL}
+file in the package.  A plain-text version of @file{INSTALL} which you
+may use comes with Autoconf.
+
+@menu
+* Basic Installation::          Instructions for typical cases
+* Compilers and Options::       Selecting compilers and optimization
+* Multiple Architectures::      Compiling for multiple architectures at once
+* Installation Names::          Installing in different directories
+* Optional Features::           Selecting optional features
+* System Type::                 Specifying the system type
+* Sharing Defaults::            Setting site-wide defaults for @code{configure}
+* Environment Variables::       Defining environment variables.
+* configure Invocation::        Changing how @code{configure} runs
+@end menu
+
+@include install.texi
+
+
+@c ============================================== Recreating a Configuration
+
+@node config.status Invocation, Obsolete Constructs, Running configure scripts, Top
+@chapter Recreating a Configuration
+@cindex @code{config.status}
+
+The @code{configure} script creates a file named @file{config.status},
+which actually configures, @dfn{instantiates}, the template files.  It
+also records the configuration options that were specified when the
+package was last configured in case reconfiguring is needed.
+
+Synopsis:
+@example
+./config.status @var{option}@dots{} [@var{file}@dots{}]
+@end example
+
+It configures the @var{files}, if none are specified, all the templates
+are instantiated.  The files must be specified without their
+dependencies, as in
+
+@example
+./config.status foobar
+@end example
+
+@noindent
+not
+
+@example
+./config.status foobar:foo.in:bar.in
+@end example
+
+The supported @var{option}s are:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options, the list of the template
+files and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --file=@var{file}[:@var{template}]
+Require that @var{file} be instantiated as if
+@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used.  Both
+@var{file} and @var{template} may be @samp{-} in which case the standard
+output and/or standard input, respectively, is used.  If a
+@var{template} filename is relative, it is first looked for in the build
+tree, and then in the source tree. @xref{Configuration Actions}, for
+more details.
+
+This option and the following ones provide one way for separately
+distributed packages to share the values computed by @code{configure}.
+Doing so can be useful if some of the packages need a superset of the
+features that one of them, perhaps a common library, does.  These
+options allow a @file{config.status} file to create files other than the
+ones that its @file{configure.ac} specifies, so it can be used for a
+different package.
+
+@item --header=@var{file}[:@var{template}]
+Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
+
+@item --recheck
+Ask @file{config.status} to update itself and exit (no instantiation).
+This option is useful if you change @code{configure}, so that the
+results of some tests might be different from the previous run.  The
+@option{--recheck} option re-runs @code{configure} with the same arguments
+you used before, plus the @option{--no-create} option, which prevents
+@code{configure} from running @file{config.status} and creating
+@file{Makefile} and other files, and the @option{--no-recursion} option,
+which prevents @code{configure} from running other @code{configure}
+scripts in subdirectories.  (This is so other @file{Makefile} rules can
+run @file{config.status} when it changes; @pxref{Automatic Remaking},
+for an example).
+@end table
+
+@file{config.status} checks several optional environment variables that
+can alter its behavior:
+
+@defvar CONFIG_SHELL
+@evindex CONFIG_SHELL
+The shell with which to run @code{configure} for the @option{--recheck}
+option.  It must be Bourne-compatible.  The default is @file{/bin/sh}.
+@end defvar
+
+@defvar CONFIG_STATUS
+@evindex CONFIG_STATUS
+The file name to use for the shell script that records the
+configuration.  The default is @file{./config.status}.  This variable is
+useful when one package uses parts of another and the @code{configure}
+scripts shouldn't be merged because they are maintained separately.
+@end defvar
+
+You can use @file{./config.status} in your Makefiles.  For example, in
+the dependencies given above (@pxref{Automatic Remaking}),
+@file{config.status} is run twice when @file{configure.ac} has changed.
+If that bothers you, you can make each run only regenerate the files for
+that rule:
+@example
+@group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        ./config.status config.h
+        echo > stamp-h
+
+Makefile: Makefile.in config.status
+        ./config.status Makefile
+@end group
+@end example
+
+The calling convention of @file{config.status} has changed, see
+@ref{Obsolete config.status Use}, for details.
+
+
+@c =================================================== Obsolete Constructs
+
+@node Obsolete Constructs, Questions, config.status Invocation, Top
+@chapter Obsolete Constructs
+
+Autoconf changes, and throughout the years some constructs are obsoleted.
+Most of the changes involve the macros, but the tools themselves, or
+even some concepts, are now considered obsolete.
+
+You may completely skip this chapter if you are new to Autoconf, its
+intention is mainly to help maintainers updating their packages by
+understanding how to move to more modern constructs.
+
+@menu
+* Obsolete config.status Use::  Different calling convention
+* acconfig.h::                  Additional entries in @file{config.h.in}
+* autoupdate Invocation::       Automatic update of @file{configure.ac}
+* Obsolete Macros::             Backward compatibility macros
+* Autoconf 1::                  Tips for upgrading your files
+* Autoconf 2.13::               Some fresher tips
+@end menu
+
+@node Obsolete config.status Use, acconfig.h, Obsolete Constructs, Obsolete Constructs
+@section Obsolete @file{config.status} Invocation
+
+@file{config.status} now supports arguments to specify the files to
+instantiate, see @ref{config.status Invocation}, for more details.
+Before, environment variables had to be used.
+
+@defvar CONFIG_COMMANDS
+@evindex CONFIG_COMMANDS
+The tags of the commands to execute.  The default is the arguments given
+to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
+@file{configure.ac}.
+@end defvar
+
+@defvar CONFIG_FILES
+@evindex CONFIG_FILES
+The files in which to perform @samp{@@@var{variable}@@} substitutions.
+The default is the arguments given to @code{AC_OUTPUT} and
+@code{AC_CONFIG_FILES} in @file{configure.ac}.
+@end defvar
+
+@defvar CONFIG_HEADERS
+@evindex CONFIG_HEADERS
+The files in which to substitute C @code{#define} statements.  The
+default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
+macro was not called, @file{config.status} ignores this variable.
+@end defvar
+
+@defvar CONFIG_LINKS
+@evindex CONFIG_LINKS
+The symbolic links to establish.  The default is the arguments given to
+@code{AC_CONFIG_LINKS}; if that macro was not called,
+@file{config.status} ignores this variable.
+@end defvar
+
+In @ref{config.status Invocation}, using this old interface, the example
+would be:
+
+@example
+@group
+config.h: stamp-h
+stamp-h: config.h.in config.status
+        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
+          CONFIG_HEADERS=config.h ./config.status
+        echo > stamp-h
+
+Makefile: Makefile.in config.status
+        CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
+          CONFIG_FILES=Makefile ./config.status
+@end group
+@end example
+
+@noindent
+(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
+no need to set @code{CONFIG_HEADERS} in the @code{make} rules, equally
+for @code{CONFIG_COMMANDS} etc.)
+
+
+@node acconfig.h, autoupdate Invocation, Obsolete config.status Use, Obsolete Constructs
+@section @file{acconfig.h}
+
+@cindex @file{acconfig.h}
+@cindex @file{config.h.top}
+@cindex @file{config.h.bot}
+
+In order to produce @file{config.h.in}, @command{autoheader} needs to
+build or to find templates for each symbol.  Modern releases of Autoconf
+use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
+Macros}), but in older releases a file, @file{acconfig.h}, contained the
+list of needed templates.  @code{autoheader} copies comments and
+@code{#define} and @code{#undef} statements from @file{acconfig.h} in
+the current directory, if present.  This file used to be mandatory if
+you @code{AC_DEFINE} any additional symbols.
+
+Modern releases of Autoconf also provide @code{AH_TOP} and
+@code{AH_BOTTOM} if you need to prepend/append some information to
+@file{config.h.in}.  Ancient versions of Autoconf had a similar feature:
+if @file{./acconfig.h} contains the string @samp{@@TOP@@},
+@code{autoheader} copies the lines before the line containing
+@samp{@@TOP@@} into the top of the file that it generates.  Similarly,
+if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
+@code{autoheader} copies the lines after that line to the end of the
+file it generates.  Either or both of those strings may be omitted.  An
+even older alternate way to produce the same effect in jurasik versions
+of Autoconf is to create the files @file{@var{file}.top} (typically
+@file{config.h.top}) and/or @file{@var{file}.bot} in the current
+directory.  If they exist, @code{autoheader} copies them to the
+beginning and end, respectively, of its output.
+
+In former versions of Autoconf, the files used in preparing a software
+package for distribution were:
+@example
+@group
+configure.ac --.   .------> autoconf* -----> configure
+               +---+
+[aclocal.m4] --+   `---.
+[acsite.m4] ---'       |
+                       +--> [autoheader*] -> [config.h.in]
+[acconfig.h] ----.     |
+                 +-----'
+[config.h.top] --+
+[config.h.bot] --'
+@end group
+@end example
+
+Use only the @code{AH_} macros, @file{configure.ac} should be
+self-contained, and should not depend upon @file{acconfig.h} etc.
+
+
+@node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs
+@section Using @code{autoupdate} to Modernize @file{configure.ac}
+@cindex @code{autoupdate}
+
+The @code{autoupdate} program updates a @file{configure.ac} file that
+calls Autoconf macros by their old names to use the current macro names.
+In version 2 of Autoconf, most of the macros were renamed to use a more
+uniform and descriptive naming scheme.  @xref{Macro Names}, for a
+description of the new scheme.  Although the old names still work
+(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
+new names), you can make your @file{configure.ac} files more readable
+and make it easier to use the current Autoconf documentation if you
+update them to use the new macro names.
+
+@evindex SIMPLE_BACKUP_SUFFIX
+If given no arguments, @code{autoupdate} updates @file{configure.ac},
+backing up the original version with the suffix @file{~} (or the value
+of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
+set).  If you give @code{autoupdate} an argument, it reads that file
+instead of @file{configure.ac} and writes the updated file to the
+standard output.
+
+@noindent
+@code{autoupdate} accepts the following options:
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the command line options and exit.
+
+@item --version
+@itemx -V
+Print the version number of Autoconf and exit.
+
+@item --verbose
+@itemx -v
+Report processing steps.
+
+@item --debug
+@itemx -d
+Don't remove the temporary files.
+
+@item --autoconf-dir=@var{dir}
+@itemx -A @var{dir}
+@evindex AC_MACRODIR
+Override the location where the installed Autoconf data files are looked
+for.  You can also set the @code{AC_MACRODIR} environment variable to a
+directory; this option overrides the environment variable.
+
+This option is rarely needed and dangerous; it is only used when one
+plays with different versions of Autoconf simultaneously.
+
+@item --localdir=@var{dir}
+@itemx -l @var{dir}
+Look for the package file @file{aclocal.m4} in directory @var{dir}
+instead of in the current directory.
+@end table
+
+@node Obsolete Macros, Autoconf 1, autoupdate Invocation, Obsolete Constructs
+@section Obsolete Macros
+
+Several macros are obsoleted in Autoconf, for various reasons (typically
+they failed to quote properly, couldn't be extended for more recent
+issues etc.).  They are still supported, but deprecated: their use
+should be avoided.
+
+During the jump from Autoconf version 1 to version 2, most of the
+macros were renamed to use a more uniform and descriptive naming scheme,
+but their signature did not change.  @xref{Macro Names}, for a
+description of the new naming scheme.  Below, there is just the mapping
+from old names to new names for these macros, the reader is invited to
+refer to the definition of the new macro for the signature and the
+description.
+
+@defmac AC_ALLOCA
+@maindex ALLOCA
+@code{AC_FUNC_ALLOCA}
+@end defmac
+
+@defmac AC_ARG_ARRAY
+@maindex ARG_ARRAY
+removed because of limited usefulness
+@end defmac
+
+@defmac AC_C_CROSS
+@maindex C_CROSS
+This macro is obsolete; it does nothing.
+@end defmac
+
+@defmac AC_CANONICAL_SYSTEM
+@maindex CANONICAL_SYSTEM
+Determine the system type and set output variables to the names of the
+canonical system types.  @xref{Canonicalizing}, for details about the
+variables this macro sets.
+
+The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
+@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
+the needs.  Using @code{AC_CANONICAL_TARGET} is enough to run the two
+other macros.
+@end defmac
+
+@defmac AC_CHAR_UNSIGNED
+@maindex CHAR_UNSIGNED
+@code{AC_C_CHAR_UNSIGNED}
+@end defmac
+
+@defmac AC_CHECK_TYPE (@var{type}, @var{default})
+@maindex CHECK_TYPE
+Autoconf, up to 2.13, used to provide this version of
+@code{AC_CHECK_TYPE}, deprecated because of its flaws.  Firstly, although
+it is a member of the @code{CHECK} clan, singular sub-family, it does
+more than just checking.  Second, missing types are not
+@code{typedef}'d, they are @code{#define}'d, which can lead to
+incompatible code in the case of pointer types.
+
+This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see
+@ref{Generic Types}, for the description of the current macro.
+
+If the type @var{type} is not defined, define it to be the C (or C++)
+builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}.
+
+This macro is equivalent to:
+
+@example
+AC_CHECK_TYPE([@var{type}],
+              [AC_DEFINE([@var{type}], [@var{default}],
+                         [Define to `@var{default}' if <sys/types.h>
+                          does not define.])])
+@end example
+
+In order to keep backward compatibility, the two versions of
+@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
+
+@enumerate
+@item
+If there are three or four arguments, the modern version is used.
+
+@item
+If the second argument appears to be a C or C++ type, then the
+obsolete version is used.  This happens if the argument is a C or C++
+@emph{builtin} type or a C identifier ending in @samp{_t}, optionally
+followed by one of @samp{[(* } and then by a string of zero or more
+characters taken from the set @samp{[]()* _a-zA-Z0-9}.
+
+@item
+If the second argument is spelled with the alphabet of valid C and C++
+types, the user is warned and the modern version is used.
+
+@item
+Otherwise, the modern version is used.
+@end enumerate
+
+@noindent
+You are encouraged either to use a valid builtin type, or to use the
+equivalent modern code (see above), or better yet, to use
+@code{AC_CHECK_TYPES} together with
+
+@example
+#if !HAVE_LOFF_T
+typedef loff_t off_t;
+#endif
+@end example
+@end defmac
+@c end of AC_CHECK_TYPE
+
+@defmac AC_CHECKING (@var{feature-description})
+@maindex CHECKING
+Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
+@end defmac
+
+@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
+@maindex COMPILE_CHECK
+This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining
+Libraries}), with the addition that it prints @samp{checking for
+@var{echo-text}} to the standard output first, if @var{echo-text} is
+non-empty.  Use @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead
+to print messages (@pxref{Printing Messages}).
+@end defmac
+
+@defmac AC_CONST
+@maindex CONST
+@code{AC_C_CONST}
+@end defmac
+
+@defmac AC_CROSS_CHECK
+@maindex CROSS_CHECK
+Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
+@code{:-)}.
+@end defmac
+
+@defmac AC_CYGWIN
+@maindex CYGWIN
+Check for the Cygwin environment in which case the shell variable
+@code{CYGWIN} is set to @samp{yes}.  Don't use this macro, the dignified
+means to check the nature of the host is using
+@code{AC_CANONICAL_HOST}.  As a matter of fact this macro is defined as:
+
+@example
+AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
+case $host_os in
+  *cygwin* ) CYGWIN=yes;;
+         * ) CYGWIN=no;;
+esac
+@end example
+
+Beware that the variable @code{CYGWIN} has a very special meaning when
+running CygWin32, and should not be changed.  That's yet another reason
+not to use this macro.
+@end defmac
+
+@defmac AC_DECL_YYTEXT
+@maindex DECL_YYTEXT
+Does nothing, now integrated in @code{AC_PROG_LEX}.
+@end defmac
+
+@defmac AC_DIR_HEADER
+@maindex DIR_HEADER
+@cvindex DIRENT
+@cvindex SYSNDIR
+@cvindex SYSDIR
+@cvindex NDIR
+Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
+but defines a different set of C preprocessor macros to indicate which
+header file is found:
+
+@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
+@item Header            @tab Old Symbol     @tab New Symbol
+@item @file{dirent.h}   @tab @code{DIRENT}  @tab @code{HAVE_DIRENT_H}
+@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
+@item @file{sys/dir.h}  @tab @code{SYSDIR}  @tab @code{HAVE_SYS_DIR_H}
+@item @file{ndir.h}     @tab @code{NDIR}    @tab @code{HAVE_NDIR_H}
+@end multitable
+@end defmac
+
+@defmac AC_DYNIX_SEQ
+@maindex DYNIX_SEQ
+If on Dynix/PTX (Sequent @sc{unix}), add @option{-lseq} to output variable
+@code{LIBS}.  This macro used to be defined as
+
+@example
+AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
+@end example
+
+@noindent
+now it is just @code{AC_FUNC_GETMNTENT}.
+@end defmac
+
+@defmac AC_EXEEXT
+@maindex EXEEXT
+@ovindex EXEEXT
+Defined the output variable @code{EXEEXT} based on the output of the
+compiler, which is now done automatically.  Typically set to empty
+string if Unix and @samp{.exe} if Win32 or OS/2.
+@end defmac
+
+@defmac AC_EMXOS2
+@maindex EMXOS2
+Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
+and sets @code{EMXOS2}.
+@end defmac
+
+@defmac AC_ERROR
+@maindex ERROR
+@code{AC_MSG_ERROR}
+@end defmac
+
+@defmac AC_FIND_X
+@maindex FIND_X
+@code{AC_PATH_X}
+@end defmac
+
+@defmac AC_FIND_XTRA
+@maindex FIND_XTRA
+@code{AC_PATH_XTRA}
+@end defmac
+
+@defmac AC_FUNC_CHECK
+@maindex FUNC_CHECK
+@code{AC_CHECK_FUNC}
+@end defmac
+
+@defmac AC_FUNC_WAIT3
+@maindex FUNC_WAIT3
+@cvindex HAVE_WAIT3
+If @code{wait3} is found and fills in the contents of its third argument
+(a @samp{struct rusage *}), which HP-UX does not do, define
+@code{HAVE_WAIT3}.
+
+These days portable programs should use @code{waitpid}, not
+@code{wait3}, as @code{wait3} is being removed from the Open Group
+standards, and will not appear in the next revision of POSIX.
+@end defmac
+
+@defmac AC_GCC_TRADITIONAL
+@maindex GCC_TRADITIONAL
+@code{AC_PROG_GCC_TRADITIONAL}
+@end defmac
+
+@defmac AC_GETGROUPS_T
+@maindex GETGROUPS_T
+@code{AC_TYPE_GETGROUPS}
+@end defmac
+
+@defmac AC_GETLOADAVG
+@maindex GETLOADAVG
+@code{AC_FUNC_GETLOADAVG}
+@end defmac
+
+@defmac AC_HAVE_FUNCS
+@maindex HAVE_FUNCS
+@code{AC_CHECK_FUNCS}
+@end defmac
+
+@defmac AC_HAVE_HEADERS
+@maindex HAVE_HEADERS
+@code{AC_CHECK_HEADERS}
+@end defmac
+
+@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
+@maindex HAVE_LIBRARY
+This macro is equivalent to calling @code{AC_CHECK_LIB} with a
+@var{function} argument of @code{main}.  In addition, @var{library} can
+be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}.  In
+all of those cases, the compiler is passed @option{-lfoo}.  However,
+@var{library} cannot be a shell variable; it must be a literal name.
+@end defmac
+
+@defmac AC_HAVE_POUNDBANG
+@maindex HAVE_POUNDBANG
+@code{AC_SYS_INTERPRETER} (different calling convention)
+@end defmac
+
+@defmac AC_HEADER_CHECK
+@maindex HEADER_CHECK
+@code{AC_CHECK_HEADER}
+@end defmac
+
+@defmac AC_HEADER_EGREP
+@maindex HEADER_EGREP
+@code{AC_EGREP_HEADER}
+@end defmac
+
+@defmac AC_INIT (@var{unique-file-in-source-dir})
+@maindex INIT
+Formerly @code{AC_INIT} used to have a single argument, and was
+equivalent to:
+
+@example
+AC_INIT
+AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
+@end example
+@end defmac
+
+@defmac AC_INLINE
+@maindex INLINE
+@code{AC_C_INLINE}
+@end defmac
+
+@defmac AC_INT_16_BITS
+@maindex INT_16_BITS
+@cvindex INT_16_BITS
+If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
+Use @samp{AC_CHECK_SIZEOF(int)} instead.
+@end defmac
+
+@defmac AC_IRIX_SUN
+@maindex IRIX_SUN
+If on IRIX (Silicon Graphics @sc{unix}), add @option{-lsun} to output
+@code{LIBS}.  If you were using it to get @code{getmntent}, use
+@code{AC_FUNC_GETMNTENT} instead.  If you used it for the NIS versions
+of the password and group functions, use @samp{AC_CHECK_LIB(sun,
+getpwnam)}.  Up to Autoconf 2.13, it used to be
+
+@example
+AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
+@end example
+
+@noindent
+now it is defined as
+
+@example
+AC_FUNC_GETMNTENT
+AC_CHECK_LIB(sun, getpwnam)
+@end example
+@end defmac
+
+@defmac AC_LANG_C
+@maindex LANG_C
+Same as @samp{AC_LANG(C)}.
+@end defmac
+
+@defmac AC_LANG_CPLUSPLUS
+@maindex LANG_CPLUSPLUS
+Same as @samp{AC_LANG(C++)}.
+@end defmac
+
+@defmac AC_LANG_FORTRAN77
+@maindex LANG_FORTRAN77
+Same as @samp{AC_LANG(Fortran 77)}.
+@end defmac
+
+@defmac AC_LANG_RESTORE
+@maindex LANG_RESTORE
+Select the @var{language} that is saved on the top of the stack, as set
+by @code{AC_LANG_SAVE}, remove it from the stack, and call
+@code{AC_LANG(@var{language})}.
+@end defmac
+
+@defmac AC_LANG_SAVE
+@maindex LANG_SAVE
+Remember the current language (as set by @code{AC_LANG}) on a stack.
+The current language does not change.  @code{AC_LANG_PUSH} is preferred.
+@end defmac
+
+@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
+@maindex LINK_FILES
+This is an obsolete version of @code{AC_CONFIG_LINKS}.  An updated
+version of:
+
+@example
+AC_LINK_FILES(config/$machine.h config/$obj_format.h,
+              host.h            object.h)
+@end example
+
+@noindent
+is:
+
+@example
+AC_CONFIG_LINKS(host.h:config/$machine.h
+                object.h:config/$obj_format.h)
+@end example
+@end defmac
+
+@defmac AC_LN_S
+@maindex LN_S
+@code{AC_PROG_LN_S}
+@end defmac
+
+@defmac AC_LONG_64_BITS
+@maindex LONG_64_BITS
+@cvindex LONG_64_BITS
+Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
+Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
+@end defmac
+
+@defmac AC_LONG_DOUBLE
+@maindex LONG_DOUBLE
+@code{AC_C_LONG_DOUBLE}
+@end defmac
+
+@defmac AC_LONG_FILE_NAMES
+@maindex LONG_FILE_NAMES
+@code{AC_SYS_LONG_FILE_NAMES}
+@end defmac
+
+@defmac AC_MAJOR_HEADER
+@maindex MAJOR_HEADER
+@code{AC_HEADER_MAJOR}
+@end defmac
+
+@defmac AC_MEMORY_H
+@maindex MEMORY_H
+@cvindex NEED_MEMORY_H
+Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
+defined in @file{memory.h}.  Today it is equivalent to
+@samp{AC_CHECK_HEADERS(memory.h)}.  Adjust your code to depend upon
+@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @xref{Standard
+Symbols}.
+@end defmac
+
+@defmac AC_MINGW32
+@maindex MINGW32
+Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
+environment and sets @code{MINGW32}.
+@end defmac
+
+@defmac AC_MINUS_C_MINUS_O
+@maindex MINUS_C_MINUS_O
+@code{AC_PROG_CC_C_O}
+@end defmac
+
+@defmac AC_MMAP
+@maindex MMAP
+@code{AC_FUNC_MMAP}
+@end defmac
+
+@defmac AC_MODE_T
+@maindex MODE_T
+@code{AC_TYPE_MODE_T}
+@end defmac
+
+@defmac AC_OBJEXT
+@maindex OBJEXT
+@ovindex OBJEXT
+Defined the output variable @code{OBJEXT} based on the output of the
+compiler, after .c files have been excluded.  Typically set to @samp{o}
+if Unix, @samp{obj} if Win32.  Now the compiler checking macros handle
+this automatically.
+@end defmac
+
+@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
+@maindex OBSOLETE
+Make @code{m4} print a message to the standard error output warning that
+@var{this-macro-name} is obsolete, and giving the file and line number
+where it was called.  @var{this-macro-name} should be the name of the
+macro that is calling @code{AC_OBSOLETE}.  If @var{suggestion} is given,
+it is printed at the end of the warning message; for example, it can be
+a suggestion for what to use instead of @var{this-macro-name}.
+
+For instance
+
+@example
+AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
+@end example
+
+You are encouraged to use @code{AU_DEFUN} instead, since it gives better
+services to the user.
+@end defmac
+
+@defmac AC_OFF_T
+@maindex OFF_T
+@code{AC_TYPE_OFF_T}
+@end defmac
+
+@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}, @ovar{save-defs})
+@maindex OUTPUT
+The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted
+interface is equivalent to:
+
+@example
+@group
+AC_CONFIG_FILES(@var{file}@dots{})
+AC_CONFIG_COMMANDS([default],
+                   @var{extra-cmds}, @var{init-cmds})
+AC_SETUP_DEFS(@var{save-defs})
+AC_OUTPUT
+@end group
+@end example
+
+If you specify @var{save-defs}, autoconf will save the @samp{#define}s in a
+different form, for use in the files specified in @code{AC_CONFIG_HEADERS}.
+In this case, autoconf substitutes the C-style @samp{#define}s where it finds
+@samp{@@DEFS@@}.
+This runs faster, and is simpler to maintain
+than building a file of @samp{#undef}s,
+since autoconf will automatically generate a @samp{#define} for each
+@code{AC_DEFINE} that you execute in the @code{configure} script.
+The value for @var{save-defs} should be
+either @code{cat}, or @code{sort};
+this value is used to filter the list of @samp{#define}s before editing.
+Sorted lists are easier to read,
+but you may wish to see the definitions in the order that they were
+processed.
+@end defmac
+
+@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
+@maindex OUTPUT_COMMANDS
+Specify additional shell commands to run at the end of
+@file{config.status}, and shell commands to initialize any variables
+from @code{configure}.  This macro may be called multiple times.  It is
+obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
+
+Here is an unrealistic example:
+
+@example
+fubar=27
+AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
+                   fubar=$fubar)
+AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
+                   [echo init bit])
+@end example
+
+Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
+additional key, an important difference is that
+@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while
+@code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
+can safely be given macro calls as arguments:
+
+@example
+AC_CONFIG_COMMANDS(foo, [my_FOO()])
+@end example
+
+@noindent
+conversely, where one level of quoting was enough for literal strings
+with @code{AC_OUTPUT_COMMANDS}, you need two with
+@code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
+
+@example
+@group
+AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
+AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]])
+@end group
+@end example
+@end defmac
+
+@defmac AC_PID_T
+@maindex PID_T
+@code{AC_TYPE_PID_T}
+@end defmac
+
+@defmac AC_PREFIX
+@maindex PREFIX
+@code{AC_PREFIX_PROGRAM}
+@end defmac
+
+@defmac AC_PROGRAMS_CHECK
+@maindex PROGRAMS_CHECK
+@code{AC_CHECK_PROGS}
+@end defmac
+
+@defmac AC_PROGRAMS_PATH
+@maindex PROGRAMS_PATH
+@code{AC_PATH_PROGS}
+@end defmac
+
+@defmac AC_PROGRAM_CHECK
+@maindex PROGRAM_CHECK
+@code{AC_CHECK_PROG}
+@end defmac
+
+@defmac AC_PROGRAM_EGREP
+@maindex PROGRAM_EGREP
+@code{AC_EGREP_CPP}
+@end defmac
+
+@defmac AC_PROGRAM_PATH
+@maindex PROGRAM_PATH
+@code{AC_PATH_PROG}
+@end defmac
+
+@defmac AC_REMOTE_TAPE
+@maindex REMOTE_TAPE
+removed because of limited usefulness
+@end defmac
+
+@defmac AC_RESTARTABLE_SYSCALLS
+@maindex RESTARTABLE_SYSCALLS
+@code{AC_SYS_RESTARTABLE_SYSCALLS}
+@end defmac
+
+@defmac AC_RETSIGTYPE
+@maindex RETSIGTYPE
+@code{AC_TYPE_SIGNAL}
+@end defmac
+
+@defmac AC_RSH
+@maindex RSH
+Removed because of limited usefulness.
+@end defmac
+
+@defmac AC_SCO_INTL
+@maindex SCO_INTL
+@ovindex LIBS
+If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}.  This
+macro used to
+
+@example
+AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
+@end example
+
+@noindent
+now it just calls @code{AC_FUNC_STRFTIME} instead.
+@end defmac
+
+@defmac AC_SETVBUF_REVERSED
+@maindex SETVBUF_REVERSED
+@code{AC_FUNC_SETVBUF_REVERSED}
+@end defmac
+
+@defmac AC_SET_MAKE
+@maindex SET_MAKE
+@code{AC_PROG_MAKE_SET}
+@end defmac
+
+@defmac AC_SIZEOF_TYPE
+@maindex SIZEOF_TYPE
+@code{AC_CHECK_SIZEOF}
+@end defmac
+
+@defmac AC_SIZE_T
+@maindex SIZE_T
+@code{AC_TYPE_SIZE_T}
+@end defmac
+
+@defmac AC_STAT_MACROS_BROKEN
+@maindex STAT_MACROS_BROKEN
+@code{AC_HEADER_STAT}
+@end defmac
+
+@defmac AC_STDC_HEADERS
+@maindex STDC_HEADERS
+@code{AC_HEADER_STDC}
+@end defmac
+
+@defmac AC_STRCOLL
+@maindex STRCOLL
+@code{AC_FUNC_STRCOLL}
+@end defmac
+
+@defmac AC_ST_BLKSIZE
+@maindex ST_BLKSIZE
+@code{AC_STRUCT_ST_BLKSIZE}
+@end defmac
+
+@defmac AC_ST_BLOCKS
+@maindex ST_BLOCKS
+@code{AC_STRUCT_ST_BLOCKS}
+@end defmac
+
+@defmac AC_ST_RDEV
+@maindex ST_RDEV
+@code{AC_STRUCT_ST_RDEV}
+@end defmac
+
+@defmac AC_SYS_RESTARTABLE_SYSCALLS
+@maindex SYS_RESTARTABLE_SYSCALLS
+@cvindex HAVE_RESTARTABLE_SYSCALLS
+If the system automatically restarts a system call that is interrupted
+by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
+not check if system calls are restarted in general--it tests whether a
+signal handler installed with @code{signal} (but not @code{sigaction})
+causes system calls to be restarted. It does not test if system calls
+can be restarted when interrupted by signals that have no handler.
+
+These days portable programs should use @code{sigaction} with
+@code{SA_RESTART} if they want restartable system calls.  They should
+not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
+system call is restartable is a dynamic issue, not a configuration-time
+issue.
+@end defmac
+
+@defmac AC_SYS_SIGLIST_DECLARED
+@maindex SYS_SIGLIST_DECLARED
+@code{AC_DECL_SYS_SIGLIST}
+@end defmac
+
+@defmac AC_TEST_CPP
+@maindex TEST_CPP
+@code{AC_TRY_CPP}
+@end defmac
+
+@defmac AC_TEST_PROGRAM
+@maindex TEST_PROGRAM
+@code{AC_TRY_RUN}
+@end defmac
+
+@defmac AC_TIMEZONE
+@maindex TIMEZONE
+@code{AC_STRUCT_TIMEZONE}
+@end defmac
+
+@defmac AC_TIME_WITH_SYS_TIME
+@maindex TIME_WITH_SYS_TIME
+@code{AC_HEADER_TIME}
+@end defmac
+
+@defmac AC_UID_T
+@maindex UID_T
+@code{AC_TYPE_UID_T}
+@end defmac
+
+@defmac AC_UNISTD_H
+@maindex UNISTD_H
+Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
+@end defmac
+
+@defmac AC_USG
+@maindex USG
+@cvindex USG
+Define @code{USG} if the @sc{bsd} string functions are defined in
+@file{strings.h}.  You should no longer depend upon @code{USG}, but on
+@code{HAVE_STRING_H}, see @xref{Standard Symbols}.
+@end defmac
+
+@defmac AC_UTIME_NULL
+@maindex UTIME_NULL
+@code{AC_FUNC_UTIME_NULL}
+@end defmac
+
+@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
+@maindex VALIDATE_CACHED_SYSTEM_TUPLE
+If the cache file is inconsistent with the current host, target and
+build system types, it used to execute @var{cmd} or print a default
+error message.
+
+This is now handled by default.
+@end defmac
+
+@defmac AC_VERBOSE (@var{result-description})
+@maindex VERBOSE
+@code{AC_MSG_RESULT}.
+@end defmac
+
+@defmac AC_VFORK
+@maindex VFORK
+@code{AC_FUNC_VFORK}
+@end defmac
+
+@defmac AC_VPRINTF
+@maindex VPRINTF
+@code{AC_FUNC_VPRINTF}
+@end defmac
+
+@defmac AC_WAIT3
+@maindex WAIT3
+@code{AC_FUNC_WAIT3}
+@end defmac
+
+@defmac AC_WARN
+@maindex WARN
+@code{AC_MSG_WARN}
+@end defmac
+
+@defmac AC_WORDS_BIGENDIAN
+@maindex WORDS_BIGENDIAN
+@code{AC_C_BIGENDIAN}
+@end defmac
+
+@defmac AC_XENIX_DIR
+@maindex XENIX_DIR
+@ovindex LIBS
+This macro used to add @option{-lx} to output variable @code{LIBS} if on
+Xenix.  Also, if @file{dirent.h} is being checked for, added
+@option{-ldir} to @code{LIBS}.  Now it is merely an alias of
+@code{AC_HEADER_DIRENT} instead, plus some code to detect whether
+running @sc{xenix} on which you should not depend:
+
+@example
+AC_MSG_CHECKING([for Xenix])
+AC_EGREP_CPP(yes,
+[#if defined M_XENIX && !defined M_UNIX
+  yes
+#endif],
+             [AC_MSG_RESULT([yes]); XENIX=yes],
+             [AC_MSG_RESULT([no]); XENIX=])
+@end example
+@end defmac
+
+@defmac AC_YYTEXT_POINTER
+@maindex YYTEXT_POINTER
+@code{AC_DECL_YYTEXT}
+@end defmac
+
+@node Autoconf 1, Autoconf 2.13, Obsolete Macros, Obsolete Constructs
+@section Upgrading From Version 1
+
+Autoconf version 2 is mostly backward compatible with version 1.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 1.  So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2.  This chapter points
+out some problems to watch for when upgrading.  Also, perhaps your
+@code{configure} scripts could benefit from some of the new features in
+version 2; the changes are summarized in the file @file{NEWS} in the
+Autoconf distribution.
+
+@menu
+* Changed File Names::          Files you might rename
+* Changed Makefiles::           New things to put in @file{Makefile.in}
+* Changed Macros::              Macro calls you might replace
+* Changed Results::             Changes in how to check test results
+* Changed Macro Writing::       Better ways to write your own macros
+@end menu
+
+@node Changed File Names, Changed Makefiles, Autoconf 1, Autoconf 1
+@subsection Changed File Names
+
+If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
+in a particular package's source directory), you must rename it to
+@file{acsite.m4}.  @xref{autoconf Invocation}.
+
+If you distribute @file{install.sh} with your package, rename it to
+@file{install-sh} so @code{make} builtin rules won't inadvertently
+create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
+looks for the script under both names, but it is best to use the new name.
+
+If you were using @file{config.h.top}, @file{config.h.bot}, or
+@file{acconfig.h}, you still can, but you will have less clutter if you
+use the @code{AH_} macros.  @xref{Autoheader Macros}.
+
+@node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1
+@subsection Changed Makefiles
+
+Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
+your @file{Makefile.in} files, so they can take advantage of the values
+of those variables in the environment when @code{configure} is run.
+Doing this isn't necessary, but it's a convenience for users.
+
+Also add @samp{@@configure_input@@} in a comment to each input file for
+@code{AC_OUTPUT}, so that the output files will contain a comment saying
+they were produced by @code{configure}.  Automatically selecting the
+right comment syntax for all the kinds of files that people call
+@code{AC_OUTPUT} on became too much work.
+
+Add @file{config.log} and @file{config.cache} to the list of files you
+remove in @code{distclean} targets.
+
+If you have the following in @file{Makefile.in}:
+
+@example
+prefix = /usr/local
+exec_prefix = $(prefix)
+@end example
+
+@noindent
+you must change it to:
+
+@example
+prefix = @@prefix@@
+exec_prefix = @@exec_prefix@@
+@end example
+
+@noindent
+The old behavior of replacing those variables without @samp{@@}
+characters around them has been removed.
+
+@node Changed Macros, Changed Results, Changed Makefiles, Autoconf 1
+@subsection Changed Macros
+
+Many of the macros were renamed in Autoconf version 2.  You can still
+use the old names, but the new ones are clearer, and it's easier to find
+the documentation for them.  @xref{Obsolete Macros}, for a table showing the
+new names for the old macros.  Use the @code{autoupdate} program to
+convert your @file{configure.ac} to using the new macro names.
+@xref{autoupdate Invocation}.
+
+Some macros have been superseded by similar ones that do the job better,
+but are not call-compatible.  If you get warnings about calling obsolete
+macros while running @code{autoconf}, you may safely ignore them, but
+your @code{configure} script will generally work better if you follow
+the advice it prints about what to replace the obsolete macros with.  In
+particular, the mechanism for reporting the results of tests has
+changed.  If you were using @code{echo} or @code{AC_VERBOSE} (perhaps
+via @code{AC_COMPILE_CHECK}), your @code{configure} script's output will
+look better if you switch to @code{AC_MSG_CHECKING} and
+@code{AC_MSG_RESULT}.  @xref{Printing Messages}.  Those macros work best
+in conjunction with cache variables.  @xref{Caching Results}.
+
+
+
+@node Changed Results, Changed Macro Writing, Changed Macros, Autoconf 1
+@subsection Changed Results
+
+If you were checking the results of previous tests by examining the
+shell variable @code{DEFS}, you need to switch to checking the values of
+the cache variables for those tests.  @code{DEFS} no longer exists while
+@code{configure} is running; it is only created when generating output
+files.  This difference from version 1 is because properly quoting the
+contents of that variable turned out to be too cumbersome and
+inefficient to do every time @code{AC_DEFINE} is called.  @xref{Cache
+Variable Names}.
+
+For example, here is a @file{configure.ac} fragment written for Autoconf
+version 1:
+
+@example
+AC_HAVE_FUNCS(syslog)
+case "$DEFS" in
+*-DHAVE_SYSLOG*) ;;
+*) # syslog is not in the default libraries.  See if it's in some other.
+  saved_LIBS="$LIBS"
+  for lib in bsd socket inet; do
+    AC_CHECKING(for syslog in -l$lib)
+    LIBS="$saved_LIBS -l$lib"
+    AC_HAVE_FUNCS(syslog)
+    case "$DEFS" in
+    *-DHAVE_SYSLOG*) break ;;
+    *) ;;
+    esac
+    LIBS="$saved_LIBS"
+  done ;;
+esac
+@end example
+
+Here is a way to write it for version 2:
+
+@example
+AC_CHECK_FUNCS(syslog)
+if test $ac_cv_func_syslog = no; then
+  # syslog is not in the default libraries.  See if it's in some other.
+  for lib in bsd socket inet; do
+    AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
+      LIBS="$LIBS -l$lib"; break])
+  done
+fi
+@end example
+
+If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
+backslashes before quotes, you need to remove them.  It now works
+predictably, and does not treat quotes (except back quotes) specially.
+@xref{Setting Output Variables}.
+
+All of the boolean shell variables set by Autoconf macros now use
+@samp{yes} for the true value.  Most of them use @samp{no} for false,
+though for backward compatibility some use the empty string instead.  If
+you were relying on a shell variable being set to something like 1 or
+@samp{t} for true, you need to change your tests.
+
+@node Changed Macro Writing,  , Changed Results, Autoconf 1
+@subsection Changed Macro Writing
+
+When defining your own macros, you should now use @code{AC_DEFUN}
+instead of @code{define}.  @code{AC_DEFUN} automatically calls
+@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
+do not interrupt other macros, to prevent nested @samp{checking@dots{}}
+messages on the screen.  There's no actual harm in continuing to use the
+older way, but it's less convenient and attractive.  @xref{Macro
+Definitions}.
+
+You probably looked at the macros that came with Autoconf as a guide for
+how to do things.  It would be a good idea to take a look at the new
+versions of them, as the style is somewhat improved and they take
+advantage of some new features.
+
+If you were doing tricky things with undocumented Autoconf internals
+(macros, variables, diversions), check whether you need to change
+anything to account for changes that have been made.  Perhaps you can
+even use an officially supported technique in version 2 instead of
+kludging.  Or perhaps not.
+
+To speed up your locally written feature tests, add caching to them.
+See whether any of your tests are of general enough usefulness to
+encapsulate into macros that you can share.
+
+
+@node Autoconf 2.13,  , Autoconf 1, Obsolete Constructs
+@section Upgrading From Version 2.13
+
+The introduction of the previous section (@pxref{Autoconf 1}) perfectly
+suits this section...
+
+@quotation
+Autoconf version 2.50 is mostly backward compatible with version 2.13.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 2.13.  So, depending on how
+sophisticated your @file{configure.ac} files are, you might have to do
+some manual work in order to upgrade to version 2.50.  This chapter
+points out some problems to watch for when upgrading.  Also, perhaps
+your @code{configure} scripts could benefit from some of the new
+features in version 2.50; the changes are summarized in the file
+@file{NEWS} in the Autoconf distribution.
+@end quotation
+
+@menu
+* Changed Quotation::           Broken code which used to work
+* New Macros::                  Interaction with foreign macros
+@end menu
+
+@node Changed Quotation, New Macros, Autoconf 2.13, Autoconf 2.13
+@subsection Changed Quotation
+
+The most important changes are invisible to you: the implementation of
+most macros have completely changed.  This allowed more factorization of
+the code, better error messages, a higher uniformity of the user's
+interface etc.  Unfortunately, as a side effect, some construct which
+used to (miraculously) work might break starting with Autoconf 2.50.
+The most common culprit is bad quotation.
+
+For instance, in the following example, the message is not properly
+quoted:
+
+@example
+AC_INIT
+AC_CHECK_HEADERS(foo.h,,
+AC_MSG_ERROR(cannot find foo.h, bailing out))
+AC_OUTPUT
+@end example
+
+@noindent
+Autoconf 2.13 simply ignores it:
+
+@example
+$ autoconf-2.13; ./configure --silent
+creating cache ./config.cache
+configure: error: cannot find foo.h
+$
+@end example
+
+@noindent
+while Autoconf 2.50 will produce a broken @file{configure}:
+
+@example
+$ autoconf-2.50; ./configure --silent
+configure: error: cannot find foo.h
+./configure: exit: bad non-numeric arg `bailing'
+./configure: exit: bad non-numeric arg `bailing'
+$
+@end example
+
+The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
+too!
+
+@example
+AC_INIT
+AC_CHECK_HEADERS(foo.h,,
+                 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
+AC_OUTPUT
+@end example
+
+Many many (and many more) Autoconf macros were lacking proper quotation,
+including no less than... @code{AC_DEFUN} itself!
+
+@example
+$ cat configure.in
+AC_DEFUN([AC_PROG_INSTALL],
+[# My own much better version
+])
+AC_INIT
+AC_PROG_INSTALL
+AC_OUTPUT
+$ autoconf-2.13
+autoconf: Undefined macros:
+***BUG in Autoconf--please report*** AC_FD_MSG
+***BUG in Autoconf--please report*** AC_EPI
+configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
+configure.in:5:AC_PROG_INSTALL
+$ autoconf-2.50
+$
+@end example
+
+
+@node New Macros,  , Changed Quotation, Autoconf 2.13
+@subsection New Macros
+
+@cindex @code{undefined macro: _m4_divert_diversion}
+
+Because Autoconf has been dormant for years, Automake provided
+Autoconf-like macros for a while.  Autoconf 2.50 now provides better
+versions of these macros, integrated in the @code{AC_} namespace,
+instead of @code{AM_}.  But in order to ease the upgrading via
+@command{autoupdate}, bindings to such @code{AM_} macros are provided.
+
+Unfortunately Automake did not quote the name of these macros!
+Therefore, when @command{m4} find in @file{aclocal.m4} something like
+@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)}, @code{AM_TYPE_PTRDIFF_T} is
+expanded, replaced with its Autoconf definition.
+
+Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
+complain, in its own words:
+
+@example
+$ cat configure.in
+AC_INIT
+AM_TYPE_PTRDIFF_T
+$ aclocal-1.4
+$ autoconf
+./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
+actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
+./aclocal.m4:17: the top level
+$
+@end example
+
+Future versions of Automake will simply no longer define most of these
+macros, and will properly quote the names of the remaining macros.
+But you don't have to wait for it to happen to do the right thing right
+now: do not depend upon macros from Automake as it is simply not its job
+to provide macros (but the one it requires by itself):
+
+@example
+$ cat configure.in
+AC_INIT
+AM_TYPE_PTRDIFF_T
+$ rm aclocal.m4
+$ autoupdate
+autoupdate: `configure.in' is updated
+$ cat configure.in
+AC_INIT
+AC_CHECK_TYPES([ptrdiff_t])
+$ aclocal-1.4
+$ autoconf
+$
+@end example
+
+@c ================================================ Questions About Autoconf.
+
+@node Questions, History, Obsolete Constructs, Top
+@chapter Questions About Autoconf
+
+Several questions about Autoconf come up occasionally.  Here some of them
+are addressed.
+
+@menu
+* Distributing::                Distributing @code{configure} scripts
+* Why GNU m4::                  Why not use the standard M4?
+* Bootstrapping::               Autoconf and GNU M4 require each other?
+* Why Not Imake::               Why GNU uses @code{configure} instead of Imake
+@end menu
+
+@node Distributing, Why GNU m4, Questions, Questions
+@section Distributing @code{configure} Scripts
+
+@display
+What are the restrictions on distributing @code{configure}
+scripts that Autoconf generates?  How does that affect my
+programs that use them?
+@end display
+
+There are no restrictions on how the configuration scripts that Autoconf
+produces may be distributed or used.  In Autoconf version 1, they were
+covered by the @sc{gnu} General Public License.  We still encourage
+software authors to distribute their work under terms like those of the
+GPL, but doing so is not required to use Autoconf.
+
+Of the other files that might be used with @code{configure},
+@file{config.h.in} is under whatever copyright you use for your
+@file{configure.ac}.  @file{config.sub} and @file{config.guess} have an
+exception to the GPL when they are used with an Autoconf-generated
+@code{configure} script, which permits you to distribute them under the
+same terms as the rest of your package.  @file{install-sh} is from the X
+Consortium and is not copyrighted.
+
+@node Why GNU m4, Bootstrapping, Distributing, Questions
+@section Why Require GNU M4?
+
+@display
+Why does Autoconf require @sc{gnu} M4?
+@end display
+
+Many M4 implementations have hard-coded limitations on the size and
+number of macros that Autoconf exceeds.  They also lack several
+builtin macros that it would be difficult to get along without in a
+sophisticated application like Autoconf, including:
+
+@example
+builtin
+indir
+patsubst
+__file__
+__line__
+@end example
+
+Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses
+frozen state files.
+
+Since only software maintainers need to use Autoconf, and since @sc{gnu}
+M4 is simple to configure and install, it seems reasonable to require
+@sc{gnu} M4 to be installed also.  Many maintainers of @sc{gnu} and
+other free software already have most of the @sc{gnu} utilities
+installed, since they prefer them.
+
+@node Bootstrapping, Why Not Imake, Why GNU m4, Questions
+@section How Can I Bootstrap?
+
+@display
+If Autoconf requires @sc{gnu} M4 and @sc{gnu} M4 has an Autoconf
+@code{configure} script, how do I bootstrap?  It seems like a chicken
+and egg problem!
+@end display
+
+This is a misunderstanding.  Although @sc{gnu} M4 does come with a
+@code{configure} script produced by Autoconf, Autoconf is not required
+in order to run the script and install @sc{gnu} M4.  Autoconf is only
+required if you want to change the M4 @code{configure} script, which few
+people have to do (mainly its maintainer).
+
+@node Why Not Imake,  , Bootstrapping, Questions
+@section Why Not Imake?
+
+@display
+Why not use Imake instead of @code{configure} scripts?
+@end display
+
+Several people have written addressing this question, so I include
+adaptations of their explanations here.
+
+The following answer is based on one written by Richard Pixley:
+
+@quotation
+Autoconf generated scripts frequently work on machines that it has
+never been set up to handle before.  That is, it does a good job of
+inferring a configuration for a new system.  Imake cannot do this.
+
+Imake uses a common database of host specific data.  For X11, this makes
+sense because the distribution is made as a collection of tools, by one
+central authority who has control over the database.
+
+@sc{gnu} tools are not released this way.  Each @sc{gnu} tool has a
+maintainer; these maintainers are scattered across the world.  Using a
+common database would be a maintenance nightmare.  Autoconf may appear
+to be this kind of database, but in fact it is not.  Instead of listing
+host dependencies, it lists program requirements.
+
+If you view the @sc{gnu} suite as a collection of native tools, then the
+problems are similar.  But the @sc{gnu} development tools can be
+configured as cross tools in almost any host+target permutation.  All of
+these configurations can be installed concurrently.  They can even be
+configured to share host independent files across hosts.  Imake doesn't
+address these issues.
+
+Imake templates are a form of standardization.  The @sc{gnu} coding
+standards address the same issues without necessarily imposing the same
+restrictions.
+@end quotation
+
+
+Here is some further explanation, written by Per Bothner:
+
+@quotation
+One of the advantages of Imake is that it easy to generate large
+Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
+However, @code{cpp} is not programmable: it has limited conditional
+facilities, and no looping.  And @code{cpp} cannot inspect its
+environment.
+
+All of these problems are solved by using @code{sh} instead of
+@code{cpp}.  The shell is fully programmable, has macro substitution,
+can execute (or source) other shell scripts, and can inspect its
+environment.
+@end quotation
+
+
+Paul Eggert elaborates more:
+
+@quotation
+With Autoconf, installers need not assume that Imake itself is already
+installed and working well.  This may not seem like much of an advantage
+to people who are accustomed to Imake.  But on many hosts Imake is not
+installed or the default installation is not working well, and requiring
+Imake to install a package hinders the acceptance of that package on
+those hosts.  For example, the Imake template and configuration files
+might not be installed properly on a host, or the Imake build procedure
+might wrongly assume that all source files are in one big directory
+tree, or the Imake configuration might assume one compiler whereas the
+package or the installer needs to use another, or there might be a
+version mismatch between the Imake expected by the package and the Imake
+supported by the host.  These problems are much rarer with Autoconf,
+where each package comes with its own independent configuration
+processor.
+
+Also, Imake often suffers from unexpected interactions between
+@code{make} and the installer's C preprocessor.  The fundamental problem
+here is that the C preprocessor was designed to preprocess C programs,
+not @file{Makefile}s.  This is much less of a problem with Autoconf,
+which uses the general-purpose preprocessor @code{m4}, and where the
+package's author (rather than the installer) does the preprocessing in a
+standard way.
+@end quotation
+
+
+Finally, Mark Eichin notes:
+
+@quotation
+Imake isn't all that extensible, either.  In order to add new features to
+Imake, you need to provide your own project template, and duplicate most
+of the features of the existing one.  This means that for a sophisticated
+project, using the vendor-provided Imake templates fails to provide any
+leverage---since they don't cover anything that your own project needs
+(unless it is an X11 program).
+
+On the other side, though:
+
+The one advantage that Imake has over @code{configure}:
+@file{Imakefile}s tend to be much shorter (likewise, less redundant)
+than @file{Makefile.in}s.  There is a fix to this, however---at least
+for the Kerberos V5 tree, we've modified things to call in common
+@file{post.in} and @file{pre.in} @file{Makefile} fragments for the
+entire tree.  This means that a lot of common things don't have to be
+duplicated, even though they normally are in @code{configure} setups.
+@end quotation
+
+
+
+
+@c ===================================================== History of Autoconf.
+
+@node History, Environment Variable Index, Questions, Top
+@chapter History of Autoconf
+
+You may be wondering, Why was Autoconf originally written?  How did it
+get into its present form?  (Why does it look like gorilla spit?)  If
+you're not wondering, then this chapter contains no information useful
+to you, and you might as well skip it.  If you @emph{are} wondering,
+then let there be light@dots{}
+
+@menu
+* Genesis::                     Prehistory and naming of @code{configure}
+* Exodus::                      The plagues of M4 and Perl
+* Leviticus::                   The priestly code of portability arrives
+* Numbers::                     Growth and contributors
+* Deuteronomy::                 Approaching the promises of easy configuration
+@end menu
+
+@node Genesis, Exodus, History, History
+@section Genesis
+
+In June 1991 I was maintaining many of the @sc{gnu} utilities for the
+Free Software Foundation.  As they were ported to more platforms and
+more programs were added, the number of @option{-D} options that users
+had to select in the @file{Makefile} (around 20) became burdensome.
+Especially for me---I had to test each new release on a bunch of
+different systems.  So I wrote a little shell script to guess some of
+the correct settings for the fileutils package, and released it as part
+of fileutils 2.0.  That @code{configure} script worked well enough that
+the next month I adapted it (by hand) to create similar @code{configure}
+scripts for several other @sc{gnu} utilities packages.  Brian Berliner
+also adapted one of my scripts for his @sc{cvs} revision control system.
+
+Later that summer, I learned that Richard Stallman and Richard Pixley
+were developing similar scripts to use in the @sc{gnu} compiler tools;
+so I adapted my @code{configure} scripts to support their evolving
+interface: using the file name @file{Makefile.in} as the templates;
+adding @samp{+srcdir}, the first option (of many); and creating
+@file{config.status} files.
+
+@node Exodus, Leviticus, Genesis, History
+@section Exodus
+
+As I got feedback from users, I incorporated many improvements, using
+Emacs to search and replace, cut and paste, similar changes in each of
+the scripts.  As I adapted more @sc{gnu} utilities packages to use
+@code{configure} scripts, updating them all by hand became impractical.
+Rich Murphey, the maintainer of the @sc{gnu} graphics utilities, sent me
+mail saying that the @code{configure} scripts were great, and asking if
+I had a tool for generating them that I could send him.  No, I thought,
+but I should!  So I started to work out how to generate them.  And the
+journey from the slavery of hand-written @code{configure} scripts to the
+abundance and ease of Autoconf began.
+
+Cygnus @code{configure}, which was being developed at around that time,
+is table driven; it is meant to deal mainly with a discrete number of
+system types with a small number of mainly unguessable features (such as
+details of the object file format).  The automatic configuration system
+that Brian Fox had developed for Bash takes a similar approach.  For
+general use, it seems to me a hopeless cause to try to maintain an
+up-to-date database of which features each variant of each operating
+system has.  It's easier and more reliable to check for most features on
+the fly---especially on hybrid systems that people have hacked on
+locally or that have patches from vendors installed.
+
+I considered using an architecture similar to that of Cygnus
+@code{configure}, where there is a single @code{configure} script that
+reads pieces of @file{configure.in} when run.  But I didn't want to have
+to distribute all of the feature tests with every package, so I settled
+on having a different @code{configure} made from each
+@file{configure.in} by a preprocessor.  That approach also offered more
+control and flexibility.
+
+I looked briefly into using the Metaconfig package, by Larry Wall,
+Harlan Stenn, and Raphael Manfredi, but I decided not to for several
+reasons.  The @code{Configure} scripts it produces are interactive,
+which I find quite inconvenient; I didn't like the ways it checked for
+some features (such as library functions); I didn't know that it was
+still being maintained, and the @code{Configure} scripts I had
+seen didn't work on many modern systems (such as System V R4 and NeXT);
+it wasn't very flexible in what it could do in response to a feature's
+presence or absence; I found it confusing to learn; and it was too big
+and complex for my needs (I didn't realize then how much Autoconf would
+eventually have to grow).
+
+I considered using Perl to generate my style of @code{configure}
+scripts, but decided that M4 was better suited to the job of simple
+textual substitutions: it gets in the way less, because output is
+implicit.  Plus, everyone already has it.  (Initially I didn't rely on
+the @sc{gnu} extensions to M4.)  Also, some of my friends at the
+University of Maryland had recently been putting M4 front ends on
+several programs, including @code{tvtwm}, and I was interested in trying
+out a new language.
+
+@node Leviticus, Numbers, Exodus, History
+@section Leviticus
+
+Since my @code{configure} scripts determine the system's capabilities
+automatically, with no interactive user intervention, I decided to call
+the program that generates them Autoconfig.  But with a version number
+tacked on, that name would be too long for old @sc{unix} file systems,
+so I shortened it to Autoconf.
+
+In the fall of 1991 I called together a group of fellow questers after
+the Holy Grail of portability (er, that is, alpha testers) to give me
+feedback as I encapsulated pieces of my handwritten scripts in M4 macros
+and continued to add features and improve the techniques used in the
+checks.  Prominent among the testers were Fran@,cois Pinard, who came up
+with the idea of making an @file{autoconf} shell script to run @code{m4}
+and check for unresolved macro calls; Richard Pixley, who suggested
+running the compiler instead of searching the file system to find
+include files and symbols, for more accurate results; Karl Berry, who
+got Autoconf to configure @TeX{} and added the macro index to the
+documentation; and Ian Lance Taylor, who added support for creating a C
+header file as an alternative to putting @option{-D} options in a
+@file{Makefile}, so he could use Autoconf for his @sc{uucp} package.
+The alpha testers cheerfully adjusted their files again and again as the
+names and calling conventions of the Autoconf macros changed from
+release to release.  They all contributed many specific checks, great
+ideas, and bug fixes.
+
+@node Numbers, Deuteronomy, Leviticus, History
+@section Numbers
+
+In July 1992, after months of alpha testing, I released Autoconf 1.0,
+and converted many @sc{gnu} packages to use it.  I was surprised by how
+positive the reaction to it was.  More people started using it than I
+could keep track of, including people working on software that wasn't
+part of the @sc{gnu} Project (such as TCL, FSP, and Kerberos V5).
+Autoconf continued to improve rapidly, as many people using the
+@code{configure} scripts reported problems they encountered.
+
+Autoconf turned out to be a good torture test for M4 implementations.
+@sc{unix} @code{m4} started to dump core because of the length of the
+macros that Autoconf defined, and several bugs showed up in @sc{gnu}
+@code{m4} as well.  Eventually, we realized that we needed to use some
+features that only @sc{gnu} M4 has.  4.3@sc{bsd} @code{m4}, in
+particular, has an impoverished set of builtin macros; the System V
+version is better, but still doesn't provide everything we need.
+
+More development occurred as people put Autoconf under more stresses
+(and to uses I hadn't anticipated).  Karl Berry added checks for X11.
+david zuhn contributed C++ support.  Fran@,cois Pinard made it diagnose
+invalid arguments.  Jim Blandy bravely coerced it into configuring
+@sc{gnu} Emacs, laying the groundwork for several later improvements.
+Roland McGrath got it to configure the @sc{gnu} C Library, wrote the
+@code{autoheader} script to automate the creation of C header file
+templates, and added a @option{--verbose} option to @code{configure}.
+Noah Friedman added the @option{--autoconf-dir} option and
+@code{AC_MACRODIR} environment variable.  (He also coined the term
+@dfn{autoconfiscate} to mean ``adapt a software package to use
+Autoconf''.)  Roland and Noah improved the quoting protection in
+@code{AC_DEFINE} and fixed many bugs, especially when I got sick of
+dealing with portability problems from February through June, 1993.
+
+@node Deuteronomy,  , Numbers, History
+@section Deuteronomy
+
+A long wish list for major features had accumulated, and the effect of
+several years of patching by various people had left some residual
+cruft.  In April 1994, while working for Cygnus Support, I began a major
+revision of Autoconf.  I added most of the features of the Cygnus
+@code{configure} that Autoconf had lacked, largely by adapting the
+relevant parts of Cygnus @code{configure} with the help of david zuhn
+and Ken Raeburn.  These features include support for using
+@file{config.sub}, @file{config.guess}, @option{--host}, and
+@option{--target}; making links to files; and running @code{configure}
+scripts in subdirectories.  Adding these features enabled Ken to convert
+@sc{gnu} @code{as}, and Rob Savoye to convert DejaGNU, to using
+Autoconf.
+
+I added more features in response to other peoples' requests.  Many
+people had asked for @code{configure} scripts to share the results of
+the checks between runs, because (particularly when configuring a large
+source tree, like Cygnus does) they were frustratingly slow.  Mike
+Haertel suggested adding site-specific initialization scripts.  People
+distributing software that had to unpack on MS-DOS asked for a way to
+override the @file{.in} extension on the file names, which produced file
+names like @file{config.h.in} containing two dots.  Jim Avera did an
+extensive examination of the problems with quoting in @code{AC_DEFINE}
+and @code{AC_SUBST}; his insights led to significant improvements.
+Richard Stallman asked that compiler output be sent to @file{config.log}
+instead of @file{/dev/null}, to help people debug the Emacs
+@code{configure} script.
+
+I made some other changes because of my dissatisfaction with the quality
+of the program.  I made the messages showing results of the checks less
+ambiguous, always printing a result.  I regularized the names of the
+macros and cleaned up coding style inconsistencies.  I added some
+auxiliary utilities that I had developed to help convert source code
+packages to use Autoconf.  With the help of Fran@,cois Pinard, I made
+the macros not interrupt each others' messages.  (That feature revealed
+some performance bottlenecks in @sc{gnu} @code{m4}, which he hastily
+corrected!)  I reorganized the documentation around problems people want
+to solve.  And I began a test suite, because experience had shown that
+Autoconf has a pronounced tendency to regress when we change it.
+
+Again, several alpha testers gave invaluable feedback, especially
+Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
+and Mark Eichin.
+
+Finally, version 2.0 was ready.  And there was much rejoicing.  (And I
+have free time again.  I think.  Yeah, right.)
+
+
+@c ========================================================== Appendices
+
+@node Environment Variable Index, Output Variable Index, History, Top
+@unnumbered Environment Variable Index
+
+This is an alphabetical list of the environment variables that Autoconf
+checks.
+
+@printindex ev
+
+@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top
+@unnumbered Output Variable Index
+
+This is an alphabetical list of the variables that Autoconf can
+substitute into files that it creates, typically one or more
+@file{Makefile}s.  @xref{Setting Output Variables}, for more information
+on how this is done.
+
+@printindex ov
+
+@node Preprocessor Symbol Index, Autoconf Macro Index, Output Variable Index, Top
+@unnumbered Preprocessor Symbol Index
+
+This is an alphabetical list of the C preprocessor symbols that the
+Autoconf macros define.  To work with Autoconf, C source code needs to
+use these names in @code{#if} directives.
+
+@printindex cv
+
+@node Autoconf Macro Index, M4 Macro Index, Preprocessor Symbol Index, Top
+@unnumbered Autoconf Macro Index
+
+This is an alphabetical list of the Autoconf macros.  To make the list
+easier to use, the macros are listed without their preceding @samp{AC_}.
+
+@printindex ma
+
+@node M4 Macro Index, Concept Index, Autoconf Macro Index, Top
+@unnumbered M4 Macro Index
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros.  To
+make the list easier to use, the macros are listed without their
+preceding @samp{m4_} or @samp{AS_}.
+
+@printindex ms
+
+@node Concept Index,  , M4 Macro Index, Top
+@unnumbered Concept Index
+
+This is an alphabetical list of the files, tools, and concepts
+introduced in this document.
+
+@printindex cp
+
+@contents
+@bye
+
+@c Local Variables:
+@c ispell-local-dictionary: "american"
+@c End:
diff --git a/doc/install.texi b/doc/install.texi
new file mode 100644
index 0000000..19fd35e
--- /dev/null
+++ b/doc/install.texi
@@ -0,0 +1,258 @@
+@c This file is included by autoconf.texi and is used to produce
+@c the INSTALL file.
+
+@node Basic Installation
+@section Basic Installation
+
+These are generic installation instructions.
+
+The @code{configure} shell script attempts to guess correct values for
+various system-dependent variables used during compilation.  It uses
+those values to create a @file{Makefile} in each directory of the
+package.  It may also create one or more @file{.h} files containing
+system-dependent definitions.  Finally, it creates a shell script
+@file{config.status} that you can run in the future to recreate the
+current configuration, and a file @file{config.log} containing compiler
+output (useful mainly for debugging @code{configure}).
+
+It can also use an optional file (typically called @file{config.cache}
+and enabled with @option{--cache-file=config.cache} or simply
+@option{-C}) that saves the results of its tests to speed up
+reconfiguring.  (Caching is disabled by default to prevent problems with
+accidental use of stale cache files.)
+
+If you need to do unusual things to compile the package, please try to
+figure out how @code{configure} could check whether to do them, and mail
+diffs or instructions to the address given in the @file{README} so they
+can be considered for the next release.  If you are using the cache, and
+at some point @file{config.cache} contains results you don't want to
+keep, you may remove or edit it.
+
+The file @file{configure.ac} (or @file{configure.in}) is used to create
+@file{configure} by a program called @code{autoconf}.  You only need
+@file{configure.ac} if you want to change it or regenerate
+@file{configure} using a newer version of @code{autoconf}.
+
+@noindent
+The simplest way to compile this package is:
+
+@enumerate
+@item
+@code{cd} to the directory containing the package's source code and type
+@samp{./configure} to configure the package for your system.  If you're
+using @code{csh} on an old version of System V, you might need to type
+@samp{sh ./configure} instead to prevent @code{csh} from trying to
+execute @code{configure} itself.
+
+Running @code{configure} takes awhile.  While running, it prints some
+messages telling which features it is checking for.
+
+@item
+Type @samp{make} to compile the package.
+
+@item
+Optionally, type @samp{make check} to run any self-tests that come with
+the package.
+
+@item
+Type @samp{make install} to install the programs and any data files and
+documentation.
+
+@item
+You can remove the program binaries and object files from the source code
+directory by typing @samp{make clean}.  To also remove the files that
+@code{configure} created (so you can compile the package for a different
+kind of computer), type @samp{make distclean}.  There is also a
+@samp{make maintainer-clean} target, but that is intended mainly for the
+package's developers.  If you use it, you may have to get all sorts of
+other programs in order to regenerate files that came with the distribution.
+@end enumerate
+
+@node Compilers and Options
+@section Compilers and Options
+
+Some systems require unusual options for compilation or linking that the
+@code{configure} script does not know about.  Run @samp{./configure
+--help} for details on some of the pertinent environment variables.
+
+You can give @code{configure} initial values for variables by setting
+them in the environment.  You can do that on the command line like this:
+
+@example
+./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
+@end example
+
+@xref{Environment Variables}, for more details.
+
+
+@node Multiple Architectures
+@section Compiling For Multiple Architectures
+
+You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory.  To do this, you must use a version of @code{make} that
+supports the @code{VPATH} variable, such as GNU @code{make}.  @code{cd}
+to the directory where you want the object files and executables to go
+and run the @code{configure} script.  @code{configure} automatically
+checks for the source code in the directory that @code{configure} is in
+and in @file{..}.
+
+If you have to use a @code{make} that does not support the @code{VPATH}
+variable, you have to compile the package for one architecture at a time
+in the source code directory.  After you have installed the package for
+one architecture, use @samp{make distclean} before reconfiguring for
+another architecture.
+
+@node Installation Names
+@section Installation Names
+
+By default, @samp{make install} will install the package's files in
+@file{/usr/local/bin}, @file{/usr/local/man}, etc.  You can specify an
+installation prefix other than @file{/usr/local} by giving
+@code{configure} the option @option{--prefix=@var{path}}.
+
+You can specify separate installation prefixes for architecture-specific
+files and architecture-independent files.  If you give @code{configure}
+the option @option{--exec-prefix=@var{path}}, the package will use
+@var{path} as the prefix for installing programs and libraries.
+Documentation and other data files will still use the regular prefix.
+
+In addition, if you use an unusual directory layout you can give options
+like @option{--bindir=@var{path}} to specify different values for
+particular kinds of files.  Run @samp{configure --help} for a list of
+the directories you can set and what kinds of files go in them.
+
+If the package supports it, you can cause programs to be installed with
+an extra prefix or suffix on their names by giving @code{configure} the
+option @option{--program-prefix=@var{PREFIX}} or
+@option{--program-suffix=@var{SUFFIX}}.
+
+@node Optional Features
+@section Optional Features
+
+Some packages pay attention to @option{--enable-@var{feature}} options
+to @code{configure}, where @var{feature} indicates an optional part of
+the package.  They may also pay attention to
+@option{--with-@var{package}} options, where @var{package} is something
+like @samp{gnu-as} or @samp{x} (for the X Window System).  The
+@file{README} should mention any @option{--enable-} and @option{--with-}
+options that the package recognizes.
+
+For packages that use the X Window System, @code{configure} can usually
+find the X include and library files automatically, but if it doesn't,
+you can use the @code{configure} options @option{--x-includes=@var{dir}}
+and @option{--x-libraries=@var{dir}} to specify their locations.
+
+@node System Type
+@section Specifying the System Type
+
+There may be some features @code{configure} cannot figure out
+automatically, but needs to determine by the type of host the package
+will run on.  Usually @code{configure} can figure that out, but if it
+prints a message saying it cannot guess the host type, give it the
+@option{--build=@var{type}} option.  @var{type} can either be a short
+name for the system type, such as @samp{sun4}, or a canonical name which
+has the form:
+
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+
+@noindent
+where @var{system} can have one of these forms:
+
+@example
+@var{os}
+@var{kernel}-@var{os}
+@end example
+
+See the file @file{config.sub} for the possible values of each field.
+If @file{config.sub} isn't included in this package, then this package
+doesn't need to know the host type.
+
+If you are @emph{building} compiler tools for cross-compiling, you should
+use the @option{--target=@var{type}} option to select the type of system
+they will produce code for.
+
+If you want to @emph{use} a cross compiler, that generates code for a
+platform different from the build platform, you should specify the host
+platform (i.e., that on which the generated programs will eventually be
+run) with @option{--host=@var{type}}.  In this case, you should also
+specify the build platform with @option{--build=@var{type}}, because, in
+this case, it may not be possible to guess the build platform (it
+sometimes involves compiling and running simple test programs, and this
+can't be done if the compiler is a cross compiler).
+
+@node Sharing Defaults
+@section Sharing Defaults
+
+If you want to set default values for @code{configure} scripts to share,
+you can create a site shell script called @file{config.site} that gives
+default values for variables like @code{CC}, @code{cache_file}, and
+@code{prefix}.  @code{configure} looks for
+@file{@var{prefix}/share/config.site} if it exists, then
+@file{@var{prefix}/etc/config.site} if it exists.  Or, you can set the
+@code{CONFIG_SITE} environment variable to the location of the site
+script.  A warning: not all @code{configure} scripts look for a site
+script.
+
+@node Environment Variables
+@section Environment Variables
+
+Variables not defined in a site shell script can be set in the
+environment passed to configure.  However, some packages may run
+configure again during the build, and the customized values of these
+variables may be lost.  In order to avoid this problem, you should set
+them in the @code{configure} command line, using @samp{VAR=value}.  For
+example:
+
+@example
+./configure CC=/usr/local2/bin/gcc
+@end example
+
+@noindent
+will cause the specified gcc to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+
+@node configure Invocation
+@section @code{configure} Invocation
+
+@code{configure} recognizes the following options to control how it
+operates.
+
+@table @option
+@item --help
+@itemx -h
+Print a summary of the options to @code{configure}, and exit.
+
+@item --version
+@itemx -V
+Print the version of Autoconf used to generate the @code{configure}
+script, and exit.
+
+@item --cache-file=@var{file}
+@cindex Cache, enabling
+Enable the cache: use and save the results of the tests in @var{file},
+traditionally @file{config.cache}.  @var{file} defaults to
+@file{/dev/null} to disable caching.
+
+@item --config-cache
+@itemx -C
+Alias for @option{--cache-file=config.cache}.
+
+@item --quiet
+@itemx --silent
+@itemx -q
+Do not print messages saying which checks are being made.  To suppress
+all normal output, redirect it to @file{/dev/null} (any error messages
+will still be shown).
+
+@item --srcdir=@var{dir}
+Look for the package's source code in directory @var{dir}.  Usually
+@code{configure} can determine that directory automatically.
+@end table
+
+@noindent
+@code{configure} also accepts some other, not widely useful, options.
+Run @samp{configure --help} for more details.
diff --git a/doc/make-stds.texi b/doc/make-stds.texi
new file mode 100644
index 0000000..68faa8d
--- /dev/null
+++ b/doc/make-stds.texi
@@ -0,0 +1,944 @@
+@comment This file is included by both standards.texi and make.texinfo.
+@comment It was broken out of standards.texi on 1/6/93 by roland.
+
+@node Makefile Conventions
+@chapter Makefile Conventions
+@comment standards.texi does not print an index, but make.texinfo does.
+@cindex makefile, conventions for
+@cindex conventions for makefiles
+@cindex standards for makefiles
+
+This
+@ifinfo
+node
+@end ifinfo
+@iftex
+@ifset CODESTD
+section
+@end ifset
+@ifclear CODESTD
+chapter
+@end ifclear
+@end iftex
+describes conventions for writing the Makefiles for GNU programs.
+Using Automake will help you write a Makefile that follows these
+conventions.
+
+@menu
+* Makefile Basics::		General Conventions for Makefiles
+* Utilities in Makefiles::	Utilities in Makefiles
+* Command Variables::		Variables for Specifying Commands
+* Directory Variables::		Variables for Installation Directories
+* Standard Targets::		Standard Targets for Users
+* Install Command Categories::  Three categories of commands in the `install'
+                                  rule: normal, pre-install and post-install.
+@end menu
+
+@node Makefile Basics
+@section General Conventions for Makefiles
+
+Every Makefile should contain this line:
+
+@example
+SHELL = /bin/sh
+@end example
+
+@noindent
+to avoid trouble on systems where the @code{SHELL} variable might be
+inherited from the environment.  (This is never a problem with GNU
+@code{make}.)
+
+Different @code{make} programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior.  So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+@example
+.SUFFIXES:
+.SUFFIXES: .c .o
+@end example
+
+@noindent
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+Don't assume that @file{.} is in the path for command execution.  When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses @file{./} if the program is built as
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code.  Without one of these prefixes, the current search
+path is used.
+
+The distinction between @file{./} (the @dfn{build directory}) and
+@file{$(srcdir)/} (the @dfn{source directory}) is important because
+users can build in a separate directory using the @samp{--srcdir} option
+to @file{configure}.  A rule of the form:
+
+@smallexample
+foo.1 : foo.man sedscript
+        sed -e sedscript foo.man > foo.1
+@end smallexample
+
+@noindent
+will fail when the build directory is not the source directory, because
+@file{foo.man} and @file{sedscript} are in the source directory.
+
+When using GNU @code{make}, relying on @samp{VPATH} to find the source
+file will work in the case where there is a single dependency file,
+since the @code{make} automatic variable @samp{$<} will represent the
+source file wherever it is.  (Many versions of @code{make} set @samp{$<}
+only in implicit rules.)  A Makefile target like
+
+@smallexample
+foo.o : bar.c
+        $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+@end smallexample
+
+@noindent
+should instead be written as
+
+@smallexample
+foo.o : bar.c
+        $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
+@end smallexample
+
+@noindent
+in order to allow @samp{VPATH} to work correctly.  When the target has
+multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
+way to make the rule work well.  For example, the target above for
+@file{foo.1} is best written as:
+
+@smallexample
+foo.1 : foo.man sedscript
+        sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
+@end smallexample
+
+GNU distributions usually contain some files which are not source
+files---for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex.  Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory.  So Makefile rules to update them should put the
+updated files in the source directory.
+
+However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+Try to make the build and installation targets, at least (and all their
+subtargets) work correctly with a parallel @code{make}.
+
+@node Utilities in Makefiles
+@section Utilities in Makefiles
+
+Write the Makefile commands (and any shell scripts, such as
+@code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
+special features of @code{ksh} or @code{bash}.
+
+The @code{configure} script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+@c dd find
+@c gunzip gzip md5sum
+@c mkfifo mknod tee uname 
+
+@example
+cat cmp cp diff echo egrep expr false grep install-info
+ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+@end example
+
+The compression program @code{gzip} can be used in the @code{dist} rule.
+
+Stick to the generally supported options for these programs.  For
+example, don't use @samp{mkdir -p}, convenient as it may be, because
+most systems don't support it.
+
+It is a good idea to avoid creating symbolic links in makefiles, since a
+few systems don't support them.
+
+The Makefile rules for building and installation can also use compilers
+and related programs, but should do so via @code{make} variables so that the
+user can substitute alternatives.  Here are some of the programs we
+mean:
+
+@example
+ar bison cc flex install ld ldconfig lex
+make makeinfo ranlib texi2dvi yacc
+@end example
+
+Use the following @code{make} variables to run those programs:
+
+@example
+$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+@end example
+
+When you use @code{ranlib} or @code{ldconfig}, you should make sure
+nothing bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem.  (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
+this.)
+
+If you use symbolic links, you should implement a fallback for systems
+that don't have symbolic links.
+
+Additional utilities that can be used via Make variables are:
+
+@example
+chgrp chmod chown mknod
+@end example
+
+It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+@node Command Variables
+@section Variables for Specifying Commands
+
+Makefiles should provide variables for overriding certain commands, options,
+and so on.
+
+In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named @code{BISON} whose default
+value is set with @samp{BISON = bison}, and refer to it with
+@code{$(BISON)} whenever you need to use Bison.
+
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
+Each program-name variable should come with an options variable that is
+used to supply options to the program.  Append @samp{FLAGS} to the
+program-name variable name to get the options variable name---for
+example, @code{BISONFLAGS}.  (The names @code{CFLAGS} for the C
+compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
+exceptions to this rule, but we keep them because they are standard.)
+Use @code{CPPFLAGS} in any compilation command that runs the
+preprocessor, and use @code{LDFLAGS} in any compilation command that
+does linking as well as in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
+
+@smallexample
+CFLAGS = -g
+ALL_CFLAGS = -I. $(CFLAGS)
+.c.o:
+        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+@end smallexample
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation.  You can consider it a default
+that is only recommended.  If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
+
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
+@code{CFLAGS} should be used in every invocation of the C compiler,
+both those which do compilation and those which do linking.
+
+Every Makefile should define the variable @code{INSTALL}, which is the
+basic command for installing a file into the system.
+
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}.  (The default for @code{INSTALL_PROGRAM} should
+be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
+@code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
+commands for actual installation, for executables and nonexecutables
+respectively.  Use these variables as follows:
+
+@example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+@end example
+
+Optionally, you may prepend the value of @code{DESTDIR} to the target
+filename.  Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later.  Do not
+set the value of @code{DESTDIR} in your Makefile, and do not include it
+in any installed files.  With support for @code{DESTDIR}, the above
+examples become:
+
+@example
+$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+@end example
+
+@noindent
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+@node Directory Variables
+@section Variables for Installation Directories
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place.  The standard names for these
+variables are described below.  They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+These two variables set the root for the installation.  All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+@table @code
+@item prefix
+@vindex prefix
+A prefix used in constructing the default values of the variables listed
+below.  The default value of @code{prefix} should be @file{/usr/local}.
+When building the complete GNU system, the prefix will be empty and
+@file{/usr} will be a symbolic link to @file{/}.
+(If you are using Autoconf, write it as @samp{@@prefix@@}.)
+
+Running @samp{make install} with a different value of @code{prefix} from
+the one used to build the program should @emph{not} recompile the
+program.
+
+@item exec_prefix
+@vindex exec_prefix
+A prefix used in constructing the default values of some of the
+variables listed below.  The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
+
+Generally, @code{$(exec_prefix)} is used for directories that contain
+machine-specific files (such as executables and subroutine libraries),
+while @code{$(prefix)} is used directly for other directories.
+
+Running @samp{make install} with a different value of @code{exec_prefix}
+from the one used to build the program should @emph{not} recompile the
+program.
+@end table
+
+Executable programs are installed in one of the following directories.
+
+@table @code
+@item bindir
+@vindex bindir
+The directory for installing executable programs that users can run.
+This should normally be @file{/usr/local/bin}, but write it as
+@file{$(exec_prefix)/bin}.
+(If you are using Autoconf, write it as @samp{@@bindir@@}.)
+
+@item sbindir
+@vindex sbindir
+The directory for installing executable programs that can be run from
+the shell, but are only generally useful to system administrators.  This
+should normally be @file{/usr/local/sbin}, but write it as
+@file{$(exec_prefix)/sbin}.
+(If you are using Autoconf, write it as @samp{@@sbindir@@}.)
+
+@item libexecdir
+@vindex libexecdir
+@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
+The directory for installing executable programs to be run by other
+programs rather than by users.  This directory should normally be
+@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
+(If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
+@end table
+
+Data files used by the program during its execution are divided into
+categories in two ways.
+
+@itemize @bullet
+@item
+Some files are normally modified by programs; others are never normally
+modified (though users may edit some of these).
+
+@item
+Some files are architecture-independent and can be shared by all
+machines at a site; some are architecture-dependent and can be shared
+only by machines of the same kind and operating system; others may never
+be shared between two machines.
+@end itemize
+
+This makes for six different possibilities.  However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries.  It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+Therefore, here are the variables Makefiles should use to specify
+directories:
+
+@table @samp
+@item datadir
+The directory for installing read-only architecture independent data
+files.  This should normally be @file{/usr/local/share}, but write it as
+@file{$(prefix)/share}.
+(If you are using Autoconf, write it as @samp{@@datadir@@}.)
+As a special exception, see @file{$(infodir)}
+and @file{$(includedir)} below.
+
+@item sysconfdir
+The directory for installing read-only data files that pertain to a
+single machine--that is to say, files for configuring a host.  Mailer
+and network configuration files, @file{/etc/passwd}, and so forth belong
+here.  All the files in this directory should be ordinary ASCII text
+files.  This directory should normally be @file{/usr/local/etc}, but
+write it as @file{$(prefix)/etc}.
+(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
+
+Do not install executables here in this directory (they probably belong
+in @file{$(libexecdir)} or @file{$(sbindir)}).  Also do not install
+files that are modified in the normal course of their use (programs
+whose purpose is to change the configuration of the system excluded).
+Those probably belong in @file{$(localstatedir)}.
+
+@item sharedstatedir
+The directory for installing architecture-independent data files which
+the programs modify while they run.  This should normally be
+@file{/usr/local/com}, but write it as @file{$(prefix)/com}.
+(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
+
+@item localstatedir
+The directory for installing data files which the programs modify while
+they run, and that pertain to one specific machine.  Users should never
+need to modify files in this directory to configure the package's
+operation; put such configuration information in separate files that go
+in @file{$(datadir)} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
+should normally be @file{/usr/local/var}, but write it as
+@file{$(prefix)/var}.
+(If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
+
+@item libdir
+The directory for object files and libraries of object code.  Do not
+install executables here, they probably ought to go in @file{$(libexecdir)}
+instead.  The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+(If you are using Autoconf, write it as @samp{@@libdir@@}.)
+
+@item infodir
+The directory for installing the Info files for this package.  By
+default, it should be @file{/usr/local/info}, but it should be written
+as @file{$(prefix)/info}.
+(If you are using Autoconf, write it as @samp{@@infodir@@}.)
+
+@item lispdir
+The directory for installing any Emacs Lisp files in this package.  By
+default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
+should be written as @file{$(prefix)/share/emacs/site-lisp}.
+
+If you are using Autoconf, write the default as @samp{@@lispdir@@}.
+In order to make @samp{@@lispdir@@} work, you need the following lines
+in your @file{configure.in} file:
+
+@example
+lispdir='$@{datadir@}/emacs/site-lisp'
+AC_SUBST(lispdir)
+@end example
+
+@item includedir
+@c rewritten to avoid overfull hbox --roland
+The directory for installing header files to be included by user
+programs with the C @samp{#include} preprocessor directive.  This
+should normally be @file{/usr/local/include}, but write it as
+@file{$(prefix)/include}.
+(If you are using Autoconf, write it as @samp{@@includedir@@}.)
+
+Most compilers other than GCC do not look for header files in directory
+@file{/usr/local/include}.  So installing the header files this way is
+only useful with GCC.  Sometimes this is not a problem because some
+libraries are only really intended to work with GCC.  But some libraries
+are intended to work with other compilers.  They should install their
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
+
+@item oldincludedir
+The directory for installing @samp{#include} header files for use with
+compilers other than GCC.  This should normally be @file{/usr/include}.
+(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
+
+The Makefile commands should check whether the value of
+@code{oldincludedir} is empty.  If it is, they should not try to use
+it; they should cancel the second installation of the header files.
+
+A package should not replace an existing header in this directory unless
+the header came from the same package.  Thus, if your Foo package
+provides a header file @file{foo.h}, then it should install the header
+file in the @code{oldincludedir} directory if either (1) there is no
+@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
+package.
+
+To tell whether @file{foo.h} came from the Foo package, put a magic
+string in the file---part of a comment---and @code{grep} for that string.
+@end table
+
+Unix-style man pages are installed in one of the following:
+
+@table @samp
+@item mandir
+The top-level directory for installing the man pages (if any) for this
+package.  It will normally be @file{/usr/local/man}, but you should
+write it as @file{$(prefix)/man}.
+(If you are using Autoconf, write it as @samp{@@mandir@@}.)
+
+@item man1dir
+The directory for installing section 1 man pages.  Write it as
+@file{$(mandir)/man1}.
+@item man2dir
+The directory for installing section 2 man pages.  Write it as
+@file{$(mandir)/man2}
+@item @dots{}
+
+@strong{Don't make the primary documentation for any GNU software be a
+man page.  Write a manual in Texinfo instead.  Man pages are just for
+the sake of people running GNU software on Unix, which is a secondary
+application only.}
+
+@item manext
+The file name extension for the installed man page.  This should contain
+a period followed by the appropriate digit; it should normally be @samp{.1}.
+
+@item man1ext
+The file name extension for installed section 1 man pages.
+@item man2ext
+The file name extension for installed section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{manext} if the package needs to install man
+pages in more than one section of the manual.
+@end table
+
+And finally, you should set the following variable:
+
+@table @samp
+@item srcdir
+The directory for the sources being compiled.  The value of this
+variable is normally inserted by the @code{configure} shell script.
+(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.)
+@end table
+
+For example:
+
+@smallexample
+@c I have changed some of the comments here slightly to fix an overfull
+@c hbox, so the make manual can format correctly. --roland
+# Common prefix for installation directories.
+# NOTE: This directory must exist when you start the install.
+prefix = /usr/local
+exec_prefix = $(prefix)
+# Where to put the executable for the command `gcc'.
+bindir = $(exec_prefix)/bin
+# Where to put the directories used by the compiler.
+libexecdir = $(exec_prefix)/libexec
+# Where to put the Info files.
+infodir = $(prefix)/info
+@end smallexample
+
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above.  The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+@node Standard Targets
+@section Standard Targets for Users
+
+All GNU programs should have the following targets in their Makefiles:
+
+@table @samp
+@item all
+Compile the entire program.  This should be the default target.  This
+target need not rebuild any documentation files; Info files should
+normally be included in the distribution, and DVI files should be made
+only when explicitly asked for.
+
+By default, the Make rules should compile and link with @samp{-g}, so
+that executable programs have debugging symbols.  Users who don't mind
+being helpless can strip the executables later if they wish.
+
+@item install
+Compile the program and copy the executables, libraries, and so on to
+the file names where they should reside for actual use.  If there is a
+simple test to verify that a program is properly installed, this target
+should run that test.
+
+Do not strip executables when installing them.  Devil-may-care users can
+use the @code{install-strip} target to do that.
+
+If possible, write the @code{install} target rule so that it does not
+modify anything in the directory where the program was built, provided
+@samp{make all} has just been done.  This is convenient for building the
+program under one user name and installing it under another.
+
+The commands should create all the directories in which files are to be
+installed, if they don't already exist.  This includes the directories
+specified as the values of the variables @code{prefix} and
+@code{exec_prefix}, as well as all subdirectories that are needed.
+One way to do this is by means of an @code{installdirs} target
+as described below.
+
+Use @samp{-} before any command for installing a man page, so that
+@code{make} will ignore any errors.  This is in case there are systems
+that don't have the Unix man page documentation system installed.
+
+The way to install Info files is to copy them into @file{$(infodir)}
+with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
+the @code{install-info} program if it is present.  @code{install-info}
+is a program that edits the Info @file{dir} file to add or update the
+menu entry for the given Info file; it is part of the Texinfo package.
+Here is a sample rule to install an Info file:
+
+@comment This example has been carefully formatted for the Make manual.
+@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
+@smallexample
+$(DESTDIR)$(infodir)/foo.info: foo.info
+        $(POST_INSTALL)
+# There may be a newer info file in . than in srcdir.
+        -if test -f foo.info; then d=.; \
+         else d=$(srcdir); fi; \
+        $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
+# Run install-info only if it exists.
+# Use `if' instead of just prepending `-' to the
+# line so we notice real errors from install-info.
+# We use `$(SHELL) -c' because some shells do not
+# fail gracefully when there is an unknown command.
+        if $(SHELL) -c 'install-info --version' \
+           >/dev/null 2>&1; then \
+          install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+                       $(DESTDIR)$(infodir)/foo.info; \
+        else true; fi
+@end smallexample
+
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.  @xref{Install Command
+Categories}.
+
+@item uninstall
+Delete all the installed files---the copies that the @samp{install}
+target creates.
+
+This rule should not modify the directories where compilation is done,
+only the directories where files are installed.
+
+The uninstallation commands are divided into three categories, just like
+the installation commands.  @xref{Install Command Categories}.
+
+@item install-strip
+Like @code{install}, but strip the executable files while installing
+them.  In simple cases, this target can use the @code{install} target in
+a simple way:
+
+@smallexample
+install-strip:
+        $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+                install
+@end smallexample
+
+But if the package installs scripts as well as real executables, the
+@code{install-strip} target can't just refer to the @code{install}
+target; it has to strip the executables but not the scripts.
+
+@code{install-strip} should not strip the executables in the build
+directory which are being copied for installation.  It should only strip
+the copies that are installed.
+
+Normally we do not recommend stripping an executable unless you are sure
+the program has no bugs.  However, it can be reasonable to install a
+stripped executable for actual execution while saving the unstripped
+executable elsewhere in case there is a bug.
+
+@comment The gratuitous blank line here is to make the table look better
+@comment in the printed Make manual.  Please leave it in.
+@item clean
+
+Delete all files from the current directory that are normally created by
+building the program.  Don't delete the files that record the
+configuration.  Also preserve files that could be made by building, but
+normally aren't because the distribution comes with them.
+
+Delete @file{.dvi} files here if they are not part of the distribution.
+
+@item distclean
+Delete all files from the current directory that are created by
+configuring or building the program.  If you have unpacked the source
+and built the program without creating any other files, @samp{make
+distclean} should leave only the files that were in the distribution.
+
+@item mostlyclean
+Like @samp{clean}, but may refrain from deleting a few files that people
+normally don't want to recompile.  For example, the @samp{mostlyclean}
+target for GCC does not delete @file{libgcc.a}, because recompiling it
+is rarely necessary and takes a lot of time.
+
+@item maintainer-clean
+Delete almost everything from the current directory that can be
+reconstructed with this Makefile.  This typically includes everything
+deleted by @code{distclean}, plus more: C source files produced by
+Bison, tags tables, Info files, and so on.
+
+The reason we say ``almost everything'' is that running the command
+@samp{make maintainer-clean} should not delete @file{configure} even if
+@file{configure} can be remade using a rule in the Makefile.  More generally,
+@samp{make maintainer-clean} should not delete anything that needs to
+exist in order to run @file{configure} and then begin to build the
+program.  This is the only exception; @code{maintainer-clean} should
+delete everything else that can be rebuilt.
+
+The @samp{maintainer-clean} target is intended to be used by a maintainer of
+the package, not by ordinary users.  You may need special tools to
+reconstruct some of the files that @samp{make maintainer-clean} deletes.
+Since these files are normally included in the distribution, we don't
+take care to make them easy to reconstruct.  If you find you need to
+unpack the full distribution again, don't blame us.
+
+To help make users aware of this, the commands for the special
+@code{maintainer-clean} target should start with these two:
+
+@smallexample
+@@echo 'This command is intended for maintainers to use; it'
+@@echo 'deletes files that may need special tools to rebuild.'
+@end smallexample
+
+@item TAGS
+Update a tags table for this program.
+@c ADR: how?
+
+@item info
+Generate any Info files needed.  The best way to write the rules is as
+follows:
+
+@smallexample
+info: foo.info
+
+foo.info: foo.texi chap1.texi chap2.texi
+        $(MAKEINFO) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{MAKEINFO} in the Makefile.  It should
+run the @code{makeinfo} program, which is part of the Texinfo
+distribution.
+
+Normally a GNU distribution comes with Info files, and that means the
+Info files are present in the source directory.  Therefore, the Make
+rule for an info file should update it in the source directory.  When
+users build the package, ordinarily Make will not update the Info files
+because they will already be up to date.
+
+@item dvi
+Generate DVI files for all Texinfo documentation.
+For example:
+
+@smallexample
+dvi: foo.dvi
+
+foo.dvi: foo.texi chap1.texi chap2.texi
+        $(TEXI2DVI) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{TEXI2DVI} in the Makefile.  It should
+run the program @code{texi2dvi}, which is part of the Texinfo
+distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
+of formatting. @TeX{} is not distributed with Texinfo.}  Alternatively,
+write just the dependencies, and allow GNU @code{make} to provide the command.
+
+@item dist
+Create a distribution tar file for this program.  The tar file should be
+set up so that the file names in the tar file start with a subdirectory
+name which is the name of the package it is a distribution for.  This
+name can include the version number.
+
+For example, the distribution tar file of GCC version 1.40 unpacks into
+a subdirectory named @file{gcc-1.40}.
+
+The easiest way to do this is to create a subdirectory appropriately
+named, use @code{ln} or @code{cp} to install the proper files in it, and
+then @code{tar} that subdirectory.
+
+Compress the tar file with @code{gzip}.  For example, the actual
+distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
+
+The @code{dist} target should explicitly depend on all non-source files
+that are in the distribution, to make sure they are up to date in the
+distribution.
+@ifset CODESTD
+@xref{Releases, , Making Releases}.
+@end ifset
+@ifclear CODESTD
+@xref{Releases, , Making Releases, standards, GNU Coding Standards}.
+@end ifclear
+
+@item check
+Perform self-tests (if any).  The user must build the program before
+running the tests, but need not install the program; you should write
+the self-tests so that they work when the program is built but not
+installed.
+@end table
+
+The following targets are suggested as conventional names, for programs
+in which they are useful.
+
+@table @code
+@item installcheck
+Perform installation tests (if any).  The user must build and install
+the program before running the tests.  You should not assume that
+@file{$(bindir)} is in the search path.
+
+@item installdirs
+It's useful to add a target named @samp{installdirs} to create the
+directories where files are installed, and their parent directories.
+There is a script called @file{mkinstalldirs} which is convenient for
+this; you can find it in the Texinfo package.
+@c It's in /gd/gnu/lib/mkinstalldirs.
+You can use a rule like this:
+
+@comment This has been carefully formatted to look decent in the Make manual.
+@comment Please be sure not to make it extend any further to the right.--roland
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+        $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+                                $(libdir) $(infodir) \
+                                $(mandir)
+@end smallexample
+
+@noindent
+or, if you wish to support @env{DESTDIR},
+
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+        $(srcdir)/mkinstalldirs \
+            $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+            $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+            $(DESTDIR)$(mandir)
+@end smallexample
+
+This rule should not modify the directories where compilation is done.
+It should do nothing but create installation directories.
+@end table
+
+@node Install Command Categories
+@section Install Command Categories
+
+@cindex pre-installation commands
+@cindex post-installation commands
+When writing the @code{install} target, you must classify all the
+commands into three categories: normal ones, @dfn{pre-installation}
+commands and @dfn{post-installation} commands.
+
+Normal commands move files into their proper places, and set their
+modes.  They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+Pre-installation and post-installation commands may alter other files;
+in particular, they can edit global configuration files or data bases.
+
+Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+The most common use for a post-installation command is to run
+@code{install-info}.  This cannot be done with a normal command, since
+it alters a file (the Info directory) which does not come entirely and
+solely from the package being installed.  It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+Most programs don't need any pre-installation commands, but we have the
+feature just in case it is needed.
+
+To classify the commands in the @code{install} rule into these three
+categories, insert @dfn{category lines} among them.  A category line
+specifies the category for the commands that follow.
+
+A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end.  There are three
+variables you can use, one for each category; the variable name
+specifies the category.  Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+@emph{should not} define them in the makefile).
+
+Here are the three possible category lines, each with a comment that
+explains what it means:
+
+@smallexample
+        $(PRE_INSTALL)     # @r{Pre-install commands follow.}
+        $(POST_INSTALL)    # @r{Post-install commands follow.}
+        $(NORMAL_INSTALL)  # @r{Normal commands follow.}
+@end smallexample
+
+If you don't use a category line at the beginning of the @code{install}
+rule, all the commands are classified as normal until the first category
+line.  If you don't use any category lines, all the commands are
+classified as normal.
+
+These are the category lines for @code{uninstall}:
+
+@smallexample
+        $(PRE_UNINSTALL)     # @r{Pre-uninstall commands follow.}
+        $(POST_UNINSTALL)    # @r{Post-uninstall commands follow.}
+        $(NORMAL_UNINSTALL)  # @r{Normal commands follow.}
+@end smallexample
+
+Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+If the @code{install} or @code{uninstall} target has any dependencies
+which act as subroutines of installation, then you should start
+@emph{each} dependency's commands with a category line, and start the
+main target's commands with a category line also.  This way, you can
+ensure that each command is placed in the right category regardless of
+which of the dependencies actually run.
+
+Pre-installation and post-installation commands should not run any
+programs except for these:
+
+@example
+[ basename bash cat chgrp chmod chown cmp cp dd diff echo
+egrep expand expr false fgrep find getopt grep gunzip gzip
+hostname install install-info kill ldconfig ln ls md5sum
+mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+test touch true uname xargs yes
+@end example
+
+@cindex binary packages
+The reason for distinguishing the commands in this way is for the sake
+of making binary packages.  Typically a binary package contains all the
+executables and other files that need to be installed, and has its own
+method of installing them---so it does not need to run the normal
+installation commands.  But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+Programs to build binary packages work by extracting the
+pre-installation and post-installation commands.  Here is one way of
+extracting the pre-installation commands:
+
+@smallexample
+make -n install -o all \
+      PRE_INSTALL=pre-install \
+      POST_INSTALL=post-install \
+      NORMAL_INSTALL=normal-install \
+  | gawk -f pre-install.awk
+@end smallexample
+
+@noindent
+where the file @file{pre-install.awk} could contain this:
+
+@smallexample
+$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
+on @{print $0@}
+$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
+@end smallexample
+
+The resulting file of pre-installation commands is executed as a shell
+script as part of installing the binary package.
diff --git a/doc/rename.sh b/doc/rename.sh
new file mode 100755
index 0000000..99b248c
--- /dev/null
+++ b/doc/rename.sh
@@ -0,0 +1,21 @@
+#!/bin/sh
+# The ac252 package renames the entries in an info directory section to avoid
+# install-time conflict with the regular autoconf package.  Newer versions of
+# install-info have a "--name" option which appears simpler, but does not solve
+# this particular problem -T.E.Dickey
+SRC=`echo "$1" | sed -e 's,^./,,'`
+DST=`echo "$2" | sed -e 's,^./,,'`
+SRC_NAME=`basename $SRC .info`
+DST_NAME=`basename $DST .info`
+if test "$SRC_NAME" != "$DST_NAME"
+then
+	PREFIX=`echo "$DST_NAME" | sed -e "s/$SRC_NAME.*$//"`
+	SUFFIX=`echo "$DST_NAME" | sed -e "s/^.*$SRC_NAME//"`
+
+	sed -e "s/^\*[ 	]*\([^ 	][^ 	]*\):[ 	]*($SRC_NAME)\(.\)/* $PREFIX\1$SUFFIX: ($DST_NAME)\2/" <$SRC | \
+	sed -e "s/^This is $SRC_NAME\.info,/This is $DST_NAME.info,/" |
+	sed -e "s/^File:[ 	]*$SRC_NAME\.info/File: $DST_NAME.info/" >$DST
+elif test "$SRC" != "$DST"
+then
+	cat $SRC >$DST
+fi
diff --git a/doc/stamp-vti b/doc/stamp-vti
new file mode 100644
index 0000000..d854139
--- /dev/null
+++ b/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 2 December 2023
+@set UPDATED-MONTH December 2023
+@set EDITION 2.52.20231210
+@set VERSION 2.52.20231210
diff --git a/doc/standards.info b/doc/standards.info
new file mode 100644
index 0000000..9e69fdc
--- /dev/null
+++ b/doc/standards.info
@@ -0,0 +1,4454 @@
+This is standards.info, produced by makeinfo version 6.3 from
+standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+
+   GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+
+File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
+
+Version
+*******
+
+Last updated March 23, 2001.
+
+* Menu:
+
+* Preface::                 About the GNU Coding Standards
+* Legal Issues::            Keeping Free Software Free
+* Design Advice::           General Program Design
+* Program Behavior::        Program Behavior for All Programs
+* Writing C::               Making The Best Use of C
+* Documentation::           Documenting Programs
+* Managing Releases::       The Release Process
+* References::              References to Non-Free Software or Documentation
+* Index::
+
+
+File: standards.info,  Node: Preface,  Next: Legal Issues,  Up: Top
+
+1 About the GNU Coding Standards
+********************************
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers.  Their purpose is to make the GNU system clean,
+consistent, and easy to install.  This document can also be read as a
+guide to writing portable, robust and reliable programs.  It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language.  The rules often
+state reasons for writing in a certain way.
+
+   This release of the GNU Coding Standards was last updated March 23,
+2001.
+
+   If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version.  You can ftp the GNU Coding
+Standards from any GNU FTP host in the directory '/pub/gnu/standards/'.
+The GNU Coding Standards are available there in several different
+formats: 'standards.text', 'standards.info', and 'standards.dvi', as
+well as the Texinfo "source" which is divided in two files:
+'standards.texi' and 'make-stds.texi'.  The GNU Coding Standards are
+also available on the GNU World Wide Web server:
+<http://www.gnu.org/prep/standards_toc.html>.
+
+   Corrections or suggestions for this document should be sent to
+<bug-standards@gnu.org>.  If you make a suggestion, please include a
+suggested new wording for it; our time is limited.  We prefer a context
+diff to the 'standards.texi' or 'make-stds.texi' files, but if you don't
+have those files, please mail your suggestion anyway.
+
+
+File: standards.info,  Node: Legal Issues,  Next: Design Advice,  Prev: Preface,  Up: Top
+
+2 Keeping Free Software Free
+****************************
+
+This node discusses how you can make sure that GNU software avoids legal
+difficulties, and other related issues.
+
+* Menu:
+
+* Reading Non-Free Code::       Referring to Proprietary Programs
+* Contributions::               Accepting Contributions
+* Trademarks::                  How We Deal with Trademark Issues
+
+
+File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Up: Legal Issues
+
+2.1 Referring to Proprietary Programs
+=====================================
+
+Don't in any circumstances refer to Unix source code for or during your
+work on GNU! (Or to any other proprietary programs.)
+
+   If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but do
+try to organize the imitation internally along different lines, because
+this is likely to make the details of the Unix version irrelevant and
+dissimilar to your results.
+
+   For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different.  You could keep the entire input file in core and scan it
+there instead of using stdio.  Use a smarter algorithm discovered more
+recently than the Unix program.  Eliminate use of temporary files.  Do
+it in one pass instead of two (we did this in the assembler).
+
+   Or, on the contrary, emphasize simplicity instead of speed.  For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+   Or go for generality.  For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead.  Make sure your program handles NULs and
+other funny characters in the input files.  Add a programming language
+for extensibility and write part of the program in that language.
+
+   Or turn some parts of the program into independently usable
+libraries.  Or use a simple garbage collector instead of tracking
+precisely when to free memory, or use a new GNU facility such as
+obstacks.
+
+
+File: standards.info,  Node: Contributions,  Next: Trademarks,  Prev: Reading Non-Free Code,  Up: Legal Issues
+
+2.2 Accepting Contributions
+===========================
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it--just as we asked you to
+sign papers initially.  _Each_ person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+   So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers.  Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+   This applies both before you release the program and afterward.  If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+   This also applies to comments and documentation files.  For copyright
+law, comments and code are just text.  Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+   We know it is frustrating to ask for legal papers; it's frustrating
+for us as well.  But if you don't wait, you are going out on a limb--for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+   You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes.  Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use.  For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+   The very worst thing is if you forget to tell us about the other
+contributor.  We could be very embarrassed in court some day as a
+result.
+
+   We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+
+File: standards.info,  Node: Trademarks,  Prev: Contributions,  Up: Legal Issues
+
+2.3 Trademarks
+==============
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+   Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so.  The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them.  There is no legal requirement for them.
+
+   What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities.  For example, since "Objective C" is (or
+at least was) a trademark, we made sure to say that we provide a
+"compiler for the Objective C language" rather than an "Objective C
+compiler".  The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using "Objective C" as a label for the compiler rather than for the
+language.
+
+
+File: standards.info,  Node: Design Advice,  Next: Program Behavior,  Prev: Legal Issues,  Up: Top
+
+3 General Program Design
+************************
+
+This node discusses some of the issues you should take into account when
+designing your program.
+
+* Menu:
+
+* Source Language::             Which languages to use.
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* Standard C::                  Using Standard C features
+
+
+File: standards.info,  Node: Source Language,  Next: Compatibility,  Up: Design Advice
+
+3.1 Which Languages to Use
+==========================
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C. Using another language is like
+using a non-standard feature: it will cause trouble for users.  Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program.  For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+   C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+   So in general it is much better to use C, rather than the comparable
+alternatives.
+
+   But there are two exceptions to that conclusion:
+
+   * It is no problem to use another language to write a tool
+     specifically intended for use with that language.  That is because
+     the only people who want to build the tool will be those who have
+     installed the other language anyway.
+
+   * If an application is of interest only to a narrow part of the
+     community, then the question of which language it is written in has
+     less effect on other people, so you may as well please yourself.
+
+   Many programs are designed to be extensible: they include an
+interpreter for a language that is higher level than C. Often much of
+the program is written in that language, too.  The Emacs editor
+pioneered this technique.
+
+   The standard extensibility interpreter for GNU software is GUILE,
+which implements the language Scheme (an especially clean and simple
+dialect of Lisp).  <http://www.gnu.org/software/guile/>.  We don't
+reject programs written in other "scripting languages" such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+
+File: standards.info,  Node: Compatibility,  Next: Using Extensions,  Prev: Source Language,  Up: Design Advice
+
+3.2 Compatibility with Other Implementations
+============================================
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their behavior, and
+upward compatible with POSIX if POSIX specifies their behavior.
+
+   When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+   Standard C and POSIX prohibit many kinds of extensions.  Feel free to
+make the extensions anyway, and include a '--ansi', '--posix', or
+'--compatible' option to turn them off.  However, if the extension has a
+significant chance of breaking any real programs or scripts, then it is
+not really upward compatible.  So you should try to redesign its
+interface to make it upward compatible.
+
+   Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable 'POSIXLY_CORRECT' is defined (even if it is defined
+with a null value).  Please make your program recognize this variable if
+appropriate.
+
+   When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+'vi' is replaced with Emacs.)  But it is nice to offer a compatible
+feature as well.  (There is a free 'vi' clone, so we offer it.)
+
+   Additional useful features are welcome regardless of whether there is
+any precedent for them.
+
+
+File: standards.info,  Node: Using Extensions,  Next: Standard C,  Prev: Compatibility,  Up: Design Advice
+
+3.3 Using Non-standard Features
+===============================
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities.  Whether to use these
+extensions in implementing your program is a difficult question.
+
+   On the one hand, using the extensions can make a cleaner program.  On
+the other hand, people will not be able to build the program unless the
+other GNU tools are available.  This might cause the program to work on
+fewer kinds of machines.
+
+   With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a "keyword" 'INLINE' and
+define that as a macro to expand into either 'inline' or nothing,
+depending on the compiler.
+
+   In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they are
+a big improvement.
+
+   An exception to this rule are the large, established programs (such
+as Emacs) which run on a great variety of systems.  Using GNU extensions
+in such programs would make many users unhappy, so we don't do that.
+
+   Another exception is for programs that are used as part of
+compilation: anything that must be compiled with other compilers in
+order to bootstrap the GNU compilation facilities.  If these require the
+GNU compiler, then no one can compile them without having them installed
+already.  That would be extremely troublesome in certain cases.
+
+
+File: standards.info,  Node: Standard C,  Prev: Using Extensions,  Up: Design Advice
+
+3.4 Standard C and Pre-Standard C
+=================================
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs.  There is one exception: do not ever use the
+"trigraph" feature of Standard C.
+
+   1999 Standard C is not widespread yet, so please do not require its
+features in programs.  It is ok to use its features if they are present.
+
+   However, it is easy to support pre-standard compilers in most
+programs, so if you know how to do that, feel free.  If a program you
+are maintaining has such support, you should try to keep it working.
+
+   To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+     int
+     foo (int x, int y)
+     ...
+
+write the definition in pre-standard style like this,
+
+     int
+     foo (x, y)
+          int x, y;
+     ...
+
+and use a separate declaration to specify the argument prototype:
+
+     int foo (int, int);
+
+   You need such a declaration anyway, in a header file, to get the
+benefit of prototypes in all the files where the function is called.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-standard style.
+
+   This technique does not work for integer types narrower than 'int'.
+If you think of an argument as being of a type narrower than 'int',
+declare it as 'int' instead.
+
+   There are a few special cases where this technique is hard to use.
+For example, if a function argument needs to hold the system type
+'dev_t', you run into trouble, because 'dev_t' is shorter than 'int' on
+some machines; but you cannot use 'int' instead, because 'dev_t' is
+wider than 'int' on some machines.  There is no type you can safely use
+on all machines in a non-standard definition.  The only way to support
+non-standard C and pass such an argument is to check the width of
+'dev_t' using Autoconf and choose the argument type accordingly.  This
+may not be worth the trouble.
+
+   In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+     /* Declare the prototype for a general external function.  */
+     #if defined (__STDC__) || defined (WINDOWSNT)
+     #define P_(proto) proto
+     #else
+     #define P_(proto) ()
+     #endif
+
+
+File: standards.info,  Node: Program Behavior,  Next: Writing C,  Prev: Design Advice,  Up: Top
+
+4 Program Behavior for All Programs
+***********************************
+
+This node describes conventions for writing robust software.  It also
+describes general standards for error messages, the command line
+interface, and how libraries should behave.
+
+* Menu:
+
+* Semantics::                   Writing robust programs
+* Libraries::                   Library behavior
+* Errors::                      Formatting error messages
+* User Interfaces::             Standards about interfaces generally
+* Graphical Interfaces::        Standards for graphical interfaces
+* Command-Line Interfaces::     Standards for command line interfaces
+* Option Table::                Table of long options
+* Memory Usage::                When and how to care about memory needs
+* File Usage::                  Which files to use, and where
+
+
+File: standards.info,  Node: Semantics,  Next: Libraries,  Up: Program Behavior
+
+4.1 Writing Robust Programs
+===========================
+
+Avoid arbitrary limits on the length or number of _any_ data structure,
+including file names, lines, files, and symbols, by allocating all data
+structures dynamically.  In most Unix utilities, "long lines are
+silently truncated".  This is not acceptable in a GNU utility.
+
+   Utilities reading files should not drop NUL characters, or any other
+nonprinting characters _including those with codes above 0177_.  The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of terminals or printers that can't handle
+those characters.  Whenever possible, try to make programs work properly
+with sequences of bytes that represent multibyte characters, using
+encodings such as UTF-8 and others.
+
+   Check every system call for an error return, unless you know you wish
+to ignore errors.  Include the system error text (from 'perror' or
+equivalent) in _every_ error message resulting from a failing system
+call, as well as the name of the file if any and the name of the
+utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.
+
+   Check every call to 'malloc' or 'realloc' to see if it returned zero.
+Check 'realloc' even if you are making the block smaller; in a system
+that rounds block sizes to a power of 2, 'realloc' may get a different
+block if you ask for less space.
+
+   In Unix, 'realloc' can destroy the storage block if it returns zero.
+GNU 'realloc' does not have this bug: if it fails, the original block is
+unchanged.  Feel free to assume the bug is fixed.  If you wish to run
+your program on Unix, and wish to avoid lossage in this case, you can
+use the GNU 'malloc'.
+
+   You must expect 'free' to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling 'free'.
+
+   If 'malloc' fails in a noninteractive program, make that a fatal
+error.  In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.  This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+   Use 'getopt_long' to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+   When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+
+   Try to avoid low-level interfaces to obscure Unix data structures
+(such as file directories, utmp, or the layout of kernel memory), since
+these are less likely to work compatibly.  If you need to find all the
+files in a directory, use 'readdir' or some other high-level interface.
+These are supported compatibly by GNU.
+
+   The preferred signal handling facilities are the BSD variant of
+'signal', and the POSIX 'sigaction' function; the alternative USG
+'signal' interface is an inferior design.
+
+   Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable.  If you use 'signal', then on GNU/Linux systems
+running GNU libc version 1, you should include 'bsd/signal.h' instead of
+'signal.h', so as to get BSD behavior.  It is up to you whether to
+support systems where 'signal' has only the USG behavior, or give up on
+them.
+
+   In error checks that detect "impossible" conditions, just abort.
+There is usually no point in printing any message.  These checks
+indicate the existence of bugs.  Whoever wants to fix the bugs will have
+to read the source code and run a debugger.  So explain the problem with
+comments in the source.  The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+   Do not use a count of errors as the exit status for a program.  _That
+does not work_, because exit status values are limited to 8 bits (0
+through 255).  A single run of the program might have 256 errors; if you
+try to return 256 as the exit status, the parent process will see 0 as
+the status, and it will appear that the program succeeded.
+
+   If you make temporary files, check the 'TMPDIR' environment variable;
+if that variable is defined, use the specified directory instead of
+'/tmp'.
+
+   In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories.  In C, you can
+avoid this problem by creating temporary files in this manner:
+
+     fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the 'mkstemps' function from libiberty.
+
+   In bash, use 'set -C' to avoid this problem.
+
+
+File: standards.info,  Node: Libraries,  Next: Errors,  Prev: Semantics,  Up: Program Behavior
+
+4.2 Library Behavior
+====================
+
+Try to make library functions reentrant.  If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of 'malloc' itself.
+
+   Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+   Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this prefix.
+In addition, there should only be one of these in any given library
+member.  This usually means putting each one in a separate source file.
+
+   An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the other;
+then they can both go in the same file.
+
+   External symbols that are not documented entry points for the user
+should have names beginning with '_'.  The '_' should be followed by the
+chosen name prefix for the library, to prevent collisions with other
+libraries.  These can go in the same files with user entry points if you
+like.
+
+   Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+
+File: standards.info,  Node: Errors,  Next: User Interfaces,  Prev: Libraries,  Up: Program Behavior
+
+4.3 Formatting Error Messages
+=============================
+
+Error messages from compilers should look like this:
+
+     SOURCE-FILE-NAME:LINENO: MESSAGE
+
+If you want to mention the column number, use this format:
+
+     SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line.  (Both
+of these conventions are chosen for compatibility.)  Calculate column
+numbers assuming that space and all ASCII printing characters have equal
+width, and assuming tab stops every 8 columns.
+
+   Error messages from other noninteractive programs should look like
+this:
+
+     PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+     PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+   If you want to mention the column number, use this format:
+
+     PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+   In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+   The string MESSAGE should not begin with a capital letter when it
+follows a program name and/or file name.  Also, it should not end with a
+period.
+
+   Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter.  But they should not
+end with a period.
+
+
+File: standards.info,  Node: User Interfaces,  Next: Graphical Interfaces,  Prev: Errors,  Up: Program Behavior
+
+4.4 Standards for Interfaces Generally
+======================================
+
+Please don't make the behavior of a utility depend on the name used to
+invoke it.  It is useful sometimes to make a link to a utility with a
+different name, and that should not change what it does.
+
+   Instead, use a run time option or a compilation switch or both to
+select among the alternate behaviors.
+
+   Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with.  Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then.  (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+   If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+   Compatibility requires certain programs to depend on the type of
+output device.  It would be disastrous if 'ls' or 'sh' did not do so in
+the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a 'dir' program much like
+'ls' except that its default output format is always multi-column
+format.
+
+
+File: standards.info,  Node: Graphical Interfaces,  Next: Command-Line Interfaces,  Prev: User Interfaces,  Up: Program Behavior
+
+4.5 Standards for Graphical Interfaces
+======================================
+
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+"displaying jpeg images while in console mode").
+
+   In addition, please provide a command-line interface to control the
+functionality.  (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.)  This is so
+that the same jobs can be done from scripts.
+
+   Please also consider providing a CORBA interface (for use from
+GNOME), a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console mode).
+Once you are doing the work to provide the functionality and the
+graphical interface, these won't be much extra work.
+
+
+File: standards.info,  Node: Command-Line Interfaces,  Next: Option Table,  Prev: Graphical Interfaces,  Up: Program Behavior
+
+4.6 Standards for Command Line Interfaces
+=========================================
+
+It is a good idea to follow the POSIX guidelines for the command-line
+options of a program.  The easiest way to do this is to use 'getopt' to
+parse them.  Note that the GNU version of 'getopt' will normally permit
+options anywhere among the arguments unless the special argument '--' is
+used.  This is not what POSIX specifies; it is a GNU extension.
+
+   Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+'getopt_long'.
+
+   One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the "verbose" option of any GNU program which has one, to be
+spelled precisely '--verbose'.  To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program (*note Option Table::).
+
+   It is usually a good idea for file names given as ordinary arguments
+to be input files only; any output files would be specified using
+options (preferably '-o' or '--output').  Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it.  This will lead to more consistency
+among GNU utilities, and fewer idiosyncrasies for users to remember.
+
+   All programs should support two standard options: '--version' and
+'--help'.
+
+'--version'
+     This option should direct the program to print information about
+     its name, version, origin and legal status, all on standard output,
+     and then exit successfully.  Other options and arguments should be
+     ignored once this is seen, and the program should not perform its
+     normal function.
+
+     The first line is meant to be easy for a program to parse; the
+     version number proper starts after the last space.  In addition, it
+     contains the canonical name for this program, in this format:
+
+          GNU Emacs 19.30
+
+     The program's name should be a constant string; _don't_ compute it
+     from 'argv[0]'.  The idea is to state the standard or canonical
+     name for the program, not its file name.  There are other ways to
+     find out the precise file name where a command is found in 'PATH'.
+
+     If the program is a subsidiary part of a larger package, mention
+     the package name in parentheses, like this:
+
+          emacsserver (GNU Emacs) 19.30
+
+     If the package has a version number which is different from this
+     program's version number, you can mention the package version
+     number just before the close-parenthesis.
+
+     If you *need* to mention the version numbers of libraries which are
+     distributed separately from the package which contains this
+     program, you can do so by printing an additional line of version
+     info for each library you want to mention.  Use the same format for
+     these lines as for the first line.
+
+     Please do not mention all of the libraries that the program uses
+     "just for completeness"--that would produce a lot of unhelpful
+     clutter.  Please mention library version numbers only if you find
+     in practice that they are very important to you in debugging.
+
+     The following line, after the version number line or lines, should
+     be a copyright notice.  If more than one copyright notice is called
+     for, put each on a separate line.
+
+     Next should follow a brief statement that the program is free
+     software, and that users are free to copy and change it on certain
+     conditions.  If the program is covered by the GNU GPL, say so here.
+     Also mention that there is no warranty, to the extent permitted by
+     law.
+
+     It is ok to finish the output with a list of the major authors of
+     the program, as a way of giving credit.
+
+     Here's an example of output that follows these rules:
+
+          GNU Emacs 19.34.5
+          Copyright (C) 1996 Free Software Foundation, Inc.
+          GNU Emacs comes with NO WARRANTY,
+          to the extent permitted by law.
+          You may redistribute copies of GNU Emacs
+          under the terms of the GNU General Public License.
+          For more information about these matters,
+          see the files named COPYING.
+
+     You should adapt this to your program, of course, filling in the
+     proper year, copyright holder, name of program, and the references
+     to distribution terms, and changing the rest of the wording as
+     necessary.
+
+     This copyright notice only needs to mention the most recent year in
+     which changes were made--there's no need to list the years for
+     previous versions' changes.  You don't have to mention the name of
+     the program in these notices, if that is inconvenient, since it
+     appeared in the first line.
+
+'--help'
+     This option should output brief documentation for how to invoke the
+     program, on standard output, then exit successfully.  Other options
+     and arguments should be ignored once this is seen, and the program
+     should not perform its normal function.
+
+     Near the end of the '--help' option's output there should be a line
+     that says where to mail bug reports.  It should have this format:
+
+          Report bugs to MAILING-ADDRESS.
+
+
+File: standards.info,  Node: Option Table,  Next: Memory Usage,  Prev: Command-Line Interfaces,  Up: Program Behavior
+
+4.7 Table of Long Options
+=========================
+
+Here is a table of long options used by GNU programs.  It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with.  If you use names not already in the table,
+please send <bug-standards@gnu.org> a list of them, with their meanings,
+so we can update the table.
+
+'after-date'
+     '-N' in 'tar'.
+
+'all'
+     '-a' in 'du', 'ls', 'nm', 'stty', 'uname', and 'unexpand'.
+
+'all-text'
+     '-a' in 'diff'.
+
+'almost-all'
+     '-A' in 'ls'.
+
+'append'
+     '-a' in 'etags', 'tee', 'time'; '-r' in 'tar'.
+
+'archive'
+     '-a' in 'cp'.
+
+'archive-name'
+     '-n' in 'shar'.
+
+'arglength'
+     '-l' in 'm4'.
+
+'ascii'
+     '-a' in 'diff'.
+
+'assign'
+     '-v' in 'gawk'.
+
+'assume-new'
+     '-W' in Make.
+
+'assume-old'
+     '-o' in Make.
+
+'auto-check'
+     '-a' in 'recode'.
+
+'auto-pager'
+     '-a' in 'wdiff'.
+
+'auto-reference'
+     '-A' in 'ptx'.
+
+'avoid-wraps'
+     '-n' in 'wdiff'.
+
+'background'
+     For server programs, run in the background.
+
+'backward-search'
+     '-B' in 'ctags'.
+
+'basename'
+     '-f' in 'shar'.
+
+'batch'
+     Used in GDB.
+
+'baud'
+     Used in GDB.
+
+'before'
+     '-b' in 'tac'.
+
+'binary'
+     '-b' in 'cpio' and 'diff'.
+
+'bits-per-code'
+     '-b' in 'shar'.
+
+'block-size'
+     Used in 'cpio' and 'tar'.
+
+'blocks'
+     '-b' in 'head' and 'tail'.
+
+'break-file'
+     '-b' in 'ptx'.
+
+'brief'
+     Used in various programs to make output shorter.
+
+'bytes'
+     '-c' in 'head', 'split', and 'tail'.
+
+'c++'
+     '-C' in 'etags'.
+
+'catenate'
+     '-A' in 'tar'.
+
+'cd'
+     Used in various programs to specify the directory to use.
+
+'changes'
+     '-c' in 'chgrp' and 'chown'.
+
+'classify'
+     '-F' in 'ls'.
+
+'colons'
+     '-c' in 'recode'.
+
+'command'
+     '-c' in 'su'; '-x' in GDB.
+
+'compare'
+     '-d' in 'tar'.
+
+'compat'
+     Used in 'gawk'.
+
+'compress'
+     '-Z' in 'tar' and 'shar'.
+
+'concatenate'
+     '-A' in 'tar'.
+
+'confirmation'
+     '-w' in 'tar'.
+
+'context'
+     Used in 'diff'.
+
+'copyleft'
+     '-W copyleft' in 'gawk'.
+
+'copyright'
+     '-C' in 'ptx', 'recode', and 'wdiff'; '-W copyright' in 'gawk'.
+
+'core'
+     Used in GDB.
+
+'count'
+     '-q' in 'who'.
+
+'count-links'
+     '-l' in 'du'.
+
+'create'
+     Used in 'tar' and 'cpio'.
+
+'cut-mark'
+     '-c' in 'shar'.
+
+'cxref'
+     '-x' in 'ctags'.
+
+'date'
+     '-d' in 'touch'.
+
+'debug'
+     '-d' in Make and 'm4'; '-t' in Bison.
+
+'define'
+     '-D' in 'm4'.
+
+'defines'
+     '-d' in Bison and 'ctags'.
+
+'delete'
+     '-D' in 'tar'.
+
+'dereference'
+     '-L' in 'chgrp', 'chown', 'cpio', 'du', 'ls', and 'tar'.
+
+'dereference-args'
+     '-D' in 'du'.
+
+'device'
+     Specify an I/O device (special file name).
+
+'diacritics'
+     '-d' in 'recode'.
+
+'dictionary-order'
+     '-d' in 'look'.
+
+'diff'
+     '-d' in 'tar'.
+
+'digits'
+     '-n' in 'csplit'.
+
+'directory'
+     Specify the directory to use, in various programs.  In 'ls', it
+     means to show directories themselves rather than their contents.
+     In 'rm' and 'ln', it means to not treat links to directories
+     specially.
+
+'discard-all'
+     '-x' in 'strip'.
+
+'discard-locals'
+     '-X' in 'strip'.
+
+'dry-run'
+     '-n' in Make.
+
+'ed'
+     '-e' in 'diff'.
+
+'elide-empty-files'
+     '-z' in 'csplit'.
+
+'end-delete'
+     '-x' in 'wdiff'.
+
+'end-insert'
+     '-z' in 'wdiff'.
+
+'entire-new-file'
+     '-N' in 'diff'.
+
+'environment-overrides'
+     '-e' in Make.
+
+'eof'
+     '-e' in 'xargs'.
+
+'epoch'
+     Used in GDB.
+
+'error-limit'
+     Used in 'makeinfo'.
+
+'error-output'
+     '-o' in 'm4'.
+
+'escape'
+     '-b' in 'ls'.
+
+'exclude-from'
+     '-X' in 'tar'.
+
+'exec'
+     Used in GDB.
+
+'exit'
+     '-x' in 'xargs'.
+
+'exit-0'
+     '-e' in 'unshar'.
+
+'expand-tabs'
+     '-t' in 'diff'.
+
+'expression'
+     '-e' in 'sed'.
+
+'extern-only'
+     '-g' in 'nm'.
+
+'extract'
+     '-i' in 'cpio'; '-x' in 'tar'.
+
+'faces'
+     '-f' in 'finger'.
+
+'fast'
+     '-f' in 'su'.
+
+'fatal-warnings'
+     '-E' in 'm4'.
+
+'file'
+     '-f' in 'info', 'gawk', Make, 'mt', and 'tar'; '-n' in 'sed'; '-r'
+     in 'touch'.
+
+'field-separator'
+     '-F' in 'gawk'.
+
+'file-prefix'
+     '-b' in Bison.
+
+'file-type'
+     '-F' in 'ls'.
+
+'files-from'
+     '-T' in 'tar'.
+
+'fill-column'
+     Used in 'makeinfo'.
+
+'flag-truncation'
+     '-F' in 'ptx'.
+
+'fixed-output-files'
+     '-y' in Bison.
+
+'follow'
+     '-f' in 'tail'.
+
+'footnote-style'
+     Used in 'makeinfo'.
+
+'force'
+     '-f' in 'cp', 'ln', 'mv', and 'rm'.
+
+'force-prefix'
+     '-F' in 'shar'.
+
+'foreground'
+     For server programs, run in the foreground; in other words, don't
+     do anything special to run the server in the background.
+
+'format'
+     Used in 'ls', 'time', and 'ptx'.
+
+'freeze-state'
+     '-F' in 'm4'.
+
+'fullname'
+     Used in GDB.
+
+'gap-size'
+     '-g' in 'ptx'.
+
+'get'
+     '-x' in 'tar'.
+
+'graphic'
+     '-i' in 'ul'.
+
+'graphics'
+     '-g' in 'recode'.
+
+'group'
+     '-g' in 'install'.
+
+'gzip'
+     '-z' in 'tar' and 'shar'.
+
+'hashsize'
+     '-H' in 'm4'.
+
+'header'
+     '-h' in 'objdump' and 'recode'
+
+'heading'
+     '-H' in 'who'.
+
+'help'
+     Used to ask for brief usage information.
+
+'here-delimiter'
+     '-d' in 'shar'.
+
+'hide-control-chars'
+     '-q' in 'ls'.
+
+'html'
+     In 'makeinfo', output HTML.
+
+'idle'
+     '-u' in 'who'.
+
+'ifdef'
+     '-D' in 'diff'.
+
+'ignore'
+     '-I' in 'ls'; '-x' in 'recode'.
+
+'ignore-all-space'
+     '-w' in 'diff'.
+
+'ignore-backups'
+     '-B' in 'ls'.
+
+'ignore-blank-lines'
+     '-B' in 'diff'.
+
+'ignore-case'
+     '-f' in 'look' and 'ptx'; '-i' in 'diff' and 'wdiff'.
+
+'ignore-errors'
+     '-i' in Make.
+
+'ignore-file'
+     '-i' in 'ptx'.
+
+'ignore-indentation'
+     '-I' in 'etags'.
+
+'ignore-init-file'
+     '-f' in Oleo.
+
+'ignore-interrupts'
+     '-i' in 'tee'.
+
+'ignore-matching-lines'
+     '-I' in 'diff'.
+
+'ignore-space-change'
+     '-b' in 'diff'.
+
+'ignore-zeros'
+     '-i' in 'tar'.
+
+'include'
+     '-i' in 'etags'; '-I' in 'm4'.
+
+'include-dir'
+     '-I' in Make.
+
+'incremental'
+     '-G' in 'tar'.
+
+'info'
+     '-i', '-l', and '-m' in Finger.
+
+'init-file'
+     In some programs, specify the name of the file to read as the
+     user's init file.
+
+'initial'
+     '-i' in 'expand'.
+
+'initial-tab'
+     '-T' in 'diff'.
+
+'inode'
+     '-i' in 'ls'.
+
+'interactive'
+     '-i' in 'cp', 'ln', 'mv', 'rm'; '-e' in 'm4'; '-p' in 'xargs'; '-w'
+     in 'tar'.
+
+'intermix-type'
+     '-p' in 'shar'.
+
+'iso-8601'
+     Used in 'date'
+
+'jobs'
+     '-j' in Make.
+
+'just-print'
+     '-n' in Make.
+
+'keep-going'
+     '-k' in Make.
+
+'keep-files'
+     '-k' in 'csplit'.
+
+'kilobytes'
+     '-k' in 'du' and 'ls'.
+
+'language'
+     '-l' in 'etags'.
+
+'less-mode'
+     '-l' in 'wdiff'.
+
+'level-for-gzip'
+     '-g' in 'shar'.
+
+'line-bytes'
+     '-C' in 'split'.
+
+'lines'
+     Used in 'split', 'head', and 'tail'.
+
+'link'
+     '-l' in 'cpio'.
+
+'lint'
+'lint-old'
+     Used in 'gawk'.
+
+'list'
+     '-t' in 'cpio'; '-l' in 'recode'.
+
+'list'
+     '-t' in 'tar'.
+
+'literal'
+     '-N' in 'ls'.
+
+'load-average'
+     '-l' in Make.
+
+'login'
+     Used in 'su'.
+
+'machine'
+     No listing of which programs already use this; someone should check
+     to see if any actually do, and tell <gnu@gnu.org>.
+
+'macro-name'
+     '-M' in 'ptx'.
+
+'mail'
+     '-m' in 'hello' and 'uname'.
+
+'make-directories'
+     '-d' in 'cpio'.
+
+'makefile'
+     '-f' in Make.
+
+'mapped'
+     Used in GDB.
+
+'max-args'
+     '-n' in 'xargs'.
+
+'max-chars'
+     '-n' in 'xargs'.
+
+'max-lines'
+     '-l' in 'xargs'.
+
+'max-load'
+     '-l' in Make.
+
+'max-procs'
+     '-P' in 'xargs'.
+
+'mesg'
+     '-T' in 'who'.
+
+'message'
+     '-T' in 'who'.
+
+'minimal'
+     '-d' in 'diff'.
+
+'mixed-uuencode'
+     '-M' in 'shar'.
+
+'mode'
+     '-m' in 'install', 'mkdir', and 'mkfifo'.
+
+'modification-time'
+     '-m' in 'tar'.
+
+'multi-volume'
+     '-M' in 'tar'.
+
+'name-prefix'
+     '-a' in Bison.
+
+'nesting-limit'
+     '-L' in 'm4'.
+
+'net-headers'
+     '-a' in 'shar'.
+
+'new-file'
+     '-W' in Make.
+
+'no-builtin-rules'
+     '-r' in Make.
+
+'no-character-count'
+     '-w' in 'shar'.
+
+'no-check-existing'
+     '-x' in 'shar'.
+
+'no-common'
+     '-3' in 'wdiff'.
+
+'no-create'
+     '-c' in 'touch'.
+
+'no-defines'
+     '-D' in 'etags'.
+
+'no-deleted'
+     '-1' in 'wdiff'.
+
+'no-dereference'
+     '-d' in 'cp'.
+
+'no-inserted'
+     '-2' in 'wdiff'.
+
+'no-keep-going'
+     '-S' in Make.
+
+'no-lines'
+     '-l' in Bison.
+
+'no-piping'
+     '-P' in 'shar'.
+
+'no-prof'
+     '-e' in 'gprof'.
+
+'no-regex'
+     '-R' in 'etags'.
+
+'no-sort'
+     '-p' in 'nm'.
+
+'no-split'
+     Used in 'makeinfo'.
+
+'no-static'
+     '-a' in 'gprof'.
+
+'no-time'
+     '-E' in 'gprof'.
+
+'no-timestamp'
+     '-m' in 'shar'.
+
+'no-validate'
+     Used in 'makeinfo'.
+
+'no-wait'
+     Used in 'emacsclient'.
+
+'no-warn'
+     Used in various programs to inhibit warnings.
+
+'node'
+     '-n' in 'info'.
+
+'nodename'
+     '-n' in 'uname'.
+
+'nonmatching'
+     '-f' in 'cpio'.
+
+'nstuff'
+     '-n' in 'objdump'.
+
+'null'
+     '-0' in 'xargs'.
+
+'number'
+     '-n' in 'cat'.
+
+'number-nonblank'
+     '-b' in 'cat'.
+
+'numeric-sort'
+     '-n' in 'nm'.
+
+'numeric-uid-gid'
+     '-n' in 'cpio' and 'ls'.
+
+'nx'
+     Used in GDB.
+
+'old-archive'
+     '-o' in 'tar'.
+
+'old-file'
+     '-o' in Make.
+
+'one-file-system'
+     '-l' in 'tar', 'cp', and 'du'.
+
+'only-file'
+     '-o' in 'ptx'.
+
+'only-prof'
+     '-f' in 'gprof'.
+
+'only-time'
+     '-F' in 'gprof'.
+
+'options'
+     '-o' in 'getopt', 'fdlist', 'fdmount', 'fdmountd', and 'fdumount'.
+
+'output'
+     In various programs, specify the output file name.
+
+'output-prefix'
+     '-o' in 'shar'.
+
+'override'
+     '-o' in 'rm'.
+
+'overwrite'
+     '-c' in 'unshar'.
+
+'owner'
+     '-o' in 'install'.
+
+'paginate'
+     '-l' in 'diff'.
+
+'paragraph-indent'
+     Used in 'makeinfo'.
+
+'parents'
+     '-p' in 'mkdir' and 'rmdir'.
+
+'pass-all'
+     '-p' in 'ul'.
+
+'pass-through'
+     '-p' in 'cpio'.
+
+'port'
+     '-P' in 'finger'.
+
+'portability'
+     '-c' in 'cpio' and 'tar'.
+
+'posix'
+     Used in 'gawk'.
+
+'prefix-builtins'
+     '-P' in 'm4'.
+
+'prefix'
+     '-f' in 'csplit'.
+
+'preserve'
+     Used in 'tar' and 'cp'.
+
+'preserve-environment'
+     '-p' in 'su'.
+
+'preserve-modification-time'
+     '-m' in 'cpio'.
+
+'preserve-order'
+     '-s' in 'tar'.
+
+'preserve-permissions'
+     '-p' in 'tar'.
+
+'print'
+     '-l' in 'diff'.
+
+'print-chars'
+     '-L' in 'cmp'.
+
+'print-data-base'
+     '-p' in Make.
+
+'print-directory'
+     '-w' in Make.
+
+'print-file-name'
+     '-o' in 'nm'.
+
+'print-symdefs'
+     '-s' in 'nm'.
+
+'printer'
+     '-p' in 'wdiff'.
+
+'prompt'
+     '-p' in 'ed'.
+
+'proxy'
+     Specify an HTTP proxy.
+
+'query-user'
+     '-X' in 'shar'.
+
+'question'
+     '-q' in Make.
+
+'quiet'
+     Used in many programs to inhibit the usual output.  *Note:* every
+     program accepting '--quiet' should accept '--silent' as a synonym.
+
+'quiet-unshar'
+     '-Q' in 'shar'
+
+'quote-name'
+     '-Q' in 'ls'.
+
+'rcs'
+     '-n' in 'diff'.
+
+'re-interval'
+     Used in 'gawk'.
+
+'read-full-blocks'
+     '-B' in 'tar'.
+
+'readnow'
+     Used in GDB.
+
+'recon'
+     '-n' in Make.
+
+'record-number'
+     '-R' in 'tar'.
+
+'recursive'
+     Used in 'chgrp', 'chown', 'cp', 'ls', 'diff', and 'rm'.
+
+'reference-limit'
+     Used in 'makeinfo'.
+
+'references'
+     '-r' in 'ptx'.
+
+'regex'
+     '-r' in 'tac' and 'etags'.
+
+'release'
+     '-r' in 'uname'.
+
+'reload-state'
+     '-R' in 'm4'.
+
+'relocation'
+     '-r' in 'objdump'.
+
+'rename'
+     '-r' in 'cpio'.
+
+'replace'
+     '-i' in 'xargs'.
+
+'report-identical-files'
+     '-s' in 'diff'.
+
+'reset-access-time'
+     '-a' in 'cpio'.
+
+'reverse'
+     '-r' in 'ls' and 'nm'.
+
+'reversed-ed'
+     '-f' in 'diff'.
+
+'right-side-defs'
+     '-R' in 'ptx'.
+
+'same-order'
+     '-s' in 'tar'.
+
+'same-permissions'
+     '-p' in 'tar'.
+
+'save'
+     '-g' in 'stty'.
+
+'se'
+     Used in GDB.
+
+'sentence-regexp'
+     '-S' in 'ptx'.
+
+'separate-dirs'
+     '-S' in 'du'.
+
+'separator'
+     '-s' in 'tac'.
+
+'sequence'
+     Used by 'recode' to chose files or pipes for sequencing passes.
+
+'shell'
+     '-s' in 'su'.
+
+'show-all'
+     '-A' in 'cat'.
+
+'show-c-function'
+     '-p' in 'diff'.
+
+'show-ends'
+     '-E' in 'cat'.
+
+'show-function-line'
+     '-F' in 'diff'.
+
+'show-tabs'
+     '-T' in 'cat'.
+
+'silent'
+     Used in many programs to inhibit the usual output.  *Note:* every
+     program accepting '--silent' should accept '--quiet' as a synonym.
+
+'size'
+     '-s' in 'ls'.
+
+'socket'
+     Specify a file descriptor for a network server to use for its
+     socket, instead of opening and binding a new socket.  This provides
+     a way to run, in a nonpriveledged process, a server that normally
+     needs a reserved port number.
+
+'sort'
+     Used in 'ls'.
+
+'source'
+     '-W source' in 'gawk'.
+
+'sparse'
+     '-S' in 'tar'.
+
+'speed-large-files'
+     '-H' in 'diff'.
+
+'split-at'
+     '-E' in 'unshar'.
+
+'split-size-limit'
+     '-L' in 'shar'.
+
+'squeeze-blank'
+     '-s' in 'cat'.
+
+'start-delete'
+     '-w' in 'wdiff'.
+
+'start-insert'
+     '-y' in 'wdiff'.
+
+'starting-file'
+     Used in 'tar' and 'diff' to specify which file within a directory
+     to start processing with.
+
+'statistics'
+     '-s' in 'wdiff'.
+
+'stdin-file-list'
+     '-S' in 'shar'.
+
+'stop'
+     '-S' in Make.
+
+'strict'
+     '-s' in 'recode'.
+
+'strip'
+     '-s' in 'install'.
+
+'strip-all'
+     '-s' in 'strip'.
+
+'strip-debug'
+     '-S' in 'strip'.
+
+'submitter'
+     '-s' in 'shar'.
+
+'suffix'
+     '-S' in 'cp', 'ln', 'mv'.
+
+'suffix-format'
+     '-b' in 'csplit'.
+
+'sum'
+     '-s' in 'gprof'.
+
+'summarize'
+     '-s' in 'du'.
+
+'symbolic'
+     '-s' in 'ln'.
+
+'symbols'
+     Used in GDB and 'objdump'.
+
+'synclines'
+     '-s' in 'm4'.
+
+'sysname'
+     '-s' in 'uname'.
+
+'tabs'
+     '-t' in 'expand' and 'unexpand'.
+
+'tabsize'
+     '-T' in 'ls'.
+
+'terminal'
+     '-T' in 'tput' and 'ul'.  '-t' in 'wdiff'.
+
+'text'
+     '-a' in 'diff'.
+
+'text-files'
+     '-T' in 'shar'.
+
+'time'
+     Used in 'ls' and 'touch'.
+
+'timeout'
+     Specify how long to wait before giving up on some operation.
+
+'to-stdout'
+     '-O' in 'tar'.
+
+'total'
+     '-c' in 'du'.
+
+'touch'
+     '-t' in Make, 'ranlib', and 'recode'.
+
+'trace'
+     '-t' in 'm4'.
+
+'traditional'
+     '-t' in 'hello'; '-W traditional' in 'gawk'; '-G' in 'ed', 'm4',
+     and 'ptx'.
+
+'tty'
+     Used in GDB.
+
+'typedefs'
+     '-t' in 'ctags'.
+
+'typedefs-and-c++'
+     '-T' in 'ctags'.
+
+'typeset-mode'
+     '-t' in 'ptx'.
+
+'uncompress'
+     '-z' in 'tar'.
+
+'unconditional'
+     '-u' in 'cpio'.
+
+'undefine'
+     '-U' in 'm4'.
+
+'undefined-only'
+     '-u' in 'nm'.
+
+'update'
+     '-u' in 'cp', 'ctags', 'mv', 'tar'.
+
+'usage'
+     Used in 'gawk'; same as '--help'.
+
+'uuencode'
+     '-B' in 'shar'.
+
+'vanilla-operation'
+     '-V' in 'shar'.
+
+'verbose'
+     Print more information about progress.  Many programs support this.
+
+'verify'
+     '-W' in 'tar'.
+
+'version'
+     Print the version number.
+
+'version-control'
+     '-V' in 'cp', 'ln', 'mv'.
+
+'vgrind'
+     '-v' in 'ctags'.
+
+'volume'
+     '-V' in 'tar'.
+
+'what-if'
+     '-W' in Make.
+
+'whole-size-limit'
+     '-l' in 'shar'.
+
+'width'
+     '-w' in 'ls' and 'ptx'.
+
+'word-regexp'
+     '-W' in 'ptx'.
+
+'writable'
+     '-T' in 'who'.
+
+'zeros'
+     '-z' in 'gprof'.
+
+
+File: standards.info,  Node: Memory Usage,  Next: File Usage,  Prev: Option Table,  Up: Program Behavior
+
+4.8 Memory Usage
+================
+
+If a program typically uses just a few meg of memory, don't bother
+making any effort to reduce memory usage.  For example, if it is
+impractical for other reasons to operate on files more than a few meg
+long, it is reasonable to read entire input files into core to operate
+on them.
+
+   However, for programs such as 'cat' or 'tail', that can usefully
+operate on very large files, it is important to avoid using a technique
+that would artificially limit the size of files it can handle.  If a
+program works by lines and could be applied to arbitrary user-supplied
+input files, it should keep only a line in memory, because this is not
+very hard and users will want to be able to operate on input files that
+are bigger than will fit in core all at once.
+
+   If your program creates complicated data structures, just make them
+in core and give a fatal error if 'malloc' returns zero.
+
+
+File: standards.info,  Node: File Usage,  Prev: Memory Usage,  Up: Program Behavior
+
+4.9 File Usage
+==============
+
+Programs should be prepared to operate when '/usr' and '/etc' are
+read-only file systems.  Thus, if the program manages log files, lock
+files, backup files, score files, or any other files which are modified
+for internal purposes, these files should not be stored in '/usr' or
+'/etc'.
+
+   There are two exceptions.  '/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in '/etc' when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+
+File: standards.info,  Node: Writing C,  Next: Documentation,  Prev: Program Behavior,  Up: Top
+
+5 Making The Best Use of C
+**************************
+
+This node provides advice on how best to use the C language when writing
+GNU software.
+
+* Menu:
+
+* Formatting::                  Formatting Your Source Code
+* Comments::                    Commenting Your Work
+* Syntactic Conventions::       Clean Use of C Constructs
+* Names::                       Naming Variables and Functions
+* System Portability::          Portability between different operating systems
+* CPU Portability::             Supporting the range of CPU types
+* System Functions::            Portability and "standard" library functions
+* Internationalization::        Techniques for internationalization
+* Mmap::                        How you can safely use 'mmap'.
+
+
+File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C
+
+5.1 Formatting Your Source Code
+===============================
+
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero.  Several tools look for
+open-braces in column zero to find the beginnings of C functions.  These
+tools will not work on code not formatted that way.
+
+   It is also important for function definitions to start the name of
+the function in column zero.  This helps people to search for function
+definitions, and may also help certain tools recognize them.  Thus, the
+proper format is this:
+
+     static char *
+     concat (s1, s2)        /* Name starts in column zero here */
+          char *s1, *s2;
+     {                     /* Open brace in column zero here */
+       ...
+     }
+
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+     static char *
+     concat (char *s1, char *s2)
+     {
+       ...
+     }
+
+   In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+     int
+     lots_of_args (int an_integer, long a_long, short a_short,
+                   double a_double, float a_float)
+     ...
+
+   The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the 'indent'
+program in version 1.2 and newer.  It corresponds to the options
+
+     -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+     -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+   We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+   But whatever style you use, please use it consistently, since a
+mixture of styles within one program tends to look ugly.  If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+   For the body of the function, our recommended style looks like this:
+
+     if (x < foo (y, z))
+       haha = bar[4] + 5;
+     else
+       {
+         while (z)
+           {
+             haha += foo (z, z);
+             z--;
+           }
+         return ++x + bar ();
+       }
+
+   We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas.  Especially after the commas.
+
+   When you split an expression into multiple lines, split it before an
+operator, not after one.  Here is the right way:
+
+     if (foo_this_is_long && bar > win (x, y, z)
+         && remaining_condition)
+
+   Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+
+     mode = (inmode[j] == VOIDmode
+             || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+             ? outmode[j] : inmode[j]);
+
+   Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+     mode = ((inmode[j] == VOIDmode
+              || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+             ? outmode[j] : inmode[j]);
+
+   Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+     v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+         + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+but Emacs would alter it.  Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+     v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+   Format do-while statements like this:
+
+     do
+       {
+         a = foo (a);
+       }
+     while (a > 0);
+
+   Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+
+
+File: standards.info,  Node: Comments,  Next: Syntactic Conventions,  Prev: Formatting,  Up: Writing C
+
+5.2 Commenting Your Work
+========================
+
+Every program should start with a comment saying briefly what it is for.
+Example: 'fmt - filter for simple filling of text'.
+
+   Please write the comments in a GNU program in English, because
+English is the one language that nearly all programmers in all countries
+can read.  If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+
+   Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for.  It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion.  If there is anything nonstandard about
+its use (such as an argument of type 'char *' which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure to
+say so.
+
+   Also explain the significance of the return value, if there is one.
+
+   Please put two spaces after the end of a sentence in your comments,
+so that the Emacs sentence commands will work.  Also, please write
+complete sentences and capitalize the first word.  If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier.  If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., "The identifier lower-case is ...").
+
+   The comment on a function is much clearer if you use the argument
+names to speak about the argument values.  The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself.  Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+   There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+   There should be a comment on each static variable as well, like this:
+
+     /* Nonzero means truncate lines in the display;
+        zero means continue them.  */
+     int truncate_lines;
+
+   Every '#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested.  The comment should
+state the condition of the conditional that is ending, _including its
+sense_.  '#else' should have a comment describing the condition _and
+sense_ of the code that follows.  For example:
+
+     #ifdef foo
+       ...
+     #else /* not foo */
+       ...
+     #endif /* not foo */
+     #ifdef foo
+       ...
+     #endif /* foo */
+
+but, by contrast, write the comments this way for a '#ifndef':
+
+     #ifndef foo
+       ...
+     #else /* foo */
+       ...
+     #endif /* foo */
+     #ifndef foo
+       ...
+     #endif /* not foo */
+
+
+File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Writing C
+
+5.3 Clean Use of C Constructs
+=============================
+
+Please explicitly declare the types of all objects.  For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return 'int' rather than omitting the 'int'.
+
+   Some programmers like to use the GCC '-Wall' option, and change the
+code whenever it issues a warning.  If you want to do this, then do.
+Other programmers prefer not to use '-Wall', because it gives warnings
+for valid and legitimate code which they do not want to change.  If you
+want to do this, then do.  The compiler should be your servant, not your
+master.
+
+   Declarations of external functions and functions to appear later in
+the source file should all go in one place near the beginning of the
+file (somewhere before the first function definition in the file), or
+else should go in a header file.  Don't put 'extern' declarations inside
+functions.
+
+   It used to be common practice to use the same local variables (with
+names like 'tem') over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+
+   Don't use local variables or parameters that shadow global
+identifiers.
+
+   Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead of
+this:
+
+     int    foo,
+            bar;
+
+write either this:
+
+     int foo, bar;
+
+or this:
+
+     int foo;
+     int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+   When you have an 'if'-'else' statement nested in another 'if'
+statement, always put braces around the 'if'-'else'.  Thus, never write
+like this:
+
+     if (foo)
+       if (bar)
+         win ();
+       else
+         lose ();
+
+always like this:
+
+     if (foo)
+       {
+         if (bar)
+           win ();
+         else
+           lose ();
+       }
+
+   If you have an 'if' statement nested inside of an 'else' statement,
+either write 'else if' on one line, like this,
+
+     if (foo)
+       ...
+     else if (bar)
+       ...
+
+with its 'then'-part indented like the preceding 'then'-part, or write
+the nested 'if' within braces like this:
+
+     if (foo)
+       ...
+     else
+       {
+         if (bar)
+           ...
+       }
+
+   Don't declare both a structure tag and variables or typedefs in the
+same declaration.  Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+   Try to avoid assignments inside 'if'-conditions.  For example, don't
+write this:
+
+     if ((foo = (char *) malloc (sizeof *foo)) == 0)
+       fatal ("virtual memory exhausted");
+
+instead, write this:
+
+     foo = (char *) malloc (sizeof *foo);
+     if (foo == 0)
+       fatal ("virtual memory exhausted");
+
+   Don't make the program ugly to placate 'lint'.  Please don't insert
+any casts to 'void'.  Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+
+File: standards.info,  Node: Names,  Next: System Portability,  Prev: Syntactic Conventions,  Up: Writing C
+
+5.4 Naming Variables and Functions
+==================================
+
+The names of global variables and functions in a program serve as
+comments of a sort.  So don't choose terse names--instead, look for
+names that give useful information about the meaning of the variable or
+function.  In a GNU program, names should be English, like other
+comments.
+
+   Local variable names can be shorter, because they are used only
+within one context, where (presumably) comments explain their purpose.
+
+   Try to limit your use of abbreviations in symbol names.  It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+   Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them.  Stick to lower case; reserve
+upper case for macros and 'enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+   For example, you should use names like 'ignore_space_change_flag';
+don't use names like 'iCantReadThis'.
+
+   Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after the
+option-letter.  A comment should state both the exact meaning of the
+option and its letter.  For example,
+
+     /* Ignore changes in horizontal whitespace (-b).  */
+     int ignore_space_change_flag;
+
+   When you want to define names with constant integer values, use
+'enum' rather than '#define'.  GDB knows about enumeration constants.
+
+   You might want to make sure that none of the file names would
+conflict the files were loaded onto an MS-DOS file system which shortens
+the names.  You can use the program 'doschk' to test for this.
+
+   Some GNU programs were designed to limit themselves to file names of
+14 characters or less, to avoid file name conflicts if they are read
+into older System V systems.  Please preserve this feature in the
+existing GNU programs that have it, but there is no need to do this in
+new GNU programs.  'doschk' also reports file names longer than 14
+characters.
+
+
+File: standards.info,  Node: System Portability,  Next: CPU Portability,  Prev: Names,  Up: Writing C
+
+5.5 Portability between System Types
+====================================
+
+In the Unix world, "portability" refers to porting to different Unix
+versions.  For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+   The primary purpose of GNU software is to run on top of the GNU
+kernel, compiled with the GNU C compiler, on various types of CPU.  So
+the kinds of portability that are absolutely necessary are quite
+limited.  But it is important to support Linux-based GNU systems, since
+they are the form of GNU that is popular.
+
+   Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to.  Supporting a variety of Unix-like systems is desirable, although
+not paramount.  It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+   The easiest way to achieve portability to most Unix-like systems is
+to use Autoconf.  It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+   Avoid using the format of semi-internal data bases (e.g.,
+directories) when there is a higher-level alternative ('readdir').
+
+   As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work.  When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+   It is a good idea to define the "feature test macro" '_GNU_SOURCE'
+when compiling your C files.  When you compile on GNU or GNU/Linux, this
+will enable the declarations of GNU library extension functions, and
+that will usually give you a compiler error message if you define the
+same function names in some other way in your program.  (You don't have
+to actually _use_ these functions, if you prefer to make the program
+more portable to other systems.)
+
+   But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings.  Doing so would make it hard
+to move your code into other GNU programs.
+
+
+File: standards.info,  Node: CPU Portability,  Next: System Functions,  Prev: System Portability,  Up: Writing C
+
+5.6 Portability between CPUs
+============================
+
+Even GNU systems will differ because of differences among CPU types--for
+example, difference in byte ordering and alignment requirements.  It is
+absolutely essential to handle these differences.  However, don't make
+any effort to cater to the possibility that an 'int' will be less than
+32 bits.  We don't support 16-bit machines in GNU.
+
+   Similarly, don't make any effort to cater to the possibility that
+'long' will be smaller than predefined types like 'size_t'.  For
+example, the following code is ok:
+
+     printf ("size = %lu\n", (unsigned long) sizeof array);
+     printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+   1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64.  We will
+leave it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+   Predefined file-size types like 'off_t' are an exception: they are
+longer than 'long' on many platforms, so code like the above won't work
+with them.  One way to print an 'off_t' value portably is to print its
+digits yourself, one by one.
+
+   Don't assume that the address of an 'int' object is also the address
+of its least-significant byte.  This is false on big-endian machines.
+Thus, don't make the following mistake:
+
+     int c;
+     ...
+     while ((c = getchar()) != EOF)
+       write(file_descriptor, &c, 1);
+
+   When calling functions, you need not worry about the difference
+between pointers of various types, or between pointers and integers.  On
+most machines, there's no difference anyway.  As for the few machines
+where there is a difference, all of them support Standard C prototypes,
+so you can use prototypes (perhaps conditionalized to be active only in
+Standard C) to make the code work on those systems.
+
+   In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system.  For example, many GNU programs have error-reporting functions
+that pass their arguments along to 'printf' and friends:
+
+     error (s, a1, a2, a3)
+          char *s;
+          char *a1, *a2, *a3;
+     {
+       fprintf (stderr, "error: ");
+       fprintf (stderr, s, a1, a2, a3);
+     }
+
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+"correct" alternative.  Be sure _not_ to use a prototype for such
+functions.
+
+   If you have decided to use Standard C, then you can instead define
+'error' using 'stdarg.h', and pass the arguments along to 'vfprintf'.
+
+   Avoid casting pointers to integers if you can.  Such casts greatly
+reduce portability, and in most programs they are easy to avoid.  In the
+cases where casting pointers to integers is essential--such as, a Lisp
+interpreter which stores type information as well as an address in one
+word--you'll have to make explicit provisions to handle different word
+sizes.  You will also need to make provision for systems in which the
+normal range of addresses you can get from 'malloc' starts far away from
+zero.
+
+
+File: standards.info,  Node: System Functions,  Next: Internationalization,  Prev: CPU Portability,  Up: Writing C
+
+5.7 Calling System Functions
+============================
+
+C implementations differ substantially.  Standard C reduces but does not
+eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do.  This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+   * Don't use the return value of 'sprintf'.  It returns the number of
+     characters written on some systems, but not on all systems.
+
+   * Be aware that 'vfprintf' is not always available.
+
+   * 'main' should be declared to return type 'int'.  It should
+     terminate either by calling 'exit' or by returning the integer
+     status code; make sure it cannot ever return an undefined value.
+
+   * Don't declare system functions explicitly.
+
+     Almost any declaration for a system function is wrong on some
+     system.  To minimize conflicts, leave it to the system header files
+     to declare system functions.  If the headers don't declare a
+     function, let it remain undeclared.
+
+     While it may seem unclean to use a function without declaring it,
+     in practice this works fine for most system library functions on
+     the systems where this really happens; thus, the disadvantage is
+     only theoretical.  By contrast, actual declarations have frequently
+     caused actual conflicts.
+
+   * If you must declare a system function, don't specify the argument
+     types.  Use an old-style declaration, not a Standard C prototype.
+     The more you specify about the function, the more likely a
+     conflict.
+
+   * In particular, don't unconditionally declare 'malloc' or 'realloc'.
+
+     Most GNU programs use those functions just once, in functions
+     conventionally named 'xmalloc' and 'xrealloc'.  These functions
+     call 'malloc' and 'realloc', respectively, and check the results.
+
+     Because 'xmalloc' and 'xrealloc' are defined in your program, you
+     can declare them in other files without any risk of type conflict.
+
+     On most systems, 'int' is the same length as a pointer; thus, the
+     calls to 'malloc' and 'realloc' work fine.  For the few exceptional
+     systems (mostly 64-bit machines), you can use *conditionalized*
+     declarations of 'malloc' and 'realloc'--or put these declarations
+     in configuration files specific to those systems.
+
+   * The string functions require special treatment.  Some Unix systems
+     have a header file 'string.h'; others have 'strings.h'.  Neither
+     file name is portable.  There are two things you can do: use
+     Autoconf to figure out which file to include, or don't include
+     either file.
+
+   * If you don't include either strings file, you can't get
+     declarations for the string functions from the header file in the
+     usual way.
+
+     That causes less of a problem than you might think.  The newer
+     standard string functions should be avoided anyway because many
+     systems still don't support them.  The string functions you can use
+     are these:
+
+          strcpy   strncpy   strcat   strncat
+          strlen   strcmp    strncmp
+          strchr   strrchr
+
+     The copy and concatenate functions work fine without a declaration
+     as long as you don't use their values.  Using their values without
+     a declaration fails on systems where the width of a pointer differs
+     from the width of 'int', and perhaps in other cases.  It is trivial
+     to avoid using their values, so do that.
+
+     The compare functions and 'strlen' work fine without a declaration
+     on most systems, possibly all the ones that GNU software runs on.
+     You may find it necessary to declare them *conditionally* on a few
+     systems.
+
+     The search functions must be declared to return 'char *'.  Luckily,
+     there is no variation in the data type they return.  But there is
+     variation in their names.  Some systems give these functions the
+     names 'index' and 'rindex'; other systems use the names 'strchr'
+     and 'strrchr'.  Some systems support both pairs of names, but
+     neither pair works on all systems.
+
+     You should pick a single pair of names and use it throughout your
+     program.  (Nowadays, it is better to choose 'strchr' and 'strrchr'
+     for new programs, since those are the standard names.)  Declare
+     both of those names as functions returning 'char *'.  On systems
+     which don't support those names, define them as macros in terms of
+     the other pair.  For example, here is what to put at the beginning
+     of your file (or in a header) if you want to use the names 'strchr'
+     and 'strrchr' throughout:
+
+          #ifndef HAVE_STRCHR
+          #define strchr index
+          #endif
+          #ifndef HAVE_STRRCHR
+          #define strrchr rindex
+          #endif
+
+          char *strchr ();
+          char *strrchr ();
+
+   Here we assume that 'HAVE_STRCHR' and 'HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist.  One way to
+get them properly defined is to use Autoconf.
+
+
+File: standards.info,  Node: Internationalization,  Next: Mmap,  Prev: System Functions,  Up: Writing C
+
+5.8 Internationalization
+========================
+
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages.  You should use this
+library in every program.  Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+   Using GNU gettext involves putting a call to the 'gettext' macro
+around each string that might need translation--like this:
+
+     printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string '"Processing file
+`%s'..."' with a translated version.
+
+   Once a program uses gettext, please make a point of writing calls to
+'gettext' when you add new strings that call for translation.
+
+   Using GNU gettext in a package involves specifying a "text domain
+name" for the package.  The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package--for example, 'fileutils' for the GNU file utilities.
+
+   To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences.  When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+   Here is an example of what not to do:
+
+     printf ("%d file%s processed", nfiles,
+             nfiles != 1 ? "s" : "");
+
+The problem with that example is that it assumes that plurals are made
+by adding 's'.  If you apply gettext to the format string, like this,
+
+     printf (gettext ("%d file%s processed"), nfiles,
+             nfiles != 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+'s' for the plural.  Here is a better way:
+
+     printf ((nfiles != 1 ? "%d files processed"
+              : "%d file processed"),
+             nfiles);
+
+This way, you can apply gettext to each of the two strings
+independently:
+
+     printf ((nfiles != 1 ? gettext ("%d files processed")
+              : gettext ("%d file processed")),
+             nfiles);
+
+This can be any method of forming the plural of the word for "file", and
+also handles languages that require agreement in the word for
+"processed".
+
+   A similar problem appears at the level of sentence structure with
+this code:
+
+     printf ("#  Implicit rule search has%s been done.\n",
+             f->tried_implicit ? "" : " not");
+
+Adding 'gettext' calls to this code cannot give correct results for all
+languages, because negation in some languages requires adding words at
+more than one place in the sentence.  By contrast, adding 'gettext'
+calls does the job straightfowardly if the code starts out like this:
+
+     printf (f->tried_implicit
+             ? "#  Implicit rule search has been done.\n",
+             : "#  Implicit rule search has not been done.\n");
+
+
+File: standards.info,  Node: Mmap,  Prev: Internationalization,  Up: Writing C
+
+5.9 Mmap
+========
+
+Don't assume that 'mmap' either works on all files or fails for all
+files.  It may work on some files and fail on others.
+
+   The proper way to use 'mmap' is to try it on the specific file for
+which you want to use it--and if 'mmap' doesn't work, fall back on doing
+the job in another way using 'read' and 'write'.
+
+   The reason this precaution is needed is that the GNU kernel (the
+HURD) provides a user-extensible file system, in which there can be many
+different kinds of "ordinary files."  Many of them support 'mmap', but
+some do not.  It is important to make programs handle all these kinds of
+files.
+
+
+File: standards.info,  Node: Documentation,  Next: Managing Releases,  Prev: Writing C,  Up: Top
+
+6 Documenting Programs
+**********************
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes.  If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+* Menu:
+
+* GNU Manuals::                 Writing proper manuals.
+* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
+* Manual Structure Details::    Specific structure conventions.
+* License for Manuals::         Writing the distribution terms for a manual.
+* Manual Credits::              Giving credit to documentation contributors.
+* Printed Manuals::             Mentioning the printed manual.
+* NEWS File::                   NEWS files supplement manuals.
+* Change Logs::                 Recording Changes
+* Man Pages::                   Man pages are secondary.
+* Reading other Manuals::       How far you can go in learning
+                                from other manuals.
+
+
+File: standards.info,  Node: GNU Manuals,  Next: Doc Strings and Manuals,  Up: Documentation
+
+6.1 GNU Manuals
+===============
+
+The preferred document format for the GNU system is the Texinfo
+formatting language.  Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners.  Texinfo
+makes it possible to produce a good quality formatted book, using TeX,
+and to generate an Info file.  It is also possible to generate HTML
+output from Texinfo source.  See the Texinfo manual, either the
+hardcopy, or the on-line version available through 'info' or the Emacs
+Info subsystem ('C-h i').
+
+   Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo.  It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+   Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know.  But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+   At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it.  Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented--but
+often they are different.  Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+   For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual.  That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+   Instead, each manual should cover a coherent _topic_.  For example,
+instead of a manual for 'diff' and a manual for 'diff3', we have one
+manual for "comparison of files" which covers both of those programs, as
+well as 'cmp'.  By documenting these programs together, we can make the
+whole subject clearer.
+
+   The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands.  It should
+give examples of their use.  But don't organize the manual as a list of
+features.  Instead, organize it logically, by subtopics.  Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+   In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside).  A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.  The
+Bison manual is a good example of this--please take a look at it to see
+what we mean.
+
+   That is not as hard as it first sounds.  Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense.  Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs.  The watchword is, _at each point, address the
+most fundamental and important issue raised by the preceding text._
+
+   If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject.  These provide
+the framework for a beginner to understand the rest of the manual.  The
+Bison manual provides a good example of how to do this.
+
+   To serve as a reference, a manual should have an Index that list all
+the functions, variables, options, and important concepts that are part
+of the program.  One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+*note Making Index Entries: (texinfo)Index Entries, and see *note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
+   Don't use Unix man pages as a model for how to write GNU
+documentation; most of them are terse, badly structured, and give
+inadequate explanation of the underlying concepts.  (There are, of
+course, some exceptions.)  Also, Unix man pages use a particular format
+which is different from what we use in GNU manuals.
+
+   Please include an email address in the manual for where to report
+bugs _in the manual_.
+
+   Please do not use the term "pathname" that is used in Unix
+documentation; use "file name" (two words) instead.  We use the term
+"path" only for search paths, which are lists of directory names.
+
+   Please do not use the term "illegal" to refer to erroneous input to a
+computer program.  Please use "invalid" for this, and reserve the term
+"illegal" for activities punishable by law.
+
+
+File: standards.info,  Node: Doc Strings and Manuals,  Next: Manual Structure Details,  Prev: GNU Manuals,  Up: Documentation
+
+6.2 Doc Strings and Manuals
+===========================
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable.  You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them--but you must not do it.  That
+approach is a fundamental mistake.  The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+   A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+   The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection.  Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables.  The previous descriptions of functions and variables in the
+section will also have given information about the topic.  A description
+written to stand alone would repeat some of that information; this
+redundance looks bad.  Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+   The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
+
+
+File: standards.info,  Node: Manual Structure Details,  Next: License for Manuals,  Prev: Doc Strings and Manuals,  Up: Documentation
+
+6.3 Manual Structure Details
+============================
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual.  The Top node of the manual should
+also contain this information.  If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+   Each program documented in the manual should have a node named
+'PROGRAM Invocation' or 'Invoking PROGRAM'.  This node (together with
+its subnodes, if any) should describe the program's command line
+arguments and how to run it (the sort of information people would look
+in a man page for).  Start with an '@example' containing a template for
+all the options and arguments that the program uses.
+
+   Alternatively, put a menu item in some menu whose item name fits one
+of the above patterns.  This identifies the node which that item points
+to as the node for this purpose, regardless of the node's actual name.
+
+   The '--usage' feature of the Info reader looks for such a node or
+menu item in order to find the relevant text, so it is essential for
+every Texinfo file to have one.
+
+   If one manual describes several programs, it should have such a node
+for each program described in the manual.
+
+
+File: standards.info,  Node: License for Manuals,  Next: Manual Credits,  Prev: Manual Structure Details,  Up: Documentation
+
+6.4 License for Manuals
+=======================
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long.  Likewise for a collection of short
+documents--you only need one copy of the GNU FDL for the whole
+collection.  For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+   See <http://www.gnu.org/copyleft/fdl-howto.html> for more explanation
+of how to employ the GFDL.
+
+   Note that it is not obligatory to include a copy of the GNU GPL or
+GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
+can be a good idea to include the program's license in a large manual;
+in a short manual, whose size would be increased considerably by
+including the program's license, it is probably better not to include
+it.
+
+
+File: standards.info,  Node: Manual Credits,  Next: Printed Manuals,  Prev: License for Manuals,  Up: Documentation
+
+6.5 Manual Credits
+==================
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual.  If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+
+File: standards.info,  Node: Printed Manuals,  Next: NEWS File,  Prev: Manual Credits,  Up: Documentation
+
+6.6 Printed Manuals
+===================
+
+The FSF publishes some GNU manuals in printed form.  To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it--for instance, with a link to the page
+<http://www.gnu.org/order/order.html>.  This should not be included in
+the printed manual, though, because there it is redundant.
+
+   It is also useful to explain in the on-line forms of the manual how
+the user can print out the manual from the sources.
+
+
+File: standards.info,  Node: NEWS File,  Next: Change Logs,  Prev: Printed Manuals,  Up: Documentation
+
+6.7 The NEWS File
+=================
+
+In addition to its manual, the package should have a file named 'NEWS'
+which contains a list of user-visible changes worth mentioning.  In each
+new release, add items to the front of the file and identify the version
+they pertain to.  Don't discard old items; leave them in the file after
+the newer items.  This way, a user upgrading from any previous version
+can see what is new.
+
+   If the 'NEWS' file gets very long, move some of the older items into
+a file named 'ONEWS' and put a note at the end referring the user to
+that file.
+
+
+File: standards.info,  Node: Change Logs,  Next: Man Pages,  Prev: NEWS File,  Up: Documentation
+
+6.8 Change Logs
+===============
+
+Keep a change log to describe all the changes made to program source
+files.  The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+* Menu:
+
+* Change Log Concepts::         
+* Style of Change Logs::        
+* Simple Changes::              
+* Conditional Changes::         
+* Indicating the Part Changed::
+
+
+File: standards.info,  Node: Change Log Concepts,  Next: Style of Change Logs,  Up: Change Logs
+
+6.8.1 Change Log Concepts
+-------------------------
+
+You can think of the change log as a conceptual "undo list" which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log to
+tell them what is in it.  What they want from a change log is a clear
+explanation of how the earlier version differed.
+
+   The change log file is normally called 'ChangeLog' and covers an
+entire directory.  Each directory can have its own change log, or a
+directory can use the change log of its parent directory-it's up to you.
+
+   Another alternative is to record change log information with a
+version control system such as RCS or CVS. This can be converted
+automatically to a 'ChangeLog' file using 'rcs2log'; in Emacs, the
+command 'C-x v a' ('vc-update-change-log') does the job.
+
+   There's no need to describe the full purpose of the changes or how
+they work together.  If you think that a change calls for explanation,
+you're probably right.  Please do explain it--but please put the
+explanation in comments in the code, where people will see it whenever
+they see the code.  For example, "New function" is enough for the change
+log when you add a function, because there should be a comment before
+the function definition to explain what it does.
+
+   However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+   The easiest way to add an entry to 'ChangeLog' is with the Emacs
+command 'M-x add-change-log-entry'.  An entry should have an asterisk,
+the name of the changed file, and then in parentheses the name of the
+changed functions, variables or whatever, followed by a colon.  Then
+describe the changes you made to that function or variable.
+
+
+File: standards.info,  Node: Style of Change Logs,  Next: Simple Changes,  Prev: Change Log Concepts,  Up: Change Logs
+
+6.8.2 Style of Change Logs
+--------------------------
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when, followed by
+descriptions of specific changes.  (These examples are drawn from Emacs
+and GCC.)
+
+     1998-08-17  Richard Stallman  <rms@gnu.org>
+
+     * register.el (insert-register): Return nil.
+     (jump-to-register): Likewise.
+
+     * sort.el (sort-subr): Return nil.
+
+     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+     Restart the tex shell if process is gone or stopped.
+     (tex-shell-running): New function.
+
+     * expr.c (store_one_arg): Round size up for move_block_to_reg.
+     (expand_call): Round up when emitting USE insns.
+     * stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+   It's important to name the changed function or variable in full.
+Don't abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+   For example, some people are tempted to abbreviate groups of function
+names by writing '* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for 'jump-to-register' or
+'insert-register' would not find that entry.
+
+   Separate unrelated change log entries with blank lines.  When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them.  Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+   Break long lists of function names by closing continued lines with
+')', rather than ',', and opening the continuation with '(' as in this
+example:
+
+     * keyboard.c (menu_bar_items, tool_bar_items)
+     (Fexecute_extended_command): Deal with `keymap' property.
+
+
+File: standards.info,  Node: Simple Changes,  Next: Conditional Changes,  Prev: Style of Change Logs,  Up: Change Logs
+
+6.8.3 Simple Changes
+--------------------
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+   When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function to use the new
+calling sequence, there is no need to make individual entries for all
+the callers that you changed.  Just write in the entry for the function
+being called, "All callers changed"--like this:
+
+     * keyboard.c (Fcommand_execute): New arg SPECIAL.
+     All callers changed.
+
+   When you change just comments or doc strings, it is enough to write
+an entry for the file, without mentioning the functions.  Just "Doc
+fixes" is enough for the change log.
+
+   There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix.  Documentation does not consist of parts that must interact in a
+precisely engineered fashion.  To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+
+File: standards.info,  Node: Conditional Changes,  Next: Indicating the Part Changed,  Prev: Simple Changes,  Up: Change Logs
+
+6.8.4 Conditional Changes
+-------------------------
+
+C programs often contain compile-time '#if' conditionals.  Many changes
+are conditional; sometimes you add a new definition which is entirely
+contained in a conditional.  It is very useful to indicate in the change
+log the conditions for which the change applies.
+
+   Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+   Here is a simple example, describing a change which is conditional
+but does not have a function or entity name associated with it:
+
+     * xterm.c [SOLARIS2]: Include string.h.
+
+   Here is an entry describing a new definition which is entirely
+conditional.  This new definition for the macro 'FRAME_WINDOW_P' is used
+only when 'HAVE_X_WINDOWS' is defined:
+
+     * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+   Here is an entry for a change within the function 'init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a '#ifdef HAVE_LIBNCURSES' conditional:
+
+     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+   Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+
+
+File: standards.info,  Node: Indicating the Part Changed,  Prev: Conditional Changes,  Up: Change Logs
+
+6.8.5 Indicating the Part Changed
+---------------------------------
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does.  Here is an entry
+for a change in the part of the function 'sh-while-getopts' that deals
+with 'sh' commands:
+
+     * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+     user-specified option string is empty.
+
+
+File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation
+
+6.9 Man Pages
+=============
+
+In the GNU project, man pages are secondary.  It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+   When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed.  The time
+you spend on the man page is time taken away from more useful work.
+
+   For a simple program which changes little, updating the man page may
+be a small job.  Then there is little reason not to include a man page,
+if you have one.
+
+   For a large program that changes a great deal, updating a man page
+may be a substantial burden.  If a user offers to donate a man page, you
+may find this gift costly to accept.  It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it--so that you can wash your hands of it entirely.  If this
+volunteer later ceases to do the job, then don't feel obliged to pick it
+up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+   When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating.  If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative.  The note should say how to access the Texinfo
+documentation.
+
+
+File: standards.info,  Node: Reading other Manuals,  Prev: Man Pages,  Up: Documentation
+
+6.10 Reading other Manuals
+==========================
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+   It is ok to use these documents for reference, just as the author of
+a new algebra textbook can read other books on algebra.  A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject.  But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation.  Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+
+File: standards.info,  Node: Managing Releases,  Next: References,  Prev: Documentation,  Up: Top
+
+7 The Release Process
+*********************
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems.  Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below.  Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration::               How Configuration Should Work
+* Makefile Conventions::	Makefile Conventions
+* Releases::                    Making Releases
+
+
+File: standards.info,  Node: Configuration,  Next: Makefile Conventions,  Up: Managing Releases
+
+7.1 How Configuration Should Work
+=================================
+
+Each GNU distribution should come with a shell script named 'configure'.
+This script is given arguments which describe the kind of machine and
+system you want to compile the program for.
+
+   The 'configure' script must record the configuration options so that
+they affect compilation.
+
+   One way to do this is to make a link from a standard name such as
+'config.h' to the proper configuration file for the chosen system.  If
+you use this technique, the distribution should _not_ contain a file
+named 'config.h'.  This is so that people won't be able to build the
+program without configuring it first.
+
+   Another thing that 'configure' can do is to edit the Makefile.  If
+you do this, the distribution should _not_ contain a file named
+'Makefile'.  Instead, it should include a file 'Makefile.in' which
+contains the input used for editing.  Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+   If 'configure' does write the 'Makefile', then 'Makefile' should have
+a target named 'Makefile' which causes 'configure' to be rerun, setting
+up the same configuration that was set up last time.  The files that
+'configure' reads should be listed as dependencies of 'Makefile'.
+
+   All the files which are output from the 'configure' script should
+have comments at the beginning explaining that they were generated
+automatically using 'configure'.  This is so that users won't think of
+trying to edit them by hand.
+
+   The 'configure' script should write a file named 'config.status'
+which describes which configuration options were specified when the
+program was last configured.  This file should be a shell script which,
+if run, will recreate the same configuration.
+
+   The 'configure' script should accept an option of the form
+'--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory).  This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+   If the user does not specify '--srcdir', then 'configure' should
+check both '.' and '..' to see if it can find the sources.  If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+   Usually the easy way to support '--srcdir' is by editing a definition
+of 'VPATH' into the Makefile.  Some rules may need to refer explicitly
+to the specified source directory.  To make this possible, 'configure'
+can add to the Makefile a variable named 'srcdir' whose value is
+precisely the specified directory.
+
+   The 'configure' script should also take an argument which specifies
+the type of system to build the program for.  This argument should look
+like this:
+
+     CPU-COMPANY-SYSTEM
+
+   For example, a Sun 3 might be 'm68k-sun-sunos4.1'.
+
+   The 'configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine.  Thus, 'sun3-sunos4.1' would
+be a valid alias.  For many programs, 'vax-dec-ultrix' would be an alias
+for 'vax-dec-bsd', simply because the differences between Ultrix and BSD
+are rarely noticeable, but a few programs might need to distinguish
+them.
+
+   There is a shell script called 'config.sub' that you can use as a
+subroutine to validate system types and canonicalize aliases.
+
+   Other options are permitted to specify in more detail the software or
+hardware present on the machine, and include or exclude optional parts
+of the package:
+
+'--enable-FEATURE[=PARAMETER]'
+     Configure the package to build and install an optional user-level
+     facility called FEATURE.  This allows users to choose which
+     optional features to include.  Giving an optional PARAMETER of 'no'
+     should omit FEATURE, if it is built by default.
+
+     No '--enable' option should *ever* cause one feature to replace
+     another.  No '--enable' option should ever substitute one useful
+     behavior for another useful behavior.  The only proper use for
+     '--enable' is for questions of whether to build part of the program
+     or exclude it.
+
+'--with-PACKAGE'
+     The package PACKAGE will be installed, so configure this package to
+     work with PACKAGE.
+
+     Possible values of PACKAGE include 'gnu-as' (or 'gas'), 'gnu-ld',
+     'gnu-libc', 'gdb', 'x', and 'x-toolkit'.
+
+     Do not use a '--with' option to specify the file name to use to
+     find certain files.  That is outside the scope of what '--with'
+     options are for.
+
+   All 'configure' scripts should accept all of these "detail" options,
+whether or not they make any difference to the particular package at
+hand.  In particular, they should accept any option that starts with
+'--with-' or '--enable-'.  This is so users will be able to configure an
+entire GNU source tree at once with a single set of options.
+
+   You will note that the categories '--with-' and '--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+
+   Packages that perform part of the compilation process may support
+cross-compilation.  In such a case, the host and target machines for the
+program may be different.
+
+   The 'configure' script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+   To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option '--target=TARGETTYPE'.  The syntax for TARGETTYPE is the same as
+for the host type.  So the command would look like this:
+
+     ./configure HOSTTYPE --target=TARGETTYPE
+
+   Programs for which cross-operation is not meaningful need not accept
+the '--target' option, because configuring an entire operating system
+for cross-operation is not a meaningful operation.
+
+   Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on.  Compilation packages accept a
+configuration option '--build=BUILDTYPE' for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using 'config.guess'), so
+this option is probably not necessary.  The host and target types
+normally default from the build type, so in bootstrapping a
+cross-compiler you must specify them both explicitly.
+
+   Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your 'configure' script can simply
+ignore most of its arguments.
+
+
+File: standards.info,  Node: Makefile Conventions,  Next: Releases,  Prev: Configuration,  Up: Managing Releases
+
+7.2 Makefile Conventions
+========================
+
+This node describes conventions for writing the Makefiles for GNU
+programs.  Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics::		General Conventions for Makefiles
+* Utilities in Makefiles::	Utilities in Makefiles
+* Command Variables::		Variables for Specifying Commands
+* Directory Variables::		Variables for Installation Directories
+* Standard Targets::		Standard Targets for Users
+* Install Command Categories::  Three categories of commands in the 'install'
+                                  rule: normal, pre-install and post-install.
+
+
+File: standards.info,  Node: Makefile Basics,  Next: Utilities in Makefiles,  Up: Makefile Conventions
+
+7.2.1 General Conventions for Makefiles
+---------------------------------------
+
+Every Makefile should contain this line:
+
+     SHELL = /bin/sh
+
+to avoid trouble on systems where the 'SHELL' variable might be
+inherited from the environment.  (This is never a problem with GNU
+'make'.)
+
+   Different 'make' programs have incompatible suffix lists and implicit
+rules, and this sometimes creates confusion or misbehavior.  So it is a
+good idea to set the suffix list explicitly using only the suffixes you
+need in the particular Makefile, like this:
+
+     .SUFFIXES:
+     .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+   Don't assume that '.' is in the path for command execution.  When you
+need to run programs that are a part of your package during the make,
+please make sure that it uses './' if the program is built as part of
+the make or '$(srcdir)/' if the file is an unchanging part of the source
+code.  Without one of these prefixes, the current search path is used.
+
+   The distinction between './' (the "build directory") and '$(srcdir)/'
+(the "source directory") is important because users can build in a
+separate directory using the '--srcdir' option to 'configure'.  A rule
+of the form:
+
+     foo.1 : foo.man sedscript
+             sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+'foo.man' and 'sedscript' are in the source directory.
+
+   When using GNU 'make', relying on 'VPATH' to find the source file
+will work in the case where there is a single dependency file, since the
+'make' automatic variable '$<' will represent the source file wherever
+it is.  (Many versions of 'make' set '$<' only in implicit rules.)  A
+Makefile target like
+
+     foo.o : bar.c
+             $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+     foo.o : bar.c
+             $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow 'VPATH' to work correctly.  When the target has
+multiple dependencies, using an explicit '$(srcdir)' is the easiest way
+to make the rule work well.  For example, the target above for 'foo.1'
+is best written as:
+
+     foo.1 : foo.man sedscript
+             sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+   GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex.  Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory.  So Makefile rules to update them should put the
+updated files in the source directory.
+
+   However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+   Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel 'make'.
+
+
+File: standards.info,  Node: Utilities in Makefiles,  Next: Command Variables,  Prev: Makefile Basics,  Up: Makefile Conventions
+
+7.2.2 Utilities in Makefiles
+----------------------------
+
+Write the Makefile commands (and any shell scripts, such as 'configure')
+to run in 'sh', not in 'csh'.  Don't use any special features of 'ksh'
+or 'bash'.
+
+   The 'configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+     cat cmp cp diff echo egrep expr false grep install-info
+     ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+   The compression program 'gzip' can be used in the 'dist' rule.
+
+   Stick to the generally supported options for these programs.  For
+example, don't use 'mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+   It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+   The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via 'make' variables so
+that the user can substitute alternatives.  Here are some of the
+programs we mean:
+
+     ar bison cc flex install ld ldconfig lex
+     make makeinfo ranlib texi2dvi yacc
+
+   Use the following 'make' variables to run those programs:
+
+     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+   When you use 'ranlib' or 'ldconfig', you should make sure nothing bad
+happens if the system does not have the program in question.  Arrange to
+ignore an error from that command, and print a message before the
+command to tell the user that failure of this command does not mean a
+problem.  (The Autoconf 'AC_PROG_RANLIB' macro can help with this.)
+
+   If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+   Additional utilities that can be used via Make variables are:
+
+     chgrp chmod chown mknod
+
+   It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+
+File: standards.info,  Node: Command Variables,  Next: Directory Variables,  Prev: Utilities in Makefiles,  Up: Makefile Conventions
+
+7.2.3 Variables for Specifying Commands
+---------------------------------------
+
+Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+   In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named 'BISON' whose default
+value is set with 'BISON = bison', and refer to it with '$(BISON)'
+whenever you need to use Bison.
+
+   File management utilities such as 'ln', 'rm', 'mv', and so on, need
+not be referred to through variables in this way, since users don't need
+to replace them with other programs.
+
+   Each program-name variable should come with an options variable that
+is used to supply options to the program.  Append 'FLAGS' to the
+program-name variable name to get the options variable name--for
+example, 'BISONFLAGS'.  (The names 'CFLAGS' for the C compiler, 'YFLAGS'
+for yacc, and 'LFLAGS' for lex, are exceptions to this rule, but we keep
+them because they are standard.)  Use 'CPPFLAGS' in any compilation
+command that runs the preprocessor, and use 'LDFLAGS' in any compilation
+command that does linking as well as in any direct use of 'ld'.
+
+   If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in 'CFLAGS'.  Users
+expect to be able to specify 'CFLAGS' freely themselves.  Instead,
+arrange to pass the necessary options to the C compiler independently of
+'CFLAGS', by writing them explicitly in the compilation commands or by
+defining an implicit rule, like this:
+
+     CFLAGS = -g
+     ALL_CFLAGS = -I. $(CFLAGS)
+     .c.o:
+             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+   Do include the '-g' option in 'CFLAGS', because that is not
+_required_ for proper compilation.  You can consider it a default that
+is only recommended.  If the package is set up so that it is compiled
+with GCC by default, then you might as well include '-O' in the default
+value of 'CFLAGS' as well.
+
+   Put 'CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use 'CFLAGS' to override
+the others.
+
+   'CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+   Every Makefile should define the variable 'INSTALL', which is the
+basic command for installing a file into the system.
+
+   Every Makefile should also define the variables 'INSTALL_PROGRAM' and
+'INSTALL_DATA'.  (The default for 'INSTALL_PROGRAM' should be
+'$(INSTALL)'; the default for 'INSTALL_DATA' should be '${INSTALL} -m
+644'.)  Then it should use those variables as the commands for actual
+installation, for executables and nonexecutables respectively.  Use
+these variables as follows:
+
+     $(INSTALL_PROGRAM) foo $(bindir)/foo
+     $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+   Optionally, you may prepend the value of 'DESTDIR' to the target
+filename.  Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later.  Do not
+set the value of 'DESTDIR' in your Makefile, and do not include it in
+any installed files.  With support for 'DESTDIR', the above examples
+become:
+
+     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+
+File: standards.info,  Node: Directory Variables,  Next: Standard Targets,  Prev: Command Variables,  Up: Makefile Conventions
+
+7.2.4 Variables for Installation Directories
+--------------------------------------------
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place.  The standard names for these
+variables are described below.  They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+   These two variables set the root for the installation.  All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+'prefix'
+     A prefix used in constructing the default values of the variables
+     listed below.  The default value of 'prefix' should be
+     '/usr/local'.  When building the complete GNU system, the prefix
+     will be empty and '/usr' will be a symbolic link to '/'.  (If you
+     are using Autoconf, write it as '@prefix@'.)
+
+     Running 'make install' with a different value of 'prefix' from the
+     one used to build the program should _not_ recompile the program.
+
+'exec_prefix'
+     A prefix used in constructing the default values of some of the
+     variables listed below.  The default value of 'exec_prefix' should
+     be '$(prefix)'.  (If you are using Autoconf, write it as
+     '@exec_prefix@'.)
+
+     Generally, '$(exec_prefix)' is used for directories that contain
+     machine-specific files (such as executables and subroutine
+     libraries), while '$(prefix)' is used directly for other
+     directories.
+
+     Running 'make install' with a different value of 'exec_prefix' from
+     the one used to build the program should _not_ recompile the
+     program.
+
+   Executable programs are installed in one of the following
+directories.
+
+'bindir'
+     The directory for installing executable programs that users can
+     run.  This should normally be '/usr/local/bin', but write it as
+     '$(exec_prefix)/bin'.  (If you are using Autoconf, write it as
+     '@bindir@'.)
+
+'sbindir'
+     The directory for installing executable programs that can be run
+     from the shell, but are only generally useful to system
+     administrators.  This should normally be '/usr/local/sbin', but
+     write it as '$(exec_prefix)/sbin'.  (If you are using Autoconf,
+     write it as '@sbindir@'.)
+
+'libexecdir'
+     The directory for installing executable programs to be run by other
+     programs rather than by users.  This directory should normally be
+     '/usr/local/libexec', but write it as '$(exec_prefix)/libexec'.
+     (If you are using Autoconf, write it as '@libexecdir@'.)
+
+   Data files used by the program during its execution are divided into
+categories in two ways.
+
+   * Some files are normally modified by programs; others are never
+     normally modified (though users may edit some of these).
+
+   * Some files are architecture-independent and can be shared by all
+     machines at a site; some are architecture-dependent and can be
+     shared only by machines of the same kind and operating system;
+     others may never be shared between two machines.
+
+   This makes for six different possibilities.  However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries.  It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+   Therefore, here are the variables Makefiles should use to specify
+directories:
+
+'datadir'
+     The directory for installing read-only architecture independent
+     data files.  This should normally be '/usr/local/share', but write
+     it as '$(prefix)/share'.  (If you are using Autoconf, write it as
+     '@datadir@'.)  As a special exception, see '$(infodir)' and
+     '$(includedir)' below.
+
+'sysconfdir'
+     The directory for installing read-only data files that pertain to a
+     single machine-that is to say, files for configuring a host.
+     Mailer and network configuration files, '/etc/passwd', and so forth
+     belong here.  All the files in this directory should be ordinary
+     ASCII text files.  This directory should normally be
+     '/usr/local/etc', but write it as '$(prefix)/etc'.  (If you are
+     using Autoconf, write it as '@sysconfdir@'.)
+
+     Do not install executables here in this directory (they probably
+     belong in '$(libexecdir)' or '$(sbindir)').  Also do not install
+     files that are modified in the normal course of their use (programs
+     whose purpose is to change the configuration of the system
+     excluded).  Those probably belong in '$(localstatedir)'.
+
+'sharedstatedir'
+     The directory for installing architecture-independent data files
+     which the programs modify while they run.  This should normally be
+     '/usr/local/com', but write it as '$(prefix)/com'.  (If you are
+     using Autoconf, write it as '@sharedstatedir@'.)
+
+'localstatedir'
+     The directory for installing data files which the programs modify
+     while they run, and that pertain to one specific machine.  Users
+     should never need to modify files in this directory to configure
+     the package's operation; put such configuration information in
+     separate files that go in '$(datadir)' or '$(sysconfdir)'.
+     '$(localstatedir)' should normally be '/usr/local/var', but write
+     it as '$(prefix)/var'.  (If you are using Autoconf, write it as
+     '@localstatedir@'.)
+
+'libdir'
+     The directory for object files and libraries of object code.  Do
+     not install executables here, they probably ought to go in
+     '$(libexecdir)' instead.  The value of 'libdir' should normally be
+     '/usr/local/lib', but write it as '$(exec_prefix)/lib'.  (If you
+     are using Autoconf, write it as '@libdir@'.)
+
+'infodir'
+     The directory for installing the Info files for this package.  By
+     default, it should be '/usr/local/info', but it should be written
+     as '$(prefix)/info'.  (If you are using Autoconf, write it as
+     '@infodir@'.)
+
+'lispdir'
+     The directory for installing any Emacs Lisp files in this package.
+     By default, it should be '/usr/local/share/emacs/site-lisp', but it
+     should be written as '$(prefix)/share/emacs/site-lisp'.
+
+     If you are using Autoconf, write the default as '@lispdir@'.  In
+     order to make '@lispdir@' work, you need the following lines in
+     your 'configure.in' file:
+
+          lispdir='${datadir}/emacs/site-lisp'
+          AC_SUBST(lispdir)
+
+'includedir'
+     The directory for installing header files to be included by user
+     programs with the C '#include' preprocessor directive.  This should
+     normally be '/usr/local/include', but write it as
+     '$(prefix)/include'.  (If you are using Autoconf, write it as
+     '@includedir@'.)
+
+     Most compilers other than GCC do not look for header files in
+     directory '/usr/local/include'.  So installing the header files
+     this way is only useful with GCC. Sometimes this is not a problem
+     because some libraries are only really intended to work with GCC.
+     But some libraries are intended to work with other compilers.  They
+     should install their header files in two places, one specified by
+     'includedir' and one specified by 'oldincludedir'.
+
+'oldincludedir'
+     The directory for installing '#include' header files for use with
+     compilers other than GCC. This should normally be '/usr/include'.
+     (If you are using Autoconf, you can write it as '@oldincludedir@'.)
+
+     The Makefile commands should check whether the value of
+     'oldincludedir' is empty.  If it is, they should not try to use it;
+     they should cancel the second installation of the header files.
+
+     A package should not replace an existing header in this directory
+     unless the header came from the same package.  Thus, if your Foo
+     package provides a header file 'foo.h', then it should install the
+     header file in the 'oldincludedir' directory if either (1) there is
+     no 'foo.h' there or (2) the 'foo.h' that exists came from the Foo
+     package.
+
+     To tell whether 'foo.h' came from the Foo package, put a magic
+     string in the file--part of a comment--and 'grep' for that string.
+
+   Unix-style man pages are installed in one of the following:
+
+'mandir'
+     The top-level directory for installing the man pages (if any) for
+     this package.  It will normally be '/usr/local/man', but you should
+     write it as '$(prefix)/man'.  (If you are using Autoconf, write it
+     as '@mandir@'.)
+
+'man1dir'
+     The directory for installing section 1 man pages.  Write it as
+     '$(mandir)/man1'.
+'man2dir'
+     The directory for installing section 2 man pages.  Write it as
+     '$(mandir)/man2'
+'...'
+
+     *Don't make the primary documentation for any GNU software be a man
+     page.  Write a manual in Texinfo instead.  Man pages are just for
+     the sake of people running GNU software on Unix, which is a
+     secondary application only.*
+
+'manext'
+     The file name extension for the installed man page.  This should
+     contain a period followed by the appropriate digit; it should
+     normally be '.1'.
+
+'man1ext'
+     The file name extension for installed section 1 man pages.
+'man2ext'
+     The file name extension for installed section 2 man pages.
+'...'
+     Use these names instead of 'manext' if the package needs to install
+     man pages in more than one section of the manual.
+
+   And finally, you should set the following variable:
+
+'srcdir'
+     The directory for the sources being compiled.  The value of this
+     variable is normally inserted by the 'configure' shell script.  (If
+     you are using Autconf, use 'srcdir = @srcdir@'.)
+
+   For example:
+
+     # Common prefix for installation directories.
+     # NOTE: This directory must exist when you start the install.
+     prefix = /usr/local
+     exec_prefix = $(prefix)
+     # Where to put the executable for the command `gcc'.
+     bindir = $(exec_prefix)/bin
+     # Where to put the directories used by the compiler.
+     libexecdir = $(exec_prefix)/libexec
+     # Where to put the Info files.
+     infodir = $(prefix)/info
+
+   If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the 'install' rule to create these subdirectories.
+
+   Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above.  The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+
+File: standards.info,  Node: Standard Targets,  Next: Install Command Categories,  Prev: Directory Variables,  Up: Makefile Conventions
+
+7.2.5 Standard Targets for Users
+--------------------------------
+
+All GNU programs should have the following targets in their Makefiles:
+
+'all'
+     Compile the entire program.  This should be the default target.
+     This target need not rebuild any documentation files; Info files
+     should normally be included in the distribution, and DVI files
+     should be made only when explicitly asked for.
+
+     By default, the Make rules should compile and link with '-g', so
+     that executable programs have debugging symbols.  Users who don't
+     mind being helpless can strip the executables later if they wish.
+
+'install'
+     Compile the program and copy the executables, libraries, and so on
+     to the file names where they should reside for actual use.  If
+     there is a simple test to verify that a program is properly
+     installed, this target should run that test.
+
+     Do not strip executables when installing them.  Devil-may-care
+     users can use the 'install-strip' target to do that.
+
+     If possible, write the 'install' target rule so that it does not
+     modify anything in the directory where the program was built,
+     provided 'make all' has just been done.  This is convenient for
+     building the program under one user name and installing it under
+     another.
+
+     The commands should create all the directories in which files are
+     to be installed, if they don't already exist.  This includes the
+     directories specified as the values of the variables 'prefix' and
+     'exec_prefix', as well as all subdirectories that are needed.  One
+     way to do this is by means of an 'installdirs' target as described
+     below.
+
+     Use '-' before any command for installing a man page, so that
+     'make' will ignore any errors.  This is in case there are systems
+     that don't have the Unix man page documentation system installed.
+
+     The way to install Info files is to copy them into '$(infodir)'
+     with '$(INSTALL_DATA)' (*note Command Variables::), and then run
+     the 'install-info' program if it is present.  'install-info' is a
+     program that edits the Info 'dir' file to add or update the menu
+     entry for the given Info file; it is part of the Texinfo package.
+     Here is a sample rule to install an Info file:
+
+          $(DESTDIR)$(infodir)/foo.info: foo.info
+                  $(POST_INSTALL)
+          # There may be a newer info file in . than in srcdir.
+                  -if test -f foo.info; then d=.; \
+                   else d=$(srcdir); fi; \
+                  $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
+          # Run install-info only if it exists.
+          # Use `if' instead of just prepending `-' to the
+          # line so we notice real errors from install-info.
+          # We use `$(SHELL) -c' because some shells do not
+          # fail gracefully when there is an unknown command.
+                  if $(SHELL) -c 'install-info --version' \
+                     >/dev/null 2>&1; then \
+                    install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+                                 $(DESTDIR)$(infodir)/foo.info; \
+                  else true; fi
+
+     When writing the 'install' target, you must classify all the
+     commands into three categories: normal ones, "pre-installation"
+     commands and "post-installation" commands.  *Note Install Command
+     Categories::.
+
+'uninstall'
+     Delete all the installed files--the copies that the 'install'
+     target creates.
+
+     This rule should not modify the directories where compilation is
+     done, only the directories where files are installed.
+
+     The uninstallation commands are divided into three categories, just
+     like the installation commands.  *Note Install Command
+     Categories::.
+
+'install-strip'
+     Like 'install', but strip the executable files while installing
+     them.  In simple cases, this target can use the 'install' target in
+     a simple way:
+
+          install-strip:
+                  $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+                          install
+
+     But if the package installs scripts as well as real executables,
+     the 'install-strip' target can't just refer to the 'install'
+     target; it has to strip the executables but not the scripts.
+
+     'install-strip' should not strip the executables in the build
+     directory which are being copied for installation.  It should only
+     strip the copies that are installed.
+
+     Normally we do not recommend stripping an executable unless you are
+     sure the program has no bugs.  However, it can be reasonable to
+     install a stripped executable for actual execution while saving the
+     unstripped executable elsewhere in case there is a bug.
+
+'clean'
+
+     Delete all files from the current directory that are normally
+     created by building the program.  Don't delete the files that
+     record the configuration.  Also preserve files that could be made
+     by building, but normally aren't because the distribution comes
+     with them.
+
+     Delete '.dvi' files here if they are not part of the distribution.
+
+'distclean'
+     Delete all files from the current directory that are created by
+     configuring or building the program.  If you have unpacked the
+     source and built the program without creating any other files,
+     'make distclean' should leave only the files that were in the
+     distribution.
+
+'mostlyclean'
+     Like 'clean', but may refrain from deleting a few files that people
+     normally don't want to recompile.  For example, the 'mostlyclean'
+     target for GCC does not delete 'libgcc.a', because recompiling it
+     is rarely necessary and takes a lot of time.
+
+'maintainer-clean'
+     Delete almost everything from the current directory that can be
+     reconstructed with this Makefile.  This typically includes
+     everything deleted by 'distclean', plus more: C source files
+     produced by Bison, tags tables, Info files, and so on.
+
+     The reason we say "almost everything" is that running the command
+     'make maintainer-clean' should not delete 'configure' even if
+     'configure' can be remade using a rule in the Makefile.  More
+     generally, 'make maintainer-clean' should not delete anything that
+     needs to exist in order to run 'configure' and then begin to build
+     the program.  This is the only exception; 'maintainer-clean' should
+     delete everything else that can be rebuilt.
+
+     The 'maintainer-clean' target is intended to be used by a
+     maintainer of the package, not by ordinary users.  You may need
+     special tools to reconstruct some of the files that 'make
+     maintainer-clean' deletes.  Since these files are normally included
+     in the distribution, we don't take care to make them easy to
+     reconstruct.  If you find you need to unpack the full distribution
+     again, don't blame us.
+
+     To help make users aware of this, the commands for the special
+     'maintainer-clean' target should start with these two:
+
+          @echo 'This command is intended for maintainers to use; it'
+          @echo 'deletes files that may need special tools to rebuild.'
+
+'TAGS'
+     Update a tags table for this program.
+
+'info'
+     Generate any Info files needed.  The best way to write the rules is
+     as follows:
+
+          info: foo.info
+
+          foo.info: foo.texi chap1.texi chap2.texi
+                  $(MAKEINFO) $(srcdir)/foo.texi
+
+     You must define the variable 'MAKEINFO' in the Makefile.  It should
+     run the 'makeinfo' program, which is part of the Texinfo
+     distribution.
+
+     Normally a GNU distribution comes with Info files, and that means
+     the Info files are present in the source directory.  Therefore, the
+     Make rule for an info file should update it in the source
+     directory.  When users build the package, ordinarily Make will not
+     update the Info files because they will already be up to date.
+
+'dvi'
+     Generate DVI files for all Texinfo documentation.  For example:
+
+          dvi: foo.dvi
+
+          foo.dvi: foo.texi chap1.texi chap2.texi
+                  $(TEXI2DVI) $(srcdir)/foo.texi
+
+     You must define the variable 'TEXI2DVI' in the Makefile.  It should
+     run the program 'texi2dvi', which is part of the Texinfo
+     distribution.(1)  Alternatively, write just the dependencies, and
+     allow GNU 'make' to provide the command.
+
+'dist'
+     Create a distribution tar file for this program.  The tar file
+     should be set up so that the file names in the tar file start with
+     a subdirectory name which is the name of the package it is a
+     distribution for.  This name can include the version number.
+
+     For example, the distribution tar file of GCC version 1.40 unpacks
+     into a subdirectory named 'gcc-1.40'.
+
+     The easiest way to do this is to create a subdirectory
+     appropriately named, use 'ln' or 'cp' to install the proper files
+     in it, and then 'tar' that subdirectory.
+
+     Compress the tar file with 'gzip'.  For example, the actual
+     distribution file for GCC version 1.40 is called 'gcc-1.40.tar.gz'.
+
+     The 'dist' target should explicitly depend on all non-source files
+     that are in the distribution, to make sure they are up to date in
+     the distribution.  *Note Making Releases: Releases.
+
+'check'
+     Perform self-tests (if any).  The user must build the program
+     before running the tests, but need not install the program; you
+     should write the self-tests so that they work when the program is
+     built but not installed.
+
+   The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+'installcheck'
+     Perform installation tests (if any).  The user must build and
+     install the program before running the tests.  You should not
+     assume that '$(bindir)' is in the search path.
+
+'installdirs'
+     It's useful to add a target named 'installdirs' to create the
+     directories where files are installed, and their parent
+     directories.  There is a script called 'mkinstalldirs' which is
+     convenient for this; you can find it in the Texinfo package.  You
+     can use a rule like this:
+
+          # Make sure all installation directories (e.g. $(bindir))
+          # actually exist by making them if necessary.
+          installdirs: mkinstalldirs
+                  $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+                                          $(libdir) $(infodir) \
+                                          $(mandir)
+
+     or, if you wish to support 'DESTDIR',
+
+          # Make sure all installation directories (e.g. $(bindir))
+          # actually exist by making them if necessary.
+          installdirs: mkinstalldirs
+                  $(srcdir)/mkinstalldirs \
+                      $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+                      $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+                      $(DESTDIR)$(mandir)
+
+     This rule should not modify the directories where compilation is
+     done.  It should do nothing but create installation directories.
+
+   ---------- Footnotes ----------
+
+   (1) 'texi2dvi' uses TeX to do the real work of formatting.  TeX is
+not distributed with Texinfo.
+
+
+File: standards.info,  Node: Install Command Categories,  Prev: Standard Targets,  Up: Makefile Conventions
+
+7.2.6 Install Command Categories
+--------------------------------
+
+When writing the 'install' target, you must classify all the commands
+into three categories: normal ones, "pre-installation" commands and
+"post-installation" commands.
+
+   Normal commands move files into their proper places, and set their
+modes.  They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+   Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+   Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+   The most common use for a post-installation command is to run
+'install-info'.  This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed.  It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+   Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+   To classify the commands in the 'install' rule into these three
+categories, insert "category lines" among them.  A category line
+specifies the category for the commands that follow.
+
+   A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end.  There are three
+variables you can use, one for each category; the variable name
+specifies the category.  Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+   Here are the three possible category lines, each with a comment that
+explains what it means:
+
+             $(PRE_INSTALL)     # Pre-install commands follow.
+             $(POST_INSTALL)    # Post-install commands follow.
+             $(NORMAL_INSTALL)  # Normal commands follow.
+
+   If you don't use a category line at the beginning of the 'install'
+rule, all the commands are classified as normal until the first category
+line.  If you don't use any category lines, all the commands are
+classified as normal.
+
+   These are the category lines for 'uninstall':
+
+             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
+             $(POST_UNINSTALL)    # Post-uninstall commands follow.
+             $(NORMAL_UNINSTALL)  # Normal commands follow.
+
+   Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+   If the 'install' or 'uninstall' target has any dependencies which act
+as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also.  This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+   Pre-installation and post-installation commands should not run any
+programs except for these:
+
+     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+     egrep expand expr false fgrep find getopt grep gunzip gzip
+     hostname install install-info kill ldconfig ln ls md5sum
+     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+     test touch true uname xargs yes
+
+   The reason for distinguishing the commands in this way is for the
+sake of making binary packages.  Typically a binary package contains all
+the executables and other files that need to be installed, and has its
+own method of installing them--so it does not need to run the normal
+installation commands.  But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+   Programs to build binary packages work by extracting the
+pre-installation and post-installation commands.  Here is one way of
+extracting the pre-installation commands:
+
+     make -n install -o all \
+           PRE_INSTALL=pre-install \
+           POST_INSTALL=post-install \
+           NORMAL_INSTALL=normal-install \
+       | gawk -f pre-install.awk
+
+where the file 'pre-install.awk' could contain this:
+
+     $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+     on {print $0}
+     $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+   The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+
+File: standards.info,  Node: Releases,  Prev: Makefile Conventions,  Up: Managing Releases
+
+7.3 Making Releases
+===================
+
+Package the distribution of 'Foo version 69.96' up in a gzipped tar file
+with the name 'foo-69.96.tar.gz'.  It should unpack into a subdirectory
+named 'foo-69.96'.
+
+   Building and installing the program should never modify any of the
+files contained in the distribution.  This means that all the files that
+form part of the program in any way must be classified into "source
+files" and "non-source files".  Source files are written by humans and
+never changed automatically; non-source files are produced from source
+files by programs under the control of the Makefile.
+
+   The distribution should contain a file named 'README' which gives the
+name of the package, and a general description of what it does.  It is
+also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any.  The 'README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+   The 'README' file should refer to the file 'INSTALL', which should
+contain an explanation of the installation procedure.
+
+   The 'README' file should also refer to the file which contains the
+copying conditions.  The GNU GPL, if used, should be in a file called
+'COPYING'.  If the GNU LGPL is used, it should be in a file called
+'COPYING.LIB'.
+
+   Naturally, all the source files must be in the distribution.  It is
+okay to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them.  We commonly include non-source files
+produced by Bison, 'lex', TeX, and 'makeinfo'; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+   Non-source files that might actually be modified by building and
+installing the program should *never* be included in the distribution.
+So if you do distribute non-source files, always make sure they are up
+to date when you make a new distribution.
+
+   Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of 'tar' which preserve the ownership and
+permissions of the files from the tar archive will be able to extract
+all the files even if the user is unprivileged.
+
+   Make sure that all the files in the distribution are world-readable.
+
+   Make sure that no file name in the distribution is more than 14
+characters long.  Likewise, no file created by building the program
+should have a name longer than 14 characters.  The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+   Don't include any symbolic links in the distribution itself.  If the
+tar file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links.  Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the distribution.
+
+   Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOS will truncate extra
+characters both before and after the period.  Thus, 'foobarhacker.c' and
+'foobarhacker.o' are not ambiguous; they are truncated to 'foobarha.c'
+and 'foobarha.o', which are distinct.
+
+   Include in your distribution a copy of the 'texinfo.tex' you used to
+test print any '*.texinfo' or '*.texi' files.
+
+   Likewise, if your program uses small GNU software packages like
+regex, getopt, obstack, or termcap, include them in the distribution
+file.  Leaving them out would make the distribution file a little
+smaller at the expense of possible inconvenience to a user who doesn't
+know what other files to get.
+
+
+File: standards.info,  Node: References,  Next: Index,  Prev: Managing Releases,  Up: Top
+
+8 References to Non-Free Software and Documentation
+***************************************************
+
+A GNU program should not recommend use of any non-free program.  We
+can't stop some people from writing proprietary programs, or stop other
+people from using them.  But we can and should avoid helping to
+advertise them to new customers.
+
+   Sometimes it is important to mention how to build your package on top
+of some non-free operating system or other non-free base package.  In
+such cases, please mention the name of the non-free package or system in
+the briefest possible way.  Don't include any references for where to
+find more information about the proprietary program.  The goal should be
+that people already using the proprietary program will get the advice
+they need about how to use your free program, while people who don't
+already use the proprietary program will not see anything to encourage
+them to take an interest in it.
+
+   Likewise, a GNU package should not refer the user to any non-free
+documentation for free software.  The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+
+
+File: standards.info,  Node: Index,  Prev: References,  Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* #endif, commenting:                    Comments.            (line  54)
+* --help option:                         Command-Line Interfaces.
+                                                              (line 107)
+* --version option:                      Command-Line Interfaces.
+                                                              (line  34)
+* -Wall compiler option:                 Syntactic Conventions.
+                                                              (line  10)
+* accepting contributions:               Contributions.       (line   6)
+* address for bug reports:               Command-Line Interfaces.
+                                                              (line 113)
+* ANSI C standard:                       Standard C.          (line   6)
+* arbitrary limits on data:              Semantics.           (line   6)
+* autoconf:                              System Portability.  (line  23)
+* avoiding proprietary code:             Reading Non-Free Code.
+                                                              (line   6)
+* behavior, dependent on program's name: User Interfaces.     (line   6)
+* binary packages:                       Install Command Categories.
+                                                              (line  80)
+* bindir:                                Directory Variables. (line  45)
+* braces, in C source:                   Formatting.          (line   6)
+* bug reports:                           Command-Line Interfaces.
+                                                              (line 113)
+* canonical name of a program:           Command-Line Interfaces.
+                                                              (line  41)
+* casting pointers to integers:          CPU Portability.     (line  66)
+* change logs:                           Change Logs.         (line   6)
+* change logs, conditional changes:      Conditional Changes. (line   6)
+* change logs, style:                    Style of Change Logs.
+                                                              (line   6)
+* command-line arguments, decoding:      Semantics.           (line  46)
+* command-line interface:                Command-Line Interfaces.
+                                                              (line   6)
+* commenting:                            Comments.            (line   6)
+* compatibility with C and POSIX standards: Compatibility.    (line   6)
+* compiler warnings:                     Syntactic Conventions.
+                                                              (line  10)
+* conditional changes, and change logs:  Conditional Changes. (line   6)
+* conditionals, comments for:            Comments.            (line  54)
+* configure:                             Configuration.       (line   6)
+* control-L:                             Formatting.          (line 114)
+* conventions for makefiles:             Makefile Conventions.
+                                                              (line   6)
+* corba:                                 Graphical Interfaces.
+                                                              (line  16)
+* credits for manuals:                   Manual Credits.      (line   6)
+* data types, and portability:           CPU Portability.     (line   6)
+* declaration for system functions:      System Functions.    (line  21)
+* documentation:                         Documentation.       (line   6)
+* doschk:                                Names.               (line  38)
+* downloading this manual:               Preface.             (line  17)
+* error messages:                        Semantics.           (line  19)
+* error messages, formatting:            Errors.              (line   6)
+* exec_prefix:                           Directory Variables. (line  27)
+* expressions, splitting:                Formatting.          (line  77)
+* file usage:                            File Usage.          (line   6)
+* file-name limitations:                 Names.               (line  38)
+* formatting error messages:             Errors.              (line   6)
+* formatting source code:                Formatting.          (line   6)
+* formfeed:                              Formatting.          (line 114)
+* function argument, declaring:          Syntactic Conventions.
+                                                              (line   6)
+* function prototypes:                   Standard C.          (line  17)
+* getopt:                                Command-Line Interfaces.
+                                                              (line   6)
+* gettext:                               Internationalization.
+                                                              (line   6)
+* gnome:                                 Graphical Interfaces.
+                                                              (line  16)
+* graphical user interface:              Graphical Interfaces.
+                                                              (line   6)
+* gtk:                                   Graphical Interfaces.
+                                                              (line   6)
+* GUILE:                                 Source Language.     (line  37)
+* implicit int:                          Syntactic Conventions.
+                                                              (line   6)
+* impossible conditions:                 Semantics.           (line  70)
+* internationalization:                  Internationalization.
+                                                              (line   6)
+* legal aspects:                         Legal Issues.        (line   6)
+* legal papers:                          Contributions.       (line   6)
+* libexecdir:                            Directory Variables. (line  58)
+* libraries:                             Libraries.           (line   6)
+* library functions, and portability:    System Functions.    (line   6)
+* license for manuals:                   License for Manuals. (line   6)
+* lint:                                  Syntactic Conventions.
+                                                              (line 109)
+* long option names:                     Option Table.        (line   6)
+* long-named options:                    Command-Line Interfaces.
+                                                              (line  12)
+* makefile, conventions for:             Makefile Conventions.
+                                                              (line   6)
+* malloc return value:                   Semantics.           (line  25)
+* man pages:                             Man Pages.           (line   6)
+* manual structure:                      Manual Structure Details.
+                                                              (line   6)
+* memory allocation failure:             Semantics.           (line  25)
+* memory usage:                          Memory Usage.        (line   6)
+* message text, and internationalization: Internationalization.
+                                                              (line  29)
+* mmap:                                  Mmap.                (line   6)
+* multiple variables in a line:          Syntactic Conventions.
+                                                              (line  35)
+* names of variables and functions:      Names.               (line   6)
+* NEWS file:                             NEWS File.           (line   6)
+* non-POSIX systems, and portability:    System Portability.  (line  32)
+* non-standard extensions:               Using Extensions.    (line   6)
+* NUL characters:                        Semantics.           (line  11)
+* open brace:                            Formatting.          (line   6)
+* optional features, configure-time:     Configuration.       (line  76)
+* options for compatibility:             Compatibility.       (line  14)
+* output device and program's behavior:  User Interfaces.     (line  13)
+* packaging:                             Releases.            (line   6)
+* portability, and data types:           CPU Portability.     (line   6)
+* portability, and library functions:    System Functions.    (line   6)
+* portability, between system types:     System Portability.  (line   6)
+* POSIX compatibility:                   Compatibility.       (line   6)
+* POSIXLY_CORRECT, environment variable: Compatibility.       (line  21)
+* post-installation commands:            Install Command Categories.
+                                                              (line   6)
+* pre-installation commands:             Install Command Categories.
+                                                              (line   6)
+* prefix:                                Directory Variables. (line  17)
+* program configuration:                 Configuration.       (line   6)
+* program design:                        Design Advice.       (line   6)
+* program name and its behavior:         User Interfaces.     (line   6)
+* program's canonical name:              Command-Line Interfaces.
+                                                              (line  41)
+* programming languages:                 Source Language.     (line   6)
+* proprietary programs:                  Reading Non-Free Code.
+                                                              (line   6)
+* README file:                           Releases.            (line  17)
+* references to non-free material:       References.          (line   6)
+* releasing:                             Managing Releases.   (line   6)
+* sbindir:                               Directory Variables. (line  51)
+* signal handling:                       Semantics.           (line  59)
+* spaces before open-paren:              Formatting.          (line  71)
+* standard command-line options:         Command-Line Interfaces.
+                                                              (line  31)
+* standards for makefiles:               Makefile Conventions.
+                                                              (line   6)
+* string library functions:              System Functions.    (line  54)
+* syntactic conventions:                 Syntactic Conventions.
+                                                              (line   6)
+* table of long options:                 Option Table.        (line   6)
+* temporary files:                       Semantics.           (line  84)
+* temporary variables:                   Syntactic Conventions.
+                                                              (line  23)
+* texinfo.tex, in a distribution:        Releases.            (line  73)
+* TMPDIR environment variable:           Semantics.           (line  84)
+* trademarks:                            Trademarks.          (line   6)
+* where to obtain standards.texi:        Preface.             (line  17)
+
+
+
+Tag Table:
+Node: Top978
+Node: Preface1577
+Node: Legal Issues3167
+Node: Reading Non-Free Code3631
+Node: Contributions5358
+Node: Trademarks7512
+Node: Design Advice8575
+Node: Source Language9082
+Node: Compatibility11087
+Node: Using Extensions12715
+Node: Standard C14292
+Node: Program Behavior16663
+Node: Semantics17582
+Node: Libraries22275
+Node: Errors23520
+Node: User Interfaces25301
+Node: Graphical Interfaces26906
+Node: Command-Line Interfaces27941
+Node: Option Table33430
+Node: Memory Usage48439
+Node: File Usage49464
+Node: Writing C50212
+Node: Formatting51052
+Node: Comments55116
+Node: Syntactic Conventions58417
+Node: Names61829
+Node: System Portability64022
+Node: CPU Portability66407
+Node: System Functions69665
+Node: Internationalization74857
+Node: Mmap78010
+Node: Documentation78720
+Node: GNU Manuals79825
+Node: Doc Strings and Manuals84882
+Node: Manual Structure Details86435
+Node: License for Manuals87853
+Node: Manual Credits88826
+Node: Printed Manuals89219
+Node: NEWS File89905
+Node: Change Logs90583
+Node: Change Log Concepts91377
+Node: Style of Change Logs93240
+Node: Simple Changes95275
+Node: Conditional Changes96519
+Node: Indicating the Part Changed97941
+Node: Man Pages98468
+Node: Reading other Manuals100092
+Node: Managing Releases100883
+Node: Configuration101638
+Node: Makefile Conventions108542
+Node: Makefile Basics109306
+Node: Utilities in Makefiles112480
+Node: Command Variables114626
+Node: Directory Variables118203
+Node: Standard Targets129094
+Ref: Standard Targets-Footnote-1140335
+Node: Install Command Categories140436
+Node: Releases145018
+Node: References149105
+Node: Index150501
+
+End Tag Table
diff --git a/doc/standards.texi b/doc/standards.texi
new file mode 100644
index 0000000..be5bfb5
--- /dev/null
+++ b/doc/standards.texi
@@ -0,0 +1,3656 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename standards.info
+@settitle GNU Coding Standards
+@c This date is automagically updated when you save this file:
+@set lastupdate March 23, 2001
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@c @setchapternewpage odd
+@setchapternewpage off
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex vr cp
+
+@c This is used by a cross ref in make-stds.texi
+@set CODESTD  1
+@iftex
+@set CHAPTER chapter
+@end iftex
+@ifinfo
+@set CHAPTER node
+@end ifinfo
+
+@ifinfo
+GNU Coding Standards
+Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node Top, Preface, (dir), (dir)
+@top Version
+
+Last updated @value{lastupdate}.
+@end ifinfo
+
+@menu
+* Preface::                 About the GNU Coding Standards
+* Legal Issues::            Keeping Free Software Free
+* Design Advice::           General Program Design
+* Program Behavior::        Program Behavior for All Programs
+* Writing C::               Making The Best Use of C
+* Documentation::           Documenting Programs
+* Managing Releases::       The Release Process
+* References::              References to Non-Free Software or Documentation
+* Index::
+@end menu
+
+@node Preface
+@chapter About the GNU Coding Standards
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers.  Their purpose is to make the GNU system clean,
+consistent, and easy to install.  This document can also be read as a
+guide to writing portable, robust and reliable programs.  It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language.  The rules often
+state reasons for writing in a certain way.
+
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+@cindex where to obtain @code{standards.texi}
+@cindex downloading this manual
+If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version.  You can ftp the GNU
+Coding Standards from any GNU FTP host in the directory
+@file{/pub/gnu/standards/}.  The GNU Coding Standards are available
+there in several different formats: @file{standards.text},
+@file{standards.info}, and @file{standards.dvi}, as well as the
+Texinfo ``source'' which is divided in two files:
+@file{standards.texi} and @file{make-stds.texi}.  The GNU Coding
+Standards are also available on the GNU World Wide Web server:
+@uref{http://www.gnu.org/prep/standards_toc.html}.
+
+Corrections or suggestions for this document should be sent to
+@email{bug-standards@@gnu.org}.  If you make a suggestion, please include a
+suggested new wording for it; our time is limited.  We prefer a context
+diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
+you don't have those files, please mail your suggestion anyway.
+
+@node Legal Issues
+@chapter Keeping Free Software Free
+@cindex legal aspects
+
+This @value{CHAPTER} discusses how you can make sure that GNU software
+avoids legal difficulties, and other related issues.
+
+@menu
+* Reading Non-Free Code::       Referring to Proprietary Programs
+* Contributions::               Accepting Contributions
+* Trademarks::                  How We Deal with Trademark Issues
+@end menu
+
+@node Reading Non-Free Code
+@section Referring to Proprietary Programs
+@cindex proprietary programs
+@cindex avoiding proprietary code
+
+Don't in any circumstances refer to Unix source code for or during
+your work on GNU!  (Or to any other proprietary programs.)
+
+If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different.  You could keep the entire input file in core and scan it
+there instead of using stdio.  Use a smarter algorithm discovered more
+recently than the Unix program.  Eliminate use of temporary files.  Do
+it in one pass instead of two (we did this in the assembler).
+
+Or, on the contrary, emphasize simplicity instead of speed.  For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+Or go for generality.  For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead.  Make sure your program handles NULs and
+other funny characters in the input files.  Add a programming language
+for extensibility and write part of the program in that language.
+
+Or turn some parts of the program into independently usable libraries.
+Or use a simple garbage collector instead of tracking precisely when
+to free memory, or use a new GNU facility such as obstacks.
+
+@node Contributions
+@section Accepting Contributions
+@cindex legal papers
+@cindex accepting contributions
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it---just as we asked you to
+sign papers initially.  @emph{Each} person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers.  Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+This applies both before you release the program and afterward.  If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+This also applies to comments and documentation files.  For copyright
+law, comments and code are just text.  Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+We know it is frustrating to ask for legal papers; it's frustrating for
+us as well.  But if you don't wait, you are going out on a limb---for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes.  Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use.  For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+The very worst thing is if you forget to tell us about the other
+contributor.  We could be very embarrassed in court some day as a
+result.
+
+We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+@node Trademarks
+@section Trademarks
+@cindex trademarks
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so.  The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them.  There is no legal requirement for them.
+
+What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities.  For example, since ``Objective C'' is
+(or at least was) a trademark, we made sure to say that we provide a
+``compiler for the Objective C language'' rather than an ``Objective C
+compiler''.  The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using ``Objective C'' as a label for the compiler rather than for the
+language.
+
+@node Design Advice
+@chapter General Program Design
+@cindex program design
+
+This @value{CHAPTER} discusses some of the issues you should take into
+account when designing your program.
+
+@c                         Standard or ANSI C
+@c
+@c In 1989 the American National Standards Institute (ANSI) standardized
+@c C   as  standard  X3.159-1989.    In  December   of  that   year  the
+@c International Standards Organization ISO  adopted the ANSI C standard
+@c making  minor changes.   In 1990  ANSI then  re-adopted  ISO standard
+@c C. This version of C is known as either ANSI C or Standard C.
+
+@c A major revision of the C Standard appeared in 1999.
+
+@menu
+* Source Language::             Which languages to use.
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* Standard C::                  Using Standard C features
+@end menu
+
+@node Source Language
+@section Which Languages to Use
+@cindex programming languages
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C.  Using another language is like
+using a non-standard feature: it will cause trouble for users.  Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program.  For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+So in general it is much better to use C, rather than the
+comparable alternatives.
+
+But there are two exceptions to that conclusion:
+
+@itemize @bullet
+@item
+It is no problem to use another language to write a tool specifically
+intended for use with that language.  That is because the only people
+who want to build the tool will be those who have installed the other
+language anyway.
+
+@item
+If an application is of interest only to a narrow part of the community,
+then the question of which language it is written in has less effect on
+other people, so you may as well please yourself.
+@end itemize
+
+Many programs are designed to be extensible: they include an interpreter
+for a language that is higher level than C.  Often much of the program
+is written in that language, too.  The Emacs editor pioneered this
+technique.
+
+@cindex GUILE
+The standard extensibility interpreter for GNU software is GUILE, which
+implements the language Scheme (an especially clean and simple dialect
+of Lisp).  @uref{http://www.gnu.org/software/guile/}.  We don't reject
+programs written in other ``scripting languages'' such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+@node Compatibility
+@section Compatibility with Other Implementations
+@cindex compatibility with C and @sc{posix} standards
+@cindex @sc{posix} compatibility
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their
+behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
+their behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+@cindex options for compatibility
+Standard C and @sc{posix} prohibit many kinds of extensions.  Feel
+free to make the extensions anyway, and include a @samp{--ansi},
+@samp{--posix}, or @samp{--compatible} option to turn them off.
+However, if the extension has a significant chance of breaking any real
+programs or scripts, then it is not really upward compatible.  So you
+should try to redesign its interface to make it upward compatible.
+
+@cindex @code{POSIXLY_CORRECT}, environment variable
+Many GNU programs suppress extensions that conflict with @sc{posix} if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value).  Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+@code{vi} is replaced with Emacs.)  But it is nice to offer a compatible
+feature as well.  (There is a free @code{vi} clone, so we offer it.)
+
+Additional useful features are welcome regardless of whether
+there is any precedent for them.
+
+@node Using Extensions
+@section Using Non-standard Features
+@cindex non-standard extensions
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities.  Whether to use these
+extensions in implementing your program is a difficult question.
+
+On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program
+unless the other GNU tools are available.  This might cause the
+program to work on fewer kinds of machines.
+
+With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a ``keyword'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems.  Using GNU extensions in
+such programs would make many users unhappy, so we don't do that.
+
+Another exception is for programs that are used as part of compilation:
+anything that must be compiled with other compilers in order to
+bootstrap the GNU compilation facilities.  If these require the GNU
+compiler, then no one can compile them without having them installed
+already.  That would be extremely troublesome in certain cases.
+
+@node Standard C
+@section Standard C and Pre-Standard C
+@cindex @sc{ansi} C standard
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs.  There is one exception: do not ever use the
+``trigraph'' feature of Standard C.
+
+1999 Standard C is not widespread yet, so please do not require its
+features in programs.  It is ok to use its features if they are present.
+
+However, it is easy to support pre-standard compilers in most programs,
+so if you know how to do that, feel free.  If a program you are
+maintaining has such support, you should try to keep it working.
+
+@cindex function prototypes
+To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+@example
+int
+foo (int x, int y)
+@dots{}
+@end example
+
+@noindent
+write the definition in pre-standard style like this,
+
+@example
+int
+foo (x, y)
+     int x, y;
+@dots{}
+@end example
+
+@noindent
+and use a separate declaration to specify the argument prototype:
+
+@example
+int foo (int, int);
+@end example
+
+You need such a declaration anyway, in a header file, to get the benefit
+of prototypes in all the files where the function is called.  And once
+you have the declaration, you normally lose nothing by writing the
+function definition in the pre-standard style.
+
+This technique does not work for integer types narrower than @code{int}.
+If you think of an argument as being of a type narrower than @code{int},
+declare it as @code{int} instead.
+
+There are a few special cases where this technique is hard to use.  For
+example, if a function argument needs to hold the system type
+@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
+@code{int} on some machines; but you cannot use @code{int} instead,
+because @code{dev_t} is wider than @code{int} on some machines.  There
+is no type you can safely use on all machines in a non-standard
+definition.  The only way to support non-standard C and pass such an
+argument is to check the width of @code{dev_t} using Autoconf and choose
+the argument type accordingly.  This may not be worth the trouble.
+
+In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+@example
+/* Declare the prototype for a general external function.  */
+#if defined (__STDC__) || defined (WINDOWSNT)
+#define P_(proto) proto
+#else
+#define P_(proto) ()
+#endif
+@end example
+
+@node Program Behavior
+@chapter Program Behavior for All Programs
+
+This @value{CHAPTER} describes conventions for writing robust
+software.  It also describes general standards for error messages, the
+command line interface, and how libraries should behave.
+
+@menu
+* Semantics::                   Writing robust programs
+* Libraries::                   Library behavior
+* Errors::                      Formatting error messages
+* User Interfaces::             Standards about interfaces generally
+* Graphical Interfaces::        Standards for graphical interfaces
+* Command-Line Interfaces::     Standards for command line interfaces
+* Option Table::                Table of long options
+* Memory Usage::                When and how to care about memory needs
+* File Usage::                  Which files to use, and where
+@end menu
+
+@node Semantics
+@section Writing Robust Programs
+
+@cindex arbitrary limits on data
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including file names, lines, files, and symbols, by allocating
+all data structures dynamically.  In most Unix utilities, ``long lines
+are silently truncated''.  This is not acceptable in a GNU utility.
+
+@cindex @code{NUL} characters
+Utilities reading files should not drop NUL characters, or any other
+nonprinting characters @emph{including those with codes above 0177}.
+The only sensible exceptions would be utilities specifically intended
+for interface to certain types of terminals or printers
+that can't handle those characters.
+Whenever possible, try to make programs work properly with
+sequences of bytes that represent multibyte characters, using encodings
+such as UTF-8 and others.
+
+@cindex error messages
+Check every system call for an error return, unless you know you wish to
+ignore errors.  Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+
+@cindex @code{malloc} return value
+@cindex memory allocation failure
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero.  Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero.  GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged.  Feel free to assume the bug is fixed.  If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+If @code{malloc} fails in a noninteractive program, make that a fatal
+error.  In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.  This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+@cindex command-line arguments, decoding
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+@c ADR: why?
+
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly.  If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These are supported compatibly by GNU.
+
+@cindex signal handling
+The preferred signal handling facilities are the BSD variant of
+@code{signal}, and the @sc{posix} @code{sigaction} function; the
+alternative USG @code{signal} interface is an inferior design.
+
+Nowadays, using the @sc{posix} signal functions may be the easiest way
+to make a program portable.  If you use @code{signal}, then on GNU/Linux
+systems running GNU libc version 1, you should include
+@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
+behavior.  It is up to you whether to support systems where
+@code{signal} has only the USG behavior, or give up on them.
+
+@cindex impossible conditions
+In error checks that detect ``impossible'' conditions, just abort.
+There is usually no point in printing any message.  These checks
+indicate the existence of bugs.  Whoever wants to fix the bugs will have
+to read the source code and run a debugger.  So explain the problem with
+comments in the source.  The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+Do not use a count of errors as the exit status for a program.
+@emph{That does not work}, because exit status values are limited to 8
+bits (0 through 255).  A single run of the program might have 256
+errors; if you try to return 256 as the exit status, the parent process
+will see 0 as the status, and it will appear that the program succeeded.
+
+@cindex temporary files
+@cindex @code{TMPDIR} environment variable
+If you make temporary files, check the @code{TMPDIR} environment
+variable; if that variable is defined, use the specified directory
+instead of @file{/tmp}.
+
+In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories.  In C, you can
+avoid this problem by creating temporary files in this manner:
+
+@example
+fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+@end example
+
+@noindent
+or by using the @code{mkstemps} function from libiberty.
+
+In bash, use @code{set -C} to avoid this problem.
+
+@node Libraries
+@section Library Behavior
+@cindex libraries
+
+Try to make library functions reentrant.  If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix.  In addition, there should only be one of these in any given
+library member.  This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}.  The @samp{_} should be
+followed by the chosen name prefix for the library, to prevent
+collisions with other libraries.  These can go in the same files with
+user entry points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+@node Errors
+@section Formatting Error Messages
+@cindex formatting error messages
+@cindex error messages, formatting
+
+Error messages from compilers should look like this:
+
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+If you want to mention the column number, use this format:
+
+@example
+@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+@noindent
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line.  (Both
+of these conventions are chosen for compatibility.)  Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+Error messages from other noninteractive programs should look like this:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+when there is an appropriate source file, or like this:
+
+@example
+@var{program}: @var{message}
+@end example
+
+@noindent
+when there is no relevant source file.
+
+If you want to mention the column number, use this format:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@end example
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or file name.  Also, it should not end
+with a period.
+
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter.  But they should not
+end with a period.
+
+@node User Interfaces
+@section Standards for Interfaces Generally
+
+@cindex program name and its behavior
+@cindex behavior, dependent on program's name
+Please don't make the behavior of a utility depend on the name used
+to invoke it.  It is useful sometimes to make a link to a utility
+with a different name, and that should not change what it does.
+
+Instead, use a run time option or a compilation switch or both
+to select among the alternate behaviors.
+
+@cindex output device and program's behavior
+Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with.  Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then.  (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device.  It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+@node Graphical Interfaces
+@section Standards for Graphical Interfaces
+@cindex graphical user interface
+
+@cindex gtk
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+``displaying jpeg images while in console mode'').
+
+In addition, please provide a command-line interface to control the
+functionality.  (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.)  This is
+so that the same jobs can be done from scripts.
+
+@cindex corba
+@cindex gnome
+Please also consider providing a CORBA interface (for use from GNOME), a
+library interface (for use from C), and perhaps a keyboard-driven
+console interface (for use by users from console mode).  Once you are
+doing the work to provide the functionality and the graphical interface,
+these won't be much extra work.
+
+@node Command-Line Interfaces
+@section Standards for Command Line Interfaces
+@cindex command-line interface
+
+@findex getopt
+It is a good idea to follow the @sc{posix} guidelines for the
+command-line options of a program.  The easiest way to do this is to use
+@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used.  This is not what @sc{posix}
+specifies; it is a GNU extension.
+
+@cindex long-named options
+Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+@code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program (@pxref{Option Table}).
+
+It is usually a good idea for file names given as ordinary arguments to
+be input files only; any output files would be specified using options
+(preferably @samp{-o} or @samp{--output}).  Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it.  This will lead to more consistency
+among GNU utilities, and fewer idiosyncrasies for users to remember.
+
+@cindex standard command-line options
+All programs should support two standard options: @samp{--version}
+and @samp{--help}.
+
+@table @code
+@cindex @samp{--version} option
+@item --version
+This option should direct the program to print information about its name,
+version, origin and legal status, all on standard output, and then exit
+successfully.  Other options and arguments should be ignored once this
+is seen, and the program should not perform its normal function.
+
+@cindex canonical name of a program
+@cindex program's canonical name
+The first line is meant to be easy for a program to parse; the version
+number proper starts after the last space.  In addition, it contains
+the canonical name for this program, in this format:
+
+@example
+GNU Emacs 19.30
+@end example
+
+@noindent
+The program's name should be a constant string; @emph{don't} compute it
+from @code{argv[0]}.  The idea is to state the standard or canonical
+name for the program, not its file name.  There are other ways to find
+out the precise file name where a command is found in @code{PATH}.
+
+If the program is a subsidiary part of a larger package, mention the
+package name in parentheses, like this:
+
+@example
+emacsserver (GNU Emacs) 19.30
+@end example
+
+@noindent
+If the package has a version number which is different from this
+program's version number, you can mention the package version number
+just before the close-parenthesis.
+
+If you @strong{need} to mention the version numbers of libraries which
+are distributed separately from the package which contains this program,
+you can do so by printing an additional line of version info for each
+library you want to mention.  Use the same format for these lines as for
+the first line.
+
+Please do not mention all of the libraries that the program uses ``just
+for completeness''---that would produce a lot of unhelpful clutter.
+Please mention library version numbers only if you find in practice that
+they are very important to you in debugging.
+
+The following line, after the version number line or lines, should be a
+copyright notice.  If more than one copyright notice is called for, put
+each on a separate line.
+
+Next should follow a brief statement that the program is free software,
+and that users are free to copy and change it on certain conditions.  If
+the program is covered by the GNU GPL, say so here.  Also mention that
+there is no warranty, to the extent permitted by law.
+
+It is ok to finish the output with a list of the major authors of the
+program, as a way of giving credit.
+
+Here's an example of output that follows these rules:
+
+@smallexample
+GNU Emacs 19.34.5
+Copyright (C) 1996 Free Software Foundation, Inc.
+GNU Emacs comes with NO WARRANTY,
+to the extent permitted by law.
+You may redistribute copies of GNU Emacs
+under the terms of the GNU General Public License.
+For more information about these matters,
+see the files named COPYING.
+@end smallexample
+
+You should adapt this to your program, of course, filling in the proper
+year, copyright holder, name of program, and the references to
+distribution terms, and changing the rest of the wording as necessary.
+
+This copyright notice only needs to mention the most recent year in
+which changes were made---there's no need to list the years for previous
+versions' changes.  You don't have to mention the name of the program in
+these notices, if that is inconvenient, since it appeared in the first
+line.
+
+@cindex @samp{--help} option
+@item --help
+This option should output brief documentation for how to invoke the
+program, on standard output, then exit successfully.  Other options and
+arguments should be ignored once this is seen, and the program should
+not perform its normal function.
+
+@cindex address for bug reports
+@cindex bug reports
+Near the end of the @samp{--help} option's output there should be a line
+that says where to mail bug reports.  It should have this format:
+
+@example
+Report bugs to @var{mailing-address}.
+@end example
+@end table
+
+@node Option Table
+@section Table of Long Options
+@cindex long option names
+@cindex table of long options
+
+Here is a table of long options used by GNU programs.  It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with.  If you use names not already in the table,
+please send @email{bug-standards@@gnu.org} a list of them, with their
+meanings, so we can update the table.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period.   --friedman
+
+@table @samp
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item archive-name
+@samp{-n} in @code{shar}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assign
+@samp{-v} in @code{gawk}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-pager
+@samp{-a} in @code{wdiff}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item avoid-wraps
+@samp{-n} in @code{wdiff}.
+
+@item background
+For server programs, run in the background.
+
+@item backward-search
+@samp{-B} in @code{ctags}.
+
+@item basename
+@samp{-f} in @code{shar}.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item bits-per-code
+@samp{-b} in @code{shar}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c@t{++}
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compat
+Used in @code{gawk}.
+
+@item compress
+@samp{-Z} in @code{tar} and @code{shar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyleft
+@samp{-W copyleft} in @code{gawk}.
+
+@item copyright
+@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
+@samp{-W copyright} in @code{gawk}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cut-mark
+@samp{-c} in @code{shar}.
+
+@item cxref
+@samp{-x} in @code{ctags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{ctags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item device
+Specify an I/O device (special file name).
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs.  In @code{ls}, it
+means to show directories themselves rather than their contents.  In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item end-delete
+@samp{-x} in @code{wdiff}.
+
+@item end-insert
+@samp{-z} in @code{wdiff}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in @code{makeinfo}.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item exit-0
+@samp{-e} in @code{unshar}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item fatal-warnings
+@samp{-E} in @code{m4}.
+
+@item file
+@samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item field-separator
+@samp{-F} in @code{gawk}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in @code{makeinfo}.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in @code{makeinfo}.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item force-prefix
+@samp{-F} in @code{shar}.
+
+@item foreground
+For server programs, run in the foreground;
+in other words, don't do anything special to run the server
+in the background.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item freeze-state
+@samp{-F} in @code{m4}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar} and @code{shar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item here-delimiter
+@samp{-d} in @code{shar}.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item html
+In @code{makeinfo}, output HTML.  
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff} and @code{wdiff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+
+@item ignore-indentation
+@samp{-I} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item init-file
+In some programs, specify the name of the file to read as the user's
+init file.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item intermix-type
+@samp{-p} in @code{shar}.
+
+@item iso-8601
+Used in @code{date}
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item language
+@samp{-l} in @code{etags}.
+
+@item less-mode
+@samp{-l} in @code{wdiff}.
+
+@item level-for-gzip
+@samp{-g} in @code{shar}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item lint
+@itemx lint-old
+Used in @code{gawk}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do, and tell @email{gnu@@gnu.org}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mixed-uuencode
+@samp{-M} in @code{shar}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item nesting-limit
+@samp{-L} in @code{m4}.
+
+@item net-headers
+@samp{-a} in @code{shar}.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-character-count
+@samp{-w} in @code{shar}.
+
+@item no-check-existing
+@samp{-x} in @code{shar}.
+
+@item no-common
+@samp{-3} in @code{wdiff}.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-deleted
+@samp{-1} in @code{wdiff}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-inserted
+@samp{-2} in @code{wdiff}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-piping
+@samp{-P} in @code{shar}.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-regex
+@samp{-R} in @code{etags}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in @code{makeinfo}.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-timestamp
+@samp{-m} in @code{shar}.
+
+@item no-validate
+Used in @code{makeinfo}.
+
+@item no-wait
+Used in @code{emacsclient}.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item options
+@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
+@code{fdmountd}, and @code{fdumount}.
+
+@item output
+In various programs, specify the output file name.
+
+@item output-prefix
+@samp{-o} in @code{shar}.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item overwrite
+@samp{-c} in @code{unshar}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in @code{makeinfo}.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item posix
+Used in @code{gawk}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item printer
+@samp{-p} in @code{wdiff}.
+
+@item prompt
+@samp{-p} in @code{ed}.
+
+@item proxy
+Specify an HTTP proxy.
+
+@item query-user
+@samp{-X} in @code{shar}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output.  @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quiet-unshar
+@samp{-Q} in @code{shar}
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item re-interval
+Used in @code{gawk}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in @code{makeinfo}.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac} and @code{etags}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item reload-state
+@samp{-R} in @code{m4}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item socket
+Specify a file descriptor for a network server to use for its socket,
+instead of opening and binding a new socket.  This provides a way to
+run, in a nonpriveledged process, a server that normally needs a
+reserved port number.
+
+@item sort
+Used in @code{ls}.
+
+@item source
+@samp{-W source} in @code{gawk}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item split-at
+@samp{-E} in @code{unshar}.
+
+@item split-size-limit
+@samp{-L} in @code{shar}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item start-delete
+@samp{-w} in @code{wdiff}.
+
+@item start-insert
+@samp{-y} in @code{wdiff}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item statistics
+@samp{-s} in @code{wdiff}.
+
+@item stdin-file-list
+@samp{-S} in @code{shar}.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item submitter
+@samp{-s} in @code{shar}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+@samp{-t} in @code{wdiff}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item text-files
+@samp{-T} in @code{shar}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item timeout
+Specify how long to wait before giving up on some operation.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-W traditional} in @code{gawk};
+@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{ctags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{ctags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
+
+@item usage
+Used in @code{gawk}; same as @samp{--help}.
+
+@item uuencode
+@samp{-B} in @code{shar}.
+
+@item vanilla-operation
+@samp{-V} in @code{shar}.
+
+@item verbose
+Print more information about progress.  Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{ctags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item whole-size-limit
+@samp{-l} in @code{shar}.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+@end table
+
+@node Memory Usage
+@section Memory Usage
+@cindex memory usage
+
+If a program typically uses just a few meg of memory, don't bother making any
+effort to reduce memory usage.  For example, if it is impractical for
+other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into core to operate on them.
+
+However, for programs such as @code{cat} or @code{tail}, that can
+usefully operate on very large files, it is important to avoid using a
+technique that would artificially limit the size of files it can handle.
+If a program works by lines and could be applied to arbitrary
+user-supplied input files, it should keep only a line in memory, because
+this is not very hard and users will want to be able to operate on input
+files that are bigger than will fit in core all at once.
+
+If your program creates complicated data structures, just make them in
+core and give a fatal error if @code{malloc} returns zero.
+
+@node File Usage
+@section File Usage
+@cindex file usage
+
+Programs should be prepared to operate when @file{/usr} and @file{/etc}
+are read-only file systems.  Thus, if the program manages log files,
+lock files, backup files, score files, or any other files which are
+modified for internal purposes, these files should not be stored in
+@file{/usr} or @file{/etc}.
+
+There are two exceptions.  @file{/etc} is used to store system
+configuration information; it is reasonable for a program to modify
+files in @file{/etc} when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+@node Writing C
+@chapter Making The Best Use of C
+
+This @value{CHAPTER} provides advice on how best to use the C language
+when writing GNU software.
+
+@menu
+* Formatting::                  Formatting Your Source Code
+* Comments::                    Commenting Your Work
+* Syntactic Conventions::       Clean Use of C Constructs
+* Names::                       Naming Variables and Functions
+* System Portability::          Portability between different operating systems
+* CPU Portability::             Supporting the range of CPU types
+* System Functions::            Portability and ``standard'' library functions
+* Internationalization::        Techniques for internationalization
+* Mmap::                        How you can safely use @code{mmap}.
+@end menu
+
+@node Formatting
+@section Formatting Your Source Code
+@cindex formatting source code
+
+@cindex open brace
+@cindex braces, in C source
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero.  Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+It is also important for function definitions to start the name of the
+function in column zero.  This helps people to search for function
+definitions, and may also help certain tools recognize them.  Thus,
+the proper format is this:
+
+@example
+static char *
+concat (s1, s2)        /* Name starts in column zero here */
+     char *s1, *s2;
+@{                     /* Open brace in column zero here */
+  @dots{}
+@}
+@end example
+
+@noindent
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+  @dots{}
+@}
+@end example
+
+In Standard C, if the arguments don't fit nicely on one line,
+split it like this:
+
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+              double a_double, float a_float)
+@dots{}
+@end example
+
+The rest of this section gives our recommendations for other aspects of
+C formatting style, which is also the default style of the @code{indent}
+program in version 1.2 and newer.  It corresponds to the options
+
+@smallexample
+-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+@end smallexample
+
+We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+But whatever style you use, please use it consistently, since a mixture
+of styles within one program tends to look ugly.  If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+For the body of the function, our recommended style looks like this:
+
+@example
+if (x < foo (y, z))
+  haha = bar[4] + 5;
+else
+  @{
+    while (z)
+      @{
+        haha += foo (z, z);
+        z--;
+      @}
+    return ++x + bar ();
+  @}
+@end example
+
+@cindex spaces before open-paren
+We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas.  Especially after the commas.
+
+When you split an expression into multiple lines, split it
+before an operator, not after one.  Here is the right way:
+
+@cindex expressions, splitting
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+    && remaining_condition)
+@end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+
+@example
+mode = (inmode[j] == VOIDmode
+        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+        ? outmode[j] : inmode[j]);
+@end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+@example
+mode = ((inmode[j] == VOIDmode
+         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+        ? outmode[j] : inmode[j]);
+@end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+    + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+
+@noindent
+but Emacs would alter it.  Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+     + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+
+Format do-while statements like this:
+
+@example
+do
+  @{
+    a = foo (a);
+  @}
+while (a > 0);
+@end example
+
+@cindex formfeed
+@cindex control-L
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+
+@node Comments
+@section Commenting Your Work
+@cindex commenting
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+
+Please write the comments in a GNU program in English, because English
+is the one language that nearly all programmers in all countries can
+read.  If you do not write English well, please write comments in
+English as well as you can, then ask other people to help rewrite them.
+If you can't write comments in English, please find someone to work with
+you and translate your comments into English.
+
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for.  It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion.  If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+Also explain the significance of the return value, if there is one.
+
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work.  Also, please write
+complete sentences and capitalize the first word.  If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier.  If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values.  The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself.  Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+
+There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+
+There should be a comment on each static variable as well, like this:
+
+@example
+/* Nonzero means truncate lines in the display;
+   zero means continue them.  */
+int truncate_lines;
+@end example
+
+@cindex conditionals, comments for
+@cindex @code{#endif}, commenting
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested.  The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}.  @samp{#else} should have a comment describing the condition
+@emph{and sense} of the code that follows.  For example:
+
+@example
+@group
+#ifdef foo
+  @dots{}
+#else /* not foo */
+  @dots{}
+#endif /* not foo */
+@end group
+@group
+#ifdef foo
+  @dots{}
+#endif /* foo */
+@end group
+@end example
+
+@noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+
+@example
+@group
+#ifndef foo
+  @dots{}
+#else /* foo */
+  @dots{}
+#endif /* foo */
+@end group
+@group
+#ifndef foo
+  @dots{}
+#endif /* not foo */
+@end group
+@end example
+
+@node Syntactic Conventions
+@section Clean Use of C Constructs
+@cindex syntactic conventions
+
+@cindex implicit @code{int}
+@cindex function argument, declaring
+Please explicitly declare the types of all objects.  For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return @code{int} rather than omitting the
+@code{int}.
+
+@cindex compiler warnings
+@cindex @samp{-Wall} compiler option
+Some programmers like to use the GCC @samp{-Wall} option, and change the
+code whenever it issues a warning.  If you want to do this, then do.
+Other programmers prefer not to use @samp{-Wall}, because it gives
+warnings for valid and legitimate code which they do not want to change.
+If you want to do this, then do.  The compiler should be your servant,
+not your master.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file.  Don't put @code{extern} declarations inside
+functions.
+
+@cindex temporary variables
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+
+@cindex multiple variables in a line
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead
+of this:
+
+@example
+@group
+int    foo,
+       bar;
+@end group
+@end example
+
+@noindent
+write either this:
+
+@example
+int foo, bar;
+@end example
+
+@noindent
+or this:
+
+@example
+int foo;
+int bar;
+@end example
+
+@noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
+
+@example
+if (foo)
+  if (bar)
+    win ();
+  else
+    lose ();
+@end example
+
+@noindent
+always like this:
+
+@example
+if (foo)
+  @{
+    if (bar)
+      win ();
+    else
+      lose ();
+  @}
+@end example
+
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+
+@example
+if (foo)
+  @dots{}
+else if (bar)
+  @dots{}
+@end example
+
+@noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+
+@example
+if (foo)
+  @dots{}
+else
+  @{
+    if (bar)
+      @dots{}
+  @}
+@end example
+
+Don't declare both a structure tag and variables or typedefs in the
+same declaration.  Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+
+Try to avoid assignments inside @code{if}-conditions.  For example,
+don't write this:
+
+@example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+  fatal ("virtual memory exhausted");
+@end example
+
+@noindent
+instead, write this:
+
+@example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+  fatal ("virtual memory exhausted");
+@end example
+
+@pindex lint
+Don't make the program ugly to placate @code{lint}.  Please don't insert any
+casts to @code{void}.  Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+@node Names
+@section Naming Variables and Functions
+
+@cindex names of variables and functions
+The names of global variables and functions in a program serve as
+comments of a sort.  So don't choose terse names---instead, look for
+names that give useful information about the meaning of the variable or
+function.  In a GNU program, names should be English, like other
+comments.
+
+Local variable names can be shorter, because they are used only within
+one context, where (presumably) comments explain their purpose.
+
+Try to limit your use of abbreviations in symbol names.  It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them.  Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter.  A comment should state both the exact meaning of
+the option and its letter.  For example,
+
+@example
+@group
+/* Ignore changes in horizontal whitespace (-b).  */
+int ignore_space_change_flag;
+@end group
+@end example
+
+When you want to define names with constant integer values, use
+@code{enum} rather than @samp{#define}.  GDB knows about enumeration
+constants.
+
+@cindex file-name limitations
+@pindex doschk
+You might want to make sure that none of the file names would conflict
+the files were loaded onto an MS-DOS file system which shortens the
+names.  You can use the program @code{doschk} to test for this.
+
+Some GNU programs were designed to limit themselves to file names of 14
+characters or less, to avoid file name conflicts if they are read into
+older System V systems.  Please preserve this feature in the existing
+GNU programs that have it, but there is no need to do this in new GNU
+programs.  @code{doschk} also reports file names longer than 14
+characters.
+
+@node System Portability
+@section Portability between System Types
+@cindex portability, between system types
+
+In the Unix world, ``portability'' refers to porting to different Unix
+versions.  For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+The primary purpose of GNU software is to run on top of the GNU kernel,
+compiled with the GNU C compiler, on various types of @sc{cpu}.  So the
+kinds of portability that are absolutely necessary are quite limited.
+But it is important to support Linux-based GNU systems, since they
+are the form of GNU that is popular.
+
+Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to.  Supporting a variety of Unix-like systems is desirable, although
+not paramount.  It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+@pindex autoconf
+The easiest way to achieve portability to most Unix-like systems is to
+use Autoconf.  It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+Avoid using the format of semi-internal data bases (e.g., directories)
+when there is a higher-level alternative (@code{readdir}).
+
+@cindex non-@sc{posix} systems, and portability
+As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work.  When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+It is a good idea to define the ``feature test macro''
+@code{_GNU_SOURCE} when compiling your C files.  When you compile on GNU
+or GNU/Linux, this will enable the declarations of GNU library extension
+functions, and that will usually give you a compiler error message if
+you define the same function names in some other way in your program.
+(You don't have to actually @emph{use} these functions, if you prefer
+to make the program more portable to other systems.)
+
+But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings.  Doing so would make it hard
+to move your code into other GNU programs.
+
+@node CPU Portability
+@section Portability between @sc{cpu}s
+
+@cindex data types, and portability
+@cindex portability, and data types
+Even GNU systems will differ because of differences among @sc{cpu}
+types---for example, difference in byte ordering and alignment
+requirements.  It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+@code{int} will be less than 32 bits.  We don't support 16-bit machines
+in GNU.
+
+Similarly, don't make any effort to cater to the possibility that
+@code{long} will be smaller than predefined types like @code{size_t}.
+For example, the following code is ok:
+
+@example
+printf ("size = %lu\n", (unsigned long) sizeof array);
+printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+@end example
+
+1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64.  We will
+leave it to those who want to port GNU programs to that environment
+to figure out how to do it.
+
+Predefined file-size types like @code{off_t} are an exception: they are
+longer than @code{long} on many platforms, so code like the above won't
+work with them.  One way to print an @code{off_t} value portably is to
+print its digits yourself, one by one.
+
+Don't assume that the address of an @code{int} object is also the
+address of its least-significant byte.  This is false on big-endian
+machines.  Thus, don't make the following mistake:
+
+@example
+int c;
+@dots{}
+while ((c = getchar()) != EOF)
+  write(file_descriptor, &c, 1);
+@end example
+
+When calling functions, you need not worry about the difference between
+pointers of various types, or between pointers and integers.  On most
+machines, there's no difference anyway.  As for the few machines where
+there is a difference, all of them support Standard C prototypes, so you can
+use prototypes (perhaps conditionalized to be active only in Standard C)
+to make the code work on those systems.
+
+In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system.  For example, many GNU programs have error-reporting functions
+that pass their arguments along to @code{printf} and friends:
+
+@example
+error (s, a1, a2, a3)
+     char *s;
+     char *a1, *a2, *a3;
+@{
+  fprintf (stderr, "error: ");
+  fprintf (stderr, s, a1, a2, a3);
+@}
+@end example
+
+@noindent
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+``correct'' alternative.  Be sure @emph{not} to use a prototype for such
+functions.
+
+If you have decided to use Standard C, then you can instead define
+@code{error} using @file{stdarg.h}, and pass the arguments along to
+@code{vfprintf}.
+
+@cindex casting pointers to integers
+Avoid casting pointers to integers if you can.  Such casts greatly
+reduce portability, and in most programs they are easy to avoid.  In the
+cases where casting pointers to integers is essential---such as, a Lisp
+interpreter which stores type information as well as an address in one
+word---you'll have to make explicit provisions to handle different word
+sizes.  You will also need to make provision for systems in which the
+normal range of addresses you can get from @code{malloc} starts far away
+from zero.
+
+@node System Functions
+@section Calling System Functions
+@cindex library functions, and portability
+@cindex portability, and library functions
+
+C implementations differ substantially.  Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do.  This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the return value of @code{sprintf}.  It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Be aware that @code{vfprintf} is not always available.
+
+@item
+@code{main} should be declared to return type @code{int}.  It should
+terminate either by calling @code{exit} or by returning the integer
+status code; make sure it cannot ever return an undefined value.
+
+@cindex declaration for system functions
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions.  If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens; thus, the disadvantage is only
+theoretical.  By contrast, actual declarations have frequently caused
+actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not a Standard C prototype.  The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}.  These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine.  For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@cindex string library functions
+@item
+The string functions require special treatment.  Some Unix systems have
+a header file @file{string.h}; others have @file{strings.h}.  Neither
+file name is portable.  There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think.  The newer standard
+string functions should be avoided anyway because many systems still
+don't support them.  The string functions you can use are these:
+
+@example
+strcpy   strncpy   strcat   strncat
+strlen   strcmp    strncmp
+strchr   strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values.  Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases.  It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}.  Luckily,
+there is no variation in the data type they return.  But there is
+variation in their names.  Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}.  Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program.  (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr} for new programs, since those are the standard
+names.)  Declare both of those names as functions returning @code{char
+*}.  On systems which don't support those names, define them as macros
+in terms of the other pair.  For example, here is what to put at the
+beginning of your file (or in a header) if you want to use the names
+@code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
+@node Internationalization
+@section Internationalization
+@cindex internationalization
+
+@pindex gettext
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages.  You should use this
+library in every program.  Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+Using GNU gettext involves putting a call to the @code{gettext} macro
+around each string that might need translation---like this:
+
+@example
+printf (gettext ("Processing file `%s'..."));
+@end example
+
+@noindent
+This permits GNU gettext to replace the string @code{"Processing file
+`%s'..."} with a translated version.
+
+Once a program uses gettext, please make a point of writing calls to
+@code{gettext} when you add new strings that call for translation.
+
+Using GNU gettext in a package involves specifying a @dfn{text domain
+name} for the package.  The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package---for example, @samp{fileutils} for the GNU file utilities.
+
+@cindex message text, and internationalization
+To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences.  When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+Here is an example of what not to do:
+
+@example
+printf ("%d file%s processed", nfiles,
+        nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+The problem with that example is that it assumes that plurals are made
+by adding `s'.  If you apply gettext to the format string, like this,
+
+@example
+printf (gettext ("%d file%s processed"), nfiles,
+        nfiles != 1 ? "s" : "");
+@end example
+
+@noindent
+the message can use different words, but it will still be forced to use
+`s' for the plural.  Here is a better way:
+
+@example
+printf ((nfiles != 1 ? "%d files processed"
+         : "%d file processed"),
+        nfiles);
+@end example
+
+@noindent
+This way, you can apply gettext to each of the two strings
+independently:
+
+@example
+printf ((nfiles != 1 ? gettext ("%d files processed")
+         : gettext ("%d file processed")),
+        nfiles);
+@end example
+
+@noindent
+This can be any method of forming the plural of the word for ``file'', and
+also handles languages that require agreement in the word for
+``processed''.
+
+A similar problem appears at the level of sentence structure with this
+code:
+
+@example
+printf ("#  Implicit rule search has%s been done.\n",
+        f->tried_implicit ? "" : " not");
+@end example
+
+@noindent
+Adding @code{gettext} calls to this code cannot give correct results for
+all languages, because negation in some languages requires adding words
+at more than one place in the sentence.  By contrast, adding
+@code{gettext} calls does the job straightfowardly if the code starts
+out like this:
+
+@example
+printf (f->tried_implicit
+        ? "#  Implicit rule search has been done.\n",
+        : "#  Implicit rule search has not been done.\n");
+@end example
+
+@node Mmap
+@section Mmap
+@findex mmap
+
+Don't assume that @code{mmap} either works on all files or fails
+for all files.  It may work on some files and fail on others.
+
+The proper way to use @code{mmap} is to try it on the specific file for
+which you want to use it---and if @code{mmap} doesn't work, fall back on
+doing the job in another way using @code{read} and @code{write}.
+
+The reason this precaution is needed is that the GNU kernel (the HURD)
+provides a user-extensible file system, in which there can be many
+different kinds of ``ordinary files.''  Many of them support
+@code{mmap}, but some do not.  It is important to make programs handle
+all these kinds of files.
+
+@node Documentation
+@chapter Documenting Programs
+@cindex documentation
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes.  If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+@menu
+* GNU Manuals::                 Writing proper manuals.
+* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
+* Manual Structure Details::    Specific structure conventions.
+* License for Manuals::         Writing the distribution terms for a manual.
+* Manual Credits::              Giving credit to documentation contributors.
+* Printed Manuals::             Mentioning the printed manual.
+* NEWS File::                   NEWS files supplement manuals.
+* Change Logs::                 Recording Changes
+* Man Pages::                   Man pages are secondary.
+* Reading other Manuals::       How far you can go in learning
+                                from other manuals.
+@end menu
+
+@node GNU Manuals
+@section GNU Manuals
+
+The preferred document format for the GNU system is the Texinfo
+formatting language.  Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners.  Texinfo
+makes it possible to produce a good quality formatted book, using
+@TeX{}, and to generate an Info file.  It is also possible to generate
+HTML output from Texinfo source.  See the Texinfo manual, either the
+hardcopy, or the on-line version available through @code{info} or the
+Emacs Info subsystem (@kbd{C-h i}).
+
+Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo.  It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know.  But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it.  Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented---but
+often they are different.  Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual.  That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+Instead, each manual should cover a coherent @emph{topic}.  For example,
+instead of a manual for @code{diff} and a manual for @code{diff3}, we
+have one manual for ``comparison of files'' which covers both of those
+programs, as well as @code{cmp}.  By documenting these programs
+together, we can make the whole subject clearer.
+
+The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands.  It should
+give examples of their use.  But don't organize the manual as a list of
+features.  Instead, organize it logically, by subtopics.  Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside).  A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+The Bison manual is a good example of this---please take a look at it
+to see what we mean.
+
+That is not as hard as it first sounds.  Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense.  Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs.  The watchword is, @emph{at each point, address
+the most fundamental and important issue raised by the preceding text.}
+
+If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject.  These provide
+the framework for a beginner to understand the rest of the manual.  The
+Bison manual provides a good example of how to do this.
+
+To serve as a reference, a manual should have an Index that list all the
+functions, variables, options, and important concepts that are part of
+the program.  One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+@ref{Index Entries, , Making Index Entries, texinfo, The GNU Texinfo
+Manual}, and see @ref{Indexing Commands, , Defining the Entries of an
+Index, texinfo, The GNU Texinfo manual}.
+
+Don't use Unix man pages as a model for how to write GNU documentation;
+most of them are terse, badly structured, and give inadequate
+explanation of the underlying concepts.  (There are, of course, some
+exceptions.)  Also, Unix man pages use a particular format which is
+different from what we use in GNU manuals.
+
+Please include an email address in the manual for where to report
+bugs @emph{in the manual}.
+
+Please do not use the term ``pathname'' that is used in Unix
+documentation; use ``file name'' (two words) instead.  We use the term
+``path'' only for search paths, which are lists of directory names.
+
+Please do not use the term ``illegal'' to refer to erroneous input to a
+computer program.  Please use ``invalid'' for this, and reserve the term
+``illegal'' for activities punishable by law.
+
+@node Doc Strings and Manuals
+@section Doc Strings and Manuals
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable.  You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them---but you must not do it.  That
+approach is a fundamental mistake.  The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+A documentation string needs to stand alone---when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection.  Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables.  The previous descriptions of functions and variables in the
+section will also have given information about the topic.  A description
+written to stand alone would repeat some of that information; this
+redundance looks bad.  Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+The only good way to use documentation strings in writing a good manual
+is to use them as a source of information for writing good text.
+
+@node Manual Structure Details
+@section Manual Structure Details
+@cindex manual structure
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual.  The Top node of the manual should
+also contain this information.  If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+Each program documented in the manual should have a node named
+@samp{@var{program} Invocation} or @samp{Invoking @var{program}}.  This
+node (together with its subnodes, if any) should describe the program's
+command line arguments and how to run it (the sort of information people
+would look in a man page for).  Start with an @samp{@@example}
+containing a template for all the options and arguments that the program
+uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns.  This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+The @samp{--usage} feature of the Info reader looks for such a node
+or menu item in order to find the relevant text, so it is essential
+for every Texinfo file to have one.
+
+If one manual describes several programs, it should have such a node for
+each program described in the manual.
+
+@node License for Manuals
+@section License for Manuals
+@cindex license for manuals
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long.  Likewise for a collection of short
+documents---you only need one copy of the GNU FDL for the whole
+collection.  For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation
+of how to employ the GFDL.
+
+Note that it is not obligatory to include a copy of the GNU GPL or GNU
+LGPL in a manual whose license is neither the GPL nor the LGPL.  It can
+be a good idea to include the program's license in a large manual; in a
+short manual, whose size would be increased considerably by including
+the program's license, it is probably better not to include it.
+
+@node Manual Credits
+@section Manual Credits
+@cindex credits for manuals
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual.  If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+@node Printed Manuals
+@section Printed Manuals
+
+The FSF publishes some GNU manuals in printed form.  To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it---for instance, with a link to the page
+@url{http://www.gnu.org/order/order.html}.  This should not be included
+in the printed manual, though, because there it is redundant.
+
+It is also useful to explain in the on-line forms of the manual how the
+user can print out the manual from the sources.
+
+@node NEWS File
+@section The NEWS File
+@cindex @file{NEWS} file
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning.  In each new release, add items to the front of the file and
+identify the version they pertain to.  Don't discard old items; leave
+them in the file after the newer items.  This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+@node Change Logs
+@section Change Logs
+@cindex change logs
+
+Keep a change log to describe all the changes made to program source
+files.  The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+@menu
+* Change Log Concepts::         
+* Style of Change Logs::        
+* Simple Changes::              
+* Conditional Changes::         
+* Indicating the Part Changed::
+@end menu
+
+@node Change Log Concepts
+@subsection Change Log Concepts
+
+You can think of the change log as a conceptual ``undo list'' which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log
+to tell them what is in it.  What they want from a change log is a
+clear explanation of how the earlier version differed.
+
+The change log file is normally called @file{ChangeLog} and covers an
+entire directory.  Each directory can have its own change log, or a
+directory can use the change log of its parent directory--it's up to
+you.
+
+Another alternative is to record change log information with a version
+control system such as RCS or CVS.  This can be converted automatically
+to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
+@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
+
+There's no need to describe the full purpose of the changes or how they
+work together.  If you think that a change calls for explanation, you're
+probably right.  Please do explain it---but please put the explanation
+in comments in the code, where people will see it whenever they see the
+code.  For example, ``New function'' is enough for the change log when
+you add a function, because there should be a comment before the
+function definition to explain what it does.
+
+However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+The easiest way to add an entry to @file{ChangeLog} is with the Emacs
+command @kbd{M-x add-change-log-entry}.  An entry should have an
+asterisk, the name of the changed file, and then in parentheses the name
+of the changed functions, variables or whatever, followed by a colon.
+Then describe the changes you made to that function or variable.
+
+@node Style of Change Logs
+@subsection Style of Change Logs
+@cindex change logs, style
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when, followed by
+descriptions of specific changes.  (These examples are drawn from Emacs
+and GCC.)
+
+@example
+1998-08-17  Richard Stallman  <rms@@gnu.org>
+
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+@end example
+
+It's important to name the changed function or variable in full.  Don't
+abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+For example, some people are tempted to abbreviate groups of function
+names by writing @samp{* register.el (@{insert,jump-to@}-register)};
+this is not a good idea, since searching for @code{jump-to-register} or
+@code{insert-register} would not find that entry.
+
+Separate unrelated change log entries with blank lines.  When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them.  Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+Break long lists of function names by closing continued lines with
+@samp{)}, rather than @samp{,}, and opening the continuation with
+@samp{(} as in this example:
+
+@example
+* keyboard.c (menu_bar_items, tool_bar_items)
+(Fexecute_extended_command): Deal with `keymap' property.
+@end example
+
+@node Simple Changes
+@subsection Simple Changes
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+When you change the calling sequence of a function in a simple fashion,
+and you change all the callers of the function to use the new calling
+sequence, there is no need to make individual entries for all the
+callers that you changed.  Just write in the entry for the function
+being called, ``All callers changed''---like this:
+
+@example
+* keyboard.c (Fcommand_execute): New arg SPECIAL.
+All callers changed.
+@end example
+
+When you change just comments or doc strings, it is enough to write an
+entry for the file, without mentioning the functions.  Just ``Doc
+fixes'' is enough for the change log.
+
+There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix.  Documentation does not consist of parts that must interact in a
+precisely engineered fashion.  To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+@node Conditional Changes
+@subsection Conditional Changes
+@cindex conditional changes, and change logs
+@cindex change logs, conditional changes
+
+C programs often contain compile-time @code{#if} conditionals.  Many
+changes are conditional; sometimes you add a new definition which is
+entirely contained in a conditional.  It is very useful to indicate in
+the change log the conditions for which the change applies.
+
+Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+Here is a simple example, describing a change which is conditional but
+does not have a function or entity name associated with it:
+
+@example
+* xterm.c [SOLARIS2]: Include string.h.
+@end example
+
+Here is an entry describing a new definition which is entirely
+conditional.  This new definition for the macro @code{FRAME_WINDOW_P} is
+used only when @code{HAVE_X_WINDOWS} is defined:
+
+@example
+* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+@end example
+
+Here is an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+
+@example
+* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+@end example
+
+Here is an entry for a change that takes affect only when
+a certain macro is @emph{not} defined:
+
+@example
+(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+@end example
+
+@node Indicating the Part Changed
+@subsection Indicating the Part Changed
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does.  Here is an entry
+for a change in the part of the function @code{sh-while-getopts} that
+deals with @code{sh} commands:
+
+@example
+* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+user-specified option string is empty.
+@end example
+
+
+@node Man Pages
+@section Man Pages
+@cindex man pages
+
+In the GNU project, man pages are secondary.  It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed.  The time
+you spend on the man page is time taken away from more useful work.
+
+For a simple program which changes little, updating the man page may be
+a small job.  Then there is little reason not to include a man page, if
+you have one.
+
+For a large program that changes a great deal, updating a man page may
+be a substantial burden.  If a user offers to donate a man page, you may
+find this gift costly to accept.  It may be better to refuse the man
+page unless the same person agrees to take full responsibility for
+maintaining it---so that you can wash your hands of it entirely.  If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating.  If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative.  The note should say how to access the Texinfo
+documentation.
+
+@node Reading other Manuals
+@section Reading other Manuals
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+It is ok to use these documents for reference, just as the author of a
+new algebra textbook can read other books on algebra.  A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject.  But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation.  Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+@node Managing Releases
+@chapter The Release Process
+@cindex releasing
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP.  You should set up your software so
+that it can be configured to run on a variety of systems.  Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below.  Doing so
+makes it easy to include your package into the larger framework of
+all GNU software.
+
+@menu
+* Configuration::               How Configuration Should Work
+* Makefile Conventions::	Makefile Conventions
+* Releases::                    Making Releases
+@end menu
+
+@node Configuration
+@section How Configuration Should Work
+@cindex program configuration
+
+@pindex configure
+Each GNU distribution should come with a shell script named
+@code{configure}.  This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+
+One way to do this is to make a link from a standard name such as
+@file{config.h} to the proper configuration file for the chosen system.
+If you use this technique, the distribution should @emph{not} contain a
+file named @file{config.h}.  This is so that people won't be able to
+build the program without configuring it first.
+
+Another thing that @code{configure} can do is to edit the Makefile.  If
+you do this, the distribution should @emph{not} contain a file named
+@file{Makefile}.  Instead, it should include a file @file{Makefile.in} which
+contains the input used for editing.  Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time.  The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}.  This is so that users won't think
+of trying to edit them by hand.
+
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured.  This file should be a shell script which,
+if run, will recreate the same configuration.
+
+The @code{configure} script should accept an option of the form
+@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory).  This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources.  If
+it finds the sources in one of these places, it should use them from
+there.  Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile.  Some rules may need to
+refer explicitly to the specified source directory.  To make this
+possible, @code{configure} can add to the Makefile a variable named
+@code{srcdir} whose value is precisely the specified directory.
+
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for.  This argument should look like
+this:
+
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+
+For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
+
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine.  Thus, @samp{sun3-sunos4.1}
+would be a valid alias.  For many programs, @samp{vax-dec-ultrix} would
+be an alias for @samp{vax-dec-bsd}, simply because the differences
+between Ultrix and @sc{bsd} are rarely noticeable, but a few programs
+might need to distinguish them.
+@c Real 4.4BSD now runs on some Suns.
+
+There is a shell script called @file{config.sub} that you can use
+as a subroutine to validate system types and canonicalize aliases.
+
+@cindex optional features, configure-time
+Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}.  This allows users to choose which
+optional features to include.  Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another.  No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior.  The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+@c  Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include 
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc},
+@samp{gdb},
+@samp{x}, 
+and
+@samp{x-toolkit}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files.  That is outside the scope of what @samp{--with}
+options are for.
+@end table
+
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand.  In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}.  This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of the compilation process may support
+cross-compilation.  In such a case, the host and target machines for the
+program may be different.
+
+The @code{configure} script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option @samp{--target=@var{targettype}}.  The syntax for
+@var{targettype} is the same as for the host type.  So the command would
+look like this:
+
+@example
+./configure @var{hosttype} --target=@var{targettype}
+@end example
+
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--target} option, because configuring an entire operating system for
+cross-operation is not a meaningful operation.
+
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on.  Compilation packages accept a
+configuration option @samp{--build=@var{buildtype}} for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using
+@file{config.guess}), so this option is probably not necessary.  The
+host and target types normally default from the build type, so in
+bootstrapping a cross-compiler you must specify them both explicitly.
+
+Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo.  Done by roland@gnu.ai.mit.edu on 1/6/93.
+@comment For this document, turn chapters into sections, etc.
+@lowersections
+@include make-stds.texi
+@raisesections
+
+@node Releases
+@section Making Releases
+@cindex packaging
+
+Package the distribution of @code{Foo version 69.96} up in a gzipped tar
+file with the name @file{foo-69.96.tar.gz}.  It should unpack into a
+subdirectory named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution.  This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}.  Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+@cindex @file{README} file
+The distribution should contain a file named @file{README} which gives
+the name of the package, and a general description of what it does.  It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any.  The @file{README} file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+The @file{README} file should refer to the file @file{INSTALL}, which
+should contain an explanation of the installation procedure.
+
+The @file{README} file should also refer to the file which contains the
+copying conditions.  The GNU GPL, if used, should be in a file called
+@file{COPYING}.  If the GNU LGPL is used, it should be in a file called
+@file{COPYING.LIB}.
+
+Naturally, all the source files must be in the distribution.  It is okay
+to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them.  We commonly include non-source files
+produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+Non-source files that might actually be modified by building and
+installing the program should @strong{never} be included in the
+distribution.  So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long.  Likewise, no file created by building the program
+should have a name longer than 14 characters.  The reason for this is
+that some systems adhere to a foolish interpretation of the @sc{posix}
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+Don't include any symbolic links in the distribution itself.  If the tar
+file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links.  Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the
+distribution.
+
+Try to make sure that all the file names will be unique on MS-DOS.  A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOS will truncate extra
+characters both before and after the period.  Thus,
+@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+
+@cindex @file{texinfo.tex}, in a distribution
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} or @file{*.texi} files.
+
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
+
+@node References
+@chapter References to Non-Free Software and Documentation
+@cindex references to non-free material
+
+A GNU program should not recommend use of any non-free program.  We
+can't stop some people from writing proprietary programs, or stop other
+people from using them.  But we can and should avoid helping to
+advertise them to new customers.
+
+Sometimes it is important to mention how to build your package on top of
+some non-free operating system or other non-free base package.  In such
+cases, please mention the name of the non-free package or system in the
+briefest possible way.  Don't include any references for where to find
+more information about the proprietary program.  The goal should be that
+people already using the proprietary program will get the advice they
+need about how to use your free program, while people who don't already
+use the proprietary program will not see anything to encourage them to
+take an interest in it.
+
+Likewise, a GNU package should not refer the user to any non-free
+documentation for free software.  The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+
+@bye
+Local variables:
+update-date-leading-regexp: "@c This date is automagically updated when you save this file:\n@set lastupdate "
+update-date-trailing-regexp: ""
+eval: (load "/gd/gnuorg/update-date.el")
+eval: (add-hook 'write-file-hooks 'update-date)
+compile-command: "make just-standards"
+End:
diff --git a/doc/version.texi b/doc/version.texi
new file mode 100644
index 0000000..d854139
--- /dev/null
+++ b/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 2 December 2023
+@set UPDATED-MONTH December 2023
+@set EDITION 2.52.20231210
+@set VERSION 2.52.20231210