[nonworking commit] Started porting newlib

2 files changed, 7701 insertions, 0 deletions

diff --git a/Unix/info/configure.info b/Unix/info/configure.info
new file mode 100644
index 0000000..59c5038
--- /dev/null
+++ b/Unix/info/configure.info
@@ -0,0 +1,2773 @@
+This is configure.info, produced by makeinfo version 4.13 from
+../../newlib-1.15.0/etc/configure.texi.
+
+INFO-DIR-SECTION GNU admin
+START-INFO-DIR-ENTRY
+* configure: (configure).	The GNU configure and build system
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU configure and build system.
+
+   Copyright (C) 1998 Cygnus Solutions.
+
+   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: configure.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+GNU configure and build system
+******************************
+
+The GNU configure and build system.
+
+* Menu:
+
+* Introduction::		Introduction.
+* Getting Started::		Getting Started.
+* Files::			Files.
+* Configuration Names::		Configuration Names.
+* Cross Compilation Tools::	Cross Compilation Tools.
+* Canadian Cross::		Canadian Cross.
+* Cygnus Configure::		Cygnus Configure.
+* Multilibs::			Multilibs.
+* FAQ::				Frequently Asked Questions.
+* Index::			Index.
+
+
+File: configure.info,  Node: Introduction,  Next: Getting Started,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+This document describes the GNU configure and build systems.  It
+describes how autoconf, automake, libtool, and make fit together.  It
+also includes a discussion of the older Cygnus configure system.
+
+   This document does not describe in detail how to use each of the
+tools; see the respective manuals for that.  Instead, it describes
+which files the developer must write, which files are machine generated
+and how they are generated, and where certain common problems should be
+addressed.
+
+   This document draws on several sources, including the autoconf
+manual by David MacKenzie (*note autoconf overview: (autoconf)Top.),
+the automake manual by David MacKenzie and Tom Tromey (*note automake
+overview: (automake)Top.), the libtool manual by Gordon Matzigkeit
+(*note libtool overview: (libtool)Top.), and the Cygnus configure
+manual by K. Richard Pixley.
+
+* Menu:
+
+* Goals::			Goals.
+* Tools::			The tools.
+* History::			History.
+* Building::			Building.
+
+
+File: configure.info,  Node: Goals,  Next: Tools,  Up: Introduction
+
+1.1 Goals
+=========
+
+The GNU configure and build system has two main goals.
+
+   The first is to simplify the development of portable programs.  The
+system permits the developer to concentrate on writing the program,
+simplifying many details of portability across Unix and even Windows
+systems, and permitting the developer to describe how to build the
+program using simple rules rather than complex Makefiles.
+
+   The second is to simplify the building of programs distributed as
+source code.  All programs are built using a simple, standardized, two
+step process.  The program builder need not install any special tools in
+order to build the program.
+
+
+File: configure.info,  Node: Tools,  Next: History,  Prev: Goals,  Up: Introduction
+
+1.2 Tools
+=========
+
+The GNU configure and build system is comprised of several different
+tools.  Program developers must build and install all of these tools.
+
+   People who just want to build programs from distributed sources
+normally do not need any special tools beyond a Unix shell, a make
+program, and a C compiler.
+
+autoconf
+     provides a general portability framework, based on testing the
+     features of the host system at build time.
+
+automake
+     a system for describing how to build a program, permitting the
+     developer to write a simplified `Makefile'.
+
+libtool
+     a standardized approach to building shared libraries.
+
+gettext
+     provides a framework for translation of text messages into other
+     languages; not really discussed in this document.
+
+m4
+     autoconf requires the GNU version of m4; the standard Unix m4 does
+     not suffice.
+
+perl
+     automake requires perl.
+
+
+File: configure.info,  Node: History,  Next: Building,  Prev: Tools,  Up: Introduction
+
+1.3 History
+===========
+
+This is a very brief and probably inaccurate history.
+
+   As the number of Unix variants increased during the 1980s, it became
+harder to write programs which could run on all variants.  While it was
+often possible to use `#ifdef' to identify particular systems,
+developers frequently did not have access to every system, and the
+characteristics of some systems changed from version to version.
+
+   By 1992, at least three different approaches had been developed:
+   * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
+     Manfredi.
+
+   * The Cygnus configure script, by K. Richard Pixley, and the gcc
+     configure script, by Richard Stallman.  These use essentially the
+     same approach, and the developers communicated regularly.
+
+   * The autoconf program, by David MacKenzie.
+
+   The Metaconfig program is still used for Perl and a few other
+programs.  It is part of the Dist package.  I do not know if it is
+being developed.
+
+   In 1994, David MacKenzie and others modified autoconf to incorporate
+all the features of Cygnus configure.  Since then, there has been a
+slow but steady conversion of GNU programs from Cygnus configure to
+autoconf. gcc has been converted, eliminating the gcc configure script.
+
+   GNU autoconf was regularly maintained until late 1996.  As of this
+writing in June, 1998, it has no public maintainer.
+
+   Most programs are built using the make program, which requires the
+developer to write Makefiles describing how to build the programs.
+Since most programs are built in pretty much the same way, this led to a
+lot of duplication.
+
+   The X Window system is built using the imake tool, which uses a
+database of rules to eliminate the duplication.  However, building a
+tool which was developed using imake requires that the builder have
+imake installed, violating one of the goals of the GNU system.
+
+   The new BSD make provides a standard library of Makefile fragments,
+which permits developers to write very simple Makefiles.  However, this
+requires that the builder install the new BSD make program.
+
+   In 1994, David MacKenzie wrote the first version of automake, which
+permitted writing a simple build description which was converted into a
+Makefile which could be used by the standard make program.  In 1995, Tom
+Tromey completely rewrote automake in Perl, and he continues to enhance
+it.
+
+   Various free packages built libraries, and by around 1995 several
+included support to build shared libraries on various platforms.
+However, there was no consistent approach.  In early 1996, Gordon
+Matzigkeit began working on libtool, which provided a standardized
+approach to building shared libraries.  This was integrated into
+automake from the start.
+
+   The development of automake and libtool was driven by the GNITS
+project, a group of GNU maintainers who designed standardized tools to
+help meet the GNU coding standards.
+
+
+File: configure.info,  Node: Building,  Prev: History,  Up: Introduction
+
+1.4 Building
+============
+
+Most readers of this document should already know how to build a tool by
+running `configure' and `make'.  This section may serve as a quick
+introduction or reminder.
+
+   Building a tool is normally as simple as running `configure'
+followed by `make'.  You should normally run `configure' from an empty
+directory, using some path to refer to the `configure' script in the
+source directory.  The directory in which you run `configure' is called
+the "object directory".
+
+   In order to use a object directory which is different from the source
+directory, you must be using the GNU version of `make', which has the
+required `VPATH' support.  Despite this restriction, using a different
+object directory is highly recommended:
+   * It keeps the files generated during the build from cluttering up
+     your sources.
+
+   * It permits you to remove the built files by simply removing the
+     entire build directory.
+
+   * It permits you to build from the same sources with several sets of
+     configure options simultaneously.
+
+   If you don't have GNU `make', you will have to run `configure' in
+the source directory.  All GNU packages should support this; in
+particular, GNU packages should not assume the presence of GNU `make'.
+
+   After running `configure', you can build the tools by running `make'.
+
+   To install the tools, run `make install'.  Installing the tools will
+copy the programs and any required support files to the "installation
+directory".  The location of the installation directory is controlled
+by `configure' options, as described below.
+
+   In the Cygnus tree at present, the info files are built and
+installed as a separate step.  To build them, run `make info'.  To
+install them, run `make install-info'. The equivalent html files are
+also built and installed in a separate step. To build the html files,
+run `make html'. To install the html files run `make install-html'.
+
+   All `configure' scripts support a wide variety of options.  The most
+interesting ones are `--with' and `--enable' options which are
+generally specific to particular tools.  You can usually use the
+`--help' option to get a list of interesting options for a particular
+configure script.
+
+   The only generic options you are likely to use are the `--prefix'
+and `--exec-prefix' options.  These options are used to specify the
+installation directory.
+
+   The directory named by the `--prefix' option will hold machine
+independent files such as info files.
+
+   The directory named by the `--exec-prefix' option, which is normally
+a subdirectory of the `--prefix' directory, will hold machine dependent
+files such as executables.
+
+   The default for `--prefix' is `/usr/local'.  The default for
+`--exec-prefix' is the value used for `--prefix'.
+
+   The convention used in Cygnus releases is to use a `--prefix' option
+of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and
+to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where
+HOST is the configuration name of the host system (*note Configuration
+Names::).
+
+   Do not use either the source or the object directory as the
+installation directory.  That will just lead to confusion.
+
+
+File: configure.info,  Node: Getting Started,  Next: Files,  Prev: Introduction,  Up: Top
+
+2 Getting Started
+*****************
+
+To start using the GNU configure and build system with your software
+package, you must write three files, and you must run some tools to
+manually generate additional files.
+
+* Menu:
+
+* Write configure.in::		Write configure.in.
+* Write Makefile.am::		Write Makefile.am.
+* Write acconfig.h::		Write acconfig.h.
+* Generate files::		Generate files.
+* Getting Started Example::	Example.
+
+
+File: configure.info,  Node: Write configure.in,  Next: Write Makefile.am,  Up: Getting Started
+
+2.1 Write configure.in
+======================
+
+You must first write the file `configure.in'.  This is an autoconf
+input file, and the autoconf manual describes in detail what this file
+should look like.
+
+   You will write tests in your `configure.in' file to check for
+conditions that may change from one system to another, such as the
+presence of particular header files or functions.
+
+   For example, not all systems support the `gettimeofday' function.
+If you want to use the `gettimeofday' function when it is available,
+and to use some other function when it is not, you would check for this
+by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'.
+
+   When the configure script is run at build time, this will arrange to
+define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the
+`gettimeofday' function is available, and to not define the macro at
+all if the function is not available.  Your code can then use `#ifdef'
+to test whether it is safe to call `gettimeofday'.
+
+   If you have an existing body of code, the `autoscan' program may
+help identify potential portability problems, and hence configure tests
+that you will want to use.  *Note Invoking autoscan: (autoconf)Invoking
+autoscan.
+
+   Another handy tool for an existing body of code is `ifnames'.  This
+will show you all the preprocessor conditionals that the code already
+uses.  *Note Invoking ifnames: (autoconf)Invoking ifnames.
+
+   Besides the portability tests which are specific to your particular
+package, every `configure.in' file should contain the following macros.
+
+`AC_INIT'
+     This macro takes a single argument, which is the name of a file in
+     your package.  For example, `AC_INIT(foo.c)'.
+
+`AC_PREREQ(VERSION)'
+     This macro is optional.  It may be used to indicate the version of
+     `autoconf' that you are using.  This will prevent users from
+     running an earlier version of `autoconf' and perhaps getting an
+     invalid `configure' script.  For example, `AC_PREREQ(2.12)'.
+
+`AM_INIT_AUTOMAKE'
+     This macro takes two arguments: the name of the package, and a
+     version number.  For example, `AM_INIT_AUTOMAKE(foo, 1.0)'.  (This
+     macro is not needed if you are not using automake).
+
+`AM_CONFIG_HEADER'
+     This macro names the header file which will hold the preprocessor
+     macro definitions at run time.  Normally this should be
+     `config.h'.  Your sources would then use `#include "config.h"' to
+     include it.
+
+     This macro may optionally name the input file for that header
+     file; by default, this is `config.h.in', but that file name works
+     poorly on DOS filesystems.  Therefore, it is often better to name
+     it explicitly as `config.in'.
+
+     This is what you should normally put in `configure.in':
+          AM_CONFIG_HEADER(config.h:config.in)
+
+     (If you are not using automake, use `AC_CONFIG_HEADER' rather than
+     `AM_CONFIG_HEADER').
+
+`AM_MAINTAINER_MODE'
+     This macro always appears in Cygnus configure scripts.  Other
+     programs may or may not use it.
+
+     If this macro is used, the `--enable-maintainer-mode' option is
+     required to enable automatic rebuilding of generated files used by
+     the configure system.  This of course requires that developers be
+     aware of, and use, that option.
+
+     If this macro is not used, then the generated files will always be
+     rebuilt automatically.  This will cause problems if the wrong
+     versions of autoconf, automake, or others are in the builder's
+     `PATH'.
+
+     (If you are not using automake, you do not need to use this macro).
+
+`AC_EXEEXT'
+     Either this macro or `AM_EXEEXT' always appears in Cygnus configure
+     files.  Other programs may or may not use one of them.
+
+     This macro looks for the executable suffix used on the host
+     system.  On Unix systems, this is the empty string.  On Windows
+     systems, this is `.exe'.  This macro directs automake to use the
+     executable suffix as appropriate when creating programs.  This
+     macro does not take any arguments.
+
+     The `AC_EXEEXT' form is new, and is part of a Cygnus patch to
+     autoconf to support compiling with Visual C++.  Older programs use
+     `AM_EXEEXT' instead.
+
+     (Programs which do not use automake use neither `AC_EXEEXT' nor
+     `AM_EXEEXT').
+
+`AC_PROG_CC'
+     If you are writing C code, you will normally want to use this
+     macro.  It locates the C compiler to use.  It does not take any
+     arguments.
+
+     However, if this `configure.in' file is for a library which is to
+     be compiled by a cross compiler which may not fully work, then you
+     will not want to use `AC_PROG_CC'.  Instead, you will want to use a
+     variant which does not call the macro `AC_PROG_CC_WORKS'.  Examples
+     can be found in various `configure.in' files for libraries that are
+     compiled with cross compilers, such as libiberty or libgloss.
+     This is essentially a bug in autoconf, and there will probably be
+     a better workaround at some point.
+
+`AC_PROG_CXX'
+     If you are writing C++ code, you will want to use this macro.  It
+     locates the C++ compiler to use.  It does not take any arguments.
+     The same cross compiler comments apply as for `AC_PROG_CC'.
+
+`AM_PROG_LIBTOOL'
+     If you want to build libraries, and you want to permit them to be
+     shared, or you want to link against libraries which were built
+     using libtool, then you will need this macro.  This macro is
+     required in order to use libtool.
+
+     By default, this will cause all libraries to be built as shared
+     libraries.  To prevent this-to change the default-use
+     `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'.  The configure
+     options `--enable-shared' and `--disable-shared' may be used to
+     override the default at build time.
+
+`AC_DEFINE(_GNU_SOURCE)'
+     GNU packages should normally include this line before any other
+     feature tests.  This defines the macro `_GNU_SOURCE' when
+     compiling, which directs the libc header files to provide the
+     standard GNU system interfaces including all GNU extensions.  If
+     this macro is not defined, certain GNU extensions may not be
+     available.
+
+`AC_OUTPUT'
+     This macro takes a list of file names which the configure process
+     should produce.  This is normally a list of one or more `Makefile'
+     files in different directories.  If your package lives entirely in
+     a single directory, you would use simply `AC_OUTPUT(Makefile)'.
+     If you also have, for example, a `lib' subdirectory, you would use
+     `AC_OUTPUT(Makefile lib/Makefile)'.
+
+   If you want to use locally defined macros in your `configure.in'
+file, then you will need to write a `acinclude.m4' file which defines
+them (if not using automake, this file is called `aclocal.m4').
+Alternatively, you can put separate macros in an `m4' subdirectory, and
+put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the
+`aclocal' program will be able to find them.
+
+   The different macro prefixes indicate which tool defines the macro.
+Macros which start with `AC_' are part of autoconf.  Macros which start
+with `AM_' are provided by automake or libtool.
+
+
+File: configure.info,  Node: Write Makefile.am,  Next: Write acconfig.h,  Prev: Write configure.in,  Up: Getting Started
+
+2.2 Write Makefile.am
+=====================
+
+You must write the file `Makefile.am'.  This is an automake input file,
+and the automake manual describes in detail what this file should look
+like.
+
+   The automake commands in `Makefile.am' mostly look like variable
+assignments in a `Makefile'.  automake recognizes special variable
+names, and automatically add make rules to the output as needed.
+
+   There will be one `Makefile.am' file for each directory in your
+package.  For each directory with subdirectories, the `Makefile.am'
+file should contain the line
+     SUBDIRS = DIR DIR ...
+   where each DIR is the name of a subdirectory.
+
+   For each `Makefile.am', there should be a corresponding `Makefile'
+in the `AC_OUTPUT' macro in `configure.in'.
+
+   Every `Makefile.am' written at Cygnus should contain the line
+     AUTOMAKE_OPTIONS = cygnus
+   This puts automake into Cygnus mode.  See the automake manual for
+details.
+
+   You may to include the version number of `automake' that you are
+using on the `AUTOMAKE_OPTIONS' line.  For example,
+     AUTOMAKE_OPTIONS = cygnus 1.3
+   This will prevent users from running an earlier version of
+`automake' and perhaps getting an invalid `Makefile.in'.
+
+   If your package builds a program, then in the directory where that
+program is built you will normally want a line like
+     bin_PROGRAMS = PROGRAM
+   where PROGRAM is the name of the program.  You will then want a line
+like
+     PROGRAM_SOURCES = FILE FILE ...
+   where each FILE is the name of a source file to link into the
+program (e.g., `foo.c').
+
+   If your package builds a library, and you do not want the library to
+ever be built as a shared library, then in the directory where that
+library is built you will normally want a line like
+     lib_LIBRARIES = libNAME.a
+   where `libNAME.a' is the name of the library.  You will then want a
+line like
+     libNAME_a_SOURCES = FILE FILE ...
+   where each FILE is the name of a source file to add to the library.
+
+   If your package builds a library, and you want to permit building the
+library as a shared library, then in the directory where that library is
+built you will normally want a line like
+     lib_LTLIBRARIES = libNAME.la
+   The use of `LTLIBRARIES', and the `.la' extension, indicate a
+library to be built using libtool.  As usual, you will then want a line
+like
+     libNAME_la_SOURCES = FILE FILE ...
+
+   The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and
+`lib_LIBRARIES' are not arbitrary.  They refer to particular
+directories, which may be set by the `--bindir' and `--libdir' options
+to `configure'.  If those options are not used, the default values are
+based on the `--prefix' or `--exec-prefix' options to `configure'.  It
+is possible to use other names if the program or library should be
+installed in some other directory.
+
+   The `Makefile.am' file may also contain almost anything that may
+appear in a normal `Makefile'.  automake also supports many other
+special variables, as well as conditionals.
+
+   See the automake manual for more information.
+
+
+File: configure.info,  Node: Write acconfig.h,  Next: Generate files,  Prev: Write Makefile.am,  Up: Getting Started
+
+2.3 Write acconfig.h
+====================
+
+If you are generating a portability header file, (i.e., you are using
+`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a
+`acconfig.h' file.  It will have to contain the following lines.
+
+     /* Name of package.  */
+     #undef PACKAGE
+
+     /* Version of package.  */
+     #undef VERSION
+
+   This requirement is really a bug in the system, and the requirement
+may be eliminated at some later date.
+
+   The `acconfig.h' file will also similar comment and `#undef' lines
+for any unusual macros in the `configure.in' file, including any macro
+which appears in a `AC_DEFINE' macro.
+
+   In particular, if you are writing a GNU package and therefore include
+`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will
+need lines like this in `acconfig.h':
+     /* Enable GNU extensions.  */
+     #undef _GNU_SOURCE
+
+   Normally the `autoheader' program will inform you of any such
+requirements by printing an error message when it is run.  However, if
+you do anything particular odd in your `configure.in' file, you will
+have to make sure that the right entries appear in `acconfig.h', since
+otherwise the results of the tests may not be available in the
+`config.h' file which your code will use.
+
+   (Thee `PACKAGE' and `VERSION' lines are not required if you are not
+using automake, and in that case you may not need a `acconfig.h' file
+at all).
+
+
+File: configure.info,  Node: Generate files,  Next: Getting Started Example,  Prev: Write acconfig.h,  Up: Getting Started
+
+2.4 Generate files
+==================
+
+Once you have written `configure.in', `Makefile.am', `acconfig.h', and
+possibly `acinclude.m4', you must use autoconf and automake programs to
+produce the first versions of the generated files.  This is done by
+executing the following sequence of commands.
+
+     aclocal
+     autoconf
+     autoheader
+     automake
+
+   The `aclocal' and `automake' commands are part of the automake
+package, and the `autoconf' and `autoheader' commands are part of the
+autoconf package.
+
+   If you are using a `m4' subdirectory for your macros, you will need
+to use the `-I m4' option when you run `aclocal'.
+
+   If you are not using the Cygnus tree, use the `-a' option when
+running `automake' command in order to copy the required support files
+into your source directory.
+
+   If you are using libtool, you must build and install the libtool
+package with the same `--prefix' and `--exec-prefix' options as you
+used with the autoconf and automake packages.  You must do this before
+running any of the above commands.  If you are not using the Cygnus
+tree, you will need to run the `libtoolize' program to copy the libtool
+support files into your directory.
+
+   Once you have managed to run these commands without getting any
+errors, you should create a new empty directory, and run the `configure'
+script which will have been created by `autoconf' with the
+`--enable-maintainer-mode' option.  This will give you a set of
+Makefiles which will include rules to automatically rebuild all the
+generated files.
+
+   After doing that, whenever you have changed some of the input files
+and want to regenerated the other files, go to your object directory
+and run `make'.  Doing this is more reliable than trying to rebuild the
+files manually, because there are complex order dependencies and it is
+easy to forget something.
+
+
+File: configure.info,  Node: Getting Started Example,  Prev: Generate files,  Up: Getting Started
+
+2.5 Example
+===========
+
+Let's consider a trivial example.
+
+   Suppose we want to write a simple version of `touch'.  Our program,
+which we will call `poke', will take a single file name argument, and
+use the `utime' system call to set the modification and access times of
+the file to the current time.  We want this program to be highly
+portable.
+
+   We'll first see what this looks like without using autoconf and
+automake, and then see what it looks like with them.
+
+* Menu:
+
+* Getting Started Example 1::		First Try.
+* Getting Started Example 2::		Second Try.
+* Getting Started Example 3::		Third Try.
+* Generate Files in Example::		Generate Files.
+
+
+File: configure.info,  Node: Getting Started Example 1,  Next: Getting Started Example 2,  Up: Getting Started Example
+
+2.5.1 First Try
+---------------
+
+Here is our first try at `poke.c'.  Note that we've written it without
+ANSI/ISO C prototypes, since we want it to be highly portable.
+
+     #include <stdio.h>
+     #include <stdlib.h>
+     #include <sys/types.h>
+     #include <utime.h>
+
+     int
+     main (argc, argv)
+          int argc;
+          char **argv;
+     {
+       if (argc != 2)
+         {
+           fprintf (stderr, "Usage: poke file\n");
+           exit (1);
+         }
+
+       if (utime (argv[1], NULL) < 0)
+         {
+           perror ("utime");
+           exit (1);
+         }
+
+       exit (0);
+     }
+
+   We also write a simple `Makefile'.
+
+     CC = gcc
+     CFLAGS = -g -O2
+
+     all: poke
+
+     poke: poke.o
+     	$(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
+
+   So far, so good.
+
+   Unfortunately, there are a few problems.
+
+   On older Unix systems derived from BSD 4.3, the `utime' system call
+does not accept a second argument of `NULL'.  On those systems, we need
+to pass a pointer to `struct utimbuf' structure.  Unfortunately, even
+older systems don't define that structure; on those systems, we need to
+pass an array of two `long' values.
+
+   The header file `stdlib.h' was invented by ANSI C, and older systems
+don't have a copy.  We included it above to get a declaration of `exit'.
+
+   We can find some of these portability problems by running
+`autoscan', which will create a `configure.scan' file which we can use
+as a prototype for our `configure.in' file.  I won't show the output,
+but it will notice the potential problems with `utime' and `stdlib.h'.
+
+   In our `Makefile', we don't provide any way to install the program.
+This doesn't matter much for such a simple example, but a real program
+will need an `install' target.  For that matter, we will also want a
+`clean' target.
+
+
+File: configure.info,  Node: Getting Started Example 2,  Next: Getting Started Example 3,  Prev: Getting Started Example 1,  Up: Getting Started Example
+
+2.5.2 Second Try
+----------------
+
+Here is our second try at this program.
+
+   We modify `poke.c' to use preprocessor macros to control what
+features are available.  (I've cheated a bit by using the same macro
+names which autoconf will use).
+
+     #include <stdio.h>
+
+     #ifdef STDC_HEADERS
+     #include <stdlib.h>
+     #endif
+
+     #include <sys/types.h>
+
+     #ifdef HAVE_UTIME_H
+     #include <utime.h>
+     #endif
+
+     #ifndef HAVE_UTIME_NULL
+
+     #include <time.h>
+
+     #ifndef HAVE_STRUCT_UTIMBUF
+
+     struct utimbuf
+     {
+       long actime;
+       long modtime;
+     };
+
+     #endif
+
+     static int
+     utime_now (file)
+          char *file;
+     {
+       struct utimbuf now;
+
+       now.actime = now.modtime = time (NULL);
+       return utime (file, &now);
+     }
+
+     #define utime(f, p) utime_now (f)
+
+     #endif /* HAVE_UTIME_NULL  */
+
+     int
+     main (argc, argv)
+          int argc;
+          char **argv;
+     {
+       if (argc != 2)
+         {
+           fprintf (stderr, "Usage: poke file\n");
+           exit (1);
+         }
+
+       if (utime (argv[1], NULL) < 0)
+         {
+           perror ("utime");
+           exit (1);
+         }
+
+       exit (0);
+     }
+
+   Here is the associated `Makefile'.  We've added support for the
+preprocessor flags we use.  We've also added `install' and `clean'
+targets.
+
+     # Set this to your installation directory.
+     bindir = /usr/local/bin
+
+     # Uncomment this if you have the standard ANSI/ISO C header files.
+     # STDC_HDRS = -DSTDC_HEADERS
+
+     # Uncomment this if you have utime.h.
+     # UTIME_H = -DHAVE_UTIME_H
+
+     # Uncomment this if utime (FILE, NULL) works on your system.
+     # UTIME_NULL = -DHAVE_UTIME_NULL
+
+     # Uncomment this if struct utimbuf is defined in utime.h.
+     # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
+
+     CC = gcc
+     CFLAGS = -g -O2
+
+     ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
+
+     all: poke
+
+     poke: poke.o
+     	$(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
+
+     .c.o:
+     	$(CC) -c $(ALL_CFLAGS) poke.c
+
+     install: poke
+     	cp poke $(bindir)/poke
+
+     clean:
+     	rm poke poke.o
+
+   Some problems with this approach should be clear.
+
+   Users who want to compile poke will have to know how `utime' works
+on their systems, so that they can uncomment the `Makefile' correctly.
+
+   The installation is done using `cp', but many systems have an
+`install' program which may be used, and which supports optional
+features such as stripping debugging information out of the installed
+binary.
+
+   The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS'
+follows the requirements of the GNU standards.  This is convenient for
+all packages, since it reduces surprises for users.  However, it is
+easy to get the details wrong, and wind up with a slightly nonstandard
+distribution.
+
+
+File: configure.info,  Node: Getting Started Example 3,  Next: Generate Files in Example,  Prev: Getting Started Example 2,  Up: Getting Started Example
+
+2.5.3 Third Try
+---------------
+
+For our third try at this program, we will write a `configure.in'
+script to discover the configuration features on the host system, rather
+than requiring the user to edit the `Makefile'.  We will also write a
+`Makefile.am' rather than a `Makefile'.
+
+   The only change to `poke.c' is to add a line at the start of the
+file:
+     #include "config.h"
+
+   The new `configure.in' file is as follows.
+
+     AC_INIT(poke.c)
+     AM_INIT_AUTOMAKE(poke, 1.0)
+     AM_CONFIG_HEADER(config.h:config.in)
+     AC_PROG_CC
+     AC_HEADER_STDC
+     AC_CHECK_HEADERS(utime.h)
+     AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
+     AC_FUNC_UTIME_NULL
+     AC_OUTPUT(Makefile)
+
+   The first four macros in this file, and the last one, were described
+above; see *note Write configure.in::.  If we omit these macros, then
+when we run `automake' we will get a reminder that we need them.
+
+   The other macros are standard autoconf macros.
+
+`AC_HEADER_STDC'
+     Check for standard C headers.
+
+`AC_CHECK_HEADERS'
+     Check whether a particular header file exists.
+
+`AC_EGREP_HEADER'
+     Check for a particular string in a particular header file, in this
+     case checking for `utimbuf' in `utime.h'.
+
+`AC_FUNC_UTIME_NULL'
+     Check whether `utime' accepts a NULL second argument to set the
+     file change time to the current time.
+
+   See the autoconf manual for a more complete description.
+
+   The new `Makefile.am' file is as follows.  Note how simple this is
+compared to our earlier `Makefile'.
+
+     bin_PROGRAMS = poke
+
+     poke_SOURCES = poke.c
+
+   This means that we should build a single program name `poke'.  It
+should be installed in the binary directory, which we called `bindir'
+earlier.  The program `poke' is built from the source file `poke.c'.
+
+   We must also write a `acconfig.h' file.  Besides `PACKAGE' and
+`VERSION', which must be mentioned for all packages which use automake,
+we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an
+`AC_DEFINE'.
+
+     /* Name of package.  */
+     #undef PACKAGE
+
+     /* Version of package.  */
+     #undef VERSION
+
+     /* Whether utime.h defines struct utimbuf.  */
+     #undef HAVE_STRUCT_UTIMBUF
+
+
+File: configure.info,  Node: Generate Files in Example,  Prev: Getting Started Example 3,  Up: Getting Started Example
+
+2.5.4 Generate Files
+--------------------
+
+We must now generate the other files, using the following commands.
+
+     aclocal
+     autoconf
+     autoheader
+     automake
+
+   When we run `autoheader', it will remind us of any macros we forgot
+to add to `acconfig.h'.
+
+   When we run `automake', it will want to add some files to our
+distribution.  It will add them automatically if we use the
+`--add-missing' option.
+
+   By default, `automake' will run in GNU mode, which means that it
+will want us to create certain additional files; as of this writing, it
+will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which
+are files which should appear in a standard GNU distribution.  We can
+either add those files, or run `automake' with the `--foreign' option.
+
+   Running these tools will generate the following files, all of which
+are described in the next chapter.
+
+   * `aclocal.m4'
+
+   * `configure'
+
+   * `config.in'
+
+   * `Makefile.in'
+
+   * `stamp-h.in'
+
+
+File: configure.info,  Node: Files,  Next: Configuration Names,  Prev: Getting Started,  Up: Top
+
+3 Files
+*******
+
+As was seen in the previous chapter, the GNU configure and build system
+uses a number of different files.  The developer must write a few files.
+The others are generated by various tools.
+
+   The system is rather flexible, and can be used in many different
+ways.  In describing the files that it uses, I will describe the common
+case, and mention some other cases that may arise.
+
+* Menu:
+
+* Developer Files::		Developer Files.
+* Build Files::			Build Files.
+* Support Files::		Support Files.
+
+
+File: configure.info,  Node: Developer Files,  Next: Build Files,  Up: Files
+
+3.1 Developer Files
+===================
+
+This section describes the files written or generated by the developer
+of a package.
+
+* Menu:
+
+* Developer Files Picture::	Developer Files Picture.
+* Written Developer Files::	Written Developer Files.
+* Generated Developer Files::	Generated Developer Files.
+
+
+File: configure.info,  Node: Developer Files Picture,  Next: Written Developer Files,  Up: Developer Files
+
+3.1.1 Developer Files Picture
+-----------------------------
+
+Here is a picture of the files which are written by the developer, the
+generated files which would be included with a complete source
+distribution, and the tools which create those files.  The file names
+are plain text and the tool names are enclosed by `*' characters (e.g.,
+`autoheader' is the name of a tool, not the name of a file).
+
+   acconfig.h       configure.in                 Makefile.am
+       |                |                           |
+       |  --------------+----------------------     |
+       |  |             |                     |     |
+       v  v             |    acinclude.m4     |     |
+   *autoheader*         |         |           v     v
+       |                |         v      --->*automake*
+       v                |--->*aclocal*   |       |
+   config.in            |         |      |       v
+                        |         v      |   Makefile.in
+                        |    aclocal.m4---
+                        |     |
+                        v     v
+                       *autoconf*
+                           |
+                           v
+                       configure
+
+
+File: configure.info,  Node: Written Developer Files,  Next: Generated Developer Files,  Prev: Developer Files Picture,  Up: Developer Files
+
+3.1.2 Written Developer Files
+-----------------------------
+
+The following files would be written by the developer.
+
+`configure.in'
+     This is the configuration script.  This script contains
+     invocations of autoconf macros.  It may also contain ordinary
+     shell script code.  This file will contain feature tests for
+     portability issues.  The last thing in the file will normally be
+     an `AC_OUTPUT' macro listing which files to create when the
+     builder runs the configure script.  This file is always required
+     when using the GNU configure system.  *Note Write configure.in::.
+
+`Makefile.am'
+     This is the automake input file.  It describes how the code should
+     be built.  It consists of definitions of automake variables.  It
+     may also contain ordinary Makefile targets.  This file is only
+     needed when using automake (newer tools normally use automake, but
+     there are still older tools which have not been converted, in
+     which the developer writes `Makefile.in' directly).  *Note Write
+     Makefile.am::.
+
+`acconfig.h'
+     When the configure script creates a portability header file, by
+     using `AM_CONFIG_HEADER' (or, if not using automake,
+     `AC_CONFIG_HEADER'), this file is used to describe macros which are
+     not recognized by the `autoheader' command.  This is normally a
+     fairly uninteresting file, consisting of a collection of `#undef'
+     lines with comments.  Normally any call to `AC_DEFINE' in
+     `configure.in' will require a line in this file. *Note Write
+     acconfig.h::.
+
+`acinclude.m4'
+     This file is not always required.  It defines local autoconf
+     macros.  These macros may then be used in `configure.in'.  If you
+     don't need any local autoconf macros, then you don't need this
+     file at all.  In fact, in general, you never need local autoconf
+     macros, since you can put everything in `configure.in', but
+     sometimes a local macro is convenient.
+
+     Newer tools may omit `acinclude.m4', and instead use a
+     subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS =
+     -I m4' in `Makefile.am' to force `aclocal' to look there for macro
+     definitions.  The macro definitions are then placed in separate
+     files in that directory.
+
+     The `acinclude.m4' file is only used when using automake; in older
+     tools, the developer writes `aclocal.m4' directly, if it is needed.
+
+
+File: configure.info,  Node: Generated Developer Files,  Prev: Written Developer Files,  Up: Developer Files
+
+3.1.3 Generated Developer Files
+-------------------------------
+
+The following files would be generated by the developer.
+
+   When using automake, these files are normally not generated manually
+after the first time.  Instead, the generated `Makefile' contains rules
+to automatically rebuild the files as required.  When
+`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in
+Cygnus code), the automatic rebuilding rules will only be defined if
+you configure using the `--enable-maintainer-mode' option.
+
+   When using automatic rebuilding, it is important to ensure that all
+the various tools have been built and installed on your `PATH'.  Using
+automatic rebuilding is highly recommended, so much so that I'm not
+going to explain what you have to do if you don't use it.
+
+`configure'
+     This is the configure script which will be run when building the
+     package.  This is generated by `autoconf' from `configure.in' and
+     `aclocal.m4'.  This is a shell script.
+
+`Makefile.in'
+     This is the file which the configure script will turn into the
+     `Makefile' at build time.  This file is generated by `automake'
+     from `Makefile.am'.  If you aren't using automake, you must write
+     this file yourself.  This file is pretty much a normal `Makefile',
+     with some configure substitutions for certain variables.
+
+`aclocal.m4'
+     This file is created by the `aclocal' program, based on the
+     contents of `configure.in' and `acinclude.m4' (or, as noted in the
+     description of `acinclude.m4' above, on the contents of an `m4'
+     subdirectory).  This file contains definitions of autoconf macros
+     which `autoconf' will use when generating the file `configure'.
+     These autoconf macros may be defined by you in `acinclude.m4' or
+     they may be defined by other packages such as automake, libtool or
+     gettext.  If you aren't using automake, you will normally write
+     this file yourself; in that case, if `configure.in' uses only
+     standard autoconf macros, this file will not be needed at all.
+
+`config.in'
+     This file is created by `autoheader' based on `acconfig.h' and
+     `configure.in'.  At build time, the configure script will define
+     some of the macros in it to create `config.h', which may then be
+     included by your program.  This permits your C code to use
+     preprocessor conditionals to change its behaviour based on the
+     characteristics of the host system.  This file may also be called
+     `config.h.in'.
+
+`stamp.h-in'
+     This rather uninteresting file, which I omitted from the picture,
+     is generated by `automake'.  It always contains the string
+     `timestamp'.  It is used as a timestamp file indicating whether
+     `config.in' is up to date.  Using a timestamp file means that
+     `config.in' can be marked as up to date without actually changing
+     its modification time.  This is useful since `config.in' depends
+     upon `configure.in', but it is easy to change `configure.in' in a
+     way which does not affect `config.in'.
+
+
+File: configure.info,  Node: Build Files,  Next: Support Files,  Prev: Developer Files,  Up: Files
+
+3.2 Build Files
+===============
+
+This section describes the files which are created at configure and
+build time.  These are the files which somebody who builds the package
+will see.
+
+   Of course, the developer will also build the package.  The
+distinction between developer files and build files is not that the
+developer does not see the build files, but that somebody who only
+builds the package does not have to worry about the developer files.
+
+* Menu:
+
+* Build Files Picture::		Build Files Picture.
+* Build Files Description::	Build Files Description.
+
+
+File: configure.info,  Node: Build Files Picture,  Next: Build Files Description,  Up: Build Files
+
+3.2.1 Build Files Picture
+-------------------------
+
+Here is a picture of the files which will be created at build time.
+`config.status' is both a created file and a shell script which is run
+to create other files, and the picture attempts to show that.
+
+   config.in        *configure*      Makefile.in
+      |                  |               |
+      |                  v               |
+      |             config.status        |
+      |                  |               |
+   *config.status*<======+==========>*config.status*
+      |                                  |
+      v                                  v
+   config.h                          Makefile
+
+
+File: configure.info,  Node: Build Files Description,  Prev: Build Files Picture,  Up: Build Files
+
+3.2.2 Build Files Description
+-----------------------------
+
+This is a description of the files which are created at build time.
+
+`config.status'
+     The first step in building a package is to run the `configure'
+     script.  The `configure' script will create the file
+     `config.status', which is itself a shell script.  When you first
+     run `configure', it will automatically run `config.status'.  An
+     `Makefile' derived from an automake generated `Makefile.in' will
+     contain rules to automatically run `config.status' again when
+     necessary to recreate certain files if their inputs change.
+
+`Makefile'
+     This is the file which make will read to build the program.  The
+     `config.status' script will transform `Makefile.in' into
+     `Makefile'.
+
+`config.h'
+     This file defines C preprocessor macros which C code can use to
+     adjust its behaviour on different systems.  The `config.status'
+     script will transform `config.in' into `config.h'.
+
+`config.cache'
+     This file did not fit neatly into the picture, and I omitted it.
+     It is used by the `configure' script to cache results between
+     runs.  This can be an important speedup.  If you modify
+     `configure.in' in such a way that the results of old tests should
+     change (perhaps you have added a new library to `LDFLAGS'), then
+     you will have to remove `config.cache' to force the tests to be
+     rerun.
+
+     The autoconf manual explains how to set up a site specific cache
+     file.  This can speed up running `configure' scripts on your
+     system.
+
+`stamp.h'
+     This file, which I omitted from the picture, is similar to
+     `stamp-h.in'.  It is used as a timestamp file indicating whether
+     `config.h' is up to date.  This is useful since `config.h' depends
+     upon `config.status', but it is easy for `config.status' to change
+     in a way which does not affect `config.h'.
+
+
+File: configure.info,  Node: Support Files,  Prev: Build Files,  Up: Files
+
+3.3 Support Files
+=================
+
+The GNU configure and build system requires several support files to be
+included with your distribution.  You do not normally need to concern
+yourself with these.  If you are using the Cygnus tree, most are already
+present.  Otherwise, they will be installed with your source by
+`automake' (with the `--add-missing' option) and `libtoolize'.
+
+   You don't have to put the support files in the top level directory.
+You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR'
+macro in `configure.in' to tell `automake' and the `configure' script
+where they are.
+
+   In this section, I describe the support files, so that you can know
+what they are and why they are there.
+
+`ABOUT-NLS'
+     Added by automake if you are using gettext.  This is a
+     documentation file about the gettext project.
+
+`ansi2knr.c'
+     Used by an automake generated `Makefile' if you put `ansi2knr' in
+     `AUTOMAKE_OPTIONS' in `Makefile.am'.  This permits compiling ANSI
+     C code with a K&R C compiler.
+
+`ansi2knr.1'
+     The man page which goes with `ansi2knr.c'.
+
+`config.guess'
+     A shell script which determines the configuration name for the
+     system on which it is run.
+
+`config.sub'
+     A shell script which canonicalizes a configuration name entered by
+     a user.
+
+`elisp-comp'
+     Used to compile Emacs LISP files.
+
+`install-sh'
+     A shell script which installs a program.  This is used if the
+     configure script can not find an install binary.
+
+`ltconfig'
+     Used by libtool.  This is a shell script which configures libtool
+     for the particular system on which it is used.
+
+`ltmain.sh'
+     Used by libtool.  This is the actual libtool script which is used,
+     after it is configured by `ltconfig' to build a library.
+
+`mdate-sh'
+     A shell script used by an automake generated `Makefile' to pretty
+     print the modification time of a file.  This is used to maintain
+     version numbers for texinfo files.
+
+`missing'
+     A shell script used if some tool is missing entirely.  This is
+     used by an automake generated `Makefile' to avoid certain sorts of
+     timestamp problems.
+
+`mkinstalldirs'
+     A shell script which creates a directory, including all parent
+     directories.  This is used by an automake generated `Makefile'
+     during installation.
+
+`texinfo.tex'
+     Required if you have any texinfo files.  This is used when
+     converting Texinfo files into DVI using `texi2dvi' and TeX.
+
+`ylwrap'
+     A shell script used by an automake generated `Makefile' to run
+     programs like `bison', `yacc', `flex', and `lex'.  These programs
+     default to producing output files with a fixed name, and the
+     `ylwrap' script runs them in a subdirectory to avoid file name
+     conflicts when using a parallel make program.
+
+
+File: configure.info,  Node: Configuration Names,  Next: Cross Compilation Tools,  Prev: Files,  Up: Top
+
+4 Configuration Names
+*********************
+
+The GNU configure system names all systems using a "configuration
+name".  All such names used to be triplets (they may now contain four
+parts in certain cases), and the term "configuration triplet" is still
+seen.
+
+* Menu:
+
+* Configuration Name Definition::	Configuration Name Definition.
+* Using Configuration Names::		Using Configuration Names.
+
+
+File: configure.info,  Node: Configuration Name Definition,  Next: Using Configuration Names,  Up: Configuration Names
+
+4.1 Configuration Name Definition
+=================================
+
+This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM.  In
+some cases, this is extended to a four part form:
+CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM.
+
+   When using a configuration name in a configure option, it is normally
+not necessary to specify an entire name.  In particular, the
+MANUFACTURER field is often omitted, leading to strings such as
+`i386-linux' or `sparc-sunos'.  The shell script `config.sub' will
+translate these shortened strings into the canonical form.  autoconf
+will arrange for `config.sub' to be run automatically when it is needed.
+
+   The fields of a configuration name are as follows:
+
+CPU
+     The type of processor.  This is typically something like `i386' or
+     `sparc'.  More specific variants are used as well, such as
+     `mipsel' to indicate a little endian MIPS processor.
+
+MANUFACTURER
+     A somewhat freeform field which indicates the manufacturer of the
+     system.  This is often simply `unknown'.  Other common strings are
+     `pc' for an IBM PC compatible system, or the name of a workstation
+     vendor, such as `sun'.
+
+OPERATING_SYSTEM
+     The name of the operating system which is run on the system.  This
+     will be something like `solaris2.5' or `irix6.3'.  There is no
+     particular restriction on the version number, and strings like
+     `aix4.1.4.0' are seen.  For an embedded system, which has no
+     operating system, this field normally indicates the type of object
+     file format, such as `elf' or `coff'.
+
+KERNEL
+     This is used mainly for GNU/Linux.  A typical GNU/Linux
+     configuration name is `i586-pc-linux-gnulibc1'.  In this case the
+     kernel, `linux', is separated from the operating system,
+     `gnulibc1'.
+
+   The shell script `config.guess' will normally print the correct
+configuration name for the system on which it is run.  It does by
+running `uname' and by examining other characteristics of the system.
+
+   Because `config.guess' can normally determine the configuration name
+for a machine, it is normally only necessary to specify a configuration
+name when building a cross-compiler or when building using a
+cross-compiler.
+
+
+File: configure.info,  Node: Using Configuration Names,  Prev: Configuration Name Definition,  Up: Configuration Names
+
+4.2 Using Configuration Names
+=============================
+
+A configure script will sometimes have to make a decision based on a
+configuration name.  You will need to do this if you have to compile
+code differently based on something which can not be tested using a
+standard autoconf feature test.
+
+   It is normally better to test for particular features, rather than to
+test for a particular system.  This is because as Unix evolves,
+different systems copy features from one another.  Even if you need to
+determine whether the feature is supported based on a configuration
+name, you should define a macro which describes the feature, rather than
+defining a macro which describes the particular system you are on.
+
+   Testing for a particular system is normally done using a case
+statement in `configure.in'.  The case statement might look something
+like the following, assuming that `host' is a shell variable holding a
+canonical configuration name (which will be the case if `configure.in'
+uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro).
+
+     case "${host}" in
+     i[3-7]86-*-linux-gnu*) do something ;;
+     sparc*-sun-solaris2.[56789]*) do something ;;
+     sparc*-sun-solaris*) do something ;;
+     mips*-*-elf*) do something ;;
+     esac
+
+   It is particularly important to use `*' after the operating system
+field, in order to match the version number which will be generated by
+`config.guess'.
+
+   In most cases you must be careful to match a range of processor
+types.  For most processor families, a trailing `*' suffices, as in
+`mips*' above.  For the i386 family, something along the lines of
+`i[3-7]86' suffices at present.  For the m68k family, you will need
+something like `m68*'.  Of course, if you do not need to match on the
+processor, it is simpler to just replace the entire field by a `*', as
+in `*-*-irix*'.
+
+
+File: configure.info,  Node: Cross Compilation Tools,  Next: Canadian Cross,  Prev: Configuration Names,  Up: Top
+
+5 Cross Compilation Tools
+*************************
+
+The GNU configure and build system can be used to build "cross
+compilation" tools.  A cross compilation tool is a tool which runs on
+one system and produces code which runs on another system.
+
+* Menu:
+
+* Cross Compilation Concepts::		Cross Compilation Concepts.
+* Host and Target::			Host and Target.
+* Using the Host Type::			Using the Host Type.
+* Specifying the Target::       	Specifying the Target.
+* Using the Target Type::		Using the Target Type.
+* Cross Tools in the Cygnus Tree::	Cross Tools in the Cygnus Tree
+
+
+File: configure.info,  Node: Cross Compilation Concepts,  Next: Host and Target,  Up: Cross Compilation Tools
+
+5.1 Cross Compilation Concepts
+==============================
+
+A compiler which produces programs which run on a different system is a
+cross compilation compiler, or simply a "cross compiler".  Similarly,
+we speak of cross assemblers, cross linkers, etc.
+
+   In the normal case, a compiler produces code which runs on the same
+system as the one on which the compiler runs.  When it is necessary to
+distinguish this case from the cross compilation case, such a compiler
+is called a "native compiler".  Similarly, we speak of native
+assemblers, etc.
+
+   Although the debugger is not strictly speaking a compilation tool,
+it is nevertheless meaningful to speak of a cross debugger: a debugger
+which is used to debug code which runs on another system.  Everything
+that is said below about configuring cross compilation tools applies to
+the debugger as well.
+
+
+File: configure.info,  Node: Host and Target,  Next: Using the Host Type,  Prev: Cross Compilation Concepts,  Up: Cross Compilation Tools
+
+5.2 Host and Target
+===================
+
+When building cross compilation tools, there are two different systems
+involved: the system on which the tools will run, and the system for
+which the tools generate code.
+
+   The system on which the tools will run is called the "host" system.
+
+   The system for which the tools generate code is called the "target"
+system.
+
+   For example, suppose you have a compiler which runs on a GNU/Linux
+system and generates ELF programs for a MIPS embedded system.  In this
+case the GNU/Linux system is the host, and the MIPS ELF system is the
+target.  Such a compiler could be called a GNU/Linux cross MIPS ELF
+compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf'
+compiler.
+
+   Naturally, most programs are not cross compilation tools.  For those
+programs, it does not make sense to speak of a target.  It only makes
+sense to speak of a target for tools like `gcc' or the `binutils' which
+actually produce running code.  For example, it does not make sense to
+speak of the target of a tool like `bison' or `make'.
+
+   Most cross compilation tools can also serve as native tools.  For a
+native compilation tool, it is still meaningful to speak of a target.
+For a native tool, the target is the same as the host.  For example, for
+a GNU/Linux native compiler, the host is GNU/Linux, and the target is
+also GNU/Linux.
+
+
+File: configure.info,  Node: Using the Host Type,  Next: Specifying the Target,  Prev: Host and Target,  Up: Cross Compilation Tools
+
+5.3 Using the Host Type
+=======================
+
+In almost all cases the host system is the system on which you run the
+`configure' script, and on which you build the tools (for the case when
+they differ, *note Canadian Cross::).
+
+   If your configure script needs to know the configuration name of the
+host system, and the package is not a cross compilation tool and
+therefore does not have a target, put `AC_CANONICAL_HOST' in
+`configure.in'.  This macro will arrange to define a few shell
+variables when the `configure' script is run.
+
+`host'
+     The canonical configuration name of the host.  This will normally
+     be determined by running the `config.guess' shell script, although
+     the user is permitted to override this by using an explicit
+     `--host' option.
+
+`host_alias'
+     In the unusual case that the user used an explicit `--host' option,
+     this will be the argument to `--host'.  In the normal case, this
+     will be the same as the `host' variable.
+
+`host_cpu'
+`host_vendor'
+`host_os'
+     The first three parts of the canonical configuration name.
+
+   The shell variables may be used by putting shell code in
+`configure.in'.  For an example, see *note Using Configuration Names::.
+
+
+File: configure.info,  Node: Specifying the Target,  Next: Using the Target Type,  Prev: Using the Host Type,  Up: Cross Compilation Tools
+
+5.4 Specifying the Target
+=========================
+
+By default, the `configure' script will assume that the target is the
+same as the host.  This is the more common case; for example, it leads
+to a native compiler rather than a cross compiler.
+
+   If you want to build a cross compilation tool, you must specify the
+target explicitly by using the `--target' option when you run
+`configure'.  The argument to `--target' is the configuration name of
+the system for which you wish to generate code.  *Note Configuration
+Names::.
+
+   For example, to build tools which generate code for a MIPS ELF
+embedded system, you would use `--target mips-elf'.
+
+
+File: configure.info,  Node: Using the Target Type,  Next: Cross Tools in the Cygnus Tree,  Prev: Specifying the Target,  Up: Cross Compilation Tools
+
+5.5 Using the Target Type
+=========================
+
+When writing `configure.in' for a cross compilation tool, you will need
+to use information about the target.  To do this, put
+`AC_CANONICAL_SYSTEM' in `configure.in'.
+
+   `AC_CANONICAL_SYSTEM' will look for a `--target' option and
+canonicalize it using the `config.sub' shell script.  It will also run
+`AC_CANONICAL_HOST' (*note Using the Host Type::).
+
+   The target type will be recorded in the following shell variables.
+Note that the host versions of these variables will also be defined by
+`AC_CANONICAL_HOST'.
+
+`target'
+     The canonical configuration name of the target.
+
+`target_alias'
+     The argument to the `--target' option.  If the user did not specify
+     a `--target' option, this will be the same as `host_alias'.
+
+`target_cpu'
+`target_vendor'
+`target_os'
+     The first three parts of the canonical target configuration name.
+
+   Note that if `host' and `target' are the same string, you can assume
+a native configuration.  If they are different, you can assume a cross
+configuration.
+
+   It is arguably possible for `host' and `target' to represent the
+same system, but for the strings to not be identical.  For example, if
+`config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures
+with `--target sparc-sun-sunos4.1', then the slight differences between
+the two versions of SunOS may be unimportant for your tool.  However,
+in the general case it can be quite difficult to determine whether the
+differences between two configuration names are significant or not.
+Therefore, by convention, if the user specifies a `--target' option
+without specifying a `--host' option, it is assumed that the user wants
+to configure a cross compilation tool.
+
+   The variables `target' and `target_alias' should be handled
+differently.
+
+   In general, whenever the user may actually see a string,
+`target_alias' should be used.  This includes anything which may appear
+in the file system, such as a directory name or part of a tool name.
+It also includes any tool output, unless it is clearly labelled as the
+canonical target configuration name.  This permits the user to use the
+`--target' option to specify how the tool will appear to the outside
+world.
+
+   On the other hand, when checking for characteristics of the target
+system, `target' should be used.  This is because a wide variety of
+`--target' options may map into the same canonical configuration name.
+You should not attempt to duplicate the canonicalization done by
+`config.sub' in your own code.
+
+   By convention, cross tools are installed with a prefix of the
+argument used with the `--target' option, also known as `target_alias'
+(*note Using the Target Type::).  If the user does not use the
+`--target' option, and thus is building a native tool, no prefix is
+used.
+
+   For example, if gcc is configured with `--target mips-elf', then the
+installed binary will be named `mips-elf-gcc'.  If gcc is configured
+without a `--target' option, then the installed binary will be named
+`gcc'.
+
+   The autoconf macro `AC_ARG_PROGRAM' will handle this for you.  If
+you are using automake, no more need be done; the programs will
+automatically be installed with the correct prefixes.  Otherwise, see
+the autoconf documentation for `AC_ARG_PROGRAM'.
+
+
+File: configure.info,  Node: Cross Tools in the Cygnus Tree,  Prev: Using the Target Type,  Up: Cross Compilation Tools
+
+5.6 Cross Tools in the Cygnus Tree
+==================================
+
+The Cygnus tree is used for various packages including gdb, the GNU
+binutils, and egcs.  It is also, of course, used for Cygnus releases.
+
+   In the Cygnus tree, the top level `configure' script uses the old
+Cygnus configure system, not autoconf.  The top level `Makefile.in' is
+written to build packages based on what is in the source tree, and
+supports building a large number of tools in a single
+`configure'/`make' step.
+
+   The Cygnus tree may be configured with a `--target' option.  The
+`--target' option applies recursively to every subdirectory, and
+permits building an entire set of cross tools at once.
+
+* Menu:
+
+* Host and Target Libraries::		Host and Target Libraries.
+* Target Library Configure Scripts::	Target Library Configure Scripts.
+* Make Targets in Cygnus Tree::         Make Targets in Cygnus Tree.
+* Target libiberty::			Target libiberty
+
+
+File: configure.info,  Node: Host and Target Libraries,  Next: Target Library Configure Scripts,  Up: Cross Tools in the Cygnus Tree
+
+5.6.1 Host and Target Libraries
+-------------------------------
+
+The Cygnus tree distinguishes host libraries from target libraries.
+
+   Host libraries are built with the compiler used to build the programs
+which run on the host, which is called the host compiler.  This includes
+libraries such as `bfd' and `tcl'.  These libraries are built with the
+host compiler, and are linked into programs like the binutils or gcc
+which run on the host.
+
+   Target libraries are built with the target compiler.  If gcc is
+present in the source tree, then the target compiler is the gcc that is
+built using the host compiler.  Target libraries are libraries such as
+`newlib' and `libstdc++'.  These libraries are not linked into the host
+programs, but are instead made available for use with programs built
+with the target compiler.
+
+   For the rest of this section, assume that gcc is present in the
+source tree, so that it will be used to build the target libraries.
+
+   There is a complication here.  The configure process needs to know
+which compiler you are going to use to build a tool; otherwise, the
+feature tests will not work correctly.  The Cygnus tree handles this by
+not configuring the target libraries until the target compiler is
+built.  In order to permit everything to build using a single
+`configure'/`make', the configuration of the target libraries is
+actually triggered during the make step.
+
+   When the target libraries are configured, the `--target' option is
+not used.  Instead, the `--host' option is used with the argument of
+the `--target' option for the overall configuration.  If no `--target'
+option was used for the overall configuration, the `--host' option will
+be passed with the output of the `config.guess' shell script.  Any
+`--build' option is passed down unchanged.
+
+   This translation of configuration options is done because since the
+target libraries are compiled with the target compiler, they are being
+built in order to run on the target of the overall configuration.  By
+the definition of host, this means that their host system is the same as
+the target system of the overall configuration.
+
+   The same process is used for both a native configuration and a cross
+configuration.  Even when using a native configuration, the target
+libraries will be configured and built using the newly built compiler.
+This is particularly important for the C++ libraries, since there is no
+reason to assume that the C++ compiler used to build the host tools (if
+there even is one) uses the same ABI as the g++ compiler which will be
+used to build the target libraries.
+
+   There is one difference between a native configuration and a cross
+configuration.  In a native configuration, the target libraries are
+normally configured and built as siblings of the host tools.  In a cross
+configuration, the target libraries are normally built in a subdirectory
+whose name is the argument to `--target'.  This is mainly for
+historical reasons.
+
+   To summarize, running `configure' in the Cygnus tree configures all
+the host libraries and tools, but does not configure any of the target
+libraries.  Running `make' then does the following steps:
+
+   * Build the host libraries.
+
+   * Build the host programs, including gcc.  Note that we call gcc
+     both a host program (since it runs on the host) and a target
+     compiler (since it generates code for the target).
+
+   * Using the newly built target compiler, configure the target
+     libraries.
+
+   * Build the target libraries.
+
+   The steps need not be done in precisely this order, since they are
+actually controlled by `Makefile' targets.
+
+
+File: configure.info,  Node: Target Library Configure Scripts,  Next: Make Targets in Cygnus Tree,  Prev: Host and Target Libraries,  Up: Cross Tools in the Cygnus Tree
+
+5.6.2 Target Library Configure Scripts
+--------------------------------------
+
+There are a few things you must know in order to write a configure
+script for a target library.  This is just a quick sketch, and beginners
+shouldn't worry if they don't follow everything here.
+
+   The target libraries are configured and built using a newly built
+target compiler.  There may not be any startup files or libraries for
+this target compiler.  In fact, those files will probably be built as
+part of some target library, which naturally means that they will not
+exist when your target library is configured.
+
+   This means that the configure script for a target library may not use
+any test which requires doing a link.  This unfortunately includes many
+useful autoconf macros, such as `AC_CHECK_FUNCS'.  autoconf macros
+which do a compile but not a link, such as `AC_CHECK_HEADERS', may be
+used.
+
+   This is a severe restriction, but normally not a fatal one, as target
+libraries can often assume the presence of other target libraries, and
+thus know which functions will be available.
+
+   As of this writing, the autoconf macro `AC_PROG_CC' does a link to
+make sure that the compiler works.  This may fail in a target library,
+so target libraries must use a different set of macros to locate the
+compiler.  See the `configure.in' file in a directory like `libiberty'
+or `libgloss' for an example.
+
+   As noted in the previous section, target libraries are sometimes
+built in directories which are siblings to the host tools, and are
+sometimes built in a subdirectory.  The `--with-target-subdir' configure
+option will be passed when the library is configured.  Its value will be
+an empty string if the target library is a sibling.  Its value will be
+the name of the subdirectory if the target library is in a subdirectory.
+
+   If the overall build is not a native build (i.e., the overall
+configure used the `--target' option), then the library will be
+configured with the `--with-cross-host' option.  The value of this
+option will be the host system of the overall build.  Recall that the
+host system of the library will be the target of the overall build.  If
+the overall build is a native build, the `--with-cross-host' option
+will not be used.
+
+   A library which can be built both standalone and as a target library
+may want to install itself into different directories depending upon the
+case.  When built standalone, or when built native, the library should
+be installed in `$(libdir)'.  When built as a target library which is
+not native, the library should be installed in `$(tooldir)/lib'.  The
+`--with-cross-host' option may be used to distinguish these cases.
+
+   This same test of `--with-cross-host' may be used to see whether it
+is OK to use link tests in the configure script.  If the
+`--with-cross-host' option is not used, then the library is being built
+either standalone or native, and a link should work.
+
+
+File: configure.info,  Node: Make Targets in Cygnus Tree,  Next: Target libiberty,  Prev: Target Library Configure Scripts,  Up: Cross Tools in the Cygnus Tree
+
+5.6.3 Make Targets in Cygnus Tree
+---------------------------------
+
+The top level `Makefile' in the Cygnus tree defines targets for every
+known subdirectory.
+
+   For every subdirectory DIR which holds a host library or program,
+the `Makefile' target `all-DIR' will build that library or program.
+
+   There are dependencies among host tools.  For example, building gcc
+requires first building gas, because the gcc build process invokes the
+target assembler.  These dependencies are reflected in the top level
+`Makefile'.
+
+   For every subdirectory DIR which holds a target library, the
+`Makefile' target `configure-target-DIR' will configure that library.
+The `Makefile' target `all-target-DIR' will build that library.
+
+   Every `configure-target-DIR' target depends upon `all-gcc', since
+gcc, the target compiler, is required to configure the tool.  Every
+`all-target-DIR' target depends upon the corresponding
+`configure-target-DIR' target.
+
+   There are several other targets which may be of interest for each
+directory: `install-DIR', `clean-DIR', and `check-DIR'.  There are also
+corresponding `target' versions of these for the target libraries ,
+such as `install-target-DIR'.
+
+
+File: configure.info,  Node: Target libiberty,  Prev: Make Targets in Cygnus Tree,  Up: Cross Tools in the Cygnus Tree
+
+5.6.4 Target libiberty
+----------------------
+
+The `libiberty' subdirectory is currently a special case, in that it is
+the only directory which is built both using the host compiler and
+using the target compiler.
+
+   This is because the files in `libiberty' are used when building the
+host tools, and they are also incorporated into the `libstdc++' target
+library as support code.
+
+   This duality does not pose any particular difficulties.  It means
+that there are targets for both `all-libiberty' and
+`all-target-libiberty'.
+
+   In a native configuration, when target libraries are not built in a
+subdirectory, the same objects are normally used as both the host build
+and the target build.  This is normally OK, since libiberty contains
+only C code, and in a native configuration the results of the host
+compiler and the target compiler are normally interoperable.
+
+   Irix 6 is again an exception here, since the SGI native compiler
+defaults to using the `O32' ABI, and gcc defaults to using the `N32'
+ABI.  On Irix 6, the target libraries are built in a subdirectory even
+for a native configuration, avoiding this problem.
+
+   There are currently no other libraries built for both the host and
+the target, but there is no conceptual problem with adding more.
+
+
+File: configure.info,  Node: Canadian Cross,  Next: Cygnus Configure,  Prev: Cross Compilation Tools,  Up: Top
+
+6 Canadian Cross
+****************
+
+It is possible to use the GNU configure and build system to build a
+program which will run on a system which is different from the system on
+which the tools are built.  In other words, it is possible to build
+programs using a cross compiler.
+
+   This is referred to as a "Canadian Cross".
+
+* Menu:
+
+* Canadian Cross Example::		Canadian Cross Example.
+* Canadian Cross Concepts::		Canadian Cross Concepts.
+* Build Cross Host Tools::		Build Cross Host Tools.
+* Build and Host Options::		Build and Host Options.
+* CCross not in Cygnus Tree::		Canadian Cross not in Cygnus Tree.
+* CCross in Cygnus Tree::		Canadian Cross in Cygnus Tree.
+* Supporting Canadian Cross::		Supporting Canadian Cross.
+
+
+File: configure.info,  Node: Canadian Cross Example,  Next: Canadian Cross Concepts,  Up: Canadian Cross
+
+6.1 Canadian Cross Example
+==========================
+
+Here is an example of a Canadian Cross.
+
+   While running on a GNU/Linux, you can build a program which will run
+on a Solaris system.  You would use a GNU/Linux cross Solaris compiler
+to build the program.
+
+   Of course, you could not run the resulting program on your GNU/Linux
+system.  You would have to copy it over to a Solaris system before you
+would run it.
+
+   Of course, you could also simply build the programs on the Solaris
+system in the first place.  However, perhaps the Solaris system is not
+available for some reason; perhaps you actually don't have one, but you
+want to build the tools for somebody else to use.  Or perhaps your
+GNU/Linux system is much faster than your Solaris system.
+
+   A Canadian Cross build is most frequently used when building
+programs to run on a non-Unix system, such as DOS or Windows.  It may
+be simpler to configure and build on a Unix system than to support the
+configuration machinery on a non-Unix system.
+
+
+File: configure.info,  Node: Canadian Cross Concepts,  Next: Build Cross Host Tools,  Prev: Canadian Cross Example,  Up: Canadian Cross
+
+6.2 Canadian Cross Concepts
+===========================
+
+When building a Canadian Cross, there are at least two different systems
+involved: the system on which the tools are being built, and the system
+on which the tools will run.
+
+   The system on which the tools are being built is called the "build"
+system.
+
+   The system on which the tools will run is called the host system.
+
+   For example, if you are building a Solaris program on a GNU/Linux
+system, as in the previous section, the build system would be GNU/Linux,
+and the host system would be Solaris.
+
+   It is, of course, possible to build a cross compiler using a Canadian
+Cross (i.e., build a cross compiler using a cross compiler).  In this
+case, the system for which the resulting cross compiler generates code
+is called the target system.  (For a more complete discussion of host
+and target systems, *note Host and Target::).
+
+   An example of building a cross compiler using a Canadian Cross would
+be building a Windows cross MIPS ELF compiler on a GNU/Linux system.  In
+this case the build system would be GNU/Linux, the host system would be
+Windows, and the target system would be MIPS ELF.
+
+   The name Canadian Cross comes from the case when the build, host, and
+target systems are all different.  At the time that these issues were
+all being hashed out, Canada had three national political parties.
+
+
+File: configure.info,  Node: Build Cross Host Tools,  Next: Build and Host Options,  Prev: Canadian Cross Concepts,  Up: Canadian Cross
+
+6.3 Build Cross Host Tools
+==========================
+
+In order to configure a program for a Canadian Cross build, you must
+first build and install the set of cross tools you will use to build the
+program.
+
+   These tools will be build cross host tools.  That is, they will run
+on the build system, and will produce code that runs on the host system.
+
+   It is easy to confuse the meaning of build and host here.  Always
+remember that the build system is where you are doing the build, and the
+host system is where the resulting program will run.  Therefore, you
+need a build cross host compiler.
+
+   In general, you must have a complete cross environment in order to do
+the build.  This normally means a cross compiler, cross assembler, and
+so forth, as well as libraries and include files for the host system.
+
+
+File: configure.info,  Node: Build and Host Options,  Next: CCross not in Cygnus Tree,  Prev: Build Cross Host Tools,  Up: Canadian Cross
+
+6.4 Build and Host Options
+==========================
+
+When you run `configure', you must use both the `--build' and `--host'
+options.
+
+   The `--build' option is used to specify the configuration name of
+the build system.  This can normally be the result of running the
+`config.guess' shell script, and it is reasonable to use
+`--build=`config.guess`'.
+
+   The `--host' option is used to specify the configuration name of the
+host system.
+
+   As we explained earlier, `config.guess' is used to set the default
+value for the `--host' option (*note Using the Host Type::).  We can
+now see that since `config.guess' returns the type of system on which
+it is run, it really identifies the build system.  Since the host
+system is normally the same as the build system (i.e., people do not
+normally build using a cross compiler), it is reasonable to use the
+result of `config.guess' as the default for the host system when the
+`--host' option is not used.
+
+   It might seem that if the `--host' option were used without the
+`--build' option that the configure script could run `config.guess' to
+determine the build system, and presume a Canadian Cross if the result
+of `config.guess' differed from the `--host' option.  However, for
+historical reasons, some configure scripts are routinely run using an
+explicit `--host' option, rather than using the default from
+`config.guess'.  As noted earlier, it is difficult or impossible to
+reliably compare configuration names (*note Using the Target Type::).
+Therefore, by convention, if the `--host' option is used, but the
+`--build' option is not used, then the build system defaults to the
+host system.
+
+
+File: configure.info,  Node: CCross not in Cygnus Tree,  Next: CCross in Cygnus Tree,  Prev: Build and Host Options,  Up: Canadian Cross
+
+6.5 Canadian Cross not in Cygnus Tree.
+======================================
+
+If you are not using the Cygnus tree, you must explicitly specify the
+cross tools which you want to use to build the program.  This is done by
+setting environment variables before running the `configure' script.
+
+   You must normally set at least the environment variables `CC', `AR',
+and `RANLIB' to the cross tools which you want to use to build.
+
+   For some programs, you must set additional cross tools as well, such
+as `AS', `LD', or `NM'.
+
+   You would set these environment variables to the build cross tools
+which you are going to use.
+
+   For example, if you are building a Solaris program on a GNU/Linux
+system, and your GNU/Linux cross Solaris compiler were named
+`solaris-gcc', then you would set the environment variable `CC' to
+`solaris-gcc'.
+
+
+File: configure.info,  Node: CCross in Cygnus Tree,  Next: Supporting Canadian Cross,  Prev: CCross not in Cygnus Tree,  Up: Canadian Cross
+
+6.6 Canadian Cross in Cygnus Tree
+=================================
+
+This section describes configuring and building a Canadian Cross when
+using the Cygnus tree.
+
+* Menu:
+
+* Standard Cygnus CCross::	Building a Normal Program.
+* Cross Cygnus CCross::		Building a Cross Program.
+
+
+File: configure.info,  Node: Standard Cygnus CCross,  Next: Cross Cygnus CCross,  Up: CCross in Cygnus Tree
+
+6.6.1 Building a Normal Program
+-------------------------------
+
+When configuring a Canadian Cross in the Cygnus tree, all the
+appropriate environment variables are automatically set to `HOST-TOOL',
+where HOST is the value used for the `--host' option, and TOOL is the
+name of the tool (e.g., `gcc', `as', etc.).  These tools must be on
+your `PATH'.
+
+   Adding a prefix of HOST will give the usual name for the build cross
+host tools.  To see this, consider that when these cross tools were
+built, they were configured to run on the build system and to produce
+code for the host system.  That is, they were configured with a
+`--target' option that is the same as the system which we are now
+calling the host.  Recall that the default name for installed cross
+tools uses the target system as a prefix (*note Using the Target
+Type::).  Since that is the system which we are now calling the host,
+HOST is the right prefix to use.
+
+   For example, if you configure with `--build=i386-linux-gnu' and
+`--host=solaris', then the Cygnus tree will automatically default to
+using the compiler `solaris-gcc'.  You must have previously built and
+installed this compiler, probably by doing a build with no `--host'
+option and with a `--target' option of `solaris'.
+
+
+File: configure.info,  Node: Cross Cygnus CCross,  Prev: Standard Cygnus CCross,  Up: CCross in Cygnus Tree
+
+6.6.2 Building a Cross Program
+------------------------------
+
+There are additional considerations if you want to build a cross
+compiler, rather than a native compiler, in the Cygnus tree using a
+Canadian Cross.
+
+   When you build a cross compiler using the Cygnus tree, then the
+target libraries will normally be built with the newly built target
+compiler (*note Host and Target Libraries::).  However, this will not
+work when building with a Canadian Cross.  This is because the newly
+built target compiler will be a program which runs on the host system,
+and therefore will not be able to run on the build system.
+
+   Therefore, when building a cross compiler with the Cygnus tree, you
+must first install a set of build cross target tools.  These tools will
+be used when building the target libraries.
+
+   Note that this is not a requirement of a Canadian Cross in general.
+For example, it would be possible to build just the host cross target
+tools on the build system, to copy the tools to the host system, and to
+build the target libraries on the host system.  The requirement for
+build cross target tools is imposed by the Cygnus tree, which expects
+to be able to build both host programs and target libraries in a single
+`configure'/`make' step.  Because it builds these in a single step, it
+expects to be able to build the target libraries on the build system,
+which means that it must use a build cross target toolchain.
+
+   For example, suppose you want to build a Windows cross MIPS ELF
+compiler on a GNU/Linux system.  You must have previously installed
+both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
+compiler.
+
+   In order to build the Windows (configuration name `i386-cygwin32')
+cross MIPS ELF (configure name `mips-elf') compiler, you might execute
+the following commands (long command lines are broken across lines with
+a trailing backslash as a continuation character).
+
+     mkdir linux-x-cygwin32
+     cd linux-x-cygwin32
+     SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \
+       --exec-prefix=INSTALLDIR/H-i386-linux
+     make
+     make install
+     cd ..
+     mkdir linux-x-mips-elf
+     cd linux-x-mips-elf
+     SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \
+       --exec-prefix=INSTALLDIR/H-i386-linux
+     make
+     make install
+     cd ..
+     mkdir cygwin32-x-mips-elf
+     cd cygwin32-x-mips-elf
+     SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \
+       --target=mips-elf --prefix=WININSTALLDIR \
+       --exec-prefix=WININSTALLDIR/H-i386-cygwin32
+     make
+     make install
+
+   You would then copy the contents of WININSTALLDIR over to the
+Windows machine, and run the resulting programs.
+
+
+File: configure.info,  Node: Supporting Canadian Cross,  Prev: CCross in Cygnus Tree,  Up: Canadian Cross
+
+6.7 Supporting Canadian Cross
+=============================
+
+If you want to make it possible to build a program you are developing
+using a Canadian Cross, you must take some care when writing your
+configure and make rules.  Simple cases will normally work correctly.
+However, it is not hard to write configure and make tests which will
+fail in a Canadian Cross.
+
+* Menu:
+
+* CCross in Configure::		Supporting Canadian Cross in Configure Scripts.
+* CCross in Make::		Supporting Canadian Cross in Makefiles.
+
+
+File: configure.info,  Node: CCross in Configure,  Next: CCross in Make,  Up: Supporting Canadian Cross
+
+6.7.1 Supporting Canadian Cross in Configure Scripts
+----------------------------------------------------
+
+In a `configure.in' file, after calling `AC_PROG_CC', you can find out
+whether this is a Canadian Cross configure by examining the shell
+variable `cross_compiling'.  In a Canadian Cross, which means that the
+compiler is a cross compiler, `cross_compiling' will be `yes'.  In a
+normal configuration, `cross_compiling' will be `no'.
+
+   You ordinarily do not need to know the type of the build system in a
+configure script.  However, if you do need that information, you can get
+it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is
+used to determine the target system.  This macro will set the variables
+`build', `build_alias', `build_cpu', `build_vendor', and `build_os',
+which correspond to the similar `target' and `host' variables, except
+that they describe the build system.
+
+   When writing tests in `configure.in', you must remember that you
+want to test the host environment, not the build environment.
+
+   Macros like `AC_CHECK_FUNCS' which use the compiler will test the
+host environment.  That is because the tests will be done by running the
+compiler, which is actually a build cross host compiler.  If the
+compiler can find the function, that means that the function is present
+in the host environment.
+
+   Tests like `test -f /dev/ptyp0', on the other hand, will test the
+build environment.  Remember that the configure script is running on the
+build system, not the host system.  If your configure scripts examines
+files, those files will be on the build system.  Whatever you determine
+based on those files may or may not be the case on the host system.
+
+   Most autoconf macros will work correctly for a Canadian Cross.  The
+main exception is `AC_TRY_RUN'.  This macro tries to compile and run a
+test program.  This will fail in a Canadian Cross, because the program
+will be compiled for the host system, which means that it will not run
+on the build system.
+
+   The `AC_TRY_RUN' macro provides an optional argument to tell the
+configure script what to do in a Canadian Cross.  If that argument is
+not present, you will get a warning when you run `autoconf':
+     warning: AC_TRY_RUN called without default to allow cross compiling
+   This tells you that the resulting `configure' script will not work
+with a Canadian Cross.
+
+   In some cases while it may better to perform a test at configure
+time, it is also possible to perform the test at run time.  In such a
+case you can use the cross compiling argument to `AC_TRY_RUN' to tell
+your program that the test could not be performed at configure time.
+
+   There are a few other autoconf macros which will not work correctly
+with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP',
+`AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and
+`AC_SYS_RESTARTABLE_SYSCALLS'.  The `AC_CHECK_SIZEOF' macro is
+generally not very useful with a Canadian Cross; it permits an optional
+argument indicating the default size, but there is no way to know what
+the correct default should be.
+
+
+File: configure.info,  Node: CCross in Make,  Prev: CCross in Configure,  Up: Supporting Canadian Cross
+
+6.7.2 Supporting Canadian Cross in Makefiles.
+---------------------------------------------
+
+The main Canadian Cross issue in a `Makefile' arises when you want to
+use a subsidiary program to generate code or data which you will then
+include in your real program.
+
+   If you compile this subsidiary program using `$(CC)' in the usual
+way, you will not be able to run it.  This is because `$(CC)' will
+build a program for the host system, but the program is being built on
+the build system.
+
+   You must instead use a compiler for the build system, rather than the
+host system.  In the Cygnus tree, this make variable `$(CC_FOR_BUILD)'
+will hold a compiler for the build system.
+
+   Note that you should not include `config.h' in a file you are
+compiling with `$(CC_FOR_BUILD)'.  The `configure' script will build
+`config.h' with information for the host system.  However, you are
+compiling the file using a compiler for the build system (a native
+compiler).  Subsidiary programs are normally simple filters which do no
+user interaction, and it is normally possible to write them in a highly
+portable fashion so that the absence of `config.h' is not crucial.
+
+   The gcc `Makefile.in' shows a complex situation in which certain
+files, such as `rtl.c', must be compiled into both subsidiary programs
+run on the build system and into the final program.  This approach may
+be of interest for advanced build system hackers.  Note that the build
+system compiler is rather confusingly called `HOST_CC'.
+
+
+File: configure.info,  Node: Cygnus Configure,  Next: Multilibs,  Prev: Canadian Cross,  Up: Top
+
+7 Cygnus Configure
+******************
+
+The Cygnus configure script predates autoconf.  All of its interesting
+features have been incorporated into autoconf.  No new programs should
+be written to use the Cygnus configure script.
+
+   However, the Cygnus configure script is still used in a few places:
+at the top of the Cygnus tree and in a few target libraries in the
+Cygnus tree.  Until those uses have been replaced with autoconf, some
+brief notes are appropriate here.  This is not complete documentation,
+but it should be possible to use this as a guide while examining the
+scripts themselves.
+
+* Menu:
+
+* Cygnus Configure Basics::		Cygnus Configure Basics.
+* Cygnus Configure in C++ Libraries::	Cygnus Configure in C++ Libraries.
+
+
+File: configure.info,  Node: Cygnus Configure Basics,  Next: Cygnus Configure in C++ Libraries,  Up: Cygnus Configure
+
+7.1 Cygnus Configure Basics
+===========================
+
+Cygnus configure does not use any generated files; there is no program
+corresponding to `autoconf'.  Instead, there is a single shell script
+named `configure' which may be found at the top of the Cygnus tree.
+This shell script was written by hand; it was not generated by
+autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in
+the top level of a Cygnus tree.
+
+   Cygnus configure works in a particular directory by examining the
+file `configure.in' in that directory.  That file is broken into four
+separate shell scripts.
+
+   The first is the contents of `configure.in' up to a line that starts
+with `# per-host:'.  This is the common part.
+
+   The second is the rest of `configure.in' up to a line that starts
+with `# per-target:'.  This is the per host part.
+
+   The third is the rest of `configure.in' up to a line that starts
+with `# post-target:'.  This is the per target part.
+
+   The fourth is the remainder of `configure.in'.  This is the post
+target part.
+
+   If any of these comment lines are missing, the corresponding shell
+script is empty.
+
+   Cygnus configure will first execute the common part.  This must set
+the shell variable `srctrigger' to the name of a source file, to
+confirm that Cygnus configure is looking at the right directory.  This
+may set the shell variables `package_makefile_frag' and
+`package_makefile_rules_frag'.
+
+   Cygnus configure will next set the `build' and `host' shell
+variables, and execute the per host part.  This may set the shell
+variable `host_makefile_frag'.
+
+   Cygnus configure will next set the `target' variable, and execute
+the per target part.  This may set the shell variable
+`target_makefile_frag'.
+
+   Any of these scripts may set the `subdirs' shell variable.  This
+variable is a list of subdirectories where a `Makefile.in' file may be
+found.  Cygnus configure will automatically look for a `Makefile.in'
+file in the current directory.  The `subdirs' shell variable is not
+normally used, and I believe that the only directory which uses it at
+present is `newlib'.
+
+   For each `Makefile.in', Cygnus configure will automatically create a
+`Makefile' by adding definitions for `make' variables such as `host'
+and `target', and automatically editing the values of `make' variables
+such as `prefix' if they are present.
+
+   Also, if any of the `makefile_frag' shell variables are set, Cygnus
+configure will interpret them as file names relative to either the
+working directory or the source directory, and will read the contents of
+the file into the generated `Makefile'.  The file contents will be read
+in after the first line in `Makefile.in' which starts with `####'.
+
+   These `Makefile' fragments are used to customize behaviour for a
+particular host or target.  They serve to select particular files to
+compile, and to define particular preprocessor macros by providing
+values for `make' variables which are then used during compilation.
+Cygnus configure, unlike autoconf, normally does not do feature tests,
+and normally requires support to be added manually for each new host.
+
+   The `Makefile' fragment support is similar to the autoconf
+`AC_SUBST_FILE' macro.
+
+   After creating each `Makefile', the post target script will be run
+(i.e., it may be run several times).  This script may further customize
+the `Makefile'.  When it is run, the shell variable `Makefile' will
+hold the name of the `Makefile', including the appropriate directory
+component.
+
+   Like an autoconf generated `configure' script, Cygnus configure will
+create a file named `config.status' which, when run, will automatically
+recreate the configuration.  The `config.status' file will simply
+execute the Cygnus configure script again with the appropriate
+arguments.
+
+   Any of the parts of `configure.in' may set the shell variables
+`files' and `links'.  Cygnus configure will set up symlinks from the
+names in `links' to the files named in `files'.  This is similar to the
+autoconf `AC_LINK_FILES' macro.
+
+   Finally, any of the parts of `configure.in' may set the shell
+variable `configdirs' to a set of subdirectories.  If it is set, Cygnus
+configure will recursively run the configure process in each
+subdirectory.  If the subdirectory uses Cygnus configure, it will
+contain a `configure.in' file but no `configure' file, in which case
+Cygnus configure will invoke itself recursively.  If the subdirectory
+has a `configure' file, Cygnus configure assumes that it is an autoconf
+generated `configure' script, and simply invokes it directly.
+
+
+File: configure.info,  Node: Cygnus Configure in C++ Libraries,  Prev: Cygnus Configure Basics,  Up: Cygnus Configure
+
+7.2 Cygnus Configure in C++ Libraries
+=====================================
+
+The C++ library configure system, written by Per Bothner, deserves
+special mention.  It uses Cygnus configure, but it does feature testing
+like that done by autoconf generated `configure' scripts.  This
+approach is used in the libraries `libio', `libstdc++', and `libg++'.
+
+   Most of the `Makefile' information is written out by the shell
+script `libio/config.shared'.  Each `configure.in' file sets certain
+shell variables, and then invokes `config.shared' to create two package
+`Makefile' fragments.  These fragments are then incorporated into the
+resulting `Makefile' by the Cygnus configure script.
+
+   The file `_G_config.h' is created in the `libio' object directory by
+running the shell script `libio/gen-params'.  This shell script uses
+feature tests to define macros and typedefs in `_G_config.h'.
+
+
+File: configure.info,  Node: Multilibs,  Next: FAQ,  Prev: Cygnus Configure,  Up: Top
+
+8 Multilibs
+***********
+
+For some targets gcc may have different processor requirements depending
+upon command line options.  An obvious example is the `-msoft-float'
+option supported on several processors.  This option means that the
+floating point registers are not available, which means that floating
+point operations must be done by calling an emulation subroutine rather
+than by using machine instructions.
+
+   For such options, gcc is often configured to compile target libraries
+twice: once with `-msoft-float' and once without.  When gcc compiles
+target libraries more than once, the resulting libraries are called
+"multilibs".
+
+   Multilibs are not really part of the GNU configure and build system,
+but we discuss them here since they require support in the `configure'
+scripts and `Makefile's used for target libraries.
+
+* Menu:
+
+* Multilibs in gcc::		        Multilibs in gcc.
+* Multilibs in Target Libraries::	Multilibs in Target Libraries.
+
+
+File: configure.info,  Node: Multilibs in gcc,  Next: Multilibs in Target Libraries,  Up: Multilibs
+
+8.1 Multilibs in gcc
+====================
+
+In gcc, multilibs are defined by setting the variable
+`MULTILIB_OPTIONS' in the target `Makefile' fragment.  Several other
+`MULTILIB' variables may also be defined there.  *Note The Target
+Makefile Fragment: (gcc)Target Fragment.
+
+   If you have built gcc, you can see what multilibs it uses by running
+it with the `-print-multi-lib' option.  The output `.;' means that no
+multilibs are used.  In general, the output is a sequence of lines, one
+per multilib.  The first part of each line, up to the `;', is the name
+of the multilib directory.  The second part is a list of compiler
+options separated by `@' characters.
+
+   Multilibs are built in a tree of directories.  The top of the tree,
+represented by `.' in the list of multilib directories, is the default
+library to use when no special compiler options are used.  The
+subdirectories of the tree hold versions of the library to use when
+particular compiler options are used.
+
+
+File: configure.info,  Node: Multilibs in Target Libraries,  Prev: Multilibs in gcc,  Up: Multilibs
+
+8.2 Multilibs in Target Libraries
+=================================
+
+The target libraries in the Cygnus tree are automatically built with
+multilibs.  That means that each library is built multiple times.
+
+   This default is set in the top level `configure.in' file, by adding
+`--enable-multilib' to the list of arguments passed to configure when
+it is run for the target libraries (*note Host and Target Libraries::).
+
+   Each target library uses the shell script `config-ml.in', written by
+Doug Evans, to prepare to build target libraries.  This shell script is
+invoked after the `Makefile' has been created by the `configure'
+script.  If multilibs are not enabled, it does nothing, otherwise it
+modifies the `Makefile' to support multilibs.
+
+   The `config-ml.in' script makes one copy of the `Makefile' for each
+multilib in the appropriate subdirectory.  When configuring in the
+source directory (which is not recommended), it will build a symlink
+tree of the sources in each subdirectory.
+
+   The `config-ml.in' script sets several variables in the various
+`Makefile's.  The `Makefile.in' must have definitions for these
+variables already; `config-ml.in' simply changes the existing values.
+The `Makefile' should use default values for these variables which will
+do the right thing in the subdirectories.
+
+`MULTISRCTOP'
+     `config-ml.in' will set this to a sequence of `../' strings, where
+     the number of strings is the number of multilib levels in the
+     source tree.  The default value should be the empty string.
+
+`MULTIBUILDTOP'
+     `config-ml.in' will set this to a sequence of `../' strings, where
+     the number of strings is number of multilib levels in the object
+     directory.  The default value should be the empty string.  This
+     will differ from `MULTISRCTOP' when configuring in the source tree
+     (which is not recommended).
+
+`MULTIDIRS'
+     In the top level `Makefile' only, `config-ml.in' will set this to
+     the list of multilib subdirectories.  The default value should be
+     the empty string.
+
+`MULTISUBDIR'
+     `config-ml.in' will set this to the installed subdirectory name to
+     use for this subdirectory, with a leading `/'.  The default value
+     shold be the empty string.
+
+`MULTIDO'
+`MULTICLEAN'
+     In the top level `Makefile' only, `config-ml.in' will set these
+     variables to commands to use when doing a recursive make.  These
+     variables should both default to the string `true', so that by
+     default nothing happens.
+
+   All references to the parent of the source directory should use the
+variable `MULTISRCTOP'.  Instead of writing `$(srcdir)/..', you must
+write `$(srcdir)/$(MULTISRCTOP)..'.
+
+   Similarly, references to the parent of the object directory should
+use the variable `MULTIBUILDTOP'.
+
+   In the installation target, the libraries should be installed in the
+subdirectory `MULTISUBDIR'.  Instead of installing
+`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
+
+   The `config-ml.in' script also modifies the top level `Makefile' to
+add `multi-do' and `multi-clean' targets which are used when building
+multilibs.
+
+   The default target of the `Makefile' should include the following
+command:
+     @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
+   This assumes that `$(FLAGS_TO_PASS)' is defined as a set of
+variables to pass to a recursive invocation of `make'.  This will build
+all the multilibs.  Note that the default value of `MULTIDO' is `true',
+so by default this command will do nothing.  It will only do something
+in the top level `Makefile' if multilibs were enabled.
+
+   The `install' target of the `Makefile' should include the following
+command:
+     @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
+
+   In general, any operation, other than clean, which should be
+performed on all the multilibs should use a `$(MULTIDO)' line, setting
+the variable `DO' to the target of each recursive call to `make'.
+
+   The `clean' targets (`clean', `mostlyclean', etc.) should use
+`$(MULTICLEAN)'.  For example, the `clean' target should do this:
+     @$(MULTICLEAN) DO=clean multi-clean
+
+
+File: configure.info,  Node: FAQ,  Next: Index,  Prev: Multilibs,  Up: Top
+
+9 Frequently Asked Questions
+****************************
+
+Which do I run first, `autoconf' or `automake'?
+     Except when you first add autoconf or automake support to a
+     package, you shouldn't run either by hand.  Instead, configure
+     with the `--enable-maintainer-mode' option, and let `make' take
+     care of it.
+
+`autoconf' says something about undefined macros.
+     This means that you have macros in your `configure.in' which are
+     not defined by `autoconf'.  You may be using an old version of
+     `autoconf'; try building and installing a newer one.  Make sure the
+     newly installled `autoconf' is first on your `PATH'.  Also, see
+     the next question.
+
+My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
+     This means that you have macros in your `configure.in' which should
+     be defined in your `aclocal.m4' file, but aren't.  This usually
+     means that `aclocal' was not able to appropriate definitions of the
+     macros.  Make sure that you have installed all the packages you
+     need.  In particular, make sure that you have installed libtool
+     (this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is
+     where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
+     of gettext).
+
+My `Makefile' has `@' characters in it.
+     This may mean that you tried to use an autoconf substitution in
+     your `Makefile.in' without adding the appropriate `AC_SUBST' call
+     to your `configure' script.  Or it may just mean that you need to
+     rebuild `Makefile' in your build directory.  To rebuild `Makefile'
+     from `Makefile.in', run the shell script `config.status' with no
+     arguments.  If you need to force `configure' to run again, first
+     run `config.status --recheck'.  These runs are normally done
+     automatically by `Makefile' targets, but if your `Makefile' has
+     gotten messed up you'll need to help them along.
+
+Why do I have to run both `config.status --recheck' and `config.status'?
+     Normally, you don't; they will be run automatically by `Makefile'
+     targets.  If you do need to run them, use `config.status --recheck'
+     to run the `configure' script again with the same arguments as the
+     first time you ran it.  Use `config.status' (with no arguments) to
+     regenerate all files (`Makefile', `config.h', etc.) based on the
+     results of the configure script.  The two cases are separate
+     because it isn't always necessary to regenerate all the files
+     after running `config.status --recheck'.  The `Makefile' targets
+     generated by automake will use the environment variables
+     `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
+     they are needed.
+
+What is the Cygnus tree?
+     The Cygnus tree is used for various packages including gdb, the GNU
+     binutils, and egcs.  It is also, of course, used for Cygnus
+     releases.  It is the build system which was developed at Cygnus,
+     using the Cygnus configure script.  It permits building many
+     different packages with a single configure and make.  The
+     configure scripts in the tree are being converted to autoconf, but
+     the general build structure remains intact.
+
+Why do I have to keep rebuilding and reinstalling the tools?
+     I know, it's a pain.  Unfortunately, there are bugs in the tools
+     themselves which need to be fixed, and each time that happens
+     everybody who uses the tools need to reinstall new versions of
+     them.  I don't know if there is going to be a clever fix until the
+     tools stabilize.
+
+Why not just have a Cygnus tree `make' target to update the tools?
+     The tools unfortunately need to be installed before they can be
+     used.  That means that they must be built using an appropriate
+     prefix, and it seems unwise to assume that every configuration
+     uses an appropriate prefix.  It might be possible to make them
+     work in place, or it might be possible to install them in some
+     subdirectory; so far these approaches have not been implemented.
+
+
+File: configure.info,  Node: Index,  Prev: FAQ,  Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* --build option:                        Build and Host Options.
+                                                              (line   9)
+* --host option:                         Build and Host Options.
+                                                              (line  14)
+* --target option:                       Specifying the Target.
+                                                              (line  10)
+* _GNU_SOURCE:                           Write configure.in.  (line 134)
+* AC_CANONICAL_HOST:                     Using the Host Type. (line  10)
+* AC_CANONICAL_SYSTEM:                   Using the Target Type.
+                                                              (line   6)
+* AC_CONFIG_HEADER:                      Write configure.in.  (line  66)
+* AC_EXEEXT:                             Write configure.in.  (line  86)
+* AC_INIT:                               Write configure.in.  (line  38)
+* AC_OUTPUT:                             Write configure.in.  (line 142)
+* AC_PREREQ:                             Write configure.in.  (line  42)
+* AC_PROG_CC:                            Write configure.in.  (line 103)
+* AC_PROG_CXX:                           Write configure.in.  (line 117)
+* acconfig.h:                            Written Developer Files.
+                                                              (line  27)
+* acconfig.h, writing:                   Write acconfig.h.    (line   6)
+* acinclude.m4:                          Written Developer Files.
+                                                              (line  37)
+* aclocal.m4:                            Generated Developer Files.
+                                                              (line  33)
+* AM_CONFIG_HEADER:                      Write configure.in.  (line  53)
+* AM_DISABLE_SHARED:                     Write configure.in.  (line 127)
+* AM_EXEEXT:                             Write configure.in.  (line  86)
+* AM_INIT_AUTOMAKE:                      Write configure.in.  (line  48)
+* AM_MAINTAINER_MODE:                    Write configure.in.  (line  70)
+* AM_PROG_LIBTOOL:                       Write configure.in.  (line 122)
+* AM_PROG_LIBTOOL in configure:          FAQ.                 (line  19)
+* build option:                          Build and Host Options.
+                                                              (line   9)
+* building with a cross compiler:        Canadian Cross.      (line   6)
+* canadian cross:                        Canadian Cross.      (line   6)
+* canadian cross in configure:           CCross in Configure. (line   6)
+* canadian cross in cygnus tree:         CCross in Cygnus Tree.
+                                                              (line   6)
+* canadian cross in makefile:            CCross in Make.      (line   6)
+* canadian cross, configuring:           Build and Host Options.
+                                                              (line   6)
+* canonical system names:                Configuration Names. (line   6)
+* config.cache:                          Build Files Description.
+                                                              (line  28)
+* config.h:                              Build Files Description.
+                                                              (line  23)
+* config.h.in:                           Generated Developer Files.
+                                                              (line  45)
+* config.in:                             Generated Developer Files.
+                                                              (line  45)
+* config.status:                         Build Files Description.
+                                                              (line   9)
+* config.status --recheck:               FAQ.                 (line  40)
+* configuration names:                   Configuration Names. (line   6)
+* configuration triplets:                Configuration Names. (line   6)
+* configure:                             Generated Developer Files.
+                                                              (line  21)
+* configure build system:                Build and Host Options.
+                                                              (line   9)
+* configure host:                        Build and Host Options.
+                                                              (line  14)
+* configure target:                      Specifying the Target.
+                                                              (line  10)
+* configure.in:                          Written Developer Files.
+                                                              (line   9)
+* configure.in, writing:                 Write configure.in.  (line   6)
+* configuring a canadian cross:          Build and Host Options.
+                                                              (line   6)
+* cross compiler:                        Cross Compilation Concepts.
+                                                              (line   6)
+* cross compiler, building with:         Canadian Cross.      (line   6)
+* cross tools:                           Cross Compilation Tools.
+                                                              (line   6)
+* CY_GNU_GETTEXT in configure:           FAQ.                 (line  19)
+* cygnus configure:                      Cygnus Configure.    (line   6)
+* goals:                                 Goals.               (line   6)
+* history:                               History.             (line   6)
+* host names:                            Configuration Names. (line   6)
+* host option:                           Build and Host Options.
+                                                              (line  14)
+* host system:                           Host and Target.     (line   6)
+* host triplets:                         Configuration Names. (line   6)
+* HOST_CC:                               CCross in Make.      (line  27)
+* libg++ configure:                      Cygnus Configure in C++ Libraries.
+                                                              (line   6)
+* libio configure:                       Cygnus Configure in C++ Libraries.
+                                                              (line   6)
+* libstdc++ configure:                   Cygnus Configure in C++ Libraries.
+                                                              (line   6)
+* Makefile:                              Build Files Description.
+                                                              (line  18)
+* Makefile, garbage characters:          FAQ.                 (line  29)
+* Makefile.am:                           Written Developer Files.
+                                                              (line  18)
+* Makefile.am, writing:                  Write Makefile.am.   (line   6)
+* Makefile.in:                           Generated Developer Files.
+                                                              (line  26)
+* multilibs:                             Multilibs.           (line   6)
+* stamp-h:                               Build Files Description.
+                                                              (line  41)
+* stamp-h.in:                            Generated Developer Files.
+                                                              (line  54)
+* system names:                          Configuration Names. (line   6)
+* system types:                          Configuration Names. (line   6)
+* target option:                         Specifying the Target.
+                                                              (line  10)
+* target system:                         Host and Target.     (line   6)
+* triplets:                              Configuration Names. (line   6)
+* undefined macros:                      FAQ.                 (line  12)
+
+
+
+Tag Table:
+Node: Top994
+Node: Introduction1522
+Node: Goals2604
+Node: Tools3328
+Node: History4322
+Node: Building7320
+Node: Getting Started10583
+Node: Write configure.in11096
+Node: Write Makefile.am18347
+Node: Write acconfig.h21524
+Node: Generate files23061
+Node: Getting Started Example25027
+Node: Getting Started Example 125782
+Node: Getting Started Example 227703
+Node: Getting Started Example 330698
+Node: Generate Files in Example33062
+Node: Files34152
+Node: Developer Files34763
+Node: Developer Files Picture35143
+Node: Written Developer Files36431
+Node: Generated Developer Files38983
+Node: Build Files42127
+Node: Build Files Picture42788
+Node: Build Files Description43552
+Node: Support Files45558
+Node: Configuration Names48440
+Node: Configuration Name Definition48940
+Node: Using Configuration Names51263
+Node: Cross Compilation Tools53233
+Node: Cross Compilation Concepts53924
+Node: Host and Target54892
+Node: Using the Host Type56393
+Node: Specifying the Target57742
+Node: Using the Target Type58531
+Node: Cross Tools in the Cygnus Tree61962
+Node: Host and Target Libraries63019
+Node: Target Library Configure Scripts66768
+Node: Make Targets in Cygnus Tree69860
+Node: Target libiberty71208
+Node: Canadian Cross72595
+Node: Canadian Cross Example73436
+Node: Canadian Cross Concepts74555
+Node: Build Cross Host Tools76067
+Node: Build and Host Options77019
+Node: CCross not in Cygnus Tree78805
+Node: CCross in Cygnus Tree79783
+Node: Standard Cygnus CCross80204
+Node: Cross Cygnus CCross81568
+Node: Supporting Canadian Cross84368
+Node: CCross in Configure84983
+Node: CCross in Make88151
+Node: Cygnus Configure89754
+Node: Cygnus Configure Basics90589
+Node: Cygnus Configure in C++ Libraries95267
+Node: Multilibs96274
+Node: Multilibs in gcc97319
+Node: Multilibs in Target Libraries98397
+Node: FAQ102588
+Node: Index106688
+
+End Tag Table
diff --git a/Unix/info/standards.info b/Unix/info/standards.info
new file mode 100644
index 0000000..a459aeb
--- /dev/null
+++ b/Unix/info/standards.info
@@ -0,0 +1,4928 @@
+This is standards.info, produced by makeinfo version 4.13 from ../../newlib-1.15.0/etc/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 copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+
+File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
+
+Version
+*******
+
+Last updated February 14, 2002.
+
+* 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
+* Copying This Manual::         How to Make Copies of This Manual
+* Index::
+
+
+File: standards.info,  Node: Preface,  Next: Legal Issues,  Prev: Top,  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 February
+14, 2002.
+
+   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.
+
+   These standards cover the minimum of what is important when writing a
+GNU package.  Likely, the needs for additional standards will come up.
+Sometimes, you might suggest that such standards be added to this
+document.  If you think your standards would be generally useful, please
+do suggest them.
+
+   You should also set standards for your package on many questions not
+addressed or not firmly specified here.  The most important point is to
+be self-consistent--try to stick to the conventions you pick, and try
+to document them as much as possible.  That way, your program will be
+more maintainable by others.
+
+
+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 languges to use.
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* Standard C::                  Using Standard C features
+* Conditional Compilation::     Compiling Code Only If A Conditional is True
+
+
+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,  Next: Conditional Compilation,  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: Conditional Compilation,  Prev: Standard C,  Up: Design Advice
+
+3.5 Conditional Compilation
+===========================
+
+When supporting configuration options already known when building your
+program we prefer using `if (... )' over conditional compilation, as in
+the former case the compiler is able to perform more extensive checking
+of all possible code paths.
+
+   For example, please write
+
+       if (HAS_FOO)
+         ...
+       else
+         ...
+
+   instead of:
+
+       #ifdef HAS_FOO
+         ...
+       #else
+         ...
+       #endif
+
+   A modern compiler such as GCC will generate exactly the same code in
+both cases, and we have been using similar techniques with good success
+in several projects.
+
+   While this is not a silver bullet solving all portability problems,
+following this policy would have saved the GCC project alone many person
+hours if not days per year.
+
+   In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
+which cannot be simply used in `if( ...)' statements, there is an easy
+workaround.  Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
+in the following example:
+
+       #ifdef REVERSIBLE_CC_MODE
+       #define HAS_REVERSIBLE_CC_MODE 1
+       #else
+       #define HAS_REVERSIBLE_CC_MODE 0
+       #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 idiosyncracies 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.
+
+     Translations of the above lines must preserve the validity of the
+     copyright notices (*note Internationalization::).  If the
+     translation's character set supports it, the `(C)' should be
+     replaced with the copyright symbol, as follows:
+
+     (the official copyright symbol, which is the letter C in a circle);
+
+     Write the word "Copyright" exactly like that, in English.  Do not
+     translate it into another language.  International treaties
+     recognize the English word "Copyright"; translations into other
+     languages do not have legal significance.
+
+`--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, Functions, and Files
+* 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, Functions, and Files
+==========================================
+
+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: Copying This Manual,  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 potential customers.  Proprietary software is a
+social and ethical problem, and the point of GNU is to solve that
+problem.
+
+   When a non-free program or system is well known, you can mention it
+in passing--that is harmless, since users who might want to use it
+probably already know about it.  For instance, it is fine to explain
+how to build your package on top of some non-free operating system, or
+how to use it together with some widely used non-free program.
+
+   However, you should give only the necessary information to help those
+who already use the non-free program to use your program with it--don't
+give, or refer to, any further information about the proprietary
+program, and don't imply that the proprietary program enhances your
+program, or that its existence is in any way a good thing.  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
+lead them to take an interest in it.
+
+   If a non-free program or system is obscure in your program's domain,
+your program should not mention or support it at all, since doing so
+would tend to popularize the non-free program more than it popularizes
+your program.  (You cannot hope to find many additional users among the
+users of Foobar if the users of Foobar are few.)
+
+   A GNU package should not refer the user to any non-free documentation
+for free software.  Free documentation that can be included in free
+operating systems is essential for completing the GNU system, so it is
+a major focus of the GNU Project; to recommend use of documentation
+that we are not allowed to use in GNU would undermine the efforts to
+get documentation that we can include.  So GNU packages should never
+recommend non-free documentation.
+
+
+File: standards.info,  Node: Copying This Manual,  Next: Index,  Prev: References,  Up: Top
+
+Annexe A Copying This Manual
+****************************
+
+* Menu:
+
+* GNU Free Documentation License::  License for copying this manual
+
+
+File: standards.info,  Node: GNU Free Documentation License,  Up: Copying This Manual
+
+Annexe B GNU Free Documentation License
+***************************************
+
+                        Version 1.1, March 2000
+
+     Copyright (C) 2000  Free Software Foundation, Inc.
+     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+
+  0. PREAMBLE
+
+     The purpose of this License is to make a manual, textbook, or other
+     written document "free" in the sense of freedom: to assure everyone
+     the effective freedom to copy and redistribute it, with or without
+     modifying it, either commercially or noncommercially.  Secondarily,
+     this License preserves for the author and publisher a way to get
+     credit for their work, while not being considered responsible for
+     modifications made by others.
+
+     This License is a kind of "copyleft", which means that derivative
+     works of the document must themselves be free in the same sense.
+     It complements the GNU General Public License, which is a copyleft
+     license designed for free software.
+
+     We have designed this License in order to use it for manuals for
+     free software, because free software needs free documentation: a
+     free program should come with manuals providing the same freedoms
+     that the software does.  But this License is not limited to
+     software manuals; it can be used for any textual work, regardless
+     of subject matter or whether it is published as a printed book.
+     We recommend this License principally for works whose purpose is
+     instruction or reference.
+
+
+  1. APPLICABILITY AND DEFINITIONS
+
+     This License applies to any manual or other work that contains a
+     notice placed by the copyright holder saying it can be distributed
+     under the terms of this License.  The "Document", below, refers to
+     any such manual or work.  Any member of the public is a licensee,
+     and is addressed as "you."
+
+     A "Modified Version" of the Document means any work containing the
+     Document or a portion of it, either copied verbatim, or with
+     modifications and/or translated into another language.
+
+     A "Secondary Section" is a named appendix or a front-matter
+     section of the Document that deals exclusively with the
+     relationship of the publishers or authors of the Document to the
+     Document's overall subject (or to related matters) and contains
+     nothing that could fall directly within that overall subject.
+     (For example, if the Document is in part a textbook of
+     mathematics, a Secondary Section may not explain any mathematics.)
+     The relationship could be a matter of historical connection with
+     the subject or with related matters, or of legal, commercial,
+     philosophical, ethical or political position regarding them.
+
+     The "Invariant Sections" are certain Secondary Sections whose
+     titles are designated, as being those of Invariant Sections, in
+     the notice that says that the Document is released under this
+     License.
+
+     The "Cover Texts" are certain short passages of text that are
+     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+     that says that the Document is released under this License.
+
+     A "Transparent" copy of the Document means a machine-readable copy,
+     represented in a format whose specification is available to the
+     general public, whose contents can be viewed and edited directly
+     and straightforwardly with generic text editors or (for images
+     composed of pixels) generic paint programs or (for drawings) some
+     widely available drawing editor, and that is suitable for input to
+     text formatters or for automatic translation to a variety of
+     formats suitable for input to text formatters.  A copy made in an
+     otherwise Transparent file format whose markup has been designed
+     to thwart or discourage subsequent modification by readers is not
+     Transparent.  A copy that is not "Transparent" is called "Opaque."
+
+     Examples of suitable formats for Transparent copies include plain
+     ASCII without markup, Texinfo input format, LaTeX input format,
+     SGML or XML using a publicly available DTD, and
+     standard-conforming simple HTML designed for human modification.
+     Opaque formats include PostScript, PDF, proprietary formats that
+     can be read and edited only by proprietary word processors, SGML
+     or XML for which the DTD and/or processing tools are not generally
+     available, and the machine-generated HTML produced by some word
+     processors for output purposes only.
+
+     The "Title Page" means, for a printed book, the title page itself,
+     plus such following pages as are needed to hold, legibly, the
+     material this License requires to appear in the title page.  For
+     works in formats which do not have any title page as such, "Title
+     Page" means the text near the most prominent appearance of the
+     work's title, preceding the beginning of the body of the text.
+
+  2. VERBATIM COPYING
+
+     You may copy and distribute the Document in any medium, either
+     commercially or noncommercially, provided that this License, the
+     copyright notices, and the license notice saying this License
+     applies to the Document are reproduced in all copies, and that you
+     add no other conditions whatsoever to those of this License.  You
+     may not use technical measures to obstruct or control the reading
+     or further copying of the copies you make or distribute.  However,
+     you may accept compensation in exchange for copies.  If you
+     distribute a large enough number of copies you must also follow
+     the conditions in section 3.
+
+     You may also lend copies, under the same conditions stated above,
+     and you may publicly display copies.
+
+  3. COPYING IN QUANTITY
+
+     If you publish printed copies of the Document numbering more than
+     100, and the Document's license notice requires Cover Texts, you
+     must enclose the copies in covers that carry, clearly and legibly,
+     all these Cover Texts: Front-Cover Texts on the front cover, and
+     Back-Cover Texts on the back cover.  Both covers must also clearly
+     and legibly identify you as the publisher of these copies.  The
+     front cover must present the full title with all words of the
+     title equally prominent and visible.  You may add other material
+     on the covers in addition.  Copying with changes limited to the
+     covers, as long as they preserve the title of the Document and
+     satisfy these conditions, can be treated as verbatim copying in
+     other respects.
+
+     If the required texts for either cover are too voluminous to fit
+     legibly, you should put the first ones listed (as many as fit
+     reasonably) on the actual cover, and continue the rest onto
+     adjacent pages.
+
+     If you publish or distribute Opaque copies of the Document
+     numbering more than 100, you must either include a
+     machine-readable Transparent copy along with each Opaque copy, or
+     state in or with each Opaque copy a publicly-accessible
+     computer-network location containing a complete Transparent copy
+     of the Document, free of added material, which the general
+     network-using public has access to download anonymously at no
+     charge using public-standard network protocols.  If you use the
+     latter option, you must take reasonably prudent steps, when you
+     begin distribution of Opaque copies in quantity, to ensure that
+     this Transparent copy will remain thus accessible at the stated
+     location until at least one year after the last time you
+     distribute an Opaque copy (directly or through your agents or
+     retailers) of that edition to the public.
+
+     It is requested, but not required, that you contact the authors of
+     the Document well before redistributing any large number of
+     copies, to give them a chance to provide you with an updated
+     version of the Document.
+
+  4. MODIFICATIONS
+
+     You may copy and distribute a Modified Version of the Document
+     under the conditions of sections 2 and 3 above, provided that you
+     release the Modified Version under precisely this License, with
+     the Modified Version filling the role of the Document, thus
+     licensing distribution and modification of the Modified Version to
+     whoever possesses a copy of it.  In addition, you must do these
+     things in the Modified Version:
+
+     A. Use in the Title Page (and on the covers, if any) a title
+     distinct    from that of the Document, and from those of previous
+     versions    (which should, if there were any, be listed in the
+     History section    of the Document).  You may use the same title
+     as a previous version    if the original publisher of that version
+     gives permission.
+     B. List on the Title Page, as authors, one or more persons or
+     entities    responsible for authorship of the modifications in the
+     Modified    Version, together with at least five of the principal
+     authors of the    Document (all of its principal authors, if it
+     has less than five).
+     C. State on the Title page the name of the publisher of the
+     Modified Version, as the publisher.
+     D. Preserve all the copyright notices of the Document.
+     E. Add an appropriate copyright notice for your modifications
+     adjacent to the other copyright notices.
+     F. Include, immediately after the copyright notices, a license
+     notice    giving the public permission to use the Modified Version
+     under the    terms of this License, in the form shown in the
+     Addendum below.
+     G. Preserve in that license notice the full lists of Invariant
+     Sections    and required Cover Texts given in the Document's
+     license notice.
+     H. Include an unaltered copy of this License.
+     I. Preserve the section entitled "History", and its title, and add
+     to    it an item stating at least the title, year, new authors, and
+       publisher of the Modified Version as given on the Title Page.  If
+       there is no section entitled "History" in the Document, create
+     one    stating the title, year, authors, and publisher of the
+     Document as    given on its Title Page, then add an item
+     describing the Modified    Version as stated in the previous
+     sentence.
+     J. Preserve the network location, if any, given in the Document for
+       public access to a Transparent copy of the Document, and likewise
+       the network locations given in the Document for previous versions
+       it was based on.  These may be placed in the "History" section.
+       You may omit a network location for a work that was published at
+       least four years before the Document itself, or if the original
+      publisher of the version it refers to gives permission.
+     K. In any section entitled "Acknowledgements" or "Dedications",
+     preserve the section's title, and preserve in the section all the
+      substance and tone of each of the contributor acknowledgements
+     and/or dedications given therein.
+     L. Preserve all the Invariant Sections of the Document,
+     unaltered in their text and in their titles.  Section numbers
+     or the equivalent are not considered part of the section titles.
+     M. Delete any section entitled "Endorsements."  Such a section
+     may not be included in the Modified Version.
+     N. Do not retitle any existing section as "Endorsements"    or to
+     conflict in title with any Invariant Section.
+
+     If the Modified Version includes new front-matter sections or
+     appendices that qualify as Secondary Sections and contain no
+     material copied from the Document, you may at your option
+     designate some or all of these sections as invariant.  To do this,
+     add their titles to the list of Invariant Sections in the Modified
+     Version's license notice.  These titles must be distinct from any
+     other section titles.
+
+     You may add a section entitled "Endorsements", provided it contains
+     nothing but endorsements of your Modified Version by various
+     parties-for example, statements of peer review or that the text has
+     been approved by an organization as the authoritative definition
+     of a standard.
+
+     You may add a passage of up to five words as a Front-Cover Text,
+     and a passage of up to 25 words as a Back-Cover Text, to the end
+     of the list of Cover Texts in the Modified Version.  Only one
+     passage of Front-Cover Text and one of Back-Cover Text may be
+     added by (or through arrangements made by) any one entity.  If the
+     Document already includes a cover text for the same cover,
+     previously added by you or by arrangement made by the same entity
+     you are acting on behalf of, you may not add another; but you may
+     replace the old one, on explicit permission from the previous
+     publisher that added the old one.
+
+     The author(s) and publisher(s) of the Document do not by this
+     License give permission to use their names for publicity for or to
+     assert or imply endorsement of any Modified Version.
+
+  5. COMBINING DOCUMENTS
+
+     You may combine the Document with other documents released under
+     this License, under the terms defined in section 4 above for
+     modified versions, provided that you include in the combination
+     all of the Invariant Sections of all of the original documents,
+     unmodified, and list them all as Invariant Sections of your
+     combined work in its license notice.
+
+     The combined work need only contain one copy of this License, and
+     multiple identical Invariant Sections may be replaced with a single
+     copy.  If there are multiple Invariant Sections with the same name
+     but different contents, make the title of each such section unique
+     by adding at the end of it, in parentheses, the name of the
+     original author or publisher of that section if known, or else a
+     unique number.  Make the same adjustment to the section titles in
+     the list of Invariant Sections in the license notice of the
+     combined work.
+
+     In the combination, you must combine any sections entitled
+     "History" in the various original documents, forming one section
+     entitled "History"; likewise combine any sections entitled
+     "Acknowledgements", and any sections entitled "Dedications."  You
+     must delete all sections entitled "Endorsements."
+
+  6. COLLECTIONS OF DOCUMENTS
+
+     You may make a collection consisting of the Document and other
+     documents released under this License, and replace the individual
+     copies of this License in the various documents with a single copy
+     that is included in the collection, provided that you follow the
+     rules of this License for verbatim copying of each of the
+     documents in all other respects.
+
+     You may extract a single document from such a collection, and
+     distribute it individually under this License, provided you insert
+     a copy of this License into the extracted document, and follow
+     this License in all other respects regarding verbatim copying of
+     that document.
+
+  7. AGGREGATION WITH INDEPENDENT WORKS
+
+     A compilation of the Document or its derivatives with other
+     separate and independent documents or works, in or on a volume of
+     a storage or distribution medium, does not as a whole count as a
+     Modified Version of the Document, provided no compilation
+     copyright is claimed for the compilation.  Such a compilation is
+     called an "aggregate", and this License does not apply to the
+     other self-contained works thus compiled with the Document, on
+     account of their being thus compiled, if they are not themselves
+     derivative works of the Document.
+
+     If the Cover Text requirement of section 3 is applicable to these
+     copies of the Document, then if the Document is less than one
+     quarter of the entire aggregate, the Document's Cover Texts may be
+     placed on covers that surround only the Document within the
+     aggregate.  Otherwise they must appear on covers around the whole
+     aggregate.
+
+  8. TRANSLATION
+
+     Translation is considered a kind of modification, so you may
+     distribute translations of the Document under the terms of section
+     4.  Replacing Invariant Sections with translations requires special
+     permission from their copyright holders, but you may include
+     translations of some or all Invariant Sections in addition to the
+     original versions of these Invariant Sections.  You may include a
+     translation of this License provided that you also include the
+     original English version of this License.  In case of a
+     disagreement between the translation and the original English
+     version of this License, the original English version will prevail.
+
+  9. TERMINATION
+
+     You may not copy, modify, sublicense, or distribute the Document
+     except as expressly provided for under this License.  Any other
+     attempt to copy, modify, sublicense or distribute the Document is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses
+     terminated so long as such parties remain in full compliance.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+     The Free Software Foundation may publish new, revised versions of
+     the GNU Free Documentation License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.  See
+     http://www.gnu.org/copyleft/.
+
+     Each version of the License is given a distinguishing version
+     number.  If the Document specifies that a particular numbered
+     version of this License "or any later version" applies to it, you
+     have the option of following the terms and conditions either of
+     that specified version or of any later version that has been
+     published (not as a draft) by the Free Software Foundation.  If
+     the Document does not specify a version number of this License,
+     you may choose any version ever published (not as a draft) by the
+     Free Software Foundation.
+
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+     Copyright (C)  YEAR  YOUR NAME.
+     Permission is granted to copy, distribute and/or modify this document
+     under the terms of the GNU Free Documentation License, Version 1.1
+     or any later version published by the Free Software Foundation;
+     with the Invariant Sections being LIST THEIR TITLES, with the
+     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+     A copy of the license is included in the section entitled "GNU
+     Free Documentation License."
+
+   If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant.  If you have no Front-Cover
+Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
+LIST"; likewise for Back-Cover Texts.
+
+   If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: standards.info,  Node: Index,  Prev: Copying This Manual,  Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* #endif, commenting:                    Comments.            (line  54)
+* --help option:                         Command-Line Interfaces.
+                                                              (line 119)
+* --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 125)
+* 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 125)
+* canonical name of a program:           Command-Line Interfaces.
+                                                              (line  41)
+* casting pointers to integers:          CPU Portability.     (line  67)
+* 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  38)
+* 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, functions, and files: 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 languges:                  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  55)
+* 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: Top712
+Node: Preface1412
+Node: Legal Issues3632
+Node: Reading Non-Free Code4096
+Node: Contributions5824
+Node: Trademarks7978
+Node: Design Advice9041
+Node: Source Language9625
+Node: Compatibility11637
+Node: Using Extensions13265
+Node: Standard C14841
+Node: Conditional Compilation17244
+Node: Program Behavior18543
+Node: Semantics19462
+Node: Libraries24155
+Node: Errors25400
+Node: User Interfaces27181
+Node: Graphical Interfaces28786
+Node: Command-Line Interfaces29821
+Node: Option Table35892
+Node: Memory Usage50901
+Node: File Usage51926
+Node: Writing C52674
+Node: Formatting53524
+Node: Comments57587
+Node: Syntactic Conventions60889
+Node: Names64301
+Node: System Portability66510
+Node: CPU Portability68895
+Node: System Functions72151
+Node: Internationalization77348
+Node: Mmap80501
+Node: Documentation81211
+Node: GNU Manuals82316
+Node: Doc Strings and Manuals87373
+Node: Manual Structure Details88926
+Node: License for Manuals90344
+Node: Manual Credits91318
+Node: Printed Manuals91711
+Node: NEWS File92397
+Node: Change Logs93075
+Node: Change Log Concepts93829
+Node: Style of Change Logs95693
+Node: Simple Changes97728
+Node: Conditional Changes98972
+Node: Indicating the Part Changed100394
+Node: Man Pages100921
+Node: Reading other Manuals102545
+Node: Managing Releases103336
+Node: Configuration104099
+Node: Makefile Conventions111004
+Node: Makefile Basics111810
+Node: Utilities in Makefiles114984
+Node: Command Variables117129
+Node: Directory Variables120706
+Node: Standard Targets131600
+Ref: Standard Targets-Footnote-1142840
+Node: Install Command Categories142940
+Node: Releases147522
+Node: References151610
+Node: Copying This Manual153895
+Node: GNU Free Documentation License154127
+Node: Index173812
+
+End Tag Table