Initial GNU binutils 2.6 import

14 files changed, 10868 insertions, 0 deletions

diff --git a/gnu/usr.bin/binutils/etc/Makefile.in b/gnu/usr.bin/binutils/etc/Makefile.in
new file mode 100644
index 00000000000..699ada6ae9a
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/Makefile.in
@@ -0,0 +1,100 @@
+# 
+# Makefile.in for etc
+#
+
+prefix 		= /usr/local
+exec_prefix 	= $(prefix)
+
+srcdir  = .
+bindir  = $(exec_prefix)/bin
+libdir  = $(exec_prefix)/lib
+tooldir = $(libdir)
+datadir = $(prefix)/lib
+
+mandir  = $(prefix)/man
+man1dir = $(mandir)/man1
+man2dir = $(mandir)/man2
+man3dir = $(mandir)/man3
+man4dir = $(mandir)/man4
+man5dir = $(mandir)/man5
+man6dir = $(mandir)/man6
+man7dir = $(mandir)/man7
+man8dir = $(mandir)/man8
+man9dir = $(mandir)/man9
+infodir = $(prefix)/info
+
+SHELL = /bin/sh
+
+INSTALL 	= install -c
+INSTALL_PROGRAM = $(INSTALL)
+INSTALL_DATA    = $(INSTALL)
+
+MAKEINFO = makeinfo
+TEXI2DVI = texi2dvi
+
+# Where to find texinfo.tex to format documentation with TeX.
+TEXIDIR = $(srcdir)/../texinfo
+
+#### Host, target, and site specific Makefile fragments come in here.
+###
+
+INFOFILES = configure.info standards.info cfg-paper.info
+DVIFILES = configure.dvi standards.dvi cfg-paper.dvi
+
+all:
+
+install:  $(srcdir)/configure.man
+	$(INSTALL_DATA) $(srcdir)/configure.man $(man1dir)/configure.1
+
+uninstall:
+	cd $(infodir) && rm -f configure.info* standards.info* cfg-paper.info*
+
+info: $(INFOFILES)
+
+install-info: info
+	if test ! -f configure.info ; then cd $(srcdir); fi; \
+	for i in configure.info* standards.info* cfg-paper.info*; do \
+	  $(INSTALL_DATA) $$i $(infodir)/$$i; \
+	done
+
+dvi: $(DVIFILES)
+
+configure.info: $(srcdir)/configure.texi
+	$(MAKEINFO) -o configure.info $(srcdir)/configure.texi
+
+configure.dvi: $(srcdir)/configure.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/configure.texi
+
+standards.info: $(srcdir)/standards.texi
+	$(MAKEINFO) -I$(srcdir) -o standards.info $(srcdir)/standards.texi
+
+standards.dvi: $(srcdir)/standards.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/standards.texi
+
+cfg-paper.info : $(srcdir)/cfg-paper.texi
+	$(MAKEINFO) -o cfg-paper.info $(srcdir)/cfg-paper.texi
+
+cfg-paper.dvi: $(srcdir)/cfg-paper.texi
+	TEXINPUTS=$(TEXIDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/cfg-paper.texi
+
+
+clean:
+	rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
+	rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs
+
+mostlyclean: clean
+
+distclean:   clean
+	rm -f Makefile config.status
+
+maintainer-clean realclean:   distclean
+	rm -f *.info*
+
+Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag)
+	$(SHELL) ./config.status
+
+## these last targets are for standards.texi conformance
+dist:
+check:
+installcheck:
+TAGS:
diff --git a/gnu/usr.bin/binutils/etc/cfg-paper.info b/gnu/usr.bin/binutils/etc/cfg-paper.info
new file mode 100644
index 00000000000..717ce559186
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/cfg-paper.info
@@ -0,0 +1,659 @@
+This is Info file cfg-paper.info, produced by Makeinfo-1.55 from the
+input file ./cfg-paper.texi.
+
+   This document attempts to describe the general concepts behind
+configuration of the GNU Development Tools.  It also discusses common
+usage.
+
+   Copyright (C) 1991, 1992, 1994 Cygnus Support 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 Cygnus Support.
+
+START-INFO-DIR-ENTRY
+* configuration: (cfg-paper).	Some theory on configuring source.
+END-INFO-DIR-ENTRY
+
+
+File: cfg-paper.info,  Node: Top,  Next: Some Basic Terms,  Prev: (dir),  Up: (dir)
+
+   This document attempts to describe the general concepts behind
+configuration of the GNU Development Tools.  It also discusses common
+usage.
+
+* Menu:
+
+* Some Basic Terms::		Some Basic Terms
+* Specifics.::			Specifics
+* Building Development Environments::  Building Development Environments
+* A Walk Through::		A Walk Through
+* Final Notes::			Final Notes
+* Index::			Index
+
+ -- The Detailed Node Listing --
+
+Some Basic Terms
+
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+
+A Walk Through
+
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+
+Final Notes
+
+* Hacking Configurations::	Hacking Configurations
+
+
+File: cfg-paper.info,  Node: Some Basic Terms,  Next: Specifics.,  Prev: Top,  Up: Top
+
+Some Basic Terms
+****************
+
+   There are a lot of terms that are frequently used when discussing
+development tools.  Most of the common terms have been used for many
+different concepts such that their meanings have become ambiguous to the
+point of being confusing.  Typically, we only guess at their meanings
+from context and we frequently guess wrong.
+
+   This document uses very few terms by comparison.  The intent is to
+make the concepts as clear as possible in order to convey the usage and
+intent of these tools.
+
+   *Programs* run on *machines*.  Programs are very nearly always
+written in *source*.  Programs are *built* from source.  *Compilation*
+is a process that is frequently, but not always, used when building
+programs.
+
+* Menu:
+
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+
+
+File: cfg-paper.info,  Node: Host Environments,  Next: Configuration Time Options,  Prev: Some Basic Terms,  Up: Some Basic Terms
+
+Host Environments
+=================
+
+   In this document, the word *host* refers to the environment in which
+the source in question will be compiled.  *host* and *host name* have
+nothing to do with the proper name of your host, like *ucbvax*,
+*prep.ai.mit.edu* or *att.com*.  Instead they refer to things like
+*sun4* and *dec3100*.
+
+   Forget for a moment that this particular directory of source is the
+source for a development environment.  Instead, pretend that it is the
+source for a simpler, more mundane, application, say, a desk calculator.
+
+   Source that can be compiled in more than one environment, generally
+needs to be set up for each environment explicitly.  Here we refer to
+that process as configuration.  That is, we configure the source for a
+host.
+
+   For example, if we wanted to configure our mythical desk calculator
+to compile on a SparcStation, we might configure for host sun4.  With
+our configuration system:
+
+     cd desk-calculator ; ./configure sun4
+
+does the trick.  `configure' is a shell script that sets up Makefiles,
+subdirectories, and symbolic links appropriate for compiling the source
+on a sun4.
+
+   The *host* environment does not necessarily refer to the machine on
+which the tools are built.  It is possible to provide a sun3 development
+environment on a sun4.  If we wanted to use a cross compiler on the sun4
+to build a program intended to be run on a sun3, we would configure the
+source for sun3.
+
+     cd desk-calculator ; ./configure sun3
+
+The fact that we are actually building the program on a sun4 makes no
+difference if the sun3 cross compiler presents an environment that looks
+like a sun3 from the point of view of the desk calculator source code.
+Specifically, the environment is a sun3 environment if the header files,
+predefined symbols, and libraries appear as they do on a sun3.
+
+   Nor does the host environment refer to the the machine on which the
+program to be built will run.  It is possible to provide a sun3
+emulation environment on a sun4 such that programs built in a sun3
+development environment actually run on the sun4.  This technique is
+often used within individual programs to remedy deficiencies in the host
+operating system.  For example, some operating systems do not provide
+the `bcopy' function and so it is emulated using the `memcpy' funtion.
+
+   Host environment simply refers to the environment in which the
+program will be built from the source.
+
+
+File: cfg-paper.info,  Node: Configuration Time Options,  Prev: Host Environments,  Up: Some Basic Terms
+
+Configuration Time Options
+==========================
+
+   Many programs have compile time options.  That is, features of the
+program that are either compiled into the program or not based on a
+choice made by the person who builds the program.  We refer to these as
+*configuration options*.  For example, our desk calculator might be
+capable of being compiled into a program that either uses infix notation
+or postfix as a configuration option.  For a sun3, to choose infix you
+might use:
+
+     ./configure sun3 --enable-notation=infix
+
+while for a sun4 with postfix you might use:
+
+     ./configure sun4 --enable-notation=postfix
+
+   If we wanted to build both at the same time, the intermediate pieces
+used in the build process must be kept separate.
+
+     mkdir ../objdir.sun4
+     (cd ../objdir.sun4 ; ../configure sun4 --enable-notation=postfix --srcdir=../src)
+     mkdir ../objdir.sun3
+     (cd ../objdir.sun3 ; ../configure sun3 --enable-notation=infix --srcdir=../src)
+
+will create subdirectories for the intermediate pieces of the sun4 and
+sun3 configurations.  This is necessary as previous systems were only
+capable of one configuration at a time.  Otherwise, a second
+configuration would write over the first.  We've chosen to retain this
+behaviour so the obj directories and the `--srcdir' configuration
+option are necessary to get the new behaviour.  The order of the
+arguments doesn't matter.  There should be exactly one argument without
+a leading `-' and that argument will be assumed to be the host name.
+
+   From here on the examples will assume that you want to build the
+tools *in place* and won't show the `--srcdir' option, but remember
+that it is available.
+
+   In order to actually install the program, the configuration system
+needs to know where you would like the program installed.  The default
+location is `/usr/local'.  We refer to this location as `$(prefix)'.
+All user visible programs will be installed in ``$(prefix)'/bin'.  All
+other programs and files will be installed in a subdirectory of
+``$(prefix)'/lib'.
+
+   You can only change `$(prefix)' as a configuration time option.
+
+     ./configure sun4 --enable-notation=postfix --prefix=/local
+
+Will configure the source such that:
+
+     make install
+
+will put its programs in `/local/bin' and `/local/lib/gcc'.  If you
+change `$(prefix)' after building the source, you will need to:
+
+     make clean
+
+before the change will be propogated properly.  This is because some
+tools need to know the locations of other tools.
+
+   With these concepts in mind, we can drop the desk calculator example
+and move on to the application that resides in these directories,
+namely, the source to a development environment.
+
+
+File: cfg-paper.info,  Node: Specifics.,  Next: Building Development Environments,  Prev: Some Basic Terms,  Up: Top
+
+Specifics
+*********
+
+   The GNU Development Tools can be built on a wide variety of hosts.
+So, of course, they must be configured.  Like the last example,
+
+     ./configure sun4 --prefix=/local
+     ./configure sun3 --prefix=/local
+
+will configure the source to be built in subdirectories, in order to
+keep the intermediate pieces separate, and to be installed in `/local'.
+
+   When built with suitable development environments, these will be
+native tools.  We'll explain the term *native* later.
+
+
+File: cfg-paper.info,  Node: Building Development Environments,  Next: A Walk Through,  Prev: Specifics.,  Up: Top
+
+Building Development Environments
+*********************************
+
+   The GNU development tools can not only be built in a number of host
+development environments, they can also be configured to create a
+number of different development environments on each of those hosts.
+We refer to a specific development environment created as a *target*.
+That is, the word *target* refers to the development environment
+produced by compiling this source and installing the resulting programs.
+
+   For the GNU development tools, the default target is the same as the
+host.  That is, the development environment produced is intended to be
+compatible with the environment used to build the tools.
+
+   In the example above, we created two configurations, one for sun4 and
+one for sun3.  The first configuration is expecting to be built in a
+sun4 development environment, to create a sun4 development environment.
+It doesn't necessarily need to be built on a sun4 if a sun4 development
+environment is available elsewhere.  Likewise, if the available sun4
+development environment produces executables intended for something
+other than sun4, then the development environment built from this sun4
+configuration will run on something other than a sun4.  From the point
+of view of the configuration system and the GNU development tools
+source, this doesn't matter.  What matters is that they will be built in
+a sun4 environment.
+
+   Similarly, the second configuration given above is expecting to be
+built in a sun3 development environment, to create a sun3 development
+environment.
+
+   The development environment produced is a configuration time option,
+just like `$(prefix)'.
+
+     ./configure sun4 --prefix=/local --target=sun3
+     ./configure sun3 --prefix=/local --target=sun4
+
+   In this example, like before, we create two configurations.  The
+first is intended to be built in a sun4 environment, in subdirectories,
+to be installed in `/local'.  The second is intended to be built in a
+sun3 environment, in subdirectories, to be installed in `/local'.
+
+   Unlike the previous example, the first configuration will produce a
+sun3 development environment, perhaps even suitable for building the
+second configuration.  Likewise, the second configuration will produce
+a sun4 development environment, perhaps even suitable for building the
+first configuration.
+
+   The development environment used to build these configurations will
+determine the machines on which the resulting development environments
+can be used.
+
+
+File: cfg-paper.info,  Node: A Walk Through,  Next: Final Notes,  Prev: Building Development Environments,  Up: Top
+
+A Walk Through
+**************
+
+* Menu:
+
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+
+
+File: cfg-paper.info,  Node: Native Development Environments,  Next: Emulation Environments,  Prev: A Walk Through,  Up: A Walk Through
+
+Native Development Environments
+===============================
+
+   Let us assume for a moment that you have a sun4 and that with your
+sun4 you received a development environment.  This development
+environment is intended to be run on your sun4 to build programs that
+can be run on your sun4.  You could, for instance, run this development
+environment on your sun4 to build our example desk calculator program.
+You could then run the desk calculator program on your sun4.
+
+   The resulting desk calculator program is referred to as a *native*
+program.  The development environment itself is composed of native
+programs that, when run, build other native programs.  Any other program
+is referred to as *foreign*.  Programs intended for other machines are
+foreign programs.
+
+   This type of development environment, which is by far the most
+common, is refered to as *native*.  That is, a native development
+environment runs on some machine to build programs for that same
+machine.  The process of using a native development environment to
+build native programs is called a *native* build.
+
+     ./configure sun4
+
+will configure this source such that when built in a sun4 development
+environment, with a development environment that builds programs
+intended to be run on sun4 machines, the programs built will be native
+programs and the resulting development environment will be a native
+development environment.
+
+   The development system that came with your sun4 is one such
+environment.  Using it to build the GNU Development Tools is a very
+common activity and the resulting development environment is quite
+popular.
+
+     make all
+
+will build the tools as configured and will assume that you want to use
+the native development environment that came with your machine.
+
+   Using a development environment to build a development environment is
+called *bootstrapping*.  The release of the GNU Development Tools is
+capable of bootstrapping itself.  This is a very powerful feature that
+we'll return to later.  For now, let's pretend that you used the native
+development environment that came with your sun4 to bootstrap the
+release and let's call the new development environment *stage1*.
+
+   Why bother?  Well, most people find that the GNU development
+environment builds programs that run faster and take up less space than
+the native development environments that came with their machines.  Some
+people didn't get development environments with their machines and some
+people just like using the GNU tools better than using other tools.
+
+   While you're at it, if the GNU tools produce better programs, maybe
+you should use them to build the GNU tools.  So let's pretend that you
+do.  Let's call the new development environment *stage2*.
+
+   So far you've built a development environment, stage1, and you've
+used stage1 to build a new, faster and smaller development environment,
+stage2, but you haven't run any of the programs that the GNU tools have
+built.  You really don't yet know if these tools work.  Do you have any
+programs built with the GNU tools?  Yes, you do.  stage2.  What does
+that program do?  It builds programs.  Ok, do you have any source handy
+to build into a program?  Yes, you do.  The GNU tools themselves.  In
+fact, if you use stage2 to build the GNU tools again the resulting
+programs should be identical to stage2.  Let's pretend that you do and
+call the new development environment *stage3*.
+
+   You've just completed what's called a *three stage boot*.  You now
+have a small, fast, somewhat tested, development environment.
+
+     make bootstrap
+
+will do a three stage boot across all tools and will compare stage2 to
+stage3 and complain if they are not identical.
+
+   Once built,
+
+     make install
+
+will install the development environment in the default location, or in
+`$(prefix)' if you specified an alternate when you configured.
+
+   Any development environment that is not a native development
+environment is refered to as a *cross* development environment.  There
+are many different types of cross development environments but most
+fall into one of three basic categories.
+
+
+File: cfg-paper.info,  Node: Emulation Environments,  Next: Simple Cross Environments,  Prev: Native Development Environments,  Up: A Walk Through
+
+Emulation Environments
+======================
+
+   The first category of cross development environment is called
+*emulation*.  There are two primary types of emulation, but both types
+result in programs that run on the native host.
+
+   The first type is *software emulation*.  This form of cross
+development environment involves a native program that when run on the
+native host, is capable of interpreting, and in most aspects running, a
+program intended for some other machine.  This technique is typically
+used when the other machine is either too expensive, too slow, too fast,
+or not available, perhaps because it hasn't yet been built.  The native,
+interpreting program is called a *software emulator*.
+
+   The GNU Development Tools do not currently include any software
+emulators.  Some do exist and the GNU Development Tools can be
+configured to create simple cross development environments for with
+these emulators.  More on this later.
+
+   The second type of emulation is when source intended for some other
+development environment is built into a program intended for the native
+host.  The concepts of operating system universes and hosted operating
+systems are two such development environments.
+
+
+File: cfg-paper.info,  Node: Simple Cross Environments,  Next: Crossing Into Targets,  Prev: Emulation Environments,  Up: A Walk Through
+
+Simple Cross Environments
+=========================
+
+     ./configure sun4 --target=a29k
+
+will configure the tools such that when compiled in a sun4 development
+environment the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on a sun4.  That would
+depend on the development environment used to build these tools.
+
+   Earlier you saw how to configure the tools to build a native
+development environment, that is, a development environment that runs
+on your sun4 and builds programs for your sun4.  Let's pretend that you
+use stage3 to build this simple cross configuration and let's call the
+new development environment gcc-a29k.  Remember that this is a native
+build.  Gcc-a29k is a collection of native programs intended to run on
+your sun4.  That's what stage3 builds, programs for your sun4.
+Gcc-a29k represents an a29k development environment that builds
+programs intended to run on an a29k.  But, remember, gcc-a29k runs on
+your sun4.  Programs built with gcc-a29k will run on your sun4 only
+with the help of an appropriate software emulator.
+
+   Building gcc-a29k is also a bootstrap but of a slightly different
+sort.  We call gcc-a29k a *simple cross* environment and using gcc-a29k
+to build a program intended for a29k is called *crossing to* a29k.
+Simple cross environments are the second category of cross development
+environments.
+
+
+File: cfg-paper.info,  Node: Crossing Into Targets,  Next: Canadian Cross,  Prev: Simple Cross Environments,  Up: A Walk Through
+
+Crossing Into Targets
+=====================
+
+     ./configure a29k --target=a29k
+
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+   If you've been following along this walk through, then you've already
+built an a29k environment, namely gcc-a29k.  Let's pretend you use
+gcc-a29k to build the current configuration.
+
+   Gcc-a29k builds programs intended for the a29k so the new development
+environment will be intended for use on an a29k.  That is, this new gcc
+consists of programs that are foreign to your sun4.  They cannot be run
+on your sun4.
+
+   The process of building this configuration is a another bootstrap.
+This bootstrap is also a cross to a29k.  Because this type of build is
+both a bootstrap and a cross to a29k, it is sometimes referred to as a
+*cross into* a29k.  This new development environment isn't really a
+cross development environment at all.  It is intended to run on an a29k
+to produce programs for an a29k.  You'll remember that this makes it, by
+definition, an a29k native compiler.  *Crossing into* has been
+introduced here not because it is a type of cross development
+environment, but because it is frequently mistaken as one.  The process
+is *a cross* but the resulting development environment is a native
+development environment.
+
+   You could not have built this configuration with stage3, because
+stage3 doesn't provide an a29k environment.  Instead it provides a sun4
+environment.
+
+   If you happen to have an a29k lying around, you could now use this
+fresh development environment on the a29k to three-stage these tools
+all over again.  This process would look just like it did when we built
+the native sun4 development environment because we would be building
+another native development environment, this one on a29k.
+
+
+File: cfg-paper.info,  Node: Canadian Cross,  Prev: Crossing Into Targets,  Up: A Walk Through
+
+Canadian Cross
+==============
+
+   So far you've seen that our development environment source must be
+configured for a specific host and for a specific target.  You've also
+seen that the resulting development environment depends on the
+development environment used in the build process.
+
+   When all four match identically, that is, the configured host, the
+configured target, the environment presented by the development
+environment used in the build, and the machine on which the resulting
+development environment is intended to run, then the new development
+environment will be a native development environment.
+
+   When all four match except the configured host, then we can assume
+that the development environment used in the build is some form of
+library emulation.
+
+   When all four match except for the configured target, then the
+resulting development environment will be a simple cross development
+environment.
+
+   When all four match except for the host on which the development
+environment used in the build runs, the build process is a *cross into*
+and the resulting development environment will be native to some other
+machine.
+
+   Most of the other permutations do exist in some form, but only one
+more is interesting to the current discussion.
+
+     ./configure a29k --target=sun3
+
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for a sun3.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+   If you are still following along, then you have two a29k development
+environments, the native development environment that runs on a29k, and
+the simple cross that runs on your sun4.  If you use the a29k native
+development environment on the a29k, you will be doing the same thing we
+did a while back, namely building a simple cross from a29k to sun3.
+Let's pretend that instead, you use gcc-a29k, the simple cross
+development environment that runs on sun4 but produces programs for
+a29k.
+
+   The resulting development environment will run on a29k because that's
+what gcc-a29k builds, a29k programs.  This development environment will
+produce programs for a sun3 because that is how it was configured.  This
+means that the resulting development environment is a simple cross.
+
+   There really isn't a common name for this process because very few
+development environments are capable of being configured this
+extensively.  For the sake of discussion, let's call this process a
+*Canadian cross*.  It's a three party cross, Canada has a three party
+system, hence Canadian Cross.
+
+
+File: cfg-paper.info,  Node: Final Notes,  Next: Index,  Prev: A Walk Through,  Up: Top
+
+Final Notes
+***********
+
+   By *configures*, I mean that links, Makefile, .gdbinit, and
+config.status are built.  Configuration is always done from the source
+directory.
+
+`./configure NAME'
+     configures this directory, perhaps recursively, for a single
+     host+target pair where the host and target are both NAME.  If a
+     previous configuration existed, it will be overwritten.
+
+`./configure HOSTNAME --target=TARGETNAME'
+     configures this directory, perhaps recursively, for a single
+     host+target pair where the host is HOSTNAME and target is
+     TARGETNAME.  If a previous configuration existed, it will be
+     overwritten.
+
+* Menu:
+
+* Hacking Configurations::	Hacking Configurations
+
+
+File: cfg-paper.info,  Node: Hacking Configurations,  Prev: Final Notes,  Up: Final Notes
+
+Hacking Configurations
+======================
+
+   The configure scripts essentially do three things, create
+subdirectories if appropriate, build a `Makefile', and create links to
+files, all based on and tailored to, a specific host+target pair.  The
+scripts also create a `.gdbinit' if appropriate but this is not
+tailored.
+
+   The Makefile is created by prepending some variable definitions to a
+Makefile template called `Makefile.in' and then inserting host and
+target specific Makefile fragments.  The variables are set based on the
+chosen host+target pair and build style, that is, if you use `--srcdir'
+or not.  The host and target specific Makefile may or may not exist.
+
+   * Makefiles can be edited directly, but those changes will
+     eventually be lost.  Changes intended to be permanent for a
+     specific host should be made to the host specific Makefile
+     fragment.  This should be in `./config/mh-HOST' if it exists.
+     Changes intended to be permanent for a specific target should be
+     made to the target specific Makefile fragment.  This should be in
+     `./config/mt-TARGET' if it exists.  Changes intended to be
+     permanent for the directory should be made in `Makefile.in'.  To
+     propogate changes to any of these, either use `make Makefile' or
+     `./config.status' or re-configure.
+
+
+File: cfg-paper.info,  Node: Index,  Prev: Final Notes,  Up: Top
+
+Index
+*****
+
+* Menu:
+
+* Bootstrapping:                        Native Development Environments.
+* Building:                             Some Basic Terms.
+* Canadian Cross:                       Canadian Cross.
+* Compilation:                          Some Basic Terms.
+* Cross:                                Native Development Environments.
+* Crossing into:                        Crossing Into Targets.
+* Crossing to:                          Simple Cross Environments.
+* Emulation:                            Emulation Environments.
+* Foreign:                              Native Development Environments.
+* host:                                 Host Environments.
+* Machines:                             Some Basic Terms.
+* Native:                               Native Development Environments.
+* Programs:                             Some Basic Terms.
+* Simple cross:                         Simple Cross Environments.
+* Software emulation:                   Emulation Environments.
+* Software emulator:                    Emulation Environments.
+* Source:                               Some Basic Terms.
+* Stage1:                               Native Development Environments.
+* Stage2:                               Native Development Environments.
+* Stage3:                               Native Development Environments.
+* Target:                               Building Development Environments.
+* Three party cross:                    Canadian Cross.
+* Three stage boot:                     Native Development Environments.
+
+
+
+Tag Table:
+Node: Top1055
+Node: Some Basic Terms2009
+Node: Host Environments2951
+Node: Configuration Time Options5513
+Node: Specifics.8316
+Node: Building Development Environments8934
+Node: A Walk Through11554
+Node: Native Development Environments11972
+Node: Emulation Environments16221
+Node: Simple Cross Environments17579
+Node: Crossing Into Targets19188
+Node: Canadian Cross21381
+Node: Final Notes24208
+Node: Hacking Configurations25003
+Node: Index26418
+
+End Tag Table
diff --git a/gnu/usr.bin/binutils/etc/cfg-paper.texi b/gnu/usr.bin/binutils/etc/cfg-paper.texi
new file mode 100644
index 00000000000..bcfbb31e13f
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/cfg-paper.texi
@@ -0,0 +1,717 @@
+\input texinfo
+@c %**start of header
+@setfilename cfg-paper.info
+@settitle On Configuring Development Tools
+@c %**end of header
+@setchapternewpage off
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the @sc{gnu} Development Tools.
+It also discusses common usage.
+
+Copyright (C) 1991, 1992, 1994 Cygnus Support
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by Cygnus Support.
+@end ifinfo
+
+@titlepage
+@sp 10
+@title{On Configuring Development Tools}
+@author{K. Richard Pixley, @code{rich@@cygnus.com}}
+@author{Cygnus Support}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991, 1992, 1994 Cygnus Support
+
+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 Cygnus Support.
+@end titlepage
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* configuration: (cfg-paper).	Some theory on configuring source.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@node top, Some Basic Terms, (dir), (dir)
+
+@ifinfo
+This document attempts to describe the general concepts behind
+configuration of the @sc{gnu} Development Tools.
+It also discusses common usage.
+@end ifinfo
+
+@menu
+* Some Basic Terms::		Some Basic Terms
+* Specifics.::			Specifics
+* Building Development Environments::  Building Development Environments
+* A Walk Through::		A Walk Through
+* Final Notes::			Final Notes
+* Index::			Index
+
+ --- The Detailed Node Listing ---
+
+Some Basic Terms
+
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+
+A Walk Through
+
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+
+Final Notes
+
+* Hacking Configurations::	Hacking Configurations
+@end menu
+
+@node Some Basic Terms, Specifics., top, top
+@chapter Some Basic Terms
+
+There are a lot of terms that are frequently used when discussing
+development tools.  Most of the common terms have been used for many
+different concepts such that their meanings have become ambiguous to the
+point of being confusing.  Typically, we only guess at their meanings
+from context and we frequently guess wrong.
+
+This document uses very few terms by comparison.  The intent is to make
+the concepts as clear as possible in order to convey the usage and
+intent of these tools.
+
+@emph{Programs} run on @emph{machines}.  Programs are very nearly always
+written in @emph{source}.  Programs are @emph{built} from source.
+@emph{Compilation} is a process that is frequently, but not always, used
+when building programs.
+@cindex Programs
+@cindex Machines
+@cindex Source
+@cindex Building
+@cindex Compilation
+
+@menu
+* Host Environments::		Host Environments
+* Configuration Time Options::	Configuration Time Options
+@end menu
+
+@node Host Environments, Configuration Time Options, Some Basic Terms, Some Basic Terms
+@section Host Environments
+
+@cindex host
+In this document, the word @emph{host} refers to the environment in
+which the source in question will be compiled.  @emph{host} and
+@emph{host name} have nothing to do with the proper name of your host,
+like @emph{ucbvax}, @emph{prep.ai.mit.edu} or @emph{att.com}.  Instead
+they refer to things like @emph{sun4} and @emph{dec3100}.
+
+Forget for a moment that this particular directory of source is the
+source for a development environment.  Instead, pretend that it is the
+source for a simpler, more mundane, application, say, a desk calculator.
+
+Source that can be compiled in more than one environment, generally
+needs to be set up for each environment explicitly.  Here we refer to
+that process as configuration.  That is, we configure the source for a
+host.
+
+For example, if we wanted to configure our mythical desk calculator to
+compile on a SparcStation, we might configure for host sun4.  With our
+configuration system:
+
+@example
+cd desk-calculator ; ./configure sun4
+@end example
+
+@noindent
+does the trick.  @code{configure} is a shell script that sets up Makefiles,
+subdirectories, and symbolic links appropriate for compiling the source
+on a sun4.
+
+The @emph{host} environment does not necessarily refer to the machine on
+which the tools are built.  It is possible to provide a sun3 development
+environment on a sun4.  If we wanted to use a cross compiler on the sun4
+to build a program intended to be run on a sun3, we would configure the
+source for sun3.
+
+@example
+cd desk-calculator ; ./configure sun3
+@end example
+
+@noindent
+The fact that we are actually building the program on a sun4 makes no
+difference if the sun3 cross compiler presents an environment that looks
+like a sun3 from the point of view of the desk calculator source code.
+Specifically, the environment is a sun3 environment if the header files,
+predefined symbols, and libraries appear as they do on a sun3.
+
+Nor does the host environment refer to the the machine on which the
+program to be built will run.  It is possible to provide a sun3
+emulation environment on a sun4 such that programs built in a sun3
+development environment actually run on the sun4.  This technique is
+often used within individual programs to remedy deficiencies in the host
+operating system.  For example, some operating systems do not provide
+the @code{bcopy} function and so it is emulated using the
+@code{memcpy} funtion.
+
+Host environment simply refers to the environment in which the program
+will be built from the source.
+
+
+@node  Configuration Time Options,  , Host Environments, Some Basic Terms
+@section Configuration Time Options
+
+Many programs have compile time options.  That is, features of the
+program that are either compiled into the program or not based on a
+choice made by the person who builds the program.  We refer to these as
+@emph{configuration options}.  For example, our desk calculator might be
+capable of being compiled into a program that either uses infix notation
+or postfix as a configuration option.  For a sun3, to choose infix you
+might use:
+
+@example
+./configure sun3 --enable-notation=infix
+@end example
+
+@noindent
+while for a sun4 with postfix you might use:
+
+@example
+./configure sun4 --enable-notation=postfix
+@end example
+
+If we wanted to build both at the same time, the intermediate pieces
+used in the build process must be kept separate.
+
+@example
+mkdir ../objdir.sun4
+(cd ../objdir.sun4 ; ../configure sun4 --enable-notation=postfix --srcdir=../src)
+mkdir ../objdir.sun3
+(cd ../objdir.sun3 ; ../configure sun3 --enable-notation=infix --srcdir=../src)
+@end example
+
+@noindent
+will create subdirectories for the intermediate pieces of the sun4 and
+sun3 configurations.  This is necessary as previous systems were only
+capable of one configuration at a time.  Otherwise, a second
+configuration would write over the first.  We've chosen to retain this
+behaviour so the obj directories and the @code{--srcdir} configuration
+option are necessary to get the new behaviour.  The order of the
+arguments doesn't matter.  There should be exactly one argument without
+a leading @samp{-} and that argument will be assumed to be the host
+name.
+
+From here on the examples will assume that you want to build the tools
+@emph{in place} and won't show the @code{--srcdir} option, but remember
+that it is available.
+
+In order to actually install the program, the configuration system needs
+to know where you would like the program installed.  The default
+location is @file{/usr/local}.  We refer to this location as
+@code{$(prefix)}.  All user visible programs will be installed in
+@file{@code{$(prefix)}/bin}.  All other programs and files will be
+installed in a subdirectory of @file{@code{$(prefix)}/lib}.
+
+You can only change @code{$(prefix)} as a configuration time
+option.
+
+@example
+./configure sun4 --enable-notation=postfix --prefix=/local
+@end example
+
+@noindent
+Will configure the source such that:
+
+@example
+make install
+@end example
+
+@noindent
+will put its programs in @file{/local/bin} and @file{/local/lib/gcc}.
+If you change @code{$(prefix)} after building the source, you will need
+to:
+
+@example
+make clean
+@end example
+
+@noindent
+before the change will be propogated properly.  This is because some
+tools need to know the locations of other tools.
+
+With these concepts in mind, we can drop the desk calculator example and
+move on to the application that resides in these directories, namely,
+the source to a development environment.
+
+@node Specifics., Building Development Environments, Some Basic Terms, top
+@chapter Specifics
+
+The @sc{gnu} Development Tools can be built on a wide variety of hosts.  So,
+of course, they must be configured.  Like the last example,
+
+@example
+./configure sun4 --prefix=/local
+./configure sun3 --prefix=/local
+@end example
+
+@noindent
+will configure the source to be built in subdirectories, in order to
+keep the intermediate pieces separate, and to be installed in
+@file{/local}.
+
+When built with suitable development environments, these will be native
+tools.  We'll explain the term @emph{native} later.
+
+@node Building Development Environments, A Walk Through, Specifics., top
+@chapter Building Development Environments
+
+@cindex Target
+
+The @sc{gnu} development tools can not only be built in a
+number of host development environments, they can also be configured to
+create a number of different development environments on each of those
+hosts.  We refer to a specific development environment created as a
+@emph{target}.  That is, the word @emph{target} refers to the development
+environment produced by compiling this source and installing the
+resulting programs.
+
+For the @sc{gnu} development tools, the default target is the
+same as the host.  That is, the development environment produced is
+intended to be compatible with the environment used to build the tools.
+
+In the example above, we created two configurations, one for sun4 and
+one for sun3.  The first configuration is expecting to be built in a
+sun4 development environment, to create a sun4 development environment.
+It doesn't necessarily need to be built on a sun4 if a sun4 development
+environment is available elsewhere.  Likewise, if the available sun4
+development environment produces executables intended for something
+other than sun4, then the development environment built from this sun4
+configuration will run on something other than a sun4.  From the point
+of view of the configuration system and the @sc{gnu} development tools
+source, this doesn't matter.  What matters is that they will be built in
+a sun4 environment.
+
+Similarly, the second configuration given above is expecting to be built
+in a sun3 development environment, to create a sun3 development
+environment.
+
+The development environment produced is a configuration time option,
+just like @code{$(prefix)}.
+
+@example
+./configure sun4 --prefix=/local --target=sun3
+./configure sun3 --prefix=/local --target=sun4
+@end example
+
+In this example, like before, we create two configurations.  The first
+is intended to be built in a sun4 environment, in subdirectories, to be
+installed in @file{/local}.  The second is intended to be built in a
+sun3 environment, in subdirectories, to be installed in @file{/local}.
+
+Unlike the previous example, the first configuration will produce a sun3
+development environment, perhaps even suitable for building the second
+configuration.  Likewise, the second configuration will produce a sun4
+development environment, perhaps even suitable for building the first
+configuration.
+
+The development environment used to build these configurations will
+determine the machines on which the resulting development environments
+can be used.
+
+
+@node A Walk Through, Final Notes, Building Development Environments, top
+@chapter A Walk Through
+
+
+@menu
+* Native Development Environments::  Native Development Environments
+* Emulation Environments::	Emulation Environments
+* Simple Cross Environments::	Simple Cross Environments
+* Crossing Into Targets::	Crossing Into Targets
+* Canadian Cross::		Canadian Cross
+@end menu
+
+@node Native Development Environments, Emulation Environments, A Walk Through, A Walk Through
+@section Native Development Environments
+
+Let us assume for a moment that you have a sun4 and that with your sun4
+you received a development environment.  This development environment is
+intended to be run on your sun4 to build programs that can be run on
+your sun4.  You could, for instance, run this development environment on
+your sun4 to build our example desk calculator program.  You could then
+run the desk calculator program on your sun4.
+
+@cindex Native
+@cindex Foreign
+The resulting desk calculator program is referred to as a @emph{native}
+program.  The development environment itself is composed of native
+programs that, when run, build other native programs.  Any other program
+is referred to as @emph{foreign}.  Programs intended for other machines are
+foreign programs.
+
+This type of development environment, which is by far the most common,
+is refered to as @emph{native}.  That is, a native development environment
+runs on some machine to build programs for that same machine.  The
+process of using a native development environment to build native
+programs is called a @emph{native} build.
+
+@example
+./configure sun4
+@end example
+
+@noindent
+will configure this source such that when built in a sun4 development
+environment, with a development environment that builds programs
+intended to be run on sun4 machines, the programs built will be native
+programs and the resulting development environment will be a native
+development environment.
+
+The development system that came with your sun4 is one such environment.
+Using it to build the @sc{gnu} Development Tools is a very common activity
+and the resulting development environment is quite popular.
+
+@example
+make all
+@end example
+
+@noindent
+will build the tools as configured and will assume that you want to use
+the native development environment that came with your machine.
+
+@cindex Bootstrapping
+@cindex Stage1
+Using a development environment to build a development environment is
+called @emph{bootstrapping}.  The release of the @sc{gnu}
+Development Tools is capable of bootstrapping itself.  This is a very
+powerful feature that we'll return to later.  For now, let's pretend
+that you used the native development environment that came with your
+sun4 to bootstrap the release and let's call the new
+development environment @emph{stage1}.
+
+Why bother?  Well, most people find that the @sc{gnu} development
+environment builds programs that run faster and take up less space than
+the native development environments that came with their machines.  Some
+people didn't get development environments with their machines and some
+people just like using the @sc{gnu} tools better than using other tools.
+
+@cindex Stage2
+While you're at it, if the @sc{gnu} tools produce better programs, maybe you
+should use them to build the @sc{gnu} tools.  So let's
+pretend that you do.  Let's call the new development environment
+@emph{stage2}.
+
+@cindex Stage3
+So far you've built a development environment, stage1, and you've used
+stage1 to build a new, faster and smaller development environment,
+stage2, but you haven't run any of the programs that the @sc{gnu} tools have
+built.  You really don't yet know if these tools work.  Do you have any
+programs built with the @sc{gnu} tools?  Yes, you do.  stage2.  What does
+that program do?  It builds programs.  Ok, do you have any source handy
+to build into a program?  Yes, you do.  The @sc{gnu} tools themselves.  In
+fact, if you use stage2 to build the @sc{gnu} tools again the resulting
+programs should be identical to stage2.  Let's pretend that you do and
+call the new development environment @emph{stage3}.
+
+@cindex Three stage boot
+You've just completed what's called a @emph{three stage boot}.  You now have
+a small, fast, somewhat tested, development environment.
+
+@example
+make bootstrap
+@end example
+
+@noindent
+will do a three stage boot across all tools and will compare stage2 to
+stage3 and complain if they are not identical.
+
+Once built,
+
+@example
+make install
+@end example
+
+@noindent
+will install the development environment in the default location, or in
+@code{$(prefix)} if you specified an alternate when you configured.
+
+@cindex Cross
+Any development environment that is not a native development environment
+is refered to as a @emph{cross} development environment.  There are many
+different types of cross development environments but most fall into one
+of three basic categories.
+
+
+@node Emulation Environments, Simple Cross Environments, Native Development Environments, A Walk Through
+@section Emulation Environments
+
+@cindex Emulation
+The first category of cross development environment is called
+@emph{emulation}.  There are two primary types of emulation, but both
+types result in programs that run on the native host.
+
+@cindex Software emulation
+@cindex Software emulator
+The first type is @emph{software emulation}.  This form of cross
+development environment involves a native program that when run on the
+native host, is capable of interpreting, and in most aspects running, a
+program intended for some other machine.  This technique is typically
+used when the other machine is either too expensive, too slow, too fast,
+or not available, perhaps because it hasn't yet been built.  The native,
+interpreting program is called a @emph{software emulator}.
+
+The @sc{gnu} Development Tools do not currently include any software
+emulators.  Some do exist and the @sc{gnu} Development Tools can be
+configured to create simple cross development environments for with
+these emulators.  More on this later.
+
+The second type of emulation is when source intended for some other
+development environment is built into a program intended for the native
+host.  The concepts of operating system universes and hosted operating
+systems are two such development environments.
+
+@node Simple Cross Environments, Crossing Into Targets, Emulation Environments, A Walk Through
+@section Simple Cross Environments
+
+@example
+./configure sun4 --target=a29k
+@end example
+
+@noindent
+will configure the tools such that when compiled in a sun4 development
+environment the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on a sun4.  That would
+depend on the development environment used to build these tools.
+
+Earlier you saw how to configure the tools to build a native development
+environment, that is, a development environment that runs on your sun4
+and builds programs for your sun4.  Let's pretend that you use stage3 to
+build this simple cross configuration and let's call the new development
+environment gcc-a29k.  Remember that this is a native build.  Gcc-a29k
+is a collection of native programs intended to run on your sun4.  That's
+what stage3 builds, programs for your sun4.  Gcc-a29k represents an a29k
+development environment that builds programs intended to run on an a29k.
+But, remember, gcc-a29k runs on your sun4.  Programs built with gcc-a29k
+will run on your sun4 only with the help of an appropriate software
+emulator.
+
+@cindex Simple cross
+@cindex Crossing to
+Building gcc-a29k is also a bootstrap but of a slightly different sort.
+We call gcc-a29k a @emph{simple cross} environment and using gcc-a29k to
+build a program intended for a29k is called @emph{crossing to} a29k.
+Simple cross environments are the second category of cross development
+environments.
+
+
+@node Crossing Into Targets, Canadian Cross, Simple Cross Environments, A Walk Through
+@section Crossing Into Targets
+
+@example
+./configure a29k --target=a29k
+@end example
+
+@noindent
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for an a29k.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+If you've been following along this walk through, then you've already
+built an a29k environment, namely gcc-a29k.  Let's pretend you use
+gcc-a29k to build the current configuration.
+
+Gcc-a29k builds programs intended for the a29k so the new development
+environment will be intended for use on an a29k.  That is, this new gcc
+consists of programs that are foreign to your sun4.  They cannot be run
+on your sun4.
+
+@cindex Crossing into
+The process of building this configuration is a another bootstrap.  This
+bootstrap is also a cross to a29k.  Because this type of build is both a
+bootstrap and a cross to a29k, it is sometimes referred to as a
+@emph{cross into} a29k.  This new development environment isn't really a
+cross development environment at all.  It is intended to run on an a29k
+to produce programs for an a29k.  You'll remember that this makes it, by
+definition, an a29k native compiler.  @emph{Crossing into} has been
+introduced here not because it is a type of cross development
+environment, but because it is frequently mistaken as one.  The process
+is @emph{a cross} but the resulting development environment is a native
+development environment.
+
+You could not have built this configuration with stage3, because stage3
+doesn't provide an a29k environment.  Instead it provides a sun4
+environment.
+
+If you happen to have an a29k lying around, you could now use this fresh
+development environment on the a29k to three-stage these tools all over
+again.  This process would look just like it did when we built the
+native sun4 development environment because we would be building another
+native development environment, this one on a29k.
+
+
+@node Canadian Cross,  , Crossing Into Targets, A Walk Through
+@section Canadian Cross
+
+So far you've seen that our development environment source must be
+configured for a specific host and for a specific target.  You've also
+seen that the resulting development environment depends on the
+development environment used in the build process.
+
+When all four match identically, that is, the configured host, the
+configured target, the environment presented by the development
+environment used in the build, and the machine on which the resulting
+development environment is intended to run, then the new development
+environment will be a native development environment.
+
+When all four match except the configured host, then we can assume that
+the development environment used in the build is some form of library
+emulation.
+
+When all four match except for the configured target, then the resulting
+development environment will be a simple cross development environment.
+
+When all four match except for the host on which the development
+environment used in the build runs, the build process is a @emph{cross into}
+and the resulting development environment will be native to some other
+machine.
+
+Most of the other permutations do exist in some form, but only one more
+is interesting to the current discussion.
+
+@example
+./configure a29k --target=sun3
+@end example
+
+@noindent
+will configure the tools such that when compiled in an a29k development
+environment, the resulting development environment can be used to create
+programs intended for a sun3.  Again, this does not necessarily mean
+that the new development environment can be run on an a29k.  That would
+depend on the development environment used to build these tools.
+
+If you are still following along, then you have two a29k development
+environments, the native development environment that runs on a29k, and
+the simple cross that runs on your sun4.  If you use the a29k native
+development environment on the a29k, you will be doing the same thing we
+did a while back, namely building a simple cross from a29k to sun3.
+Let's pretend that instead, you use gcc-a29k, the simple cross
+development environment that runs on sun4 but produces programs for
+a29k.
+
+The resulting development environment will run on a29k because that's
+what gcc-a29k builds, a29k programs.  This development environment will
+produce programs for a sun3 because that is how it was configured.  This
+means that the resulting development environment is a simple cross.
+
+@cindex Canadian Cross
+@cindex Three party cross
+There really isn't a common name for this process because very few
+development environments are capable of being configured this
+extensively.  For the sake of discussion, let's call this process a
+@emph{Canadian cross}.  It's a three party cross, Canada has a three
+party system, hence Canadian Cross.
+
+@node Final Notes, Index, A Walk Through, top
+@chapter Final Notes
+
+By @emph{configures}, I mean that links, Makefile, .gdbinit, and
+config.status are built.  Configuration is always done from the source
+directory.
+
+@table @code
+
+@item ./configure @var{name}
+configures this directory, perhaps recursively, for a single host+target
+pair where the host and target are both @var{name}.  If a previous
+configuration existed, it will be overwritten.
+
+@item ./configure @var{hostname} --target=@var{targetname}
+configures this directory, perhaps recursively, for a single host+target
+pair where the host is @var{hostname} and target is @var{targetname}.
+If a previous configuration existed, it will be overwritten.
+
+@end table
+
+@menu
+* Hacking Configurations::	Hacking Configurations
+@end menu
+
+@node Hacking Configurations,  , Final Notes, Final Notes
+@section Hacking Configurations
+
+The configure scripts essentially do three things, create subdirectories
+if appropriate, build a @file{Makefile}, and create links to files, all
+based on and tailored to, a specific host+target pair.  The scripts also
+create a @file{.gdbinit} if appropriate but this is not tailored.
+
+The Makefile is created by prepending some variable definitions to a
+Makefile template called @file{Makefile.in} and then inserting host and
+target specific Makefile fragments.  The variables are set based on the
+chosen host+target pair and build style, that is, if you use
+@code{--srcdir} or not.  The host and target specific Makefile may or may
+not exist.
+
+@itemize @bullet
+
+@item
+Makefiles can be edited directly, but those changes will eventually be
+lost.  Changes intended to be permanent for a specific host should be
+made to the host specific Makefile fragment.  This should be in
+@file{./config/mh-@var{host}} if it exists.  Changes intended to be
+permanent for a specific target should be made to the target specific
+Makefile fragment.  This should be in @file{./config/mt-@var{target}} if
+it exists.  Changes intended to be permanent for the directory should be
+made in @file{Makefile.in}.  To propogate changes to any of these,
+either use @code{make Makefile} or @code{./config.status} or
+re-configure.
+
+@end itemize
+
+@page
+@node Index,  , Final Notes, top
+@appendix Index
+
+@printindex cp
+
+@contents
+@bye
+
+@c Local Variables:
+@c fill-column: 72
+@c End:
diff --git a/gnu/usr.bin/binutils/etc/configure.in b/gnu/usr.bin/binutils/etc/configure.in
new file mode 100644
index 00000000000..c94a6237ba8
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.in
@@ -0,0 +1,17 @@
+# This file is a shell script fragment that supplies the information
+# necessary to tailor a template configure script into the configure
+# script appropriate for this directory.  For more information, check
+# any existing configure script.
+
+srctrigger=configure.texi
+srcname="general documentation"
+
+# per-host:
+
+# per-target:
+
+#
+# Local Variables:
+# fill-column: 131
+# End:
+#
diff --git a/gnu/usr.bin/binutils/etc/configure.info b/gnu/usr.bin/binutils/etc/configure.info
new file mode 100644
index 00000000000..b1a3f01b5a8
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.info
@@ -0,0 +1,64 @@
+This is Info file configure.info, produced by Makeinfo-1.55 from the
+input file ./configure.texi.
+
+START-INFO-DIR-ENTRY
+* configure: (configure).        Cygnus configure.
+END-INFO-DIR-ENTRY
+
+   This document describes the Cygnus Support version of `configure'.
+
+   Copyright (C) 1991, 1992, 1993 Cygnus Support 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 Cygnus Support.
+
+
+Indirect:
+configure.info-1: 968
+configure.info-2: 50440
+
+Tag Table:
+(Indirect)
+Node: Top968
+Node: What configure does1463
+Node: Invoking configure4783
+Node: Using configure11838
+Node: What configure really does13103
+Node: Build variables18380
+Node: Build directories20582
+Node: Makefile generation23984
+Node: config.guess25515
+Node: config.status26405
+Node: configure.in26962
+Node: configure variables28632
+Node: Minimal36798
+Node: Declarations37608
+Node: per-host38082
+Node: per-target38819
+Node: post-target39642
+Node: Example40225
+Node: Install locations40932
+Node: prefix41733
+Node: exec_prefix42626
+Node: Install details44431
+Node: Host49368
+Node: Target50004
+Node: Makefile fragments50440
+Node: Makefile extensions52056
+Node: Porting55783
+Node: Programs56235
+Node: Hosts and targets61089
+Node: Sites62752
+Node: Variables Index63452
+Node: Concept Index66624
+
+End Tag Table
diff --git a/gnu/usr.bin/binutils/etc/configure.info-1 b/gnu/usr.bin/binutils/etc/configure.info-1
new file mode 100644
index 00000000000..52e8c46aae7
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.info-1
@@ -0,0 +1,1174 @@
+This is Info file configure.info, produced by Makeinfo-1.55 from the
+input file ./configure.texi.
+
+START-INFO-DIR-ENTRY
+* configure: (configure).        Cygnus configure.
+END-INFO-DIR-ENTRY
+
+   This document describes the Cygnus Support version of `configure'.
+
+   Copyright (C) 1991, 1992, 1993 Cygnus Support 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 Cygnus Support.
+
+
+File: configure.info,  Node: Top,  Next: What configure does,  Prev: (DIR),  Up: (DIR)
+
+Cygnus configure
+****************
+
+   This file documents the configuration system used and distributed by
+Cygnus Support.
+
+* Menu:
+
+* What configure does::    What configure does
+* Invoking configure::     Invoking configure--basic usage
+* Using configure::        More than you ever wanted to know
+* Porting::                How to use configure with new programs
+* Variables Index::
+* Concept Index::
+
+
+File: configure.info,  Node: What configure does,  Next: Invoking configure,  Prev: Top,  Up: Top
+
+What `configure' does
+*********************
+
+   This manual documents Cygnus `configure', a program which helps to
+automate much of the setup activity associated with building large
+suites of programs, such the Cygnus Support Developer's Kit.  This
+manual is therefore geared toward readers who are likely to face the
+problem of configuring software in source form before compiling and
+installing it.  We assume you are an experienced programmer or system
+administrator.  For further background on this topic, see *Note
+Apologia Configure: (cfg-paper)Some Basic Terms, by K. Richard Pixley.
+
+   When `configure' runs, it does the following things:
+
+** creates build directories*
+     When you run `configure' with the `--srcdir' option, it uses the
+     current directory as the "build directory", creating under it a
+     directory tree that parallels the directory structure of the
+     source directory.  If you don't specify a `srcdir', `configure'
+     first assumes that the source code you wish to configure is in
+     your current directory; if it finds no `configure.in' input file
+     there, it searches in the directory `configure' itself lies in.
+     (For details, see *Note Build directories: Build directories.)
+
+** generates `Makefile'*
+     A `Makefile' template from the source directory, usually called
+     `Makefile.in', is copied to an output file in the build directory
+     which is most often named `Makefile'.  `configure' places
+     definitions for a number of standard `Makefile' macros at the
+     beginning of the output file.  If `--prefix=DIR' or
+     `--exec_prefix=DIR' are specified on the `configure' command line,
+     corresponding `Makefile' variables are set accordingly.  If host,
+     target, or site-specific `Makefile' fragments exist, these are
+     inserted into the output file.  (For details, see *Note `Makefile'
+     generation: Makefile generation.)
+
+** generates `.gdbinit'*
+     If the source directory contains a `.gdbinit' file and the build
+     directory is not the same as the source directory, a `.gdbinit'
+     file is created in the build directory.  This `.gdbinit' file
+     contains commands which allow the source directory to be read when
+     debugging with the GNU debugger, `gdb'.  (*Note Command Files:
+     (gdb)Command Files.)
+
+** makes symbolic links*
+     Most build directories require that some symbolic links with
+     generic names are built pointing to specific files in the source
+     directory.  If the system where `configure' runs cannot support
+     symbolic links, hard links are used instead.  (For details, see
+     *Note The `configure.in' input file: configure.in.)
+
+** generates `config.status'*
+     `configure' creates a shell script named `config.status' in the
+     build directory.  This shell script, when run from the build
+     directory (usually from within a `Makefile'), will reconfigure the
+     build directory (but not its subdirectories).  This is most often
+     used to have a `Makefile' update itself automatically if a new
+     source directory is available.
+
+** calls itself recursively*
+     If the source directory has subdirectories that should also be
+     configured, `configure' is called for each.
+
+
+File: configure.info,  Node: Invoking configure,  Next: Using configure,  Prev: What configure does,  Up: Top
+
+Invoking `configure'
+********************
+
+   Cygnus `configure' is a shell script which resides in a source tree.
+The usual way to invoke `configure' is from the shell, as follows:
+
+     eg$ ./configure HOSTTYPE
+
+This prepares the source in the current directory (`.') to be compiled
+for a HOSTTYPE environment.  It assumes that you wish to build programs
+and files in the default "build directory" (also the current directory,
+`.').  If you do not specify a value for HOSTTYPE, Cygnus `configure'
+will attempt to discover this information by itself (*note Determining
+system information: config.guess.).  For information on HOSTTYPE
+environments, *Note Host: Host.
+
+   All GNU software is packaged with one or more `configure' script(s)
+(*note How Configuration Should Work: (standards)Configuration.).  By
+using `configure' you prepare the source for your specific environment
+by selecting and using `Makefile' fragments and fragments of shell
+scripts, which are prepared in advance and stored with the source.
+
+   `configure''s command-line options also allow you to specify other
+aspects of the source configuration:
+
+       configure HOSTTYPE  [--target=TARGET] [--srcdir=DIR] [--rm]
+                 [--site=SITE] [--prefix=DIR] [--exec-prefix=DIR]
+                 [--program-prefix=STRING] [--tmpdir=DIR]
+                 [--with-PACKAGE[=YES/NO]] [--without-PACKAGE]
+                 [--enable-FEATURE[=YES/NO]] [--disable-FEATURE]
+                 [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
+
+`--target=TARGET'
+     Requests that the sources be configured to target the TARGET
+     machine.  If no target is specified explicitly, the target is
+     assumed to be the same as the host (i.e., a "native"
+     configuration).  *Note Host: Host, and *Note Target: Target, for
+     discussions of each.
+
+`--srcdir=DIR'
+     Direct each generated `Makefile' to use the sources located in
+     directory DIR.  Use this option whenever you wish the object code
+     to reside in a different place from the source code.  The "build
+     directory" is always assumed to be the directory you call
+     `configure' from.  See *Note Build directories: Build directories,
+     for an example.  If the source directory is not specified,
+     `configure' assumes that the source is in your current directory.
+     If `configure' finds no `configure.in' there, it searches in the
+     same directory that the `configure' script itself lies in.
+     Pathnames specified (Values for DIR) can be either absolute
+     relative to the *build* directory.
+
+`--rm'
+     *Remove* the configuration specified by HOSTTYPE and the other
+     command-line options, rather than create it.
+
+          *Note:* We recommend that you use `make distclean' rather than
+          use this option; see *Note Invoking `make': (make)Invoking
+          make, for details on `make distclean'.
+
+`--site=SITE'
+     Generate the `Makefile' using site-specific `Makefile' fragments
+     for SITE.  *Note Adding information about local conventions:
+     Makefile fragments.
+
+`--prefix=DIR'
+     Configure the source to install programs and files under directory
+     DIR.
+
+     This option sets the variable `prefix'.  Each generated `Makefile'
+     will have its `prefix' variables set to this value.  (*Note What
+     `configure' really does: What configure really does.)
+
+`--exec-prefix=DIR'
+     Configure the source to install "host dependent" files in DIR.
+
+     This option sets the variable `exec_prefix'.  Each generated
+     `Makefile' will have its `exec_prefix' variables set to this value.
+     (*Note What `configure' really does: What configure really does.)
+
+`--program-prefix=STRING'
+     Configure the source to install certain programs using STRING as a
+     prefix.  This applies to programs which might be used for
+     cross-compilation, such as the compiler and the binary utilities,
+     and also to programs which have the same names as common Unix
+     programs, such as `make'.
+
+     This option sets the variable `program_prefix'.  Each generated
+     `Makefile' will have its `program_prefix' variables set to this
+     value.  (*Note What `configure' really does: What configure really
+     does.)
+
+`--tmpdir=TMPDIR'
+     Use the directory TMPDIR for `configure''s temporary files.  The
+     default is the value of the environment variable `TMPDIR', or
+     `/tmp' if the environment variable is not set.
+
+`--with-PACKAGE[=YES/NO]'
+`--without-PACKAGE'
+     Indicate that PACKAGE is present, or not present, depending on
+     YES/NO.  If YES/NO is nonexistent, its value is assumed to be
+     `yes'.  `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'.
+
+     For example, if you wish to configure the program `gcc' for a Sun
+     SPARCstation running SunOS 4.x, and you want `gcc' to use the GNU
+     linker `ld', you can configure `gcc' using
+
+          eg$ configure --with-gnu-ld sun4
+
+     *Note What `configure' really does: What configure really does, for
+     details.  See the installation or release notes for your
+     particular package for details on which other PACKAGE options are
+     recognized.
+
+`--enable-FEATURE[=YES/NO]'
+`--disable-FEATURE'
+     Include FEATURE, or not, depending on YES/NO.  If YES/NO is
+     nonexistent, its value is assumed to be `yes'.
+     `--disable-FEATURE' is equivalent to `--enable-FEATURE=no'.
+
+     *Note What `configure' really does: What configure really does, for
+     details.  See the installation or release notes for your
+     particular package for details on which other FEATURE options are
+     recognized.
+
+`--norecursion'
+     Configure only this directory; ignore any subdirectories.  This is
+     used by the executable shell script `config.status' to reconfigure
+     only the current directory; it is most often used
+     non-interactively, when `make' is invoked.  (*Note
+     `config.status': config.status.)
+
+`--nfp'
+     Assume that the intended HOSTTYPE has no floating point unit.
+
+`-s'
+     Suppress status output.  This option is used internally by
+     `configure' when calling itself recursively in subdirectories.  You
+     can override this option with the `--verbose' option.
+
+`-v'
+`--verbose'
+     Print status lines for each directory configured.  Normally, only
+     the status lines for the initial working directory are printed.
+
+`--version'
+`-V'
+     Print the `configure' version number.
+
+`--help'
+     Print a short summary of how to invoke `configure'.
+
+   *Note:* You may introduce options with a single dash, `-', rather
+than two dashes, `--'.  However, you may not be able to truncate long
+option names when using a single dash.  When using two dashes, options
+may be abbreviated as long as each option can be uniquely identified.
+For example,
+     eg$ configure --s=/u/me/src HOSTTYPE
+
+is ambiguous, as `--s' could refer to either `--site' or `--srcdir'.
+However,
+     eg$ configure --src=/u/me/src HOSTTYPE
+
+is a valid abbreviation.
+
+
+File: configure.info,  Node: Using configure,  Next: Porting,  Prev: Invoking configure,  Up: Top
+
+Using `configure'
+*****************
+
+   `configure' prepares source directories for building programs in
+them.  "Configuring" is the process of preparing software to compile
+correctly on a given "host", for a given "target".
+
+   `configure' subsequently writes a configured `Makefile' from a
+pre-built template; `configure' uses variables that have been set in the
+configuring process to determine the values of some variables in the
+`Makefile'.  Because of this we will refer to both `configure'
+variables and `Makefile' variables.  This convention allows us to
+determine where the variable should be set initially, in either
+`configure.in' or `Makefile.in'.
+
+* Menu:
+
+* What configure really does:: What configure really does
+* configure.in::               The configure.in input file
+* Install locations::          Where to install things once they are built
+* Host::                       Telling configure what will source will be built
+* Target::                     Telling configure what the source will target
+* Makefile fragments::         Adding information about local conventions
+* Makefile extensions::        Extensions to the GNU coding standards
+
+
+File: configure.info,  Node: What configure really does,  Next: configure.in,  Up: Using configure
+
+What `configure' really does
+============================
+
+   Cygnus `configure' is a shell script that sets up an environment in
+which your programs will compile correctly for your machine and
+operating system, and will install in proper places.  `configure'
+accomplishes this task by doing the following:
+
+   * it generates a `Makefile' from a custom template called
+     `Makefile.in' in each relevant source directory;
+
+   * it customizes the build process to your specifications; you set
+     certain variables for `configure', either on the command line or
+     in the file `configure.in', which subsequently sets variables in
+     each generated `Makefile' to be used by `make' when actually
+     building the software;
+
+   * it creates "build directories", places for your code to be compiled
+     in before being installed;
+
+   * it generates a `.gdbinit' in the build directory, if needed, to
+     communicate to `gdb' where to find the program's source code;
+
+   * it generates a shell script called `config.status' which is used
+     most often by the `Makefile' to reconfigure itself;
+
+   * it recurses in subdirectories, setting up entire trees so that
+     they build correctly; if `configure' finds another `configure'
+     script further down in a given source tree, it knows to use this
+     script and not recur.
+
+   For the sake of safety (i.e., in order to prevent broken
+installations), the GNU coding standards call for software to be
+"configured" in such a way that an end user trying to build a given
+package will be able to do so by affecting a finite number of
+variables.  All GNU software comes with an executable `configure' shell
+script which sets up an environment within a build directory which will
+correctly compile your new package for your host (or, alternatively,
+whatever host you specify to `configure').  For further background on
+this topic, see *Note Apologia Configure: (cfg-paper)Some Basic Terms,
+by K. Richard Pixley.
+
+   Use `configure' to set for the build process:
+
+   * correct values for certain variables;
+
+   * which type of host you wish to configure a given package for
+     (*note Host: Host.);
+
+   * where you want to install this package (by using `prefix',
+     `exec-prefix' and `program-prefix'; *note Full descriptions of all
+     installation directories: Install details.);
+
+   * optionally, which type of machine you wish to "target" this
+     package's output to (*note Target: Target.);
+
+   * which other GNU packages are already installed and available to
+     this particular build (by using the `--with-PACKAGE' option; *note
+     Invoking `configure': Invoking configure.);
+
+   * where to place temporary files (by using the `--tmpdir=DIR'
+     option; *note Invoking `configure': Invoking configure.);
+
+   * whether to recur in subdirectories (changeable through the
+     `--norecursion' option; *note Invoking `configure': Invoking
+     configure.).
+
+   `configure' uses a few other files to complete its tasks.  These are
+discussed in detail where noted.
+
+`configure.in'
+     Input file for `configure'.  Shell script fragments reside here.
+     *Note The `configure.in' input file: configure.in.
+
+`Makefile.in'
+     Template which `configure' uses to build a file called `Makefile'
+     in the "build directory".  *Note `Makefile' generation: Makefile
+     generation.
+
+`config.sub'
+     Shell script used by `configure' to expand referents to the
+     HOSTTYPE argument into a single specification of the form
+     CPU-VENDOR-OS.  For instance, on the command line you can specify
+
+          eg$ ./configure sun4
+
+     to configure for a Sun SPARCstation running SunOS 4.x.  `configure'
+     consults `config.sub' to find that the three-part specification
+     for this is
+
+          sparc-sun-sunos4.1.1
+
+     which notes the CPU as `sparc', the MANUFACTURER as `sun' (Sun
+     Microsystems), and the OS (operating system) as `sunos4.1.1', the
+     SunOS 4.1.1 release.  *Note Variables available to `configure':
+     configure variables.
+
+`config.guess'
+     If you do not put the HOSTTYPE argument on the command line,
+     `configure' uses the `config.guess' shell script to make an
+     analysis of your machine (it assumes that you wish to configure
+     your software for the type of machine on which you are running).
+     The output of `config.guess' is a three-part identifier as
+     described above.
+
+`config.status'
+     The final step in configuring a directory is to create a shell
+     script, `config.status'.  The main purpose of this file is to
+     allow the `Makefile' for the current directory to rebuild itself,
+     if necessary.  *Note `config.status': config.status.
+
+`config/*'
+     `configure' uses three types of `Makefile' "fragments", which
+     reside in the directory `SRCDIR/config/'.  *Note Adding
+     information about local conventions: Makefile fragments.
+
+* Menu:
+
+* Build variables::         Variable-spaghetti made simple
+* Build directories::       Build directories described well
+* Makefile generation::     To build a Makefile
+* config.guess::            Be vewwy quiet, I'm hunting system information
+* config.status::           To rebuild a Makefile
+
+
+File: configure.info,  Node: Build variables,  Next: Build directories,  Up: What configure really does
+
+Build variables
+---------------
+
+   There are several variables in the build process which you can
+control through build programs such as `make'.  These include machine
+definitions, local conventions, installation locations, locations for
+temporary files, etc.  This data is accessible through certain
+variables which are configurable in the build process; we refer to them
+as "build variables".
+
+   For lists of build variables which you can affect by using
+`configure', see *Note Variables available to `configure.in': configure
+variables, and *Note Full descriptions of all installation directories:
+Install details.
+
+   Generally, build variables, which are used by the `Makefile' to
+determine various aspects of the build and installation processes, are
+changeable with command-line options to `configure'.  In most large
+suites of programs, like the Cygnus Support Developer's Kit, the
+individual programs reside in several subdirectories of a single source
+code "tree".  All of these subdirectories need to be configured with
+information relative to the "build directory", which is not known until
+`configure' is run.  Unless specified otherwise, `configure'
+recursively configures every subdirectory in the source tree.
+
+   Build variables are passed from `configure' directly into the
+`Makefile', and use the same names (except that dashes are transformed
+into underbars; for example, when you specify the option
+`--exec-prefix' on the command line, the `Makefile' variable
+`exec_prefix' is set).  In other words, if you specify
+
+     eg$ ./configure --prefix=/usr/gnu/local ... HOSTTYPE
+
+on the command line, `configure' sets an variable called `prefix' to
+`/usr/gnu/local', and passes this into the `Makefile' in the same
+manner.  After this command, each `Makefile' generated by `configure'
+will contain a line that reads:
+
+     prefix = /usr/gnu/local
+
+   For a list of the `Makefile' variables `configure' can change, and
+instructions on how to change them, see *Note Variables available to
+`configure.in': configure variables, and *Note Invoking `configure':
+Invoking configure.
+
+
+File: configure.info,  Node: Build directories,  Next: Makefile generation,  Prev: Build variables,  Up: What configure really does
+
+Build directories
+-----------------
+
+   By default, `configure' builds a `Makefile' and symbolic links in the
+same directory as the source files.  This default works for many cases,
+but it has limitations.  For instance, using this approach, you can
+only build object code for one host at a time.
+
+   We refer to each directory where `configure' builds a `Makefile' as
+a "build directory".
+
+   The build directory for any given build is always the directory from
+which you call `configure', or `.' relative to your prompt.  The default
+"source directory", the place `configure' looks to find source code, is
+also `.'.  For instance, if we have a directory `/gnu-stuff/src/' that
+is the top branch of a tree of GNU source code we wish to configure,
+then the program we will use to configure this code is
+`/gnu-stuff/src/configure', as follows.  (Assume for the sake of
+argument that our machine is a sun4.)
+
+     eg$ cd /gnu-stuff/src
+     eg$ ./configure sun4
+     Created "Makefile" in /gnu-stuff/src
+     eg$
+
+   We just configured the code in `/gnu-stuff/src' to run on a Sun
+SPARCstation using SunOS 4.x by creating a `Makefile' in
+`/gnu-stuff/src'.  By default, we also specified that when this code is
+built, the object code should reside in the same directory,
+`/gnu-stuff/src'.
+
+   However, if we wanted to build this code for more than one host, we
+would be in trouble, because the new configuration would write over the
+old one, destroying it in the process.  What we can do is to make a new
+"build directory" and configure from there.  Running `configure' from
+the new directory will place a correct `Makefile' and a `config.status'
+in this new file.  That is all `configure' does; we must run `make' to
+generate any object code.
+
+   The new `Makefile' in `/gnu-stuff/sun4-obj', created from the
+template file `/gnu-stuff/src/Makefile.in', contains all the information
+needed to build the program.
+
+     eg$ mkdir /gnu-stuff/sun4-obj
+     eg$ cd /gnu-stuff/sun4-obj
+     eg$ ../src/configure --srcdir=../src sun4
+     Created "Makefile" in /gnu-stuff/sun4-obj
+     eg$ ls
+     Makefile       config.status
+     eg$ make all info install install-info clean
+     COMPILATION MESSAGES...
+     eg$ mkdir /gnu-stuff/solaris2
+     eg$ cd /gnu-stuff/solaris2
+     eg$ ../src/configure --srcdir=../src sol2
+     Created "Makefile" in /gnu-stuff/solaris2
+     eg$ ls
+     Makefile       config.status
+     eg$ make all info install install-info clean
+     COMPILATION MESSAGES...
+
+   We can repeat this for other configurations of the same software
+simply by making a new build directory and reconfiguring from inside
+it.  If you do not specify the HOSTTYPE argument, `configure' will
+attempt to figure out what kind of machine and operating system you
+happen to be using.  *Note Determining system information:
+config.guess.  Of course, this may not always be the configuration you
+wish to build.
+
+   *Caution:* If you build more than one configuration for a single
+program, remember that you must also specify a different `--prefix' for
+each configuration at configure-time.  Otherwise, both configurations
+will be installed in the same default location (`/usr/local'); the
+configuration to be installed last would overwrite previously installed
+configurations.
+
+
+File: configure.info,  Node: Makefile generation,  Next: config.guess,  Prev: Build directories,  Up: What configure really does
+
+`Makefile' generation
+---------------------
+
+   Cygnus `configure' creates a file called `Makefile' in the build
+directory which can be used with `make' to automatically build a given
+program or package.  `configure' also builds a `Makefile' for each
+relevant subdirectory for a given program or package (irrelevant
+subdirectories would be those which contain no code which needs
+configuring, and which therefore have no `configure' input file
+`configure.in' and no `Makefile' template `Makefile.in').  *Note `make'
+Invocation: (make)Running, for details on using `make' to compile your
+source code.
+
+   Each `Makefile' contains variables which have been configured for a
+specific build.  These build variables are determined when `configure'
+is run.  All build variables have defaults.  By default, `configure'
+generates a `Makefile' which specifies:
+
+   * a "native" build, which is to occur
+
+   * in the current directory, and which will be installed
+
+   * in the default installation directory (`/usr/local') when the code
+     is compiled with `make'.
+
+Variables are changeable through command-line options to `configure'
+(*note Invoking `configure': Invoking configure.).
+
+   If you are porting a new program and intend to use `configure', see
+*Note Porting with `configure': Porting, as well as *Note Writing
+Makefiles: (make)Makefiles, and *Note Makefile Conventions:
+(standards)Makefiles.
+
+
+File: configure.info,  Node: config.guess,  Next: config.status,  Prev: Makefile generation,  Up: What configure really does
+
+Determining system information
+------------------------------
+
+   The shell script `config.guess' is called when you do not specify a
+HOSTTYPE on the command line to `configure'.  `config.guess' acquires
+available system information from your local machine through the shell
+command `uname'.  It compares this information to a database and
+attempts to determine a usable three-part system identifier (known as a
+"triple") to use as your HOSTTYPE.  *Note What `configure' really does:
+What configure really does, to see how this information is used.
+
+   *Note:*  If you do not specify a HOSTTYPE on the command line,
+`configure' will attempt to configure your software to run on the
+machine you happen to be using.  This may not be the configuration you
+desire.
+
+
+File: configure.info,  Node: config.status,  Prev: config.guess,  Up: What configure really does
+
+`config.status'
+---------------
+
+   The final step in configuring a directory is to create an executable
+shell script, `config.status'.  The main purpose of this file is to
+allow the `Makefile' for the current directory to rebuild itself, if
+necessary.  It is usually run from within the `Makefile'.  *Note
+Extensions to the GNU coding standards: Makefile extensions.
+
+   `config.status' also contains a record of the `configure' session
+which created it.
+
+
+File: configure.info,  Node: configure.in,  Next: Install locations,  Prev: What configure really does,  Up: Using configure
+
+The `configure.in' input file
+=============================
+
+   A `configure.in' file for Cygnus `configure' consists of a
+"per-invocation" section, followed by a "per-host" section, followed by
+a "per-target" section, optionally followed by a "post-target" section.
+Each section is a shell script fragment, which is executed by the
+`configure' shell script at an appropriate time.  Values are passed
+among `configure' and the shell fragments through a set of shell
+variables.  When each section is being interpreted by the shell, the
+shell's current directory is the build directory, and any files created
+by the section (or referred to by the section) will be relative to the
+build directory.  To reference files in other places (such as the
+source directory), prepend a shell variable such as `$(srcdir)/' to the
+desired file name.
+
+   The beginning of the `configure.in' file begins the "per-invocation"
+section.
+
+   A line beginning with `# per-host:' begins the "per-host" section.
+
+   A line beginning with `# per-target:' begins the "per-target"
+section.
+
+   If it exists, the "post-target" section begins with `# post-target:'.
+
+* Menu:
+
+* configure variables::    Variables available to configure.in
+* Minimal::                A minimal configure.in
+* Declarations::           For each invocation
+* per-host::               Host-specific instructions
+* per-target::             Target-specific instructions
+* post-target::            Instructions to be executed after target info
+* Example::                An example configure.in
+
+
+File: configure.info,  Node: configure variables,  Next: Minimal,  Up: configure.in
+
+Variables available to `configure.in'
+-------------------------------------
+
+   The following variables pass information between the standard parts
+of `configure' and the shell-script fragments in `configure.in':
+
+`srctrigger'
+     Contains the name of a source file that is expected to live in the
+     source directory.  You must usually set this in the
+     "per-invocation" section of `configure.in'.  `configure' tests to
+     see that this file exists.  If the file does not exist,
+     `configure' prints an error message.  This is used as a sanity
+     check that `configure.in' matches the source directory.
+
+`srcname'
+     Contains the name of the source collection contained in the source
+     directory.  You must usually set this in the "per-invocation"
+     section of `configure.in'.  If the file named in `srctrigger' does
+     not exist, `configure' uses the value of `srcname' when it prints
+     the error message.
+
+`configdirs'
+     Contains the names of any subdirectories in which `configure'
+     should recurse.  You must usually set this in the "per-invocation"
+     section of `configure.in'.  If `Makefile.in' contains a line
+     starting with `SUBDIRS =', then it will be replaced with an
+     assignment to `SUBDIRS' using the value of `configdirs' (if
+     `subdirs' is empty).  This can be used to determine which
+     directories to configure and build depending on the host and
+     target configurations.  Use `configdirs' (instead of the `subdirs'
+     variable described below) if you want to be able to partition the
+     subdirectories, or use independent `Makefile' fragments.  Each
+     subdirectory can be independent, and independently reconfigured.
+
+`subdirs'
+     Contains the names of any subdirectories where `configure' should
+     create a `Makefile' (in addition to the current directory),
+     *without* recursively running `configure'.  Use `subdirs' (instead
+     of the `configdirs' variable described above) if you want to
+     configure all of the directories as a unit.  Since there is a
+     single invocation of `configure' that configures many directories,
+     all the directories can use the same `Makefile' fragments, and the
+     same `configure.in'.
+
+`host'
+     Contains the full configuration name for the host (generated by
+     the script `config.sub' from the name that you entered).  This is
+     a three-part name (commonly referred to as a "triple") of the form
+     CPU-VENDOR-OS.
+
+     There are separate variables `host_cpu', `host_vendor', and
+     `host_os' that you can use to test each of the three parts; this
+     variable is useful, however, for error messages, and for testing
+     combinations of the three components.
+
+`host_cpu'
+     Contains the first element of the canonical triple representing
+     the host as returned by `config.sub'.  This is occasionally used to
+     distinguish between minor variations of a particular vendor's
+     operating system and sometimes to determine variations in binary
+     format between the host and the target.
+
+`host_vendor'
+     Contains the second element of the canonical triple representing
+     the host as returned by `config.sub'.  This is usually used to
+     distinguish among the numerous variations of *common* operating
+     systems.
+
+`host_os'
+     Contains the the third element of the canonical triple
+     representing the host as returned by `config.sub'.
+
+`target'
+     Contains the full configuration name (generated by the script
+     `config.sub' from the name that you entered) for the target.  Like
+     the host, this is a three-part name of the form CPU-VENDOR-OS.
+
+     There are separate variables `target_cpu', `target_vendor', and
+     `target_os' that you can use to test each of the three parts; this
+     variable is useful, however, for error messages, and for testing
+     combinations of the three components.
+
+`target_cpu'
+     Contains the first element of the canonical triple representing
+     the target as returned by `config.sub'.  This variable is used
+     heavily by programs which are involved in building other programs,
+     like the compiler, assembler, linker, etc.  Most programs will not
+     need the `target' variables at all, but this one could conceivably
+     be used to build a program, for instance, that operated on binary
+     data files whose byte order or alignment differ from the system
+     where the program is running.
+
+`target_vendor'
+     Contains the second element of the canonical triple representing
+     the target as returned by `config.sub'.  This is usually used to
+     distinguish among the numerous variations of *common* operating
+     systems or object file formats.  It is sometimes used to switch
+     between different flavors of user interfaces.
+
+`target_os'
+     Contains the the third element of the canonical triple
+     representing the target as returned by `config.sub'.  This
+     variable is used by development tools to distinguish between
+     subtle variations in object file formats that some vendors use
+     across operating system releases.  It might also be use to decide
+     which libraries to build or what user interface the tool should
+     provide.
+
+`floating_point'
+     Set to `no' if you invoked `configure' with the `--nfp'
+     command-line option, otherwise it is empty.  This is a request to
+     target machines with "no floating point" unit, even if the targets
+     ordinarily have floating point units available.
+
+`gas'
+     Set to `true' if you invoked `configure' with the `--with-gnu-as'
+     command line option, otherwise it is empty.  This is a request to
+     assume that the specified HOSTTYPE machine has GNU `as' available
+     even if it ordinarily does not.
+
+`srcdir'
+     Set to the name of the directory containing the source for this
+     program.  This will be different from `.' if you have specified the
+     `--srcdir=DIR' option.  `srcdir' can indicate either an absolute
+     path or a path relative to the build directory.
+
+`package_makefile_frag'
+     If set in `configure.in', this variable should be the name a file
+     relative to `srcdir' to be included in the resulting `Makefile'.
+     If the named file does not exist, `configure' will print a warning
+     message.  This variable is not set by `configure'.
+
+`host_makefile_frag'
+     If set in `configure.in', this variable should be the name a file
+     relative to `srcdir' to be included in the resulting `Makefile'.
+     If the named file does not exist, `configure' will print a warning
+     message.  This variable is not set by `configure'.
+
+`target_makefile_frag'
+     If set in `configure.in', this variable should be the name of a
+     file, relative to `srcdir', to be included in the resulting
+     `Makefile'.  If the named file does not exist, `configure' will
+     print a warning message.  This variable is not set by `configure'.
+
+`site_makefile_frag'
+     Set to a file name representing to the default `Makefile' fragment
+     for this host.  It may be set in `configure.in' to override this
+     default.  Normally `site_makefile_frag' is empty, but will have a
+     value if you specify `--site=SITE' on the command line.
+
+`Makefile'
+     Set to the name of the generated `Makefile'.  Normally this value
+     is precisely `Makefile', but some programs may want something else.
+
+`removing'
+     Normally empty but will be set to some non-null value if you
+     specified `--rm' on the command line.  That is, if `removing' is
+     not empty, then `configure' is *removing* a configuration rather
+     than creating one.
+
+`files'
+     If this variable is not empty following the "per-target" section,
+     then each word in its value will be the target of a symbolic link
+     named in the corresponding word from the `links' variable.
+
+`links'
+     If the `files' variable is not empty following the "per-target"
+     section, then `configure' creates symbolic links with the first
+     word of `links' pointing to the first word of `files', the second
+     word of `links' pointing to the second word of `files', and so on.
+
+
+File: configure.info,  Node: Minimal,  Next: Declarations,  Prev: configure variables,  Up: configure.in
+
+A minimal `configure.in'
+------------------------
+
+   A minimal `configure.in' consists of four lines.
+
+     srctrigger=foo.c
+     srcname="source for the foo program"
+     # per-host:
+     # per-target:
+
+   The `# per-host:' and `# per-target:' lines divide the file into the
+three required sections.  The `srctrigger' line names a file.
+`configure' checks to see that this file exists in the source directory
+before configuring.  If the `srctrigger' file does not exist,
+`configure' uses the value of `srcname' to print an error message about
+not finding the source.
+
+   This particular example uses no links, and only the default host,
+target, and site-specific `Makefile' fragments if they exist.
+
+
+File: configure.info,  Node: Declarations,  Next: per-host,  Prev: Minimal,  Up: configure.in
+
+For each invocation
+-------------------
+
+   `configure' invokes the entire shell script fragment from the start
+of `configure.in' up to a line beginning with `# per-host:' immediately
+after parsing command line arguments.  The variables `srctrigger' and
+`srcname' *must* be set here.
+
+   You might also want to set the variables `configdirs' and
+`package_makefile_frag' here.
+
+
+File: configure.info,  Node: per-host,  Next: per-target,  Prev: Declarations,  Up: configure.in
+
+Host-specific instructions
+--------------------------
+
+   The "per-host" section of `configure.in' starts with the line that
+begins with `# per-host:' and ends before a line beginning with
+`# per-target:'.  `configure' invokes the commands in the "per-host"
+section when determining host-specific information.
+
+   This section usually contains a big `case' statement using the
+variable `host' to determine appropriate values for
+`host_makefile_frag' and `files', although `files' is not usually set
+here.  Usually, it is set at the end of the "per-target" section after
+determining the names of the target specific configuration files.
+
+
+File: configure.info,  Node: per-target,  Next: post-target,  Prev: per-host,  Up: configure.in
+
+Target-specific instructions
+----------------------------
+
+   The "per-target" section of `configure.in' starts with the line that
+begins with `# per-target:' and ends before the line that begins with
+`# post-target:', if there is such a line.  Otherwise the "per-target"
+section extends to the end of the file.  `configure' invokes the
+commands in the "per-target" section when determining target-specific
+information, and before building any files, directories, or links.
+
+   This section usually contains a big `case' statement using the
+variable `target' to determine appropriate values for
+`target_makefile_frag' and `files'.  The last lines in the "per-target"
+section normally set the variables `files' and `links'.
+
+
+File: configure.info,  Node: post-target,  Next: Example,  Prev: per-target,  Up: configure.in
+
+Instructions to be executed after target info
+---------------------------------------------
+
+   The "post-target" section is optional.  If it exists, the
+`post-target' section starts with a line beginning with
+`# Post-target:' and extends to the end of the file.  If it exists,
+`configure' invokes this section once for each target after building
+all files, directories, or links.
+
+   This section is seldom needed, but you can use it to edit the
+`Makefile' generated by `configure'.
+
+
+File: configure.info,  Node: Example,  Prev: post-target,  Up: configure.in
+
+An example `configure.in'
+-------------------------
+
+   Here is a small example of a `configure.in' file.
+
+     # This file is a collection of shell script fragments
+     # used to tailor a template configure script as
+     # appropriate for this directory.  For more information,
+     # see configure.texi.
+     
+     configdirs=
+     srctrigger=warshall.c
+     srcname="bison"
+     
+     # per-host:
+     case "${host}" in
+     m88k-motorola-*)
+             host_makefile_frag=config/mh-delta88
+             ;;
+     esac
+     
+     # per-target:
+     files="bison_in.hairy"
+     links="bison.hairy"
+     
+     # post-target:
+
+
+File: configure.info,  Node: Install locations,  Next: Host,  Prev: configure.in,  Up: Using configure
+
+Install locations
+=================
+
+   Using the default configuration, `make install' creates a single
+tree of files, some of which are programs.  The location of this tree
+is determined by the value of the variable `prefix'.  The default value
+of `prefix' is `/usr/local'.  This is often correct for native tools
+installed on only one host.
+
+* Menu:
+
+* prefix::            Changing the default install directory
+* exec_prefix::       How to separate host independent files
+                                         from host dependent files when
+                                         installing for multiple hosts
+* Install details::   Full descriptions of all installation subdirectories
+
+
+File: configure.info,  Node: prefix,  Next: exec_prefix,  Up: Install locations
+
+Changing the default install directory
+--------------------------------------
+
+   In the default configuration, all files are installed in
+subdirectories of `/usr/local'.  The location is determined by the
+value of the `configure' variable `prefix'; in turn, this determines the
+value of the `Makefile' variable of the same name (`prefix').
+
+   You can also set the value of the `Makefile' variable `prefix'
+explicitly each time you invoke `make' if you are so inclined.  However,
+because many programs have this location compiled in, you must specify
+the `prefix' value consistently on each invocation of `make', or you
+will end up with a broken installation.
+
+   To make this easier, the value of the `configure' variable `prefix'
+can be set on the command line to `configure' using the option
+`--prefix='.
+
+
+File: configure.info,  Node: exec_prefix,  Next: Install details,  Prev: prefix,  Up: Install locations
+
+Installing for multiple hosts
+-----------------------------
+
+   By default, host dependent files are installed in subdirectories of
+`$(exec_prefix)'.  The location is determined by the value of the
+`configure' variable `exec_prefix', which determines the value of the
+`Makefile' variable `exec_prefix'.  This makes it easier to install for
+a single host, and simplifies changing the default location for the
+install tree.  The default doesn't allow for multiple hosts to
+effectively share host independent files, however.
+
+   To configure so that multiple hosts can share common files, use
+something like:
+
+     configure HOST1 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
+     make all info install install-info clean
+     
+     configure HOST2 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
+     make all info install install-info
+
+   The first line configures the source for HOST1 to place host-specific
+programs in subdirectories of `/usr/gnu/H-HOST1'.
+
+   The second line builds and installs all programs for HOST1,
+including both host-independent and host-specific files, as well as
+removing the host-specific object files from of the build directory.
+
+   The third line reconfigures the source for HOST2 to place host
+specific programs in subdirectories of `/usr/gnu/H-HOST2'.
+
+   The fourth line builds and installs all programs for HOST2.  Host
+specific files are installed in new directories, but the host
+independent files are installed *on top of* the host independent files
+installed for HOST1.  This results in a single copy of the host
+independent files, suitable for use by both hosts.
+
+   *Note Extensions to the GNU coding standards: Makefile extensions,
+for more information.
+
+
+File: configure.info,  Node: Install details,  Prev: exec_prefix,  Up: Install locations
+
+Full descriptions of all installation subdirectories
+----------------------------------------------------
+
+   During any install, a number of standard directories are created.
+Their names are determined by `Makefile' variables.  Some of the
+defaults for `Makefile' variables can be changed at configuration time
+using command line options to `configure'.  For more information on the
+standard directories or the `Makefile' variables, please refer to *Note
+Makefile Conventions: (standards)Makefiles.  See also *Note Extensions
+to the GNU coding standards: Makefile extensions.
+
+   Note that `configure' does not create the directory indicated by the
+variable `srcdir' at any time.  `$(srcdir)' is not an installation
+directory.
+
+   You can override all `Makefile' variables on the command line to
+`make'.  (*Note Overriding Variables: (make)Overriding.)  If you do so,
+you will need to specify the value precisely the same way for each
+invocation of `make', or you risk ending up with a broken installation.
+This is because many programs have the locations of other programs or
+files compiled into them.  If you find yourself overriding any of the
+variables frequently, you should consider site dependent `Makefile'
+fragments.  See also *Note Adding site info: Sites.
+
+   During `make install', a number of standard directories are created
+and populated.  The following `Makefile' variables define them.  Those
+whose defaults are set by corresponding `configure' variables are marked
+"`Makefile' and `configure'".
+
+`prefix (`Makefile' and `configure')'
+     The root of the installation tree.  You can set its `Makefile'
+     default with the `--prefix=' command line option to `configure'
+     (*note Invoking `configure': Invoking configure.).  The default
+     value for `prefix' is `/usr/local'.
+
+`bindir'
+     A directory for binary programs that users can run.  The default
+     value for `bindir' depends on `prefix'; `bindir' is normally
+     changed only indirectly through `prefix'.  The default value for
+     `bindir' is `$(prefix)/bin'.
+
+`exec_prefix (`Makefile' and `configure')'
+     A directory for host dependent files.  You can specify the
+     `Makefile' default value by using the `--exec_prefix=' option to
+     `configure'.  (*Note Invoking `configure': Invoking configure.)
+     The default value for `exec_prefix' is `$(prefix)'.
+
+`libdir'
+     A directory for libraries and support programs.  The default value
+     for `libdir' depends on `prefix'; `libdir' is normally changed only
+     indirectly through `prefix'.  The default value for `libdir' is
+     `$(prefix)/lib'.
+
+`mandir'
+     A directory for `man' format documentation ("man pages").  The
+     default value for `mandir' depends on `prefix'; `mandir' is
+     normally changed only indirectly through `prefix'.  The default
+     value for `mandir' is `$(prefix)/man'.
+
+`manNdir'
+     These are eight variables named `man1dir', `man2dir', etc.  They
+     name the specific directories for each man page section.  For
+     example, `man1dir' by default holds the filename `$(mandir)/man1';
+     this directory contains `emacs.1' (the man page for GNU Emacs).
+     Similarly, `man5dir' contains the value `$(mandir)/man5',
+     indicating the directory which holds `rcsfile.5' (the man page
+     describing the `rcs' data file format).  The default value for any
+     of the `manNdir' variables depends indirectly on `prefix', and is
+     normally changed only through `prefix'.  The default value for
+     `manNdir' is `$(mandir)/manN'.
+
+`manNext'
+     *Not supported by Cygnus `configure'*.  The `GNU Coding Standards'
+     do not call for `man1ext', `man2ext', so the intended use for
+     `manext' is apparently not parallel to `mandir'.  Its use is not
+     clear.  (See also *Note Extensions to the GNU coding standards:
+     Makefile extensions.)
+
+`infodir'
+     A directory for `info' format documentation.  The default value for
+     `infodir' depends indirectly on `prefix'; `infodir' is normally
+     changed only through `prefix'.  The default value for `infodir' is
+     `$(prefix)/info'.
+
+`docdir'
+     A directory for any documentation that is in a format other than
+     those used by `info' or `man'.  The default value for `docdir'
+     depends indirectly on `prefix'; `docdir' is normally changed only
+     through `prefix'.  The default value for `docdir' is
+     `$(datadir)/doc'.  *This variable is an extension to the GNU
+     coding standards*.  (See also *Note Extensions to the GNU coding
+     standards: Makefile extensions.)
+
+`includedir'
+     A directory for the header files accompanying the libraries
+     installed in `libdir'.  The default value for `includedir' depends
+     on `prefix'; `includedir' is normally changed only indirectly
+     through `prefix'.  The default value for `includedir' is
+     `$(prefix)/include'.
+
+
+File: configure.info,  Node: Host,  Next: Target,  Prev: Install locations,  Up: Using configure
+
+Host
+====
+
+   The arguments to `configure' are "hosttypes".  By "hosttype" we mean
+the "environment" in which the source will be compiled.  This need not
+necessarily be the same as the physical machine involved, although it
+usually is.
+
+   For example, if some obscure machine had the GNU `POSIX' emulation
+libraries available, it would be possible to configure most GNU source
+for a `POSIX' system and build it on the obscure host.
+
+   For more on this topic, see *Note On Configuring Development Tools:
+(cfg-paper)Host Environments.
+
+
+File: configure.info,  Node: Target,  Next: Makefile fragments,  Prev: Host,  Up: Using configure
+
+Target
+======
+
+   For building native development tools, or most of the other GNU
+tools, you need not worry about the target.  The "target" of a
+configuration defaults to the same as the "host".
+
+   For building cross development tools, please see *Note On
+Configuring Development Tools: (cfg-paper)Building Development
+Environments.
+
diff --git a/gnu/usr.bin/binutils/etc/configure.info-2 b/gnu/usr.bin/binutils/etc/configure.info-2
new file mode 100644
index 00000000000..022d187f819
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.info-2
@@ -0,0 +1,572 @@
+This is Info file configure.info, produced by Makeinfo-1.55 from the
+input file ./configure.texi.
+
+START-INFO-DIR-ENTRY
+* configure: (configure).        Cygnus configure.
+END-INFO-DIR-ENTRY
+
+   This document describes the Cygnus Support version of `configure'.
+
+   Copyright (C) 1991, 1992, 1993 Cygnus Support 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 Cygnus Support.
+
+
+File: configure.info,  Node: Makefile fragments,  Next: Makefile extensions,  Prev: Target,  Up: Using configure
+
+Adding information about local conventions
+==========================================
+
+   If you find that a tool does not get configured to your liking, or if
+`configure''s conventions differ from your local conventions, you should
+probably consider "site-specific `Makefile' fragments".  See also *Note
+Adding site info: Sites.
+
+   These are probably not the right choice for options that can be set
+from the `configure' command line or for differences that are host or
+target dependent.
+
+   Cygnus `configure' uses three types of `Makefile' fragments.  In a
+generated `Makefile' they appear in the order: "target fragment", "host
+fragment", and "site fragment".  This allows host fragments to override
+target fragments, and site fragments to override both.
+
+   Host-specific `Makefile' fragments conventionally reside in the
+`./config/' subdirectory with names of the form `mh-HOSTTYPE'.  They
+are used for hosts that require odd options to the standard compiler and
+for compile time options based on the host configuration.
+
+   Target-specific `Makefile' fragments conventionally reside in the
+`./config/' subdirectory with names of the form `mt-TARGET'.  They are
+used for target dependent compile time options.
+
+   Site specific `Makefile' fragments conventionally reside in the
+`./config/' subdirectory with names of the form `ms-SITE'.  They are
+used to override host- and target-independent compile time options.
+Note that you can also override these options on the `make' invocation
+line.
+
+
+File: configure.info,  Node: Makefile extensions,  Prev: Makefile fragments,  Up: Using configure
+
+Extensions to the GNU coding standards
+======================================
+
+   The following additions to the GNU coding standards are required for
+Cygnus `configure' to work properly.
+
+   * The `Makefile' must contain exactly one line starting with `####'.
+     This line should follow any default macro definitions but precede
+     any rules.  Host, target, and site-specific `Makefile' fragments
+     will be inserted immediately after this line.  If the line is
+     missing, the fragments will not be inserted.
+
+   * Cygnus adds the following targets to each `Makefile'.  Their
+     existence is not required for Cygnus `configure', but they are
+     documented here for completeness.
+
+    `info'
+          Build all info files from texinfo source.
+
+    `install-info'
+          Install all info files.
+
+    `clean-info'
+          Remove all info files and any intermediate files that can be
+          generated from texinfo source.
+
+    `Makefile'
+          Calls `./config.status' to rebuild the `Makefile' in this
+          directory.
+
+   * The following `Makefile' targets have revised semantics:
+
+    `install'
+          Should *not* depend on the target `all'.  If the program is
+          not already built, `make install' should fail.  This allows
+          you to install programs even when `make' would otherwise
+          determine them to be out of date.  This can happen, for
+          example, when the result of a `make all' is transported via
+          tape to another machine for installation.
+
+    `clean'
+          Should remove any file that can be regenerated by the
+          `Makefile', excepting only the `Makefile' itself, and any
+          links created by `configure'.  That is, `make all clean'
+          should return all directories to their original condition.
+          If this is not done, then the command sequence
+
+               configure HOST1 ; make all install clean ;
+               configure HOST2 ; make all install
+
+          will fail because of intermediate files intended for HOST1.
+
+   * Cygnus adds the following macros to all `Makefile.in' files, but
+     you are not required to use them to run Cygnus `configure'.
+
+    `docdir'
+          The directory in which to install any documentation that is
+          not either a `man' page or an `info' file.  For `man' pages,
+          see `mandir'; for `info', see `infodir'.
+
+    `includedir'
+          The directory in which to install any header files that
+          should be made available to users.  This is distinct from the
+          `gcc' include directory, which is intended for `gcc' only.
+          Files in `includedir' may be used by `cc' as well.
+
+   * The following macros have revised semantics.  Most of them describe
+     installation directories; see also *Note Full description of all
+     installation subdirectories: Install details.
+
+    `datadir'
+          is used for host independent data files.
+
+    `mandir'
+          The default path for `mandir' depends on `prefix'.
+
+    `infodir'
+          The default path for `infodir' depends on `prefix'.
+
+    `BISON'
+          is assumed to have a `yacc' calling convention.  To use GNU
+          `bison', use `BISON=bison -y'.
+
+   * Each Cygnus `Makefile' also conforms to one additional restriction:
+
+     When libraries are installed, the line containing the call to
+     `INSTALL_DATA' should always be followed by a line containing a
+     call to `RANLIB' on the installed library.  This is to accommodate
+     systems that use `ranlib'.  Systems that do not use `ranlib' can
+     set `RANLIB' to "`echo'" in a host specific `Makefile' fragment.
+
+
+File: configure.info,  Node: Porting,  Next: Variables Index,  Prev: Using configure,  Up: Top
+
+Porting with `configure'
+************************
+
+   This section explains how to add programs, host and target
+configuration names, and site-specific information to Cygnus
+`configure'.
+
+* Menu:
+
+* Programs::               Adding configure to new programs
+* Hosts and targets::      Adding hosts and targets
+* Sites::                  Adding site info
+
+
+File: configure.info,  Node: Programs,  Next: Hosts and targets,  Up: Porting
+
+Adding `configure' to new programs
+==================================
+
+   If you are writing a new program, you probably shouldn't worry about
+porting or configuration issues until it is running reasonably on some
+host.  Then refer back to this section.
+
+   If your program currently has a `configure' script that meets the GNU
+standards (*note How Configuration Should Work:
+(standards)Configuration., please do not add Cygnus `configure'.  It
+should be possible to add this program without change to a Cygnus
+`configure' style source tree.
+
+   If the program is not target dependent, please consider using
+`autoconf' instead of Cygnus `configure'.  `autoconf' is available from
+the Free Software Foundation; it is a program which generates an
+executable shell script called `configure' by automatically finding
+information on the system to be configured on and embedding this
+information in the shell script.  `configure' scripts generated by
+`autoconf' require no arguments, and accept the same options as Cygnus
+`configure'.  For detailed instructions on using `autoconf', see *Note
+How to organize and produce Autoconf scripts: (autoconf)Making
+configure Scripts.
+
+   To add Cygnus `configure' to an existing program, do the following:
+
+*Make sure the `Makefile' conforms to the GNU standard
+     The coding standard for writing a GNU `Makefile' is described in
+     *Note Makefile Conventions: (standards)Makefiles.  For technical
+     information on writing a `Makefile', see *Note Writing Makefiles:
+     (make)Makefiles.
+
+*Add Cygnus extensions to the `Makefile'
+     These are described in *Note Extensions to the GNU coding
+     standards: Makefile extensions.
+
+*Collect package specific definitions in a single file
+     Many packages are best configured using a common `Makefile'
+     fragment which is included by all of the makefiles in the
+     different directories of the package.  In order to accomplish
+     this, set the variable `package_makefile_fragment' to the name of
+     the file.  It will be inserted into the final `Makefile' before
+     the target-specific fragment.
+
+*Move host support from `Makefile' to fragments
+     This usually involves finding sections of the `Makefile' that say
+     things like "uncomment these lines for host HOSTTYPE" and moving
+     them to a new file called `./config/mh-HOSTTYPE'. For more
+     information, see *Note Adding hosts and targets: Hosts and targets.
+
+*Choose defaults
+     If the program has compile-time options that determine the way the
+     program should behave, choose reasonable defaults and make these
+     `Makefile' variables.  Be sure the variables are assigned their
+     default values before the `####' line so that site-specific
+     `Makefile' fragments can override them (*note Extensions to the
+     GNU coding standards: Makefile extensions.).
+
+*Locate configuration files
+     If there is configuration information in header files or source
+     files, separate it in such a way that the files have generic
+     names.  Then move the specific instances of those files into the
+     `./config/' subdirectory.
+
+*Separate host and target information
+     Some programs already have this information separated.  If yours
+     does not, you will need to separate these two kinds of
+     configuration information.  "Host specific" information is the
+     information needed to compile the program.  "Target specific"
+     information is information on the format of data files that the
+     program will read or write.  This information should live in
+     separate files in the `./config/' subdirectory with names that
+     reflect the configuration for which they are intended.
+
+     At this point you might skip this step and simply move on.  If you
+     do, you should end up with a program that can be configured only
+     to build "native" tools, that is, tools for which the host system
+     is also the target system.  Later, you could attempt to build a
+     cross tool and separate out the target-specific information by
+     figuring out what went wrong.  This is often simpler than combing
+     through all of the source code.
+
+*Write `configure.in'
+     Usually this involves writing shell script fragments to map from
+     canonical configuration names into the names of the configuration
+     files.  These files will then be linked at configure time from the
+     specific instances of those files in `./config' to files in the
+     build directory with more generic names.  (See also *Note Build
+     directories: Build directories.)  The format of `configure.in' is
+     described in *Note The `configure.in' input file: configure.in.
+
+*Rename `Makefile' to `Makefile.in'
+   At this point you should have a program that can be configured using
+Cygnus `configure'.
+
+
+File: configure.info,  Node: Hosts and targets,  Next: Sites,  Prev: Programs,  Up: Porting
+
+Adding hosts and targets
+========================
+
+   To add a host or target to a program that already uses Cygnus
+`configure', do the following.
+
+   * Make sure the new configuration name is represented in
+     `config.sub'.  If not, add it.  For more details, see the comments
+     in the shell script `config.sub'.
+
+   * If you are adding a host configuration, look in `configure.in', in
+     the "per-host" section.  Make sure that your configuration name is
+     represented in the mapping from host configuration names to
+     configuration files.  If not, add it.  Also see *Note The
+     `configure.in' input file: configure.in.
+
+   * If you are adding a target configuration, look in `configure.in',
+     in the "per-target" section.  Make sure that your configuration
+     name is represented in the mapping from target configuration names
+     to configuration files.  If not, add it.  Also see *Note The
+     `configure.in' input file: configure.in.
+
+   * Look in `configure.in' for the variables `files', `links',
+     `host_makefile_frag', and `target_makefile_frag'.  The values
+     assigned to these variables are the names of the configuration
+     files, (relative to `srcdir') that the program uses.  Make sure
+     that copies of the files exist for your host.  If not, create
+     them.  See also *Note Variables available to `configure.in':
+     configure variables.
+
+   This should be enough to `configure' for a new host or target
+configuration name.  Getting the program to compile and run properly
+represents the hardest work of any port.
+
+
+File: configure.info,  Node: Sites,  Prev: Hosts and targets,  Up: Porting
+
+Adding site info
+================
+
+   If some of the `Makefile' defaults are not right for your site, you
+can build site-specific `Makefile' fragments.  To do this, do the
+following.
+
+   * Choose a name for your site.  It must currently be less than
+     eleven characters.
+
+   * If the program source does not have a `./config/' subdirectory,
+     create it.
+
+   * Create a file called `./config/ms-SITE' where SITE is the name of
+     your site.  In it, set whatever `Makefile' variables you need to
+     override to match your site's conventions.
+
+   * Configure the program with:
+
+          configure ... --site=SITE
+
+
+File: configure.info,  Node: Variables Index,  Next: Concept Index,  Prev: Porting,  Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* bindir:                               Install details.
+* configdirs:                           configure variables.
+* disable-FEATURE:                      Invoking configure.
+* docdir:                               Install details.
+* enable-FEATURE:                       Invoking configure.
+* exec-prefix:                          Invoking configure.
+* exec_prefix:                          exec_prefix.
+* exec_prefix:                          Install details.
+* files:                                configure variables.
+* floating_point:                       configure variables.
+* gas:                                  configure variables.
+* host:                                 configure variables.
+* host_cpu:                             configure variables.
+* host_makefile_frag:                   configure variables.
+* host_os:                              configure variables.
+* host_vendor:                          configure variables.
+* includedir:                           Install details.
+* infodir:                              Install details.
+* libdir:                               Install details.
+* links:                                configure variables.
+* Makefile:                             configure variables.
+* manNdir:                              Install details.
+* manNext:                              Install details.
+* mandir:                               Install details.
+* nfp:                                  Invoking configure.
+* norecursion:                          Invoking configure.
+* package_makefile_frag:                configure variables.
+* prefix:                               prefix.
+* prefix:                               Install details.
+* prefix:                               Invoking configure.
+* program-prefix:                       Invoking configure.
+* removing:                             configure variables.
+* rm:                                   Invoking configure.
+* site:                                 Invoking configure.
+* site_makefile_frag:                   configure variables.
+* srcdir:                               configure variables.
+* srcdir:                               What configure does.
+* srcdir:                               Invoking configure.
+* srcname:                              configure variables.
+* srctrigger:                           configure variables.
+* subdirs:                              configure variables.
+* target:                               Invoking configure.
+* target:                               configure variables.
+* target_cpu:                           configure variables.
+* target_makefile_frag:                 configure variables.
+* target_os:                            configure variables.
+* target_vendor:                        configure variables.
+* tmpdir:                               Invoking configure.
+* verbose:                              Invoking configure.
+* with-PACKAGE:                         Invoking configure.
+* without-PACKAGE:                      Invoking configure.
+
+
+File: configure.info,  Node: Concept Index,  Prev: Variables Index,  Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* -disable-FEATURE:                     Invoking configure.
+* -enable-FEATURE:                      Invoking configure.
+* -exec-prefix:                         Invoking configure.
+* -help:                                Invoking configure.
+* -nfp:                                 Invoking configure.
+* -norecursion:                         Invoking configure.
+* -prefix:                              Invoking configure.
+* -program-prefix:                      Invoking configure.
+* -rm:                                  Invoking configure.
+* -site:                                Invoking configure.
+* -srcdir:                              Invoking configure.
+* -target:                              Invoking configure.
+* -tmpdir:                              Invoking configure.
+* -verbose:                             Invoking configure.
+* -version:                             Invoking configure.
+* -with-PACKAGE:                        Invoking configure.
+* -without-PACKAGE:                     Invoking configure.
+* -s:                                   Invoking configure.
+* -v:                                   Invoking configure.
+* .gdbinit:                             What configure does.
+* autoconf:                             Programs.
+* bindir:                               Install details.
+* config.guess:                         config.guess.
+* config.guess definition:              What configure really does.
+* config.status:                        config.status.
+* config.status:                        What configure does.
+* config.status definition:             What configure really does.
+* config.sub definition:                What configure really does.
+* config/ subdirectory:                 What configure really does.
+* configdirs:                           configure variables.
+* configure.in:                         configure.in.
+* configure.in definition:              What configure really does.
+* configure back end:                   What configure really does.
+* configure details:                    What configure really does.
+* disable-FEATURE option:               Invoking configure.
+* docdir:                               Install details.
+* enable-FEATURE option:                Invoking configure.
+* exec-prefix option:                   Invoking configure.
+* exec_prefix:                          Install details.
+* floating_point:                       configure variables.
+* help option:                          Invoking configure.
+* host:                                 configure variables.
+* includedir:                           Install details.
+* infodir:                              Install details.
+* libdir:                               Install details.
+* Makefile.in definition:               What configure really does.
+* Makefile extensions:                  Makefile extensions.
+* Makefile fragments:                   Makefile fragments.
+* Makefile generation:                  Makefile generation.
+* Makefile generation:                  What configure does.
+* manNdir:                              Install details.
+* manNext:                              Install details.
+* mandir:                               Install details.
+* nfp option:                           Invoking configure.
+* nfp option:                           configure variables.
+* norecursion option:                   Invoking configure.
+* prefix:                               Install details.
+* prefix option:                        Invoking configure.
+* prefix option:                        prefix.
+* program-prefix option:                Invoking configure.
+* rm option:                            Invoking configure.
+* rm option:                            configure variables.
+* site option:                          Invoking configure.
+* srcdir:                               configure variables.
+* srcdir:                               What configure does.
+* srcdir option:                        Invoking configure.
+* srcname:                              configure variables.
+* srctrigger:                           configure variables.
+* subdirs:                              configure variables.
+* s option:                             Invoking configure.
+* target:                               configure variables.
+* target option:                        Invoking configure.
+* tmpdir option:                        Invoking configure.
+* verbose option:                       Invoking configure.
+* v option:                             Invoking configure.
+* with-PACKAGE option:                  Invoking configure.
+* with-gnu-as option:                   configure variables.
+* without-PACKAGE option:               Invoking configure.
+* configure.in interface:               configure variables.
+* host shell-script fragment:           per-host.
+* per-host section:                     per-host.
+* per-host section:                     configure.in.
+* per-invocation section:               configure.in.
+* per-invocation section:               Declarations.
+* per-target section:                   configure.in.
+* per-target section:                   per-target.
+* post-target section:                  configure.in.
+* post-target section:                  post-target.
+* Abbreviating option names:            Invoking configure.
+* Adding configure to new programs:     Programs.
+* Adding hosts and targets:             Hosts and targets.
+* Adding local info:                    Makefile fragments.
+* Adding site info:                     Sites.
+* Adding site info:                     Makefile fragments.
+* Behind the scenes:                    What configure really does.
+* BISON:                                Makefile extensions.
+* Build directories:                    What configure does.
+* Build directories:                    Build directories.
+* Build variables:                      Build variables.
+* Building for multiple hosts:          Build directories.
+* Building for multiple targets:        Build directories.
+* Canonical "triple":                   configure variables.
+* Canonical "triple":                   configure variables.
+* Changing the install directory:       prefix.
+* clean:                                Makefile extensions.
+* clean-info:                           Makefile extensions.
+* Coding standards extensions:          Makefile extensions.
+* configure variables:                  configure variables.
+* Configuring for multiple hosts:       exec_prefix.
+* Cygnus extensions:                    Makefile extensions.
+* Cygnus Support Developer's Kit:       What configure does.
+* Cygnus Support Developer's Kit:       Build variables.
+* datadir:                              Makefile extensions.
+* Declarations section:                 Declarations.
+* Default configuration:                Makefile generation.
+* Detailed usage:                       Using configure.
+* docdir:                               Makefile extensions.
+* Example configure.in:                 Example.
+* Example session:                      Build directories.
+* Example session:                      Build directories.
+* Example session:                      exec_prefix.
+* Example session:                      Build variables.
+* Example session:                      Makefile extensions.
+* Example session:                      What configure really does.
+* Example session:                      Sites.
+* Example session:                      Invoking configure.
+* Example session:                      Invoking configure.
+* For each invocation:                  Declarations.
+* Host:                                 Host.
+* Host-specific instructions:           per-host.
+* Hosts and targets:                    Hosts and targets.
+* includedir:                           Makefile extensions.
+* info:                                 Makefile extensions.
+* infodir:                              Makefile extensions.
+* install:                              Makefile extensions.
+* Install details:                      Install details.
+* Install locations:                    Install locations.
+* install-info:                         Makefile extensions.
+* Installation subdirectories:          Install details.
+* Installing host-independent files:    exec_prefix.
+* Introduction:                         What configure does.
+* Invoking configure:                   Invoking configure.
+* Local conventions:                    Makefile fragments.
+* Makefile:                             Makefile extensions.
+* mandir:                               Makefile extensions.
+* Minimal configure.in example:         Minimal.
+* Object directories:                   Build directories.
+* Other files:                          What configure really does.
+* Overview:                             What configure does.
+* Porting with configure:               Porting.
+* Post-target shell-script fragment:    post-target.
+* Recursion:                            What configure does.
+* Sample configure.in:                  Example.
+* Sharing host-independent files:       exec_prefix.
+* Sites:                                Sites.
+* Subdirectories:                       Install details.
+* Symbolic links:                       What configure does.
+* Symbolic links:                       configure variables.
+* Symbolic links:                       configure variables.
+* Target:                               Target.
+* target shell-script fragment:         per-target.
+* Target-specific instructions:         per-target.
+* The exec_prefix directory:            exec_prefix.
+* Truncating option names:              Invoking configure.
+* Usage:                                Invoking configure.
+* Usage:                                Invoking configure.
+* Usage: detailed:                      Using configure.
+* Using configure:                      Using configure.
+* Variables:                            Build variables.
+* Verbose Output:                       Invoking configure.
+* version:                              Invoking configure.
+* version:                              Invoking configure.
+* What configure does:                  What configure does.
+* What configure really does:           What configure really does.
+* Where to install:                     Install locations.
+
+
diff --git a/gnu/usr.bin/binutils/etc/configure.man b/gnu/usr.bin/binutils/etc/configure.man
new file mode 100644
index 00000000000..0761854dc43
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.man
@@ -0,0 +1,166 @@
+.\" -*- nroff -*-
+.\" Copyright (c) 1991, 1992 Cygnus Support
+.\" written by K. Richard Pixley
+.TH configure 1 "2 February 1993" "cygnus support" "Cygnus Support"
+.de BP
+.sp
+.ti \-.2i
+\(**
+..
+
+.SH NAME
+configure \(em\& prepare source code to be built
+
+.SH SYNOPSIS
+configure HOST [--target=TARGET] [--srcdir=DIR] [--rm]
+            [--site=SITE] [--prefix=DIR] [--exec_prefix=DIR]
+            [--program_prefix=DIR] [--tmpdir=DIR]
+            [--with-PACKAGE[=YES/NO]] [--without-PACKAGE]
+            [--enable-FEATURE[=YES/NO]] [--disable-FEATURE]
+            [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
+
+.SH DESCRIPTION
+.I configure
+is a program used to prepare souce code to be built.  It does this by
+generating Makefiles and .gdbinit files, creating symlinks, recursing
+in subdirectories, and some other miscellaneous file editing.
+
+.SH OPTIONS
+.I configure
+accepts the following options:
+
+.TP
+.I \--target=TARGET
+Requests that the sources be configured to target the
+.I TARGET
+machine.  If no target is specified explicitly, the target is assumed
+to be the same as the host.
+
+.TP
+.I \--srcdir=DIR
+tells configure to find the source in 
+.I DIR.
+Object code is always built in the current directory,
+.I `.'.
+
+.TP
+.I \--rm
+asks configure to remove a configuration rather than create one.
+
+.TP
+.I \--site=SITE
+asks configure to use any site-specific Makefile fragments for
+.I SITE
+when building Makefiles.
+
+.TP
+.I \--prefix=DIR
+sets the location in which to install files to
+.I DIR.
+The default is "/usr/local".
+
+.TP
+.I \--exec_prefix=DIR
+sets the root directory for host-dependent files to
+.I DIR.
+The default location is the value of
+.I prefix.
+
+.TP
+.I \--program_prefix=DIR
+configures the source to install programs which have the same names as
+common Unix programs, such as "make", in
+.I DIR.
+Also applies to programs which might be used for cross-compilation.
+
+.TP
+.I \--tmpdir=DIR
+sets the directory in which configure creates temporary files to
+.I DIR.
+
+.TP
+.I \--with-PACKAGE[=YES/NO]
+sets a flag for the build to recognize that
+.I PACKAGE
+is explicitly present or not present.  If
+.I \=YES/NO
+is nonexistent, the default is
+.I YES.
+.I \--without-PACKAGE
+is equivalent to 
+.IR \--with-PACKAGE=no .
+
+.TP
+.I \--enable-FEATURE[=YES/NO]
+sets a flag for the build to recognize that
+.I FEATURE
+should be included or not included.  If
+.I \=YES/NO
+is nonexistent, the default is
+.I YES.
+.I \--disable-FEATURE
+is equivalent to
+.IR --enable-FEATURE=no .
+
+.TP
+.I \--norecursion
+asks that only the current directory be configured.  Normally
+.I configure
+recurs on subdirectories.
+
+.TP
+.I \-nfp
+Notifies
+.I configure
+that all of the specified hosts have
+.I no floating point
+units.
+
+.TP
+.I \-s
+used internally by configure to supress status messages on
+subdirectory recursions.  Override with
+.I \-v
+
+.TP
+.I \-v
+verbose output.  Asks that configure print status lines for each
+directory configured.  Normally, only the status lines for the current
+directory are printed.
+
+.TP
+.I \--version
+.I \-V
+prints
+.I configure
+version number.
+
+.TP
+.I \-help
+displays a brief usage summary.
+
+
+.SH FILES
+configure.in	for each directory's individual needs
+.br
+Makefile.in	Makefile template
+.br
+config.sub	for parsing configuration names
+.br
+config.guess	for guessing HOST when not specified
+.br
+config.status	non-recursively rebuilds current directory
+
+.SH FILES
+.ta \w'gmon.sum 'u
+a.out	the namelist and text space.
+.br
+gmon.out	dynamic call graph and profile.
+.br
+gmon.sum summarized dynamic call graph and profile.
+
+.SH "SEE ALSO"
+.RB "`\|" configure "\|'"
+entry in 
+.B
+info.
diff --git a/gnu/usr.bin/binutils/etc/configure.texi b/gnu/usr.bin/binutils/etc/configure.texi
new file mode 100644
index 00000000000..445777491fb
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/configure.texi
@@ -0,0 +1,1830 @@
+\input texinfo    @c -*-texinfo-*-
+@setfilename configure.info
+@settitle Cygnus configure
+
+@synindex ky cp
+
+@setchapternewpage odd
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* configure: (configure).        Cygnus configure.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@ifinfo
+This document describes the Cygnus Support version of @code{configure}.
+
+Copyright (C) 1991, 1992, 1993 Cygnus Support
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by Cygnus Support.
+@end ifinfo
+
+@c We should not distribute texinfo files with smallbook enabled.
+@c @smallbook
+@finalout
+@titlepage
+@title Cygnus configure
+@author K. Richard Pixley
+@author Cygnus Support
+@page
+@cindex copyleft
+
+@vskip 0pt plus 1filll
+Edited January, 1993, by Jeffrey Osier, Cygnus Support.
+
+Copyright @copyright{} 1991, 1992, 1993 Cygnus Support
+
+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 Cygnus Support.
+@end titlepage
+
+@c ---------------------------------------------------------------------
+@ifinfo
+@node Top
+@top Cygnus configure
+
+This file documents the configuration system used and distributed by
+Cygnus Support.
+
+@menu
+* What configure does::    What configure does
+* Invoking configure::     Invoking configure---basic usage
+* Using configure::        More than you ever wanted to know
+* Porting::                How to use configure with new programs
+* Variables Index::
+* Concept Index::
+@end menu
+@end ifinfo
+
+@c ---------------------------------------------------------------------
+@node What configure does
+@chapter What @code{configure} does
+@cindex Introduction
+@cindex Overview
+@cindex What @code{configure} does
+@kindex Cygnus Support Developer's Kit
+
+This manual documents Cygnus @code{configure}, a program which helps to
+automate much of the setup activity associated with building large suites of
+programs, such the Cygnus Support Developer's Kit.  This manual is therefore
+geared toward readers who are likely to face the problem of configuring
+software in source form before compiling and installing it.  We assume you are
+an experienced programmer or system administrator.
+@ifinfo
+For further background on this topic, see @ref{Some Basic Terms, , Apologia
+Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
+Pixley.
+@end ifinfo
+@iftex
+For further background on this topic, see @cite{On Configuring Development
+Tools} by K. Richard Pixley.
+@end iftex
+
+When @code{configure} runs, it does the following things:
+
+@table @emph
+@item @bullet{} creates build directories
+@vindex srcdir
+@cindex @code{srcdir}
+@cindex Build directories
+When you run @code{configure} with the @samp{--srcdir} option, it uses the
+current directory as the @dfn{build directory}, creating under it a directory
+tree that parallels the directory structure of the source directory.  If you
+don't specify a @samp{srcdir}, @code{configure} first assumes that the source
+code you wish to configure is in your current directory; if it finds no
+@file{configure.in} input file there, it searches in the directory
+@code{configure} itself lies in.  (For details, see @ref{Build directories, ,
+Build directories}.)
+
+@item @bullet{} generates @file{Makefile}
+@cindex @code{Makefile} generation
+A @file{Makefile} template from the source directory, usually called
+@file{Makefile.in}, is copied to an output file in the build directory which is
+most often named @file{Makefile}.  @code{configure} places definitions for a
+number of standard @file{Makefile} macros at the beginning of the output file.
+If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are
+specified on the @code{configure} command line, corresponding @file{Makefile}
+variables are set accordingly.  If host, target, or site-specific
+@file{Makefile} fragments exist, these are inserted into the output file.  (For
+details, see @ref{Makefile generation, , @code{Makefile} generation}.)
+
+@item @bullet{} generates @file{.gdbinit}
+@cindex @code{.gdbinit}
+If the source directory contains a @file{.gdbinit} file and the build directory
+is not the same as the source directory, a @file{.gdbinit} file is created in
+the build directory.  This @file{.gdbinit} file contains commands which allow
+the source directory to be read when debugging with the @sc{gnu} debugger,
+@code{gdb}.  (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.)
+
+@item @bullet{} makes symbolic links
+@cindex Symbolic links
+Most build directories require that some symbolic links with generic names are
+built pointing to specific files in the source directory.  If the system where
+@code{configure} runs cannot support symbolic links, hard links are used
+instead.  (For details, see @ref{configure.in, , The @code{configure.in} input
+file}.)
+
+@item @bullet{} generates @file{config.status}
+@cindex @code{config.status}
+@code{configure} creates a shell script named @file{config.status} in the build
+directory.  This shell script, when run from the build directory (usually from
+within a @file{Makefile}), will reconfigure the build directory (but not its
+subdirectories).  This is most often used to have a @file{Makefile} update
+itself automatically if a new source directory is available.
+
+@item @bullet{} calls itself recursively
+@cindex Recursion
+If the source directory has subdirectories that should also be configured,
+@code{configure} is called for each.  
+@end table
+
+@c ---------------------------------------------------------------------
+@node Invoking configure
+@chapter Invoking @code{configure}
+@cindex Invoking @code{configure}
+@cindex Usage
+
+Cygnus @code{configure} is a shell script which resides in a source tree.  The
+usual way to invoke @code{configure} is from the shell, as follows:
+
+@cindex Example session
+@example
+eg$ ./configure @var{hosttype}
+@end example
+
+@noindent
+This prepares the source in the current directory (@file{.}) to be
+compiled for a @var{hosttype} environment.  It assumes that you wish to
+build programs and files in the default @dfn{build directory} (also the
+current directory, @file{.}).  If you do not specify a value for
+@var{hosttype}, Cygnus @code{configure} will attempt to discover this
+information by itself (@pxref{config.guess, , Determining system
+information}).  For information on @var{hosttype} environments,
+@xref{Host, , Host}.
+
+All @sc{gnu} software is packaged with one or more @code{configure} script(s)
+(@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding
+Standards}).  By using @code{configure} you prepare the source for your
+specific environment by selecting and using @file{Makefile} fragments and
+fragments of shell scripts, which are prepared in advance and stored with the
+source.
+
+@code{configure}'s command-line options also allow you to specify other aspects
+of the source configuration:
+
+@smallexample
+  configure @var{hosttype}  [--target=@var{target}] [--srcdir=@var{dir}] [--rm]
+            [--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}]
+            [--program-prefix=@var{string}] [--tmpdir=@var{dir}]
+            [--with-@var{package}[=@var{yes/no}]] [--without-@var{package}]
+            [--enable-@var{feature}[=@var{yes/no}]] [--disable-@var{feature}]
+            [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
+@end smallexample
+
+@table @code
+@item --target=@var{target}
+@cindex @code{--target}
+@cindex @code{target} option
+@vindex target
+Requests that the sources be configured to target the @var{target} machine.  If
+no target is specified explicitly, the target is assumed to be the same as the
+host (i.e., a @dfn{native} configuration).  @xref{Host, , Host}, and
+@ref{Target, , Target}, for
+discussions of each.
+
+@item --srcdir=@var{dir}
+@cindex @code{--srcdir}
+@cindex @code{srcdir} option
+@vindex srcdir
+Direct each generated @file{Makefile} to use the sources located in directory
+@var{dir}.  Use this option whenever you wish the object code to reside in a
+different place from the source code.  The @dfn{build directory} is always
+assumed to be the directory you call @code{configure} from.  See @ref{Build
+directories, , Build directories}, for an example.  If the source directory is
+not specified, @code{configure} assumes that the source is in your current
+directory.  If @code{configure} finds no @file{configure.in} there, it searches
+in the same directory that the @code{configure} script itself lies in.
+Pathnames specified (Values for @var{dir}) can be either absolute relative to
+the @emph{build} directory.
+
+@item --rm
+@cindex @code{--rm}
+@cindex @code{rm} option
+@vindex rm
+@emph{Remove} the configuration specified by @var{hosttype} and the other
+command-line options, rather than create it.
+
+@c FIXME: check @ref
+@quotation
+@emph{Note:} We recommend that you use @samp{make distclean} rather than
+use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU
+Make}, for details on @samp{make distclean}.
+@end quotation
+
+@item --site=@var{site}
+@cindex @code{--site}
+@cindex @code{site} option
+@vindex site
+Generate the @file{Makefile} using site-specific @file{Makefile} fragments for
+@var{site}.  @xref{Makefile fragments, , Adding information about local
+conventions}.
+
+@item --prefix=@var{dir}
+@cindex @code{--prefix}
+@cindex @code{prefix} option
+@vindex prefix
+Configure the source to install programs and files under directory @var{dir}.
+
+This option sets the variable @samp{prefix}.  Each generated @file{Makefile}
+will have its @samp{prefix} variables set to this value.  (@xref{What configure
+really does, , What @code{configure} really does}.)
+
+@item --exec-prefix=@var{dir}
+@cindex @code{--exec-prefix}
+@cindex @code{exec-prefix} option
+@vindex exec-prefix
+Configure the source to install @dfn{host dependent} files in @var{dir}.
+
+This option sets the variable @samp{exec_prefix}.  Each generated
+@file{Makefile} will have its @samp{exec_prefix} variables set to this value.
+(@xref{What configure really does, , What @code{configure} really does}.)
+
+@item --program-prefix=@var{string}
+@cindex @code{--program-prefix}
+@cindex @code{program-prefix} option
+@vindex program-prefix
+Configure the source to install certain programs using @var{string} as a
+prefix.  This applies to programs which might be used for cross-compilation,
+such as the compiler and the binary utilities, and also to programs which have
+the same names as common Unix programs, such as @code{make}.
+
+This option sets the variable @samp{program_prefix}.  Each generated
+@file{Makefile} will have its @samp{program_prefix} variables set to this
+value.  (@xref{What configure really does, , What @code{configure} really
+does}.)
+
+@item --tmpdir=@var{tmpdir}
+@cindex @code{--tmpdir}
+@cindex @code{tmpdir} option
+@vindex tmpdir
+Use the directory @var{tmpdir} for @code{configure}'s temporary files.  The
+default is the value of the environment variable @w{@code{TMPDIR}}, or
+@file{/tmp} if the environment variable is not set.
+
+@item --with-@var{package}[=@var{yes/no}]
+@itemx --without-@var{package}
+@cindex @code{--with-@var{package}}
+@cindex @code{with-@var{package}} option
+@vindex with-@var{package}
+@cindex @code{--without-@var{package}}
+@cindex @code{without-@var{package}} option
+@vindex without-@var{package}
+Indicate that @var{package} is present, or not present, depending on
+@var{yes/no}.  If @var{yes/no} is nonexistent, its value is assumed to be
+@code{yes}.  @samp{--without-@var{package}} is equivalent to
+@samp{--with-@var{package}=no}.
+
+For example, if you wish to configure the program @code{gcc} for a Sun
+SPARCstation running SunOS 4.x, and you want @code{gcc} to use the
+@sc{gnu} linker @code{ld}, you can configure @code{gcc} using
+
+@cindex Example session
+@smallexample
+eg$ configure --with-gnu-ld sun4
+@end smallexample
+
+@noindent
+@xref{What configure really does, , What @code{configure} really does}, for
+details.  See the installation or release notes for your particular package for
+details on which other @var{package} options are recognized.
+@c FIXME - need to include info about --with-* in other dox!
+
+@item --enable-@var{feature}[=@var{yes/no}]
+@itemx --disable-@var{feature}
+@cindex @code{--enable-@var{feature}}
+@cindex @code{enable-@var{feature}} option
+@vindex enable-@var{feature}
+@cindex @code{--disable-@var{feature}}
+@cindex @code{disable-@var{feature}} option
+@vindex disable-@var{feature}
+Include @var{feature}, or not, depending on @var{yes/no}.  If @var{yes/no} is
+nonexistent, its value is assumed to be @code{yes}.
+@samp{--disable-@var{feature}} is equivalent to
+@samp{--enable-@var{feature}=no}.
+
+@noindent
+@xref{What configure really does, , What @code{configure} really does}, for
+details.  See the installation or release notes for your particular package for
+details on which other @var{feature} options are recognized.
+@c FIXME - need to include info about --enable-* in other dox!
+
+@item --norecursion
+@cindex @code{--norecursion}
+@cindex @code{norecursion} option
+@vindex norecursion
+Configure only this directory; ignore any subdirectories.  This is used by the
+executable shell script @file{config.status} to reconfigure only the current
+directory; it is most often used non-interactively, when @code{make} is
+invoked.  (@xref{config.status, , @code{config.status}}.)
+
+@item --nfp
+@cindex @code{--nfp}
+@cindex @code{nfp} option
+@vindex nfp
+Assume that the intended @var{hosttype} has no floating point unit.
+
+@item -s
+@cindex @code{-s}
+@cindex @code{s} option
+Suppress status output.  This option is used internally by
+@code{configure} when calling itself recursively in subdirectories.  You
+can override this option with the @code{--verbose} option.
+
+@item -v
+@itemx --verbose
+@cindex @code{-v}
+@cindex @code{--verbose}
+@cindex @code{v} option
+@cindex @code{verbose} option
+@cindex Verbose Output
+@vindex verbose
+Print status lines for each directory configured.  Normally, only the
+status lines for the initial working directory are printed.
+
+@item --version
+@itemx -V
+@cindex version
+@cindex @code{--version}
+@cindex version
+Print the @code{configure} version number.
+
+@item --help
+@cindex Usage
+@cindex @code{--help}
+@cindex @code{help} option
+Print a short summary of how to invoke @code{configure}.
+@end table
+
+@cindex Abbreviating option names
+@cindex Truncating option names
+@cartouche
+@emph{Note:} You may introduce options with a single dash, @samp{-}, rather
+than two dashes, @samp{--}.  However, you may not be able to truncate long
+option names when using a single dash.  When using two dashes, options may be
+abbreviated as long as each option can be uniquely identified.  For example,
+@smallexample
+eg$ configure --s=/u/me/src @var{hosttype}
+@end smallexample
+@noindent
+is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or
+@w{@samp{--srcdir}}.  However,
+@smallexample
+eg$ configure --src=/u/me/src @var{hosttype}
+@end smallexample
+@noindent
+is a valid abbreviation.
+@end cartouche
+
+
+@c ========================================================================
+@node Using configure
+@chapter Using @code{configure}
+@cindex Using @code{configure}
+@cindex Detailed usage
+@cindex Usage: detailed
+
+@code{configure} prepares source directories for building programs in
+them.  ``Configuring'' is the process of preparing software to compile
+correctly on a given @dfn{host}, for a given @dfn{target}.
+
+@code{configure} subsequently writes a configured @file{Makefile} from a
+pre-built template; @code{configure} uses variables that have been set in the
+configuring process to determine the values of some variables in the
+@file{Makefile}.  Because of this we will refer to both @code{configure}
+variables and @file{Makefile} variables.  This convention allows us to
+determine where the variable should be set initially, in either
+@file{configure.in} or @file{Makefile.in}.
+
+@menu
+* What configure really does:: What configure really does
+* configure.in::               The configure.in input file
+* Install locations::          Where to install things once they are built
+* Host::                       Telling configure what will source will be built
+* Target::                     Telling configure what the source will target
+* Makefile fragments::         Adding information about local conventions
+* Makefile extensions::        Extensions to the GNU coding standards
+@end menu
+
+@c ---------------------------------------------------------------------
+@node What configure really does
+@section What @code{configure} really does
+@cindex What @code{configure} really does
+@cindex Behind the scenes
+@cindex @code{configure} back end
+@cindex @code{configure} details
+
+Cygnus @code{configure} is a shell script that sets up an environment in
+which your programs will compile correctly for your machine and
+operating system, and will install in proper places.  @code{configure}
+accomplishes this task by doing the following:
+
+@itemize @bullet
+@item 
+it generates a @file{Makefile} from a custom template called
+@file{Makefile.in} in each relevant source directory;
+
+@item 
+it customizes the build process to your specifications; you set certain
+variables for @code{configure}, either on the command line or in the
+file @file{configure.in}, which subsequently sets variables in each
+generated @file{Makefile} to be used by @code{make} when actually
+building the software;
+
+@item 
+it creates @dfn{build directories}, places for your code to be compiled
+in before being installed;
+
+@item 
+it generates a @file{.gdbinit} in the build directory, if needed, to
+communicate to @code{gdb} where to find the program's source code;
+
+@item 
+it generates a shell script called @file{config.status}
+which is used most often by the @file{Makefile} to reconfigure itself;
+
+@item 
+it recurses in subdirectories, setting up entire trees so that they build
+correctly; if @code{configure} finds another @code{configure} script
+further down in a given source tree, it knows to use this script and not
+recur.
+@end itemize
+
+For the sake of safety (i.e., in order to prevent broken installations), the
+@sc{gnu} coding standards call for software to be @dfn{configured} in such a
+way that an end user trying to build a given package will be able to do so by
+affecting a finite number of variables.  All @sc{gnu} software comes with an
+executable @code{configure} shell script which sets up an environment within a
+build directory which will correctly compile your new package for your host
+(or, alternatively, whatever host you specify to @code{configure}).
+@ifinfo
+For further background on this topic, see @ref{Some Basic Terms, , Apologia
+Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
+Pixley.
+@end ifinfo
+@iftex
+For further background on this topic, see @cite{On Configuring Development
+Tools} by K. Richard Pixley.
+@end iftex
+
+Use @code{configure} to set for the build process:
+
+@itemize @bullet
+@item 
+correct values for certain variables;
+
+@item 
+which type of host you wish to configure a given package for
+(@pxref{Host, , Host});
+
+@item 
+where you want to install this package (by using @samp{prefix},
+@samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, ,
+Full descriptions of all installation directories});
+
+@item 
+optionally, which type of machine you wish to @dfn{target} this
+package's output to (@pxref{Target, , Target});
+
+@item 
+which other @sc{gnu} packages are already installed and available to
+this particular build (by using the @samp{--with-@var{package}} option;
+@pxref{Invoking configure, , Invoking @code{configure}});
+
+@item 
+where to place temporary files (by using the @samp{--tmpdir=@var{dir}}
+option; @pxref{Invoking configure, , Invoking @code{configure}});
+
+@item whether to recur in subdirectories (changeable through the
+@w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking
+@code{configure}}).
+@end itemize
+
+@code{configure} uses a few other files to complete its tasks.  These are
+discussed in detail where noted.
+
+@table @code
+@cindex Other files
+@item configure.in
+@cindex @code{configure.in} definition
+Input file for @code{configure}.  Shell script fragments reside here.
+@xref{configure.in, , The @code{configure.in} input file}.
+
+@item Makefile.in
+@cindex @code{Makefile.in} definition
+Template which @code{configure} uses to build a file called @file{Makefile} in
+the @dfn{build directory}.  @xref{Makefile generation, , @code{Makefile}
+generation}.
+
+@item config.sub
+@cindex @code{config.sub} definition
+Shell script used by @code{configure} to expand referents to the
+@var{hosttype} argument into a single specification of the form
+@w{@var{cpu-vendor-os}}.  For instance, on the command line you can
+specify
+
+@cindex Example session
+@example
+eg$ ./configure sun4
+@end example
+
+@noindent
+to configure for a Sun SPARCstation running SunOS 4.x.  @code{configure}
+consults @code{config.sub} to find that the three-part specification for this
+is
+
+@example
+sparc-sun-sunos4.1.1
+@end example
+
+@noindent
+which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun}
+(Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1},
+the SunOS 4.1.1 release.  @xref{configure variables, , Variables available to @code{configure}}.
+
+@item config.guess
+@cindex @code{config.guess} definition
+If you do not put the @var{hosttype} argument on the command line,
+@code{configure} uses the @code{config.guess} shell script to make an
+analysis of your machine (it assumes that you wish to configure your
+software for the type of machine on which you are running).  The output
+of @code{config.guess} is a three-part identifier as described above.
+
+@item config.status
+@cindex @code{config.status} definition
+The final step in configuring a directory is to create a shell script,
+@code{config.status}.  The main purpose of this file is to allow the
+@file{Makefile} for the current directory to rebuild itself, if
+necessary.  @xref{config.status, , @code{config.status}}.
+
+@item config/*
+@cindex @code{config/} subdirectory
+@code{configure} uses three types of @file{Makefile} @dfn{fragments}, which
+reside in the directory @file{@var{srcdir}/config/}.  @xref{Makefile fragments,
+, Adding information about local conventions}.
+@end table
+
+@menu
+* Build variables::         Variable-spaghetti made simple 
+* Build directories::       Build directories described well
+* Makefile generation::     To build a Makefile
+* config.guess::            Be vewwy quiet, I'm hunting system information
+* config.status::           To rebuild a Makefile
+@end menu
+
+@c ---------------------------------------------------------------------
+@node Build variables
+@subsection Build variables
+@cindex Build variables
+@cindex Cygnus Support Developer's Kit
+@cindex Variables
+
+There are several variables in the build process which you can control through
+build programs such as @code{make}.  These include machine definitions, local
+conventions, installation locations, locations for temporary files, etc.  This
+data is accessible through certain variables which are configurable in the
+build process; we refer to them as @dfn{build variables}.
+
+For lists of build variables which you can affect by using @code{configure},
+see @ref{configure variables, , Variables available to @code{configure.in}},
+and @ref{Install details, , Full descriptions of all installation directories}.
+
+Generally, build variables, which are used by the @file{Makefile} to
+determine various aspects of the build and installation processes, are
+changeable with command-line options to @code{configure}.  In most large
+suites of programs, like the Cygnus Support Developer's Kit, the
+individual programs reside in several subdirectories of a single source
+code ``tree''.  All of these subdirectories need to be configured with
+information relative to the @dfn{build directory}, which is not known
+until @code{configure} is run.  Unless specified otherwise,
+@code{configure} recursively configures every subdirectory in the source
+tree.
+
+Build variables are passed from @code{configure} directly into the
+@file{Makefile}, and use the same names (except that dashes are
+transformed into underbars; for example, when you specify the option
+@samp{--exec-prefix} on the command line, the @file{Makefile} variable
+@samp{exec_prefix} is set).  In other words, if you specify
+
+@cindex Example session
+@example
+eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype}
+@end example
+
+@noindent
+on the command line, @code{configure} sets an variable called @samp{prefix} to
+@samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same
+manner.  After this command, each @file{Makefile} generated by @code{configure}
+will contain a line that reads:
+
+@example
+prefix = /usr/gnu/local
+@end example
+
+For a list of the @file{Makefile} variables @code{configure} can change, and
+instructions on how to change them, see @ref{configure variables, , Variables
+available to @code{configure.in}}, and @ref{Invoking configure, , Invoking
+@code{configure}}.
+
+@c ---------------------------------------------------------------------
+@node Build directories
+@subsection Build directories
+@cindex Build directories
+@cindex Object directories
+@cindex Building for multiple hosts
+@cindex Building for multiple targets
+
+By default, @code{configure} builds a @file{Makefile} and symbolic links in the
+same directory as the source files.  This default works for many cases, but it
+has limitations.  For instance, using this approach, you can only build object
+code for one host at a time.
+
+We refer to each directory where @code{configure} builds a @file{Makefile} as
+a @dfn{build directory}.
+
+The build directory for any given build is always the directory from which you
+call @code{configure}, or @file{.} relative to your prompt.  The default
+@dfn{source directory}, the place @code{configure} looks to find source code,
+is also @file{.}.  For instance, if we have a directory @file{/gnu-stuff/src/}
+that is the top branch of a tree of @sc{gnu} source code we wish to configure,
+then the program we will use to configure this code is
+@file{/gnu-stuff/src/configure}, as follows.  (Assume for the sake of argument
+that our machine is a sun4.)
+
+@cindex Example session
+@smallexample
+@group
+eg$ cd /gnu-stuff/src
+eg$ ./configure sun4
+Created "Makefile" in /gnu-stuff/src
+eg$
+@end group
+@end smallexample
+
+We just configured the code in @file{/gnu-stuff/src} to run on a Sun
+SPARCstation using SunOS 4.x by creating a @file{Makefile} in
+@file{/gnu-stuff/src}.  By default, we also specified that when this code is
+built, the object code should reside in the same directory,
+@file{/gnu-stuff/src}.
+
+However, if we wanted to build this code for more than one host, we would be in
+trouble, because the new configuration would write over the old one, destroying
+it in the process.  What we can do is to make a new @dfn{build directory} and
+configure from there.  Running @code{configure} from the new directory will
+place a correct @file{Makefile} and a @file{config.status} in this new file.
+That is all @code{configure} does; we must run @code{make} to generate any
+object code.  
+
+The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the
+template file @file{/gnu-stuff/src/Makefile.in}, contains all the information
+needed to build the program.
+
+@cindex Example session
+@smallexample
+@group
+eg$ mkdir /gnu-stuff/sun4-obj
+eg$ cd /gnu-stuff/sun4-obj
+eg$ ../src/configure --srcdir=../src sun4
+Created "Makefile" in /gnu-stuff/sun4-obj
+eg$ ls
+Makefile       config.status
+eg$ make all info install install-info clean
+@var{compilation messages@dots{}}
+eg$ mkdir /gnu-stuff/solaris2
+eg$ cd /gnu-stuff/solaris2
+eg$ ../src/configure --srcdir=../src sol2
+Created "Makefile" in /gnu-stuff/solaris2
+eg$ ls
+Makefile       config.status
+eg$ make all info install install-info clean
+@var{compilation messages@dots{}}
+@end group
+@end smallexample
+
+We can repeat this for other configurations of the same software simply
+by making a new build directory and reconfiguring from inside it.  If
+you do not specify the @var{hosttype} argument, @code{configure}
+will attempt to figure out what kind of machine and operating system you
+happen to be using.  @xref{config.guess, , Determining system
+information}.  Of course, this may not always be the configuration you
+wish to build.
+
+@emph{Caution:} If you build more than one configuration for a single program,
+remember that you must also specify a different @samp{--prefix} for each
+configuration at configure-time.  Otherwise, both configurations will be
+installed in the same default location (@file{/usr/local}); the configuration
+to be installed last would overwrite previously installed configurations.
+
+@c ---------------------------------------------------------------------
+@node Makefile generation
+@subsection @code{Makefile} generation
+@cindex @code{Makefile} generation
+
+Cygnus @code{configure} creates a file called @file{Makefile} in the build
+directory which can be used with @code{make} to automatically build a given
+program or package.  @code{configure} also builds a @file{Makefile} for each
+relevant subdirectory for a given program or package (irrelevant subdirectories
+would be those which contain no code which needs configuring, and which
+therefore have no @code{configure} input file @file{configure.in} and no
+@file{Makefile} template @file{Makefile.in}).  @xref{Running, @code{make}
+Invocation, How to Run @code{make}, make, GNU Make}, for details on using
+@code{make} to compile your source code.
+
+Each @file{Makefile} contains variables which have been configured for a
+specific build.  These build variables are determined when @code{configure} is
+run.  All build variables have defaults.  By default, @code{configure}
+generates a @file{Makefile} which specifies: 
+
+@cindex Default configuration
+@itemize @bullet
+@item a @dfn{native} build, which is to occur 
+
+@item in the current directory, and which will be installed 
+
+@item in the default installation directory (@file{/usr/local}) when the code
+is compiled with @code{make}.  
+@end itemize
+
+@noindent
+Variables are changeable through command-line options to @code{configure}
+(@pxref{Invoking configure, , Invoking @code{configure}}).
+
+If you are porting a new program and intend to use @code{configure}, see
+@ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, ,
+Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions,
+standards, GNU Coding Standards}.
+
+@c ---------------------------------------------------------------------
+@node config.guess
+@subsection Determining system information
+@cindex @code{config.guess}
+
+The shell script @code{config.guess} is called when you do not specify a
+@var{hosttype} on the command line to @code{configure}.  @code{config.guess}
+acquires available system information from your local machine through the shell
+command @code{uname}.  It compares this information to a database and attempts
+to determine a usable three-part system identifier (known as a @dfn{triple}) to
+use as your @var{hosttype}.  @xref{What configure really does, , What
+@code{configure} really does}, to see how this information is used.
+
+@emph{Note:}  If you do not specify a @var{hosttype} on the command line,
+@code{configure} will attempt to configure your software to run on the machine
+you happen to be using.  This may not be the configuration you desire.
+
+@c ---------------------------------------------------------------------
+@node config.status
+@subsection @code{config.status}
+@cindex @code{config.status}
+
+The final step in configuring a directory is to create an executable shell
+script, @file{config.status}.  The main purpose of this file is to allow the
+@file{Makefile} for the current directory to rebuild itself, if necessary.  It
+is usually run from within the @file{Makefile}.  @xref{Makefile extensions, ,
+Extensions to the @sc{gnu} coding standards}.
+
+@file{config.status} also contains a record of the @code{configure} session
+which created it.  
+
+@c ---------------------------------------------------------------------
+@node configure.in
+@section The @code{configure.in} input file
+@cindex @code{configure.in}
+
+A @file{configure.in} file for Cygnus @code{configure} consists of a
+@dfn{per-invocation} section, followed by a @dfn{per-host} section, followed by
+a @dfn{per-target} section, optionally followed by a @dfn{post-target} section.
+Each section is a shell script fragment, which is executed by the
+@code{configure} shell script at an appropriate time.  Values are passed among
+@code{configure} and the shell fragments through a set of shell variables.
+When each section is being interpreted by the shell, the shell's current
+directory is the build directory, and any files created by the section (or
+referred to by the section) will be relative to the build directory.  To
+reference files in other places (such as the source directory), prepend a shell
+variable such as @samp{$(srcdir)/} to the desired file name.
+
+@cindex @i{per-invocation} section
+The beginning of the @file{configure.in} file begins the @dfn{per-invocation}
+section.
+
+@cindex @i{per-host} section
+A line beginning with @samp{# per-host:} begins the @dfn{per-host} section.
+
+@cindex @i{per-target} section
+A line beginning with @samp{# per-target:} begins the @dfn{per-target} section.
+
+@cindex @i{post-target} section
+If it exists, the @dfn{post-target} section begins with @samp{# post-target:}.
+
+@menu
+* configure variables::    Variables available to configure.in
+* Minimal::                A minimal configure.in
+* Declarations::           For each invocation
+* per-host::               Host-specific instructions
+* per-target::             Target-specific instructions
+* post-target::            Instructions to be executed after target info
+* Example::                An example configure.in
+@end menu
+
+@c ---------------------------------------------------------------------
+@node configure variables
+@subsection Variables available to @code{configure.in}
+@cindex @file{configure.in} interface
+@cindex configure variables
+
+The following variables pass information between the standard parts of
+@code{configure} and the shell-script fragments in @file{configure.in}:
+
+@table @code
+@item srctrigger
+@cindex @code{srctrigger}
+@vindex srctrigger
+Contains the name of a source file that is expected to live in the source
+directory.  You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.  @code{configure} tests to see that this file exists.  If
+the file does not exist, @code{configure} prints an error message.  This is
+used as a sanity check that @file{configure.in} matches the source directory.
+
+@item srcname
+@cindex @code{srcname}
+@vindex srcname
+Contains the name of the source collection contained in the source directory.
+You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.  If the file named in @samp{srctrigger} does not exist,
+@code{configure} uses the value of @samp{srcname} when it prints the error
+message.
+
+@item configdirs
+@cindex @code{configdirs}
+@vindex configdirs
+Contains the names of any subdirectories in which @code{configure} should
+recurse.  You must usually set this in the @dfn{per-invocation} section of
+@file{configure.in}.
+If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =},
+then it will be replaced with an assignment to @samp{SUBDIRS} using
+the value of @samp{configdirs} (if @samp{subdirs} is empty).  This can
+be used to determine which directories to configure and build depending
+on the host and target configurations.
+@c Most other matching makefile/config vars use the same name.  Why not
+@c this? (FIXME).
+@c Can we get rid of SUBDIRS-substitution?  It doesn't work well with subdirs.
+Use @samp{configdirs} (instead of the @samp{subdirs} variable
+described below) if you want to be able to partition the
+subdirectories, or use independent @file{Makefile} fragments.
+Each subdirectory can be independent, and independently reconfigured.
+
+@item subdirs
+@cindex @code{subdirs}
+@vindex subdirs
+Contains the names of any subdirectories where @code{configure} should create a
+@file{Makefile} (in addition to the current directory), @emph{without}
+recursively running @code{configure}.  Use @samp{subdirs} (instead of the
+@samp{configdirs} variable described above) if you want to configure all of the
+directories as a unit.  Since there is a single invocation of @code{configure}
+that configures many directories, all the directories can use the same
+@file{Makefile} fragments, and the same @code{configure.in}.
+
+@item host
+@cindex @code{host}
+@cindex Canonical ``triple''
+@vindex host
+Contains the full configuration name for the host (generated by the script
+@file{config.sub} from the name that you entered).  This is a three-part
+name (commonly referred to as a @dfn{triple}) of the form
+@var{cpu}-@var{vendor}-@var{os}.
+
+There are separate variables @samp{host_cpu}, @samp{host_vendor}, and
+@samp{host_os} that you can use to test each of the three parts; this variable
+is useful, however, for error messages, and for testing combinations of the
+three components.
+
+@item host_cpu
+@vindex host_cpu
+Contains the first element of the canonical triple representing the host
+as returned by @file{config.sub}.  This is occasionally used to
+distinguish between minor variations of a particular vendor's operating
+system and sometimes to determine variations in binary format between
+the host and the target.
+
+@item host_vendor
+@vindex host_vendor
+Contains the second element of the canonical triple representing the host as
+returned by @file{config.sub}.  This is usually used to distinguish among the
+numerous variations of @emph{common} operating systems.
+@c "@emph{common} OS" doesn't convey much to me.  Is this meant to cover 
+@c cases like Unix, widespread but with many variations?
+
+@item host_os
+@vindex host_os
+Contains the the third element of the canonical triple representing the
+host as returned by @file{config.sub}.
+
+@item target
+@cindex @code{target}
+@cindex Canonical ``triple''
+@vindex target
+Contains the full configuration name (generated by the script @file{config.sub}
+from the name that you entered) for the target.  Like the host, this is a
+three-part name of the form @var{cpu}-@var{vendor}-@var{os}.
+
+There are separate variables @samp{target_cpu}, @samp{target_vendor}, and
+@samp{target_os} that you can use to test each of the three parts; this
+variable is useful, however, for error messages, and for testing combinations
+of the three components.
+
+@item target_cpu
+@vindex target_cpu
+Contains the first element of the canonical triple representing the target as
+returned by @file{config.sub}.  This variable is used heavily by programs which
+are involved in building other programs, like the compiler, assembler, linker,
+etc.  Most programs will not need the @samp{target} variables at all, but this
+one could conceivably be used to build a program, for instance, that operated
+on binary data files whose byte order or alignment differ from the system where
+the program is running.
+
+@item target_vendor
+@vindex target_vendor
+Contains the second element of the canonical triple representing the target as
+returned by @file{config.sub}.  This is usually used to distinguish among the
+numerous variations of @emph{common} operating systems or object file
+formats.  It is sometimes used to switch between different flavors of user
+interfaces.
+@c above query re "@emph{common} OS" applies here too
+
+@item target_os
+@vindex target_os
+Contains the the third element of the canonical triple representing the
+target as returned by @file{config.sub}.  This variable is used by
+development tools to distinguish between subtle variations in object
+file formats that some vendors use across operating system releases.  It
+might also be use to decide which libraries to build or what user
+interface the tool should provide.
+
+@item floating_point
+@cindex @code{floating_point}
+@cindex @code{nfp} option
+@vindex floating_point
+Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp}
+command-line option, otherwise it is empty.  This is a request to target
+machines with @dfn{no floating point} unit, even if the targets ordinarily have
+floating point units available.
+
+@item gas
+@cindex @code{with-gnu-as} option
+@vindex gas
+Set to @samp{true} if you invoked @code{configure} with the
+@w{@samp{--with-gnu-as}} command line option, otherwise it is empty.  This is a
+request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as}
+available even if it ordinarily does not.
+
+@item srcdir
+@cindex @code{srcdir}
+@vindex srcdir
+Set to the name of the directory containing the source for this program.
+This will be different from @file{.} if you have specified the
+@samp{--srcdir=@var{dir}} option.  @samp{srcdir} can indicate either an
+absolute path or a path relative to the build directory.
+
+@item package_makefile_frag
+@vindex package_makefile_frag
+If set in @file{configure.in}, this variable should be the name a file relative
+to @samp{srcdir} to be included in the resulting @file{Makefile}.  If the named
+file does not exist, @code{configure} will print a warning message.  This
+variable is not set by @code{configure}.
+
+@item host_makefile_frag
+@vindex host_makefile_frag
+If set in @file{configure.in}, this variable should be the name a file relative
+to @samp{srcdir} to be included in the resulting @file{Makefile}.  If the named
+file does not exist, @code{configure} will print a warning message.  This
+variable is not set by @code{configure}.
+
+@item target_makefile_frag
+@vindex target_makefile_frag
+If set in @file{configure.in}, this variable should be the name of a file,
+relative to @samp{srcdir}, to be included in the resulting @file{Makefile}.  If
+the named file does not exist, @code{configure} will print a warning message.
+This variable is not set by @code{configure}.
+
+@item site_makefile_frag
+@vindex site_makefile_frag
+Set to a file name representing to the default @file{Makefile} fragment for
+this host.  It may be set in @file{configure.in} to override this default.
+Normally @samp{site_makefile_frag} is empty, but will have a value if you
+specify @samp{--site=@var{site}} on the command line.
+@ignore -- this doesn't fit
+It is probably not a good idea to override this variable from
+@file{configure.in}, since that may defeat the @code{configure} user's
+intentions.
+@end ignore
+
+@item Makefile
+@vindex Makefile
+Set to the name of the generated @file{Makefile}.  Normally this value is
+precisely @file{Makefile}, but some programs may want something else.
+
+@item removing
+@cindex @code{rm} option
+@vindex removing
+Normally empty but will be set to some non-null value if you specified
+@samp{--rm} on the command line.  That is, if @samp{removing} is not empty,
+then @code{configure} is @emph{removing} a configuration rather than creating
+one.
+
+@item files
+@cindex Symbolic links
+@vindex files
+If this variable is not empty following the @dfn{per-target} section,
+then each word in its value will be the target of a symbolic link named
+in the corresponding word from the @samp{links} variable.
+
+@item links
+@cindex Symbolic links
+@vindex links
+If the @samp{files} variable is not empty following the @dfn{per-target}
+section, then @code{configure} creates symbolic links with the first word of
+@samp{links} pointing to the first word of @samp{files}, the second word of
+@samp{links} pointing to the second word of @samp{files}, and so on.
+@end table
+
+@c ---------------------------------------------------------------------
+@node Minimal
+@subsection A minimal @code{configure.in}
+@cindex Minimal @file{configure.in} example
+
+A minimal @file{configure.in} consists of four lines.
+
+@example
+srctrigger=foo.c
+srcname="source for the foo program"
+# per-host:
+# per-target:
+@end example
+
+The @samp{# per-host:} and @samp{# per-target:} lines divide the file into the
+three required sections.  The @samp{srctrigger} line names a file.
+@code{configure} checks to see that this file exists in the source directory
+before configuring.  If the @samp{srctrigger} file does not exist,
+@code{configure} uses the value of @samp{srcname} to print an error message
+about not finding the source.
+
+This particular example uses no links, and only the default host,
+target, and site-specific @file{Makefile} fragments if they exist.
+
+@c ---------------------------------------------------------------------
+@node Declarations
+@subsection For each invocation
+@cindex For each invocation
+@cindex Declarations section
+@cindex @i{per-invocation} section
+
+@code{configure} invokes the entire shell script fragment from the start of
+@file{configure.in} up to a line beginning with @w{@samp{# per-host:}}
+immediately after parsing command line arguments.  The variables
+@samp{srctrigger} and @samp{srcname} @emph{must} be set here.
+
+You might also want to set the variables @samp{configdirs} and
+@samp{package_makefile_frag} here.
+
+@c ---------------------------------------------------------------------
+@node per-host
+@subsection Host-specific instructions
+@cindex Host-specific instructions
+@cindex @i{host} shell-script fragment
+@cindex @i{per-host} section
+
+The @dfn{per-host} section of @file{configure.in} starts with the line that
+begins with @w{@samp{# per-host:}} and ends before a line beginning with
+@w{@samp{# per-target:}}.  @code{configure} invokes the commands in the
+@dfn{per-host} section when determining host-specific information.
+
+This section usually contains a big @code{case} statement using the variable
+@samp{host} to determine appropriate values for @samp{host_makefile_frag} and
+@samp{files}, although @samp{files} is not usually set here.  Usually, it is
+set at the end of the @dfn{per-target} section after determining the names of
+the target specific configuration files.
+
+@c ---------------------------------------------------------------------
+@node per-target
+@subsection Target-specific instructions
+@cindex Target-specific instructions
+@cindex target shell-script fragment
+@cindex @i{per-target} section
+
+The @dfn{per-target} section of @file{configure.in} starts with the line that
+begins with @w{@samp{# per-target:}} and ends before the line that begins with
+@w{@samp{# post-target:}}, if there is such a line.  Otherwise the
+@dfn{per-target} section extends to the end of the file.  @code{configure}
+invokes the commands in the @dfn{per-target} section when determining
+target-specific information, and before building any files, directories, or
+links.
+
+This section usually contains a big @code{case} statement using the variable
+@samp{target} to determine appropriate values for @samp{target_makefile_frag}
+and @samp{files}.  The last lines in the @dfn{per-target} section normally set
+the variables @samp{files} and @samp{links}.
+
+@c ---------------------------------------------------------------------
+@node post-target
+@subsection Instructions to be executed after target info
+@cindex Post-target shell-script fragment
+@cindex @i{post-target} section
+
+The @dfn{post-target} section is optional.  If it exists, the
+@samp{post-target} section starts with a line beginning with @w{@samp{#
+Post-target:}} and extends to the end of the file.  If it exists,
+@code{configure} invokes this section once for each target after
+building all files, directories, or links.
+
+This section is seldom needed, but you can use it to edit the @file{Makefile}
+generated by @code{configure}.
+
+@c ---------------------------------------------------------------------
+@node Example
+@subsection An example @code{configure.in}
+@cindex Example @file{configure.in}
+@cindex Sample @file{configure.in}
+@c @cindex @code{bison} @file{configure.in}
+@c this won't be the bison configure.in for long.. need better example
+
+Here is a small example of a @file{configure.in} file.
+
+@cartouche
+@example
+@group
+# This file is a collection of shell script fragments
+# used to tailor a template configure script as
+# appropriate for this directory.  For more information,
+# see configure.texi.
+
+configdirs=
+srctrigger=warshall.c
+srcname="bison"
+
+# per-host:
+case "$@{host@}" in
+m88k-motorola-*)
+        host_makefile_frag=config/mh-delta88
+        ;;
+esac
+
+# per-target:
+files="bison_in.hairy"
+links="bison.hairy"
+
+# post-target:
+@end group
+@end example
+@end cartouche
+
+@c ---------------------------------------------------------------------
+@node Install locations
+@section Install locations
+@cindex Where to install
+@cindex Install locations
+
+Using the default configuration, @samp{make install} creates a single tree of
+files, some of which are programs.  The location of this tree is determined by
+the value of the variable @samp{prefix}.  The default value of @samp{prefix} is
+@samp{/usr/local}.  This is often correct for native tools installed on only
+one host.
+
+@menu
+* prefix::            Changing the default install directory
+* exec_prefix::       How to separate host independent files
+                                         from host dependent files when
+                                         installing for multiple hosts
+* Install details::   Full descriptions of all installation subdirectories
+@end menu
+
+@c ---------------------------------------------------------------------
+@node prefix
+@subsection Changing the default install directory
+@cindex Changing the install directory
+@cindex @code{prefix} option
+@vindex prefix
+
+In the default configuration, all files are installed in subdirectories
+of @file{/usr/local}.  The location is determined by the value of
+the @code{configure} variable @samp{prefix}; in turn, this determines the
+value of the @file{Makefile} variable of the same name (@samp{prefix}).
+
+You can also set the value of the @file{Makefile} variable @samp{prefix}
+explicitly each time you invoke @code{make} if you are so inclined.  However,
+because many programs have this location compiled in, you must specify the
+@samp{prefix} value consistently on each invocation of @code{make}, or you will
+end up with a broken installation.
+
+To make this easier, the value of the @code{configure} variable
+@samp{prefix} can be set on the command line to @code{configure}
+using the option @samp{--prefix=}.  
+
+@c ---------------------------------------------------------------------
+@node exec_prefix
+@subsection Installing for multiple hosts
+@cindex Configuring for multiple hosts
+@cindex Sharing host-independent files
+@cindex Installing host-independent files
+@cindex The @code{exec_prefix} directory
+@vindex exec_prefix
+
+By default, host dependent files are installed in subdirectories of
+@file{$(exec_prefix)}.  The location is determined by the value of the
+@code{configure} variable @samp{exec_prefix}, which determines the value of the
+@file{Makefile} variable @samp{exec_prefix}.  This makes it easier to install
+for a single host, and simplifies changing the default location for the install
+tree.  The default doesn't allow for multiple hosts to effectively share
+host independent files, however.
+
+To configure so that multiple hosts can share common files, use something like:
+
+@cindex Example session
+@smallexample
+configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
+make all info install install-info clean
+
+configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
+make all info install install-info
+@end smallexample
+
+The first line configures the source for @var{host1} to place host-specific
+programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
+
+The second line builds and installs all programs for @var{host1},
+including both host-independent and host-specific files, as well as removing
+the host-specific object files from of the build directory.
+
+The third line reconfigures the source for @var{host2} to place host
+specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
+
+The fourth line builds and installs all programs for @var{host2}.  Host
+specific files are installed in new directories, but the host
+independent files are installed @emph{on top of} the host
+independent files installed for @var{host1}.  This results in a single
+copy of the host independent files, suitable for use by both hosts.
+
+@xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for
+more information.
+
+@c ---------------------------------------------------------------------
+@node Install details
+@subsection Full descriptions of all installation subdirectories
+@cindex Install details
+@cindex Installation subdirectories
+@cindex Subdirectories
+
+During any install, a number of standard directories are created.  Their names
+are determined by @file{Makefile} variables.  Some of the defaults for
+@file{Makefile} variables can be changed at configuration time using command
+line options to @code{configure}.  For more information on the standard
+directories or the @file{Makefile} variables, please refer to @ref{Makefiles, ,
+Makefile Conventions, standards, GNU Coding Standards}.  See also @ref{Makefile
+extensions, , Extensions to the @sc{gnu} coding standards}.
+
+Note that @code{configure} does not create the directory indicated by the
+variable @samp{srcdir} at any time.  @code{$(srcdir)} is not an installation
+directory.
+
+You can override all @file{Makefile} variables on the command line to
+@code{make}.  (@xref{Overriding, , Overriding Variables, make, GNU Make}.)  If
+you do so, you will need to specify the value precisely the same way for each
+invocation of @code{make}, or you risk ending up with a broken installation.
+This is because many programs have the locations of other programs or files
+compiled into them.  If you find yourself overriding any of the variables
+frequently, you should consider site dependent @file{Makefile} fragments.  See
+also @ref{Sites, , Adding site info}.
+
+During @samp{make install}, a number of standard directories are created and
+populated.  The following @file{Makefile} variables define them.  Those whose
+defaults are set by corresponding @code{configure} variables are marked
+``@code{Makefile} and @code{configure}''.
+
+@table @code
+@item prefix (@code{Makefile} and @code{configure})
+@cindex @code{prefix}
+@vindex prefix
+The root of the installation tree.  You can set its @file{Makefile} default
+with the @samp{--prefix=} command line option to @code{configure}
+(@pxref{Invoking configure, , Invoking @code{configure}}).  The default value
+for @samp{prefix} is @samp{/usr/local}.
+
+@item bindir
+@cindex @code{bindir}
+@vindex bindir
+A directory for binary programs that users can run.  The default value for
+@samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only
+indirectly through @samp{prefix}.  The default value for @samp{bindir} is
+@samp{$(prefix)/bin}.
+
+@item exec_prefix (@code{Makefile} and @code{configure})
+@cindex @code{exec_prefix}
+@vindex exec_prefix
+A directory for host dependent files.  You can specify the @file{Makefile}
+default value by using the @samp{--exec_prefix=} option to @code{configure}.
+(@xref{Invoking configure, , Invoking @code{configure}}.)  The default value
+for @samp{exec_prefix} is @samp{$(prefix)}.
+
+@item libdir
+@cindex @code{libdir}
+@vindex libdir
+A directory for libraries and support programs.  The default value for
+@samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only
+indirectly through @samp{prefix}.  The default value for @samp{libdir} is
+@samp{$(prefix)/lib}.
+
+@item mandir
+@cindex @code{mandir}
+@vindex mandir
+A directory for @code{man} format documentation (``man pages'').  The default
+value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally
+changed only indirectly through @samp{prefix}.  The default value for
+@samp{mandir} is @samp{$(prefix)/man}.
+
+@item man@var{N}dir
+@cindex @code{man@var{N}dir}
+@vindex man@var{N}dir
+These are eight variables named @samp{man1dir}, @samp{man2dir}, etc.  They name
+the specific directories for each man page section.  For example,
+@samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this
+directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs).
+Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating
+the directory which holds @file{rcsfile.5} (the man page describing the
+@code{rcs} data file format).  The default value for any of the
+@samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is
+normally changed only through @samp{prefix}.  The default value for
+@samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}.
+
+@item man@var{N}ext
+@cindex @code{man@var{N}ext}
+@vindex man@var{N}ext
+@emph{Not supported by Cygnus @code{configure}}.  The @cite{@sc{gnu} Coding
+Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use
+for @code{manext} is apparently not parallel to @samp{mandir}.  Its use is not
+clear.  (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding
+standards}.)
+
+@item infodir
+@cindex @code{infodir}
+@vindex infodir
+A directory for @code{info} format documentation.  The default value for
+@samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is
+normally changed only through @samp{prefix}.  The default value for
+@samp{infodir} is @samp{$(prefix)/info}.
+
+@item docdir
+@cindex @code{docdir}
+@vindex docdir
+A directory for any documentation that is in a format other than those used by
+@code{info} or @code{man}.  The default value for @samp{docdir} depends
+indirectly on @samp{prefix}; @samp{docdir} is normally changed only through
+@samp{prefix}.  The default value for @samp{docdir} is @samp{$(datadir)/doc}.
+@emph{This variable is an extension to the @sc{gnu} coding standards}.  (See
+also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.)
+
+@item includedir
+@cindex @code{includedir}
+@vindex includedir
+A directory for the header files accompanying the libraries installed in
+@samp{libdir}.  The default value for @samp{includedir} depends on
+@samp{prefix}; @samp{includedir} is normally changed only indirectly
+through @samp{prefix}.  The default value for @samp{includedir} is
+@samp{$(prefix)/include}.
+@end table
+
+@c ---------------------------------------------------------------------
+@node Host
+@section Host
+@cindex Host
+
+The arguments to @code{configure} are @dfn{hosttypes}.  By
+@dfn{hosttype} we mean the @dfn{environment} in which the source will be
+compiled.  This need not necessarily be the same as the physical machine
+involved, although it usually is.
+
+For example, if some obscure machine had the @sc{gnu} @code{POSIX} emulation
+libraries available, it would be possible to configure most @sc{gnu} source for
+a @code{POSIX} system and build it on the obscure host.
+
+For more on this topic, see @ref{Host Environments, On Configuring Development
+Tools, Host Environments, cfg-paper, On Configuring Development Tools}.
+
+@c ---------------------------------------------------------------------
+@node Target
+@section Target
+@cindex Target
+
+For building native development tools, or most of the other @sc{gnu}
+tools, you need not worry about the target.  The @dfn{target} of a
+configuration defaults to the same as the @dfn{host}.
+
+For building cross development tools, please see @ref{Building Development
+Environments, On Configuring Development Tools, Building Development
+Environments, cfg-paper, On Configuring Development Tools}.
+
+@c ---------------------------------------------------------------------
+@node Makefile fragments
+@section Adding information about local conventions
+@cindex @code{Makefile} fragments
+@cindex Local conventions
+@cindex Adding local info
+@cindex Adding site info
+
+If you find that a tool does not get configured to your liking, or if
+@code{configure}'s conventions differ from your local conventions, you should
+probably consider @dfn{site-specific @file{Makefile} fragments}.  See also
+@ref{Sites, , Adding site info}.
+
+These are probably not the right choice for options that can be set from
+the @code{configure} command line or for differences that are host or
+target dependent.
+
+Cygnus @code{configure} uses three types of @file{Makefile} fragments.  In a
+generated @file{Makefile} they appear in the order: @dfn{target fragment},
+@dfn{host fragment}, and @dfn{site fragment}.  This allows host fragments to
+override target fragments, and site fragments to override both.
+
+Host-specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}.
+They are used for hosts that require odd options to the standard compiler and
+for compile time options based on the host configuration.
+
+Target-specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{mt-@var{target}}.
+They are used for target dependent compile time options.
+
+Site specific @file{Makefile} fragments conventionally reside in the
+@file{./config/} subdirectory with names of the form @file{ms-@var{site}}.
+They are used to override host- and target-independent compile time options.
+Note that you can also override these options on the @code{make} invocation
+line.
+
+@c ---------------------------------------------------------------------
+@node Makefile extensions
+@section Extensions to the @sc{gnu} coding standards
+@cindex @code{Makefile} extensions
+@cindex Cygnus extensions
+@cindex Coding standards extensions
+
+The following additions to the @sc{gnu} coding standards are required for
+Cygnus @code{configure} to work properly.
+
+@itemize @bullet
+@item
+The @file{Makefile} must contain exactly one line starting with @samp{####}.
+This line should follow any default macro definitions but precede any rules.
+Host, target, and site-specific @file{Makefile} fragments will be inserted
+immediately after this line.  If the line is missing, the fragments will not be
+inserted.
+
+@item
+Cygnus adds the following targets to each @file{Makefile}.  Their existence is
+not required for Cygnus @code{configure}, but they are documented here for
+completeness.
+
+@table @code
+@kindex info
+@item info
+Build all info files from texinfo source.
+
+@kindex install-info
+@item install-info
+Install all info files.
+
+@kindex clean-info
+@item clean-info
+Remove all info files and any intermediate files that can be generated
+from texinfo source.
+
+@kindex Makefile
+@item Makefile
+Calls @code{./config.status} to rebuild the @file{Makefile} in this directory.
+@end table
+
+@item
+The following @file{Makefile} targets have revised semantics:
+
+@table @code
+@kindex install
+@item install
+Should @emph{not} depend on the target @samp{all}.  If the program is not
+already built, @samp{make install} should fail.  This allows you to install
+programs even when @code{make} would otherwise determine them to be out of
+date.  This can happen, for example, when the result of a @samp{make all} is
+transported via tape to another machine for installation.
+
+@kindex clean
+@item clean
+Should remove any file that can be regenerated by the @file{Makefile},
+excepting only the @file{Makefile} itself, and any links created by
+@code{configure}.  That is, @code{make all clean} should return all directories
+to their original condition.  If this is not done, then the command sequence
+
+@cindex Example session
+@example
+configure @var{host1} ; make all install clean ; 
+configure @var{host2} ; make all install
+@end example
+
+@noindent
+will fail because of intermediate files intended for @var{host1}.
+@end table
+
+@item
+Cygnus adds the following macros to all @file{Makefile.in} files, but
+you are not required to use them to run Cygnus @code{configure}.
+
+@table @code
+@kindex docdir
+@item docdir
+The directory in which to install any documentation that is not either a
+@code{man} page or an @code{info} file.  For @code{man} pages, see
+@samp{mandir}; for @code{info}, see @samp{infodir}.
+
+@kindex includedir
+@item includedir
+The directory in which to install any header files that should be made
+available to users.  This is distinct from the @code{gcc} include directory,
+which is intended for @code{gcc} only.  Files in @samp{includedir} may be used
+by @code{cc} as well.
+@end table
+
+@item
+The following macros have revised semantics.  Most of them describe
+installation directories; see also @ref{Install details, , Full description of
+all installation subdirectories}.
+
+@table @code
+@kindex datadir
+@item datadir
+is used for host independent data files.
+
+@kindex mandir
+@item mandir
+The default path for @samp{mandir} depends on @samp{prefix}.
+
+@kindex infodir
+@item infodir
+The default path for @samp{infodir} depends on @samp{prefix}.
+
+@kindex BISON
+@item BISON
+is assumed to have a @code{yacc} calling convention.  To use @sc{gnu}
+@code{bison}, use @samp{BISON=bison -y}.
+@end table
+
+@item
+Each Cygnus @file{Makefile} also conforms to one additional restriction:
+
+When libraries are installed, the line containing the call to
+@samp{INSTALL_DATA} should always be followed by a line containing a call to
+@samp{RANLIB} on the installed library.  This is to accommodate systems that
+use @code{ranlib}.  Systems that do not use @code{ranlib} can set @samp{RANLIB}
+to ``@code{echo}'' in a host specific @file{Makefile} fragment.
+@end itemize
+
+@c ========================================================================
+@node Porting
+@chapter Porting with @code{configure}
+@cindex Porting with @code{configure}
+
+This section explains how to add programs, host and target configuration
+names, and site-specific information to Cygnus @code{configure}.
+
+@menu
+* Programs::               Adding configure to new programs
+* Hosts and targets::      Adding hosts and targets
+* Sites::                  Adding site info
+@end menu
+
+@c ---------------------------------------------------------------------
+@node Programs
+@section Adding @code{configure} to new programs
+@cindex Adding @code{configure} to new programs
+
+If you are writing a new program, you probably shouldn't worry about porting or
+configuration issues until it is running reasonably on some host.  Then refer
+back to this section.
+
+If your program currently has a @code{configure} script that meets the @sc{gnu}
+standards (@pxref{Configuration, , How Configuration Should Work, standards,
+GNU Coding Standards}, please do not add Cygnus @code{configure}.  It should be
+possible to add this program without change to a Cygnus @code{configure} style
+source tree.
+
+@cindex @code{autoconf}
+If the program is not target dependent, please consider using @code{autoconf}
+instead of Cygnus @code{configure}.  @code{autoconf} is available from the Free
+Software Foundation; it is a program which generates an executable shell script
+called @file{configure} by automatically finding information on the system to
+be configured on and embedding this information in the shell script.
+@file{configure} scripts generated by @code{autoconf} require no arguments, and
+accept the same options as Cygnus @code{configure}.  For detailed instructions
+on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize
+and produce Autoconf scripts, autoconf, Autoconf}.
+
+
+To add Cygnus @code{configure} to an existing program, do the following:
+
+@table @bullet
+@item Make sure the @file{Makefile} conforms to the @sc{gnu} standard
+The coding standard for writing a @sc{gnu} @file{Makefile} is described in
+@ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}.  For
+technical information on writing a @file{Makefile}, see @ref{Makefiles, ,
+Writing Makefiles, make, GNU Make}.
+
+@item Add Cygnus extensions to the @file{Makefile}
+These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu}
+coding standards}.
+
+@item Collect package specific definitions in a single file
+Many packages are best configured using a common @file{Makefile} fragment which
+is included by all of the makefiles in the different directories of the
+package.  In order to accomplish this, set the variable
+@samp{package_makefile_fragment} to the name of the file.  It will be inserted
+into the final @file{Makefile} before the target-specific fragment.
+
+@item Move host support from @file{Makefile} to fragments
+This usually involves finding sections of the @file{Makefile} that say things
+like ``uncomment these lines for host @var{hosttype}'' and moving them to a new
+file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts
+and targets, , Adding hosts and targets}.
+
+@item Choose defaults
+If the program has compile-time options that determine the way the program
+should behave, choose reasonable defaults and make these @file{Makefile}
+variables.  Be sure the variables are assigned their default values before the
+@samp{####} line so that site-specific @file{Makefile} fragments can override
+them (@pxref{Makefile extensions, , Extensions to the @sc{gnu} coding
+standards}).
+
+@item Locate configuration files
+If there is configuration information in header files or source files, separate
+it in such a way that the files have generic names.  Then move the specific
+instances of those files into the @file{./config/} subdirectory.
+
+@item Separate host and target information
+Some programs already have this information separated.  If yours does not, you
+will need to separate these two kinds of configuration information.  @dfn{Host
+specific} information is the information needed to compile the program.
+@dfn{Target specific} information is information on the format of data files
+that the program will read or write.  This information should live in separate
+files in the @file{./config/} subdirectory with names that reflect the
+configuration for which they are intended.
+
+At this point you might skip this step and simply move on.  If you do, you
+should end up with a program that can be configured only to build @dfn{native}
+tools, that is, tools for which the host system is also the target system.
+Later, you could attempt to build a cross tool and separate out the
+target-specific information by figuring out what went wrong.  This is often
+simpler than combing through all of the source code.
+
+@item Write @code{configure.in}
+Usually this involves writing shell script fragments to map from canonical
+configuration names into the names of the configuration files.  These files
+will then be linked at configure time from the specific instances of those
+files in @file{./config} to files in the build directory with more generic
+names.  (See also @ref{Build directories, , Build directories}.)  The format of
+@file{configure.in} is described in @ref{configure.in, , The
+@code{configure.in} input file}.
+
+@item Rename @file{Makefile} to @file{Makefile.in}
+@end table
+
+At this point you should have a program that can be configured using
+Cygnus @code{configure}.
+
+@c ---------------------------------------------------------------------
+@node Hosts and targets
+@section Adding hosts and targets
+@cindex Adding hosts and targets
+@cindex Hosts and targets
+
+To add a host or target to a program that already uses Cygnus @code{configure},
+do the following.
+
+@itemize @bullet
+
+@item
+Make sure the new configuration name is represented in @file{config.sub}.  If
+not, add it.  For more details, see the comments in the shell script
+@file{config.sub}.
+
+@item
+If you are adding a host configuration, look in @file{configure.in}, in the
+@dfn{per-host} section.  Make sure that your configuration name is represented
+in the mapping from host configuration names to configuration files.  If not,
+add it.  Also see @ref{configure.in, , The @code{configure.in} input file}.
+
+@item
+If you are adding a target configuration, look in @file{configure.in}, in the
+@dfn{per-target} section.  Make sure that your configuration name is
+represented in the mapping from target configuration names to configuration
+files.  If not, add it.  Also see @ref{configure.in, , The @code{configure.in}
+input file}.
+
+@item
+Look in @file{configure.in} for the variables @samp{files}, @samp{links},
+@samp{host_makefile_frag}, and @samp{target_makefile_frag}.  The values
+assigned to these variables are the names of the configuration files, (relative
+to @samp{srcdir}) that the program uses.  Make sure that copies of the files
+exist for your host.  If not, create them.  See also @ref{configure variables,
+, Variables available to @code{configure.in}}.
+@end itemize
+
+This should be enough to @code{configure} for a new host or target
+configuration name.  Getting the program to compile and run properly represents
+the hardest work of any port.
+
+@c ---------------------------------------------------------------------
+@node Sites
+@section Adding site info
+@cindex Sites
+@cindex Adding site info
+
+If some of the @file{Makefile} defaults are not right for your site, you can
+build site-specific @file{Makefile} fragments.  To do this, do the following.
+
+@itemize @bullet
+
+@item
+Choose a name for your site.  It must currently be less than eleven characters.
+
+@item
+If the program source does not have a @file{./config/} subdirectory, create it.
+
+@item
+Create a file called @file{./config/ms-@var{site}} where @var{site} is the name
+of your site.  In it, set whatever @file{Makefile} variables you need to
+override to match your site's conventions.
+
+@item
+Configure the program with:
+
+@cindex Example session
+@example
+configure @dots{} --site=@var{site}
+@end example
+
+@end itemize
+
+@c ---------------------------------------------------------------------
+@node Variables Index
+@unnumbered Variable Index
+
+@printindex vr
+
+@page
+@c ---------------------------------------------------------------------
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+@contents
+@bye
+
+@c Local Variables:
+@c fill-column: 79
+@c outline-regexp: "@chap"
+@c End:
+@c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")
+
diff --git a/gnu/usr.bin/binutils/etc/make-stds.texi b/gnu/usr.bin/binutils/etc/make-stds.texi
new file mode 100644
index 00000000000..4b4ff7ef953
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/make-stds.texi
@@ -0,0 +1,528 @@
+@comment This file is included by both standards.texi and make.texinfo.
+@comment It was broken out of standards.texi on 1/6/93 by roland.
+
+@node Makefile Conventions
+@chapter Makefile Conventions
+@comment standards.texi does not print an index, but make.texinfo does.
+@cindex makefile, conventions for
+@cindex conventions for makefiles
+@cindex standards for makefiles
+
+This chapter describes conventions for writing the Makefiles for GNU programs.
+
+@menu
+* Makefile Basics::
+* Utilities in Makefiles::
+* Standard Targets::
+* Command Variables::
+* Directory Variables::
+@end menu
+
+@node Makefile Basics
+@section General Conventions for Makefiles
+
+Every Makefile should contain this line:
+
+@example
+SHELL = /bin/sh
+@end example
+
+@noindent
+to avoid trouble on systems where the @code{SHELL} variable might be
+inherited from the environment.  (This is never a problem with GNU
+@code{make}.)
+
+Don't assume that @file{.} is in the path for command execution.  When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses @file{./} if the program is built as
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code.  Without one of these prefixes, the current search
+path is used.  
+
+The distinction between @file{./} and @file{$(srcdir)/} is important
+when using the @samp{--srcdir} option to @file{configure}.  A rule of
+the form:
+
+@smallexample
+foo.1 : foo.man sedscript
+        sed -e sedscript foo.man > foo.1
+@end smallexample
+
+@noindent
+will fail when the current directory is not the source directory,
+because @file{foo.man} and @file{sedscript} are not in the current
+directory.
+
+When using GNU @code{make}, relying on @samp{VPATH} to find the source
+file will work in the case where there is a single dependency file,
+since the @file{make} automatic variable @samp{$<} will represent the
+source file wherever it is.  (Many versions of @code{make} set @samp{$<}
+only in implicit rules.)  A makefile target like
+
+@smallexample
+foo.o : bar.c
+        $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+@end smallexample
+
+@noindent
+should instead be written as
+
+@smallexample
+foo.o : bar.c
+        $(CC) $(CFLAGS) $< -o $@@
+@end smallexample
+
+@noindent
+in order to allow @samp{VPATH} to work correctly.  When the target has
+multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
+way to make the rule work well.  For example, the target above for
+@file{foo.1} is best written as:
+
+@smallexample
+foo.1 : foo.man sedscript
+        sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
+@end smallexample
+
+@node Utilities in Makefiles
+@section Utilities in Makefiles
+
+Write the Makefile commands (and any shell scripts, such as
+@code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
+special features of @code{ksh} or @code{bash}.
+
+The @code{configure} script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+@example
+cat cmp cp echo egrep expr grep
+ln mkdir mv pwd rm rmdir sed test touch
+@end example
+
+Stick to the generally supported options for these programs.  For
+example, don't use @samp{mkdir -p}, convenient as it may be, because
+most systems don't support it.
+
+The Makefile rules for building and installation can also use compilers
+and related programs, but should do so via @code{make} variables so that the
+user can substitute alternatives.  Here are some of the programs we
+mean:
+
+@example
+ar bison cc flex install ld lex
+make makeinfo ranlib texi2dvi yacc
+@end example
+
+When you use @code{ranlib}, you should test whether it exists, and run
+it only if it exists, so that the distribution will work on systems that
+don't have @code{ranlib}.
+
+If you use symbolic links, you should implement a fallback for systems
+that don't have symbolic links.
+
+It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities to
+exist.
+
+@node Standard Targets
+@section Standard Targets for Users
+
+All GNU programs should have the following targets in their Makefiles:
+
+@table @samp
+@item all
+Compile the entire program.  This should be the default target.  This
+target need not rebuild any documentation files; Info files should
+normally be included in the distribution, and DVI files should be made
+only when explicitly asked for.
+
+@item install
+Compile the program and copy the executables, libraries, and so on to
+the file names where they should reside for actual use.  If there is a
+simple test to verify that a program is properly installed, this target
+should run that test.
+
+The commands should create all the directories in which files are to be
+installed, if they don't already exist.  This includes the directories
+specified as the values of the variables @code{prefix} and
+@code{exec_prefix}, as well as all subdirectories that are needed.
+One way to do this is by means of an @code{installdirs} target
+as described below.
+
+Use @samp{-} before any command for installing a man page, so that
+@code{make} will ignore any errors.  This is in case there are systems
+that don't have the Unix man page documentation system installed.
+
+The way to install Info files is to copy them into @file{$(infodir)}
+with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
+the @code{install-info} program if it is present.  @code{install-info}
+is a script that edits the Info @file{dir} file to add or update the
+menu entry for the given Info file; it will be part of the Texinfo package.
+Here is a sample rule to install an Info file:
+
+@comment This example has been carefully formatted for the Make manual.
+@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
+@smallexample
+$(infodir)/foo.info: foo.info
+# 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 $@@; \
+# 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 --infodir=$(infodir) $$d/foo.info; \
+        else true; fi
+@end smallexample
+
+@item uninstall
+Delete all the installed files that the @samp{install} target would
+create (but not the noninstalled files such as @samp{make all} would
+create).
+
+@comment The gratuitous blank line here is to make the table look better
+@comment in the printed Make manual.  Please leave it in.
+@item clean
+
+Delete all files from the current directory that are normally created by
+building the program.  Don't delete the files that record the
+configuration.  Also preserve files that could be made by building, but
+normally aren't because the distribution comes with them.
+
+Delete @file{.dvi} files here if they are not part of the distribution.
+
+@item distclean
+Delete all files from the current directory that are created by
+configuring or building the program.  If you have unpacked the source
+and built the program without creating any other files, @samp{make
+distclean} should leave only the files that were in the distribution.
+
+@item mostlyclean
+Like @samp{clean}, but may refrain from deleting a few files that people
+normally don't want to recompile.  For example, the @samp{mostlyclean}
+target for GCC does not delete @file{libgcc.a}, because recompiling it
+is rarely necessary and takes a lot of time.
+
+@item realclean
+Delete everything from the current directory that can be reconstructed
+with this Makefile.  This typically includes everything deleted by
+@code{distclean}, plus more: C source files produced by Bison, tags tables,
+Info files, and so on.
+
+One exception, however: @samp{make realclean} should not delete
+@file{configure} even if @file{configure} can be remade using a rule in
+the Makefile.  More generally, @samp{make realclean} should not delete
+anything that needs to exist in order to run @file{configure}
+and then begin to build the program.
+
+@item TAGS
+Update a tags table for this program.
+
+@item info
+Generate any Info files needed.  The best way to write the rules is as
+follows:
+
+@smallexample
+info: foo.info
+
+foo.info: foo.texi chap1.texi chap2.texi
+        $(MAKEINFO) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{MAKEINFO} in the Makefile.  It should
+run the @code{makeinfo} program, which is part of the Texinfo
+distribution.
+
+@item dvi
+Generate DVI files for all TeXinfo documentation.  
+For example:
+
+@smallexample
+dvi: foo.dvi
+
+foo.dvi: foo.texi chap1.texi chap2.texi
+        $(TEXI2DVI) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+You must define the variable @code{TEXI2DVI} in the Makefile.  It should
+run the program @code{texi2dvi}, which is part of the Texinfo
+distribution.  Alternatively, write just the dependencies, and allow GNU
+Make to provide the command.
+
+@item dist
+Create a distribution tar file for this program.  The tar file should be
+set up so that the file names in the tar file start with a subdirectory
+name which is the name of the package it is a distribution for.  This
+name can include the version number.
+
+For example, the distribution tar file of GCC version 1.40 unpacks into
+a subdirectory named @file{gcc-1.40}.
+
+The easiest way to do this is to create a subdirectory appropriately
+named, use @code{ln} or @code{cp} to install the proper files in it, and
+then @code{tar} that subdirectory.
+
+The @code{dist} target should explicitly depend on all non-source files
+that are in the distribution, to make sure they are up to date in the
+distribution.  
+@xref{Releases, , Making Releases, standards, GNU Coding Standards}.
+
+@item check
+Perform self-tests (if any).  The user must build the program before
+running the tests, but need not install the program; you should write
+the self-tests so that they work when the program is built but not
+installed.
+@end table
+
+The following targets are suggested as conventional names, for programs
+in which they are useful.
+
+@table @code
+@item installcheck
+Perform installation tests (if any).  The user must build and install
+the program before running the tests.  You should not assume that
+@file{$(bindir)} is in the search path.  
+
+@item installdirs
+It's useful to add a target named @samp{installdirs} to create the
+directories where files are installed, and their parent directories.
+There is a script called @file{mkinstalldirs} which is convenient for
+this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
+You can use a rule like this:
+
+@comment This has been carefully formatted to look decent in the Make manual.
+@comment Please be sure not to make it extend any further to the right.--roland
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+        $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+                                $(libdir) $(infodir) \
+                                $(mandir)
+@end smallexample
+@end table
+
+@node Command Variables
+@section Variables for Specifying Commands
+
+Makefiles should provide variables for overriding certain commands, options,
+and so on.
+
+In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named @code{BISON} whose default
+value is set with @samp{BISON = bison}, and refer to it with
+@code{$(BISON)} whenever you need to use Bison.
+
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
+Each program-name variable should come with an options variable that is
+used to supply options to the program.  Append @samp{FLAGS} to the
+program-name variable name to get the options variable name---for
+example, @code{BISONFLAGS}.  (The name @code{CFLAGS} is an exception to
+this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
+in any compilation command that runs the preprocessor, and use
+@code{LDFLAGS} in any compilation command that does linking as well as
+in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
+
+@smallexample
+CFLAGS = -g
+ALL_CFLAGS = -I. $(CFLAGS)
+.c.o:
+        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+@end smallexample
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation.  You can consider it a default
+that is only recommended.  If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
+
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
+Every Makefile should define the variable @code{INSTALL}, which is the
+basic command for installing a file into the system.
+
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}.  (The default for each of these should be
+@code{$(INSTALL)}.)  Then it should use those variables as the commands
+for actual installation, for executables and nonexecutables
+respectively.  Use these variables as follows:
+
+@example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+@end example
+
+@noindent
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+@node Directory Variables
+@section Variables for Installation Directories
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place.  The standard names for these
+variables are:
+
+@table @samp
+@item prefix
+A prefix used in constructing the default values of the variables listed
+below.  The default value of @code{prefix} should be @file{/usr/local}
+(at least for now).
+
+@item exec_prefix
+A prefix used in constructing the default values of some of the
+variables listed below.  The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+
+Generally, @code{$(exec_prefix)} is used for directories that contain
+machine-specific files (such as executables and subroutine libraries),
+while @code{$(prefix)} is used directly for other directories.
+
+@item bindir
+The directory for installing executable programs that users can run.
+This should normally be @file{/usr/local/bin}, but write it as
+@file{$(exec_prefix)/bin}.
+
+@item libdir
+The directory for installing executable files to be run by the program
+rather than by users.  Object files and libraries of object code should
+also go in this directory.  The idea is that this directory is used for
+files that pertain to a specific machine architecture, but need not be
+in the path for commands.  The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+
+@item datadir
+The directory for installing read-only data files which the programs
+refer to while they run.  This directory is used for files which are
+independent of the type of machine being used.  This should normally be
+@file{/usr/local/lib}, but write it as @file{$(prefix)/lib}.
+
+@item statedir
+The directory for installing data files which the programs modify while
+they run.  These files should be independent of the type of machine
+being used, and it should be possible to share them among machines at a
+network installation.  This should normally be @file{/usr/local/lib},
+but write it as @file{$(prefix)/lib}.
+
+@item includedir
+@c rewritten to avoid overfull hbox --roland
+The directory for installing header files to be included by user
+programs with the C @samp{#include} preprocessor directive.  This
+should normally be @file{/usr/local/include}, but write it as
+@file{$(prefix)/include}.
+
+Most compilers other than GCC do not look for header files in
+@file{/usr/local/include}.  So installing the header files this way is
+only useful with GCC.  Sometimes this is not a problem because some
+libraries are only really intended to work with GCC.  But some libraries
+are intended to work with other compilers.  They should install their
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
+
+@item oldincludedir
+The directory for installing @samp{#include} header files for use with
+compilers other than GCC.  This should normally be @file{/usr/include}.
+
+The Makefile commands should check whether the value of
+@code{oldincludedir} is empty.  If it is, they should not try to use
+it; they should cancel the second installation of the header files.
+
+A package should not replace an existing header in this directory unless
+the header came from the same package.  Thus, if your Foo package
+provides a header file @file{foo.h}, then it should install the header
+file in the @code{oldincludedir} directory if either (1) there is no
+@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
+package.
+
+To tell whether @file{foo.h} came from the Foo package, put a magic
+string in the file---part of a comment---and grep for that string.
+
+@item mandir
+The directory for installing the man pages (if any) for this package.
+It should include the suffix for the proper section of the
+manual---usually @samp{1} for a utility.  It will normally be
+@file{/usr/local/man/man1}, but you should write it as
+@file{$(prefix)/man/man1}. 
+
+@item man1dir
+The directory for installing section 1 man pages.
+@item man2dir
+The directory for installing section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{mandir} if the package needs to install man
+pages in more than one section of the manual.
+
+@strong{Don't make the primary documentation for any GNU software be a
+man page.  Write a manual in Texinfo instead.  Man pages are just for
+the sake of people running GNU software on Unix, which is a secondary
+application only.}
+
+@item manext
+The file name extension for the installed man page.  This should contain
+a period followed by the appropriate digit; it should normally be @samp{.1}.
+
+@item man1ext
+The file name extension for installed section 1 man pages.
+@item man2ext
+The file name extension for installed section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{manext} if the package needs to install man
+pages in more than one section of the manual.
+
+@item infodir
+The directory for installing the Info files for this package.  By
+default, it should be @file{/usr/local/info}, but it should be written
+as @file{$(prefix)/info}.
+
+@item srcdir
+The directory for the sources being compiled.  The value of this
+variable is normally inserted by the @code{configure} shell script.
+@end table
+
+For example:
+
+@smallexample
+@c I have changed some of the comments here slightly to fix an overfull
+@c hbox, so the make manual can format correctly. --roland
+# Common prefix for installation directories.
+# NOTE: This directory must exist when you start the install.
+prefix = /usr/local
+exec_prefix = $(prefix)
+# Where to put the executable for the command `gcc'.
+bindir = $(exec_prefix)/bin
+# Where to put the directories used by the compiler.
+libdir = $(exec_prefix)/lib
+# Where to put the Info files.
+infodir = $(prefix)/info
+@end smallexample
+
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above.  The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
diff --git a/gnu/usr.bin/binutils/etc/standards.info b/gnu/usr.bin/binutils/etc/standards.info
new file mode 100644
index 00000000000..92b0dc90c04
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/standards.info
@@ -0,0 +1,59 @@
+This is Info file standards.info, produced by Makeinfo-1.55 from the
+input file ./standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+
+   GNU Coding Standards Copyright (C) 1992, 1993, 1994 Free Software
+Foundation
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+
+Indirect:
+standards.info-1: 950
+standards.info-2: 49237
+
+Tag Table:
+(Indirect)
+Node: Top950
+Node: Reading Non-Free Code2051
+Node: Contributions3777
+Node: Change Logs5375
+Node: Compatibility9091
+Node: Makefile Conventions10730
+Node: Makefile Basics11087
+Node: Utilities in Makefiles12978
+Node: Standard Targets14414
+Node: Command Variables21523
+Node: Directory Variables24353
+Node: Configuration30825
+Node: Source Language37849
+Node: Formatting38979
+Node: Comments42269
+Node: Syntactic Conventions45055
+Node: Names47947
+Node: Using Extensions49237
+Node: System Functions50978
+Node: Semantics55781
+Node: Errors58747
+Node: Libraries59950
+Node: Portability61174
+Node: User Interfaces64461
+Node: Documentation79291
+Node: Releases83225
+
+End Tag Table
diff --git a/gnu/usr.bin/binutils/etc/standards.info-1 b/gnu/usr.bin/binutils/etc/standards.info-1
new file mode 100644
index 00000000000..38184e4a1bb
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/standards.info-1
@@ -0,0 +1,1225 @@
+This is Info file standards.info, produced by Makeinfo-1.55 from the
+input file ./standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+
+   GNU Coding Standards Copyright (C) 1992, 1993, 1994 Free Software
+Foundation
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+
+File: standards.info,  Node: Top,  Next: Reading Non-Free Code,  Prev: (dir),  Up: (dir)
+
+Version
+*******
+
+   Last updated 28 March 1994.
+
+* Menu:
+
+* Reading Non-Free Code::	Referring to Proprietary Programs
+* Contributions::		Accepting Contributions
+* Change Logs::			Recording Changes
+* Compatibility::		Compatibility with Other Implementations
+* Makefile Conventions::	Makefile Conventions
+* Configuration::		How Configuration Should Work
+* Source Language::		Using Languages Other Than C
+* Formatting::			Formatting Your Source Code
+* Comments::			Commenting Your Work
+* Syntactic Conventions::	Clean Use of C Constructs
+* Names::			Naming Variables and Functions
+* Using Extensions::		Using Non-standard Features
+* System Functions::            Portability and "standard" library functions
+* Semantics::			Program Behavior for All Programs
+* Errors::			Formatting Error Messages
+* Libraries::			Library Behavior
+* Portability::			Portability As It Applies to GNU
+* User Interfaces::		Standards for Command Line Interfaces
+* Documentation::		Documenting Programs
+* Releases::			Making Releases
+
+
+File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Prev: Top,  Up: Top
+
+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: Change Logs,  Prev: Reading Non-Free Code,  Up: Top
+
+Accepting Contributions
+***********************
+
+   If someone else sends you a piece of code to add to the program you
+are working on, we need legal papers to use it--the same sort of legal
+papers we will need to get from you.  *Each* significant contributor 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, 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 change, we
+need legal papers for it.
+
+   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 you write a different solution to the
+problem, you don't need to get papers.
+
+   I know this is frustrating; 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!
+
+   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.
+
+
+File: standards.info,  Node: Change Logs,  Next: Compatibility,  Prev: Contributions,  Up: Top
+
+Change Logs
+***********
+
+   Keep a change log for each directory, describing the changes made to
+source files in that directory.  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
+eliminate conceptual inconsistencies between different parts of a
+program; they can give you a history of how the conflicting concepts
+arose.
+
+   Use the Emacs command `M-x add-change' to start a new entry in the
+change log.  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.
+
+   Separate unrelated 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.
+
+   Here are some examples:
+
+     * 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 them; 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 the entry.
+
+   There's no need to describe the full purpose of the changes or how
+they work together.  It is better to put such explanations in comments
+in the code.  That's why just "New function" is enough; there is a
+comment with the function in the source to explain what it does.
+
+   However, sometimes it is useful to write one line to describe the
+overall purpose of a large batch of changes.
+
+   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.
+
+   When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function, there is no
+need to make individual entries for all the callers.  Just write in the
+entry for the function being called, "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.  Write just,
+"Doc fix."  There's no need to keep a change log 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.
+
+
+File: standards.info,  Node: Compatibility,  Next: Makefile Conventions,  Prev: Change Logs,  Up: Top
+
+Compatibility with Other Implementations
+****************************************
+
+   With certain exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with ANSI C if ANSI 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.
+
+   ANSI C and POSIX prohibit many kinds of extensions.  Feel free to
+make the extensions anyway, and include a `--ansi' 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.  Try to redesign its interface.
+
+   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 not in Berkeley Unix are welcome.
+Additional programs with no counterpart in Unix may be useful, but our
+first priority is usually to duplicate what Unix already has.
+
+
+File: standards.info,  Node: Makefile Conventions,  Next: Configuration,  Prev: Compatibility,  Up: Top
+
+Makefile Conventions
+********************
+
+   This chapter describes conventions for writing the Makefiles for GNU
+programs.
+
+* Menu:
+
+* Makefile Basics::
+* Utilities in Makefiles::
+* Standard Targets::
+* Command Variables::
+* Directory Variables::
+
+
+File: standards.info,  Node: Makefile Basics,  Next: Utilities in Makefiles,  Up: Makefile Conventions
+
+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'.)
+
+   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 `./' and `$(srcdir)/' is important when
+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 current directory is not the source directory,
+because `foo.man' and `sedscript' are not in the current 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) $(CFLAGS) $< -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 -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
+
+
+File: standards.info,  Node: Utilities in Makefiles,  Next: Standard Targets,  Prev: Makefile Basics,  Up: Makefile Conventions
+
+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 echo egrep expr grep
+     ln mkdir mv pwd rm rmdir sed test touch
+
+   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.
+
+   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 lex
+     make makeinfo ranlib texi2dvi yacc
+
+   When you use `ranlib', you should test whether it exists, and run it
+only if it exists, so that the distribution will work on systems that
+don't have `ranlib'.
+
+   If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+   It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities to
+exist.
+
+
+File: standards.info,  Node: Standard Targets,  Next: Command Variables,  Prev: Utilities in Makefiles,  Up: Makefile Conventions
+
+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.
+
+`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.
+
+     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
+     script that edits the Info `dir' file to add or update the menu
+     entry for the given Info file; it will be part of the Texinfo
+     package.  Here is a sample rule to install an Info file:
+
+          $(infodir)/foo.info: foo.info
+          # 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 $@; \
+          # 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 --infodir=$(infodir) $$d/foo.info; \
+                  else true; fi
+
+`uninstall'
+     Delete all the installed files that the `install' target would
+     create (but not the noninstalled files such as `make all' would
+     create).
+
+`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.
+
+`realclean'
+     Delete 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.
+
+     One exception, however: `make realclean' should not delete
+     `configure' even if `configure' can be remade using a rule in the
+     Makefile.  More generally, `make realclean' should not delete
+     anything that needs to exist in order to run `configure' and then
+     begin to build the program.
+
+`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.
+
+`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.  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.
+
+     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: (standards)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; 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)
+
+
+File: standards.info,  Node: Command Variables,  Next: Directory Variables,  Prev: Standard Targets,  Up: Makefile Conventions
+
+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 name `CFLAGS' is an exception to this
+rule, but we keep it because it is 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.
+
+   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 each of these should be
+`$(INSTALL)'.)  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
+
+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,  Prev: Command Variables,  Up: Makefile Conventions
+
+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:
+
+`prefix'
+     A prefix used in constructing the default values of the variables
+     listed below.  The default value of `prefix' should be `/usr/local'
+     (at least for now).
+
+`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)'.
+
+     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.
+
+`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'.
+
+`libdir'
+     The directory for installing executable files to be run by the
+     program rather than by users.  Object files and libraries of
+     object code should also go in this directory.  The idea is that
+     this directory is used for files that pertain to a specific
+     machine architecture, but need not be in the path for commands.
+     The value of `libdir' should normally be `/usr/local/lib', but
+     write it as `$(exec_prefix)/lib'.
+
+`datadir'
+     The directory for installing read-only data files which the
+     programs refer to while they run.  This directory is used for
+     files which are independent of the type of machine being used.
+     This should normally be `/usr/local/lib', but write it as
+     `$(prefix)/lib'.
+
+`statedir'
+     The directory for installing data files which the programs modify
+     while they run.  These files should be independent of the type of
+     machine being used, and it should be possible to share them among
+     machines at a network installation.  This should normally be
+     `/usr/local/lib', but write it as `$(prefix)/lib'.
+
+`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'.
+
+     Most compilers other than GCC do not look for header files in
+     `/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'.
+
+     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.
+
+`mandir'
+     The directory for installing the man pages (if any) for this
+     package.  It should include the suffix for the proper section of
+     the manual--usually `1' for a utility.  It will normally be
+     `/usr/local/man/man1', but you should write it as
+     `$(prefix)/man/man1'.
+
+`man1dir'
+     The directory for installing section 1 man pages.
+
+`man2dir'
+     The directory for installing section 2 man pages.
+
+`...'
+     Use these names instead of `mandir' if the package needs to
+     install man pages in more than one section of the manual.
+
+     *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.
+
+`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'.
+
+`srcdir'
+     The directory for the sources being compiled.  The value of this
+     variable is normally inserted by the `configure' shell script.
+
+   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.
+     libdir = $(exec_prefix)/lib
+     # 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: Configuration,  Next: Source Language,  Prev: Makefile Conventions,  Up: Top
+
+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, 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.  So would `sun3-bsd4.2', since SunOS is
+basically BSD and no other BSD system is used on a Sun.  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 `x', `x-toolkit', `gnu-as' (or
+     `gas'), `gnu-ld', `gnu-libc', and `gdb'.
+
+     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.
+
+`--nfp'
+     The target machine has no floating point processor.
+
+`--gas'
+     The target machine assembler is GAS, the GNU assembler.  This is
+     obsolete; users should use `--with-gnu-as' instead.
+
+`--x'
+     The target machine has the X Window System installed.  This is
+     obsolete; users should use `--with-x' instead.
+
+   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 compilation 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.
+
+   The way to build a cross-compiler, cross-assembler, or what have
+you, is to specify the option `--host=HOSTTYPE' when running
+`configure'.  This specifies the host system without changing the type
+of target system.  The syntax for HOSTTYPE is the same as described
+above.
+
+   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=HOSTTYPE' for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
+   Programs for which cross-operation is not meaningful need not accept
+the `--host' option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+
+   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: Source Language,  Next: Formatting,  Prev: Configuration,  Up: Top
+
+Using Languages Other Than C
+****************************
+
+   Using a language other than C 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.  So
+please write in C.
+
+   There are three exceptions for this rule:
+
+   * It is okay to use a special language if the same program contains
+     an interpreter for that language.
+
+     Thus, it is not a problem that GNU Emacs contains code written in
+     Emacs Lisp, because it comes with a Lisp interpreter.
+
+   * It is okay to use another language in a tool specifically intended
+     for use with that language.
+
+     This is okay because the only people who want to build the tool
+     will be those who have installed the other language anyway.
+
+   * If an application is not of extremely widespread interest, then
+     perhaps it's not important if the application is inconvenient to
+     install.
+
+
+File: standards.info,  Node: Formatting,  Next: Comments,  Prev: Source Language,  Up: Top
+
+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 ANSI C, format the definition like this:
+
+     static char *
+     concat (char *s1, char *s2)
+     {
+       ...
+     }
+
+   In ANSI 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)
+     ...
+
+   For the body of the function, we prefer code formatted 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,
+but Emacs would mess it up:
+
+     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 adding a set of parentheses solves the problem:
+
+     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: Top
+
+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 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
+identifer 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 */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+     #ifndef foo
+       ...
+     #else /* foo */
+       ...
+     #endif /* foo */
+
+
+File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Top
+
+Clean Use of C Constructs
+*************************
+
+   Please explicitly declare all arguments to functions.  Don't omit
+them just because they are `int's.
+
+   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.
+
+
+File: standards.info,  Node: Names,  Next: Using Extensions,  Prev: Syntactic Conventions,  Up: Top
+
+Naming Variables and Functions
+******************************
+
+   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.
+
+   Use file names of 14 characters or less, to avoid creating gratuitous
+problems on System V.  You can use the program `doschk' to test for
+this.  `doschk' also tests for potential name conflicts if the files
+were loaded onto an MS-DOS file system--something you may or may not
+care about.
+
diff --git a/gnu/usr.bin/binutils/etc/standards.info-2 b/gnu/usr.bin/binutils/etc/standards.info-2
new file mode 100644
index 00000000000..119f28149f4
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/standards.info-2
@@ -0,0 +1,1462 @@
+This is Info file standards.info, produced by Makeinfo-1.55 from the
+input file ./standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+
+   GNU Coding Standards Copyright (C) 1992, 1993, 1994 Free Software
+Foundation
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+
+File: standards.info,  Node: Using Extensions,  Next: System Functions,  Prev: Names,  Up: Top
+
+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.  Such programs would
+be broken by use of GNU extensions.
+
+   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 no good.
+
+   Since most computer systems do not yet implement ANSI C, using the
+ANSI C features is effectively using a GNU extension, so the same
+considerations apply.  (Except for ANSI features that we discourage,
+such as trigraphs--don't ever use them.)
+
+
+File: standards.info,  Node: System Functions,  Next: Semantics,  Prev: Using Extensions,  Up: Top
+
+Calling System Functions
+************************
+
+   C implementations differ substantially.  ANSI C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-ANSI compilers.  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 value of `sprintf'.  It returns the number of
+     characters written on some systems, but not on all systems.
+
+   * 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.  The problem 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 an ANSI 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'; other 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 ANSI
+     string functions are off-limits 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'.)  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: Semantics,  Next: Errors,  Prev: System Functions,  Up: Top
+
+Program Behavior for All Programs
+*********************************
+
+   Avoid arbitrary limits on the length or number of *any* data
+structure, including filenames, 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 printers that can't handle those
+characters.
+
+   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'.
+
+   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 will be supported compatibly by GNU.
+
+   By default, the GNU system will provide the signal handling
+functions of BSD and of POSIX.  So GNU software should be written to use
+these.
+
+   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.
+
+
+File: standards.info,  Node: Errors,  Next: Libraries,  Prev: Semantics,  Up: Top
+
+Formatting Error Messages
+*************************
+
+   Error messages from compilers should look like this:
+
+     SOURCE-FILE-NAME:LINENO: MESSAGE
+
+   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.
+
+   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 filename.  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: Libraries,  Next: Portability,  Prev: Errors,  Up: Top
+
+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 `_'.  They should also contain 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: Portability,  Next: User Interfaces,  Prev: Libraries,  Up: Top
+
+Portability As It Applies to GNU
+********************************
+
+   Much of what is called "portability" in the Unix world refers to
+porting to different Unix versions.  This is a secondary consideration
+for GNU software, because its primary purpose is to run on top of one
+and only one kernel, the GNU kernel, compiled with one and only one C
+compiler, the GNU C compiler.  The amount and kinds of variation among
+GNU systems on different cpu's will be like the variation among Berkeley
+4.3 systems on different cpu's.
+
+   All users today run GNU software on non-GNU systems.  So supporting a
+variety of non-GNU systems is desirable; simply not paramount.  The
+easiest way to achieve portability to a reasonable range of systems is
+to use Autoconf.  It's unlikely that your program needs to know more
+information about the host machine than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+   It is difficult to be sure exactly what facilities the GNU kernel
+will provide, since it isn't finished yet.  Therefore, assume you can
+use anything in 4.3; just avoid using the format of semi-internal data
+bases (e.g., directories) when there is a higher-level alternative
+(`readdir').
+
+   You can freely assume any reasonably standard facilities in the C
+language, libraries or kernel, because we will find it necessary to
+support these facilities in the full GNU system, whether or not we have
+already done so.  The fact that there may exist kernels or C compilers
+that lack these facilities is irrelevant as long as the GNU kernel and
+C compiler support them.
+
+   It remains necessary to worry about differences among cpu types, such
+as the difference in byte ordering and alignment restrictions.  It's
+unlikely that 16-bit machines will ever be supported by GNU, so there
+is no point in spending any time to consider the possibility that an
+int will be less than 32 bits.
+
+   You can assume that all pointers have the same format, regardless of
+the type they point to, and that this is really an integer.  There are
+some weird machines where this isn't true, but they aren't important;
+don't waste time catering to them.  Besides, eventually we will put
+function prototypes into all GNU programs, and that will probably make
+your program work even on weird machines.
+
+   Since some important machines (including the 68000) are big-endian,
+it is important not to assume that the address of an `int' object is
+also the address of its least-significant byte.  Thus, don't make the
+following mistake:
+
+     int c;
+     ...
+     while ((c = getchar()) != EOF)
+             write(file_descriptor, &c, 1);
+
+   You can assume that it is reasonable to use a meg of memory.  Don't
+strain to reduce memory usage unless it can get to that level.  If your
+program creates complicated data structures, just make them in core and
+give a fatal error if malloc returns zero.
+
+   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.
+
+
+File: standards.info,  Node: User Interfaces,  Next: Documentation,  Prev: Portability,  Up: Top
+
+Standards for Command Line Interfaces
+*************************************
+
+   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.
+
+   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.
+
+   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.  The table appears below.
+
+   If you use names not already in the table, please send
+`gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can
+update the 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').  Even if you allow an output file name as an
+ordinary argument for compatibility, try to provide a suitable option
+as well.  This will lead to more consistency among GNU utilities, so
+that there are fewer idiosyncracies for users to remember.
+
+   Programs should support an option `--version' which prints the
+program's version number on standard output and exits successfully, and
+an option `--help' which prints option usage information on standard
+output and exits successfully.  These options should inhibit the normal
+function of the command; they should do nothing except print the
+requested information.
+
+`auto-check'
+     `-a' in `recode'.
+
+`auto-reference'
+     `-A' in `ptx'.
+
+`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'.
+
+`arglength'
+     `-l' in `m4'.
+
+`ascii'
+     `-a' in `diff'.
+
+`assume-new'
+     `-W' in Make.
+
+`assume-old'
+     `-o' in Make.
+
+`backward-search'
+     `-B' in etags.
+
+`batch'
+     Used in GDB.
+
+`baud'
+     Used in GDB.
+
+`before'
+     `-b' in `tac'.
+
+`binary'
+     `-b' in `cpio' and `diff'.
+
+`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'.
+
+`compress'
+     `-Z' in `tar'.
+
+`concatenate'
+     `-A' in `tar'.
+
+`confirmation'
+     `-w' in `tar'.
+
+`context'
+     Used in `diff'.
+
+`copyright'
+     `-C' in `ptx' and `recode'.
+
+`core'
+     Used in GDB.
+
+`count'
+     `-q' in `who'.
+
+`count-links'
+     `-l' in `du'.
+
+`create'
+     Used in `tar' and `cpio'.
+
+`cxref'
+     `-x' in `etags'.
+
+`date'
+     `-d' in `touch'.
+
+`debug'
+     `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+     `-D' in `m4'.
+
+`defines'
+     `-d' in Bison and `etags'.
+
+`delete'
+     `-D' in `tar'.
+
+`dereference'
+     `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+     `-D' in `du'.
+
+`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'.
+
+`diversions'
+     `-N' in `m4'.
+
+`dry-run'
+     `-n' in Make.
+
+`ed'
+     `-e' in `diff'.
+
+`elide-empty-files'
+     `-z' in `csplit'.
+
+`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'.
+
+`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'.
+
+`file'
+     `-f' in `info', Make, `mt', and `tar'; `-n' in `sed'; `-r' in
+     `touch'.
+
+`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'.
+
+`format'
+     Used in `ls', `time', and `ptx'.
+
+`forward-search'
+     `-F' in `etags'.
+
+`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'.
+
+`hashsize'
+     `-H' in `m4'.
+
+`header'
+     `-h' in `objdump' and `recode'
+
+`heading'
+     `-H' in `who'.
+
+`help'
+     Used to ask for brief usage information.
+
+`hide-control-chars'
+     `-q' in `ls'.
+
+`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'.
+
+`ignore-errors'
+     `-i' in Make.
+
+`ignore-file'
+     `-i' in `ptx'.
+
+`ignore-indentation'
+     `-S' 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.
+
+`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'.
+
+`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'.
+
+`line-bytes'
+     `-C' in `split'.
+
+`lines'
+     Used in `split', `head', and `tail'.
+
+`link'
+     `-l' in `cpio'.
+
+`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@prep.ai.mit.edu'.
+
+`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'.
+
+`mode'
+     `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+     `-m' in `tar'.
+
+`multi-volume'
+     `-M' in `tar'.
+
+`name-prefix'
+     `-a' in Bison.
+
+`new-file'
+     `-W' in Make.
+
+`no-builtin-rules'
+     `-r' in Make.
+
+`no-create'
+     `-c' in `touch'.
+
+`no-defines'
+     `-D' in `etags'.
+
+`no-dereference'
+     `-d' in `cp'.
+
+`no-keep-going'
+     `-S' in Make.
+
+`no-lines'
+     `-l' in Bison.
+
+`no-prof'
+     `-e' in `gprof'.
+
+`no-sort'
+     `-p' in `nm'.
+
+`no-split'
+     Used in Makeinfo.
+
+`no-static'
+     `-a' in `gprof'.
+
+`no-time'
+     `-E' in `gprof'.
+
+`no-validate'
+     Used in Makeinfo.
+
+`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'.
+
+`output'
+     In various programs, specify the output file name.
+
+`override'
+     `-o' in `rm'.
+
+`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'.
+
+`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'.
+
+`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.
+
+`quote-name'
+     `-Q' in `ls'.
+
+`rcs'
+     `-n' in `diff'.
+
+`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'.
+
+`release'
+     `-r' in `uname'.
+
+`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'.
+
+`sort'
+     Used in `ls'.
+
+`sparse'
+     `-S' in `tar'.
+
+`speed-large-files'
+     `-H' in `diff'.
+
+`squeeze-blank'
+     `-s' in `cat'.
+
+`starting-file'
+     Used in `tar' and `diff' to specify which file within a directory
+     to start processing with.
+
+`stop'
+     `-S' in Make.
+
+`strict'
+     `-s' in `recode'.
+
+`strip'
+     `-s' in `install'.
+
+`strip-all'
+     `-s' in `strip'.
+
+`strip-debug'
+     `-S' in `strip'.
+
+`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'.
+
+`text'
+     `-a' in `diff'.
+
+`time'
+     Used in `ls' and `touch'.
+
+`to-stdout'
+     `-O' in `tar'.
+
+`total'
+     `-c' in `du'.
+
+`touch'
+     `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+     `-t' in `m4'.
+
+`traditional'
+     `-t' in `hello'; `-G' in `m4' and `ptx'.
+
+`tty'
+     Used in GDB.
+
+`typedefs'
+     `-t' in `etags'.
+
+`typedefs-and-c++'
+     `-T' in `etags'.
+
+`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', `etags', `mv', `tar'.
+
+`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 `etags'.
+
+`volume'
+     `-V' in `tar'.
+
+`what-if'
+     `-W' in Make.
+
+`width'
+     `-w' in `ls' and `ptx'.
+
+`word-regexp'
+     `-W' in `ptx'.
+
+`writable'
+     `-T' in `who'.
+
+`zeros'
+     `-z' in `gprof'.
+
+
+File: standards.info,  Node: Documentation,  Next: Releases,  Prev: User Interfaces,  Up: Top
+
+Documenting Programs
+********************
+
+   Please use Texinfo for documenting GNU programs.  See the Texinfo
+manual, either the hardcopy or the version in the GNU Emacs Info
+subsystem (`C-h i').  See existing GNU Texinfo files (e.g., those under
+the `man/' directory in the GNU Emacs distribution) for examples.
+
+   The title page of the manual should state the version of the program
+which the manual applies to.  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.
+
+   The manual should document all command-line arguments and all
+commands.  It should give examples of their use.  But don't organize
+the manual as a list of features.  Instead, organize it by the concepts
+a user will have before reaching that point in the manual.  Address the
+goals that a user will have in mind, and explain how to accomplish
+them.  Don't use Unix man pages as a model for how to write GNU
+documentation; they are a bad example to follow.
+
+   The manual should have a node named `PROGRAM Invocation' or
+`Invoking PROGRAM', where PROGRAM stands for the name of the program
+being described, as you would type it in the shell to run the 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.
+
+   There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+   If one manual describes several programs, it should have such a node
+for each program described.
+
+   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.
+
+   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 file names.
+
+   It is ok to supply a man page for the program as well as a Texinfo
+manual if you wish to.  But keep in mind that supporting a man page
+requires continual effort, each time the program is changed.  Any time
+you spend on the man page is time taken away from more useful things you
+could contribute.
+
+   Thus, even if a user volunteers to donate a man page, you may find
+this gift costly to accept.  Unless you have time on your hands, it may
+be better to refuse the man page unless the same volunteer agrees to
+take full responsibility for maintaining it--so that you can wash your
+hands of it entirely.  If the volunteer ceases to do the job, then
+don't feel obliged to pick it up yourself; it may be better to withdraw
+the man page until another volunteer offers to carry on with it.
+
+   Alternatively, if you expect the discrepancies to be small enough
+that the man page remains useful, 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, and describing how to
+access the Texinfo documentation.
+
+
+File: standards.info,  Node: Releases,  Prev: Documentation,  Up: Top
+
+Making Releases
+***************
+
+   Package the distribution of Foo version 69.96 in a gzipped tar file
+named `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.
+
+   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-DOG.  A
+name on MS-DOG consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOG 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' 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.
+
+
diff --git a/gnu/usr.bin/binutils/etc/standards.texi b/gnu/usr.bin/binutils/etc/standards.texi
new file mode 100644
index 00000000000..13908d65fe4
--- /dev/null
+++ b/gnu/usr.bin/binutils/etc/standards.texi
@@ -0,0 +1,2295 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename standards.info
+@settitle GNU Coding Standards
+@c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
+@set lastupdate 28 March 1994
+@c %**end of header
+
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* Standards: (standards).        GNU coding standards.
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+@setchapternewpage off
+
+@ifinfo
+GNU Coding Standards
+Copyright (C) 1992, 1993, 1994 Free Software Foundation
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+@end ifinfo
+
+@titlepage
+@title GNU Coding Standards
+@author Richard Stallman
+@author last updated @value{lastupdate}
+@page
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993 Free Software Foundation
+
+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 Free Software Foundation.
+@end titlepage
+
+@ifinfo
+@node Top, Reading Non-Free Code, (dir), (dir)
+@top Version
+
+Last updated @value{lastupdate}.
+@end ifinfo
+
+@menu
+* Reading Non-Free Code::	Referring to Proprietary Programs
+* Contributions::		Accepting Contributions
+* Change Logs::			Recording Changes
+* Compatibility::		Compatibility with Other Implementations
+* Makefile Conventions::	Makefile Conventions
+* Configuration::		How Configuration Should Work
+* Source Language::		Using Languages Other Than C
+* Formatting::			Formatting Your Source Code
+* Comments::			Commenting Your Work
+* Syntactic Conventions::	Clean Use of C Constructs
+* Names::			Naming Variables and Functions
+* Using Extensions::		Using Non-standard Features
+* System Functions::            Portability and ``standard'' library functions
+* Semantics::			Program Behavior for All Programs
+* Errors::			Formatting Error Messages
+* Libraries::			Library Behavior
+* Portability::			Portability As It Applies to GNU
+* User Interfaces::		Standards for Command Line Interfaces
+* Documentation::		Documenting Programs
+* Releases::			Making Releases
+@end menu
+
+@node Reading Non-Free Code
+@chapter 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.
+
+
+@node Contributions
+@chapter Accepting Contributions
+
+If someone else sends you a piece of code to add to the program you are
+working on, we need legal papers to use it---the same sort of legal
+papers we will need to get from you.  @emph{Each} significant
+contributor 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, 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 change, we
+need legal papers for it.
+
+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 you write a different solution to the
+problem, you don't need to get papers.
+
+I know this is frustrating; 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!
+
+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.
+
+@node Change Logs
+@chapter Change Logs
+
+Keep a change log for each directory, describing the changes made to
+source files in that directory.  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 eliminate conceptual inconsistencies between different parts
+of a program; they can give you a history of how the conflicting
+concepts arose.
+
+Use the Emacs command @kbd{M-x add-change} to start a new entry in the
+change log.  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.
+
+Separate unrelated 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.
+
+Here are some examples:
+
+@example
+* register.el (insert-register): Return nil.
+(jump-to-register): Likewise.
+
+* sort.el (sort-subr): Return nil.
+
+* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+Restart the tex shell if process is gone or stopped.
+(tex-shell-running): New function.
+
+* expr.c (store_one_arg): Round size up for move_block_to_reg.
+(expand_call): Round up when emitting USE insns.
+* stmt.c (assign_parms): Round size up for move_block_from_reg.
+@end example
+
+It's important to name the changed function or variable in full.  Don't
+abbreviate them; don't combine them.  Subsequent maintainers will often
+search for a function name to find all the change log entries that
+pertain to it; if you abbreviate the name, they won't find it when they
+search.  For example, some people are tempted to abbreviate groups of
+function names by writing @samp{* register.el
+(@{insert,jump-to@}-register)}; this is not a good idea, since searching
+for @code{jump-to-register} or @code{insert-register} would not find the
+entry.
+
+There's no need to describe the full purpose of the changes or how they
+work together.  It is better to put such explanations in comments in the
+code.  That's why just ``New function'' is enough; there is a comment
+with the function in the source to explain what it does.
+
+However, sometimes it is useful to write one line to describe the
+overall purpose of a large batch of changes.
+
+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.
+
+When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function, there is no
+need to make individual entries for all the callers.  Just write in
+the entry for the function being called, ``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.  Write just,
+``Doc fix.''  There's no need to keep a change log 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.
+
+
+@node Compatibility
+@chapter Compatibility with Other Implementations
+
+With certain exceptions, utility programs and libraries for GNU should
+be upward compatible with those in Berkeley Unix, and upward compatible
+with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward
+compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior.
+
+When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions.  Feel
+free to make the extensions anyway, and include a @samp{--ansi} or
+@samp{--compatible} option to turn them off.  However, if the extension
+has a significant chance of breaking any real programs or scripts,
+then it is not really upward compatible.  Try to redesign its
+interface.
+
+Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable @code{POSIXLY_CORRECT} is defined (even if it is
+defined with a null value).  Please make your program recognize this
+variable if appropriate.
+
+When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+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 not in Berkeley Unix are welcome.
+Additional programs with no counterpart in Unix may be useful,
+but our first priority is usually to duplicate what Unix already
+has.
+
+@comment The makefile standards are in a separate file that is also
+@comment included by make.texinfo.  Done by roland@gnu.ai.mit.edu on 1/6/93.
+@include make-stds.texi
+
+@node Configuration
+@chapter How Configuration Should Work
+
+Each GNU distribution should come with a shell script named
+@code{configure}.  This script is given arguments which describe the
+kind of machine and system you want to compile the program for.
+
+The @code{configure} script must record the configuration options so
+that they affect compilation.
+
+One way to do this is to make a link from a standard name such as
+@file{config.h} to the proper configuration file for the chosen system.
+If you use this technique, the distribution should @emph{not} contain a
+file named @file{config.h}.  This is so that people won't be able to
+build the program without configuring it first.
+
+Another thing that @code{configure} can do is to edit the Makefile.  If
+you do this, the distribution should @emph{not} contain a file named
+@file{Makefile}.  Instead, include a file @file{Makefile.in} which
+contains the input used for editing.  Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+If @code{configure} does write the @file{Makefile}, then @file{Makefile}
+should have a target named @file{Makefile} which causes @code{configure}
+to be rerun, setting up the same configuration that was set up last
+time.  The files that @code{configure} reads should be listed as
+dependencies of @file{Makefile}.
+
+All the files which are output from the @code{configure} script should
+have comments at the beginning explaining that they were generated
+automatically using @code{configure}.  This is so that users won't think
+of trying to edit them by hand.
+
+The @code{configure} script should write a file named @file{config.status}
+which describes which configuration options were specified when the
+program was last configured.  This file should be a shell script which,
+if run, will recreate the same configuration.
+
+The @code{configure} script should accept an option of the form
+@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
+(if it is not the current directory).  This makes it possible to build
+the program in a separate directory, so that the actual source directory
+is not modified.
+
+If the user does not specify @samp{--srcdir}, then @code{configure} should
+check both @file{.} and @file{..} to see if it can find the sources.  If
+it finds the sources in one of these places, it should use them from
+there.  Otherwise, it should report that it cannot find the sources, and
+should exit with nonzero status.
+
+Usually the easy way to support @samp{--srcdir} is by editing a
+definition of @code{VPATH} into the Makefile.  Some rules may need to
+refer explicitly to the specified source directory.  To make this
+possible, @code{configure} can add to the Makefile a variable named
+@code{srcdir} whose value is precisely the specified directory.
+
+The @code{configure} script should also take an argument which specifies the
+type of system to build the program for.  This argument should look like
+this:
+
+@example
+@var{cpu}-@var{company}-@var{system}
+@end example
+
+For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
+
+The @code{configure} script needs to be able to decode all plausible
+alternatives for how to describe a machine.  Thus, @samp{sun3-sunos4.1}
+would be a valid alias.  So would @samp{sun3-bsd4.2}, since SunOS is
+basically @sc{BSD} and no other @sc{BSD} system is used on a Sun.  For many
+programs, @samp{vax-dec-ultrix} would be an alias for
+@samp{vax-dec-bsd}, simply because the differences between Ultrix and
+@sc{BSD} are rarely noticeable, but a few programs might need to distinguish
+them.
+
+There is a shell script called @file{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:
+
+@table @samp
+@item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
+Configure the package to build and install an optional user-level
+facility called @var{feature}.  This allows users to choose which
+optional features to include.  Giving an optional @var{parameter} of
+@samp{no} should omit @var{feature}, if it is built by default.
+
+No @samp{--enable} option should @strong{ever} cause one feature to
+replace another.  No @samp{--enable} option should ever substitute one
+useful behavior for another useful behavior.  The only proper use for
+@samp{--enable} is for questions of whether to build part of the program
+or exclude it.
+
+@item --with-@var{package}
+@c @r{[}=@var{parameter}@r{]}
+The package @var{package} will be installed, so configure this package
+to work with @var{package}.
+
+@c  Giving an optional @var{parameter} of
+@c @samp{no} should omit @var{package}, if it is used by default.
+
+Possible values of @var{package} include @samp{x}, @samp{x-toolkit},
+@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and
+@samp{gdb}.
+
+Do not use a @samp{--with} option to specify the file name to use to
+find certain files.  That is outside the scope of what @samp{--with}
+options are for.
+
+@item --nfp
+The target machine has no floating point processor.
+
+@item --gas
+The target machine assembler is GAS, the GNU assembler.
+This is obsolete; users should use @samp{--with-gnu-as} instead.
+
+@item --x
+The target machine has the X Window System installed.
+This is obsolete; users should use @samp{--with-x} instead.
+@end table
+
+All @code{configure} scripts should accept all of these ``detail''
+options, whether or not they make any difference to the particular
+package at hand.  In particular, they should accept any option that
+starts with @samp{--with-} or @samp{--enable-}.  This is so users will
+be able to configure an entire GNU source tree at once with a single set
+of options.
+
+You will note that the categories @samp{--with-} and @samp{--enable-}
+are narrow: they @strong{do not} provide a place for any sort of option
+you might think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+
+Packages that perform part of compilation may support cross-compilation.
+In such a case, the host and target machines for the program may be
+different.  The @code{configure} script should normally treat the
+specified type of system as both the host and the target, thus producing
+a program which works for the same type of machine that it runs on.
+
+The way to build a cross-compiler, cross-assembler, or what have you, is
+to specify the option @samp{--host=@var{hosttype}} when running
+@code{configure}.  This specifies the host system without changing the
+type of target system.  The syntax for @var{hosttype} is the same as
+described above.
+
+Bootstrapping a cross-compiler requires compiling it on a machine other
+than the host it will run on.  Compilation packages accept a
+configuration option @samp{--build=@var{hosttype}} for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
+Programs for which cross-operation is not meaningful need not accept the
+@samp{--host} option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+
+Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your @code{configure} script can simply
+ignore most of its arguments.
+
+
+@node Source Language
+@chapter Using Languages Other Than C
+
+Using a language other than C 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.  So please write in C.
+
+There are three exceptions for this rule:
+
+@itemize @bullet
+@item
+It is okay to use a special language if the same program contains an
+interpreter for that language.
+
+Thus, it is not a problem that GNU Emacs contains code written in Emacs
+Lisp, because it comes with a Lisp interpreter.
+
+@item
+It is okay to use another language in a tool specifically intended for
+use with that language.
+
+This is okay because the only people who want to build the tool will be
+those who have installed the other language anyway.
+
+@item
+If an application is not of extremely widespread interest, then perhaps
+it's not important if the application is inconvenient to install.
+@end itemize
+
+@node Formatting
+@chapter 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:
+
+@example
+static char *
+concat (s1, s2)        /* Name starts in column zero here */
+     char *s1, *s2;
+@{                     /* Open brace in column zero here */
+  @dots{}
+@}
+@end example
+
+@noindent
+or, if you want to use @sc{ANSI} C, format the definition like this:
+
+@example
+static char *
+concat (char *s1, char *s2)
+@{
+  @dots{}
+@}
+@end example
+
+In @sc{ANSI} C, if the arguments don't fit nicely on one line,
+split it like this:
+
+@example
+int
+lots_of_args (int an_integer, long a_long, short a_short,
+              double a_double, float a_float)
+@dots{}
+@end example
+
+For the body of the function, we prefer code formatted like this:
+
+@example
+if (x < foo (y, z))
+  haha = bar[4] + 5;
+else
+  @{
+    while (z)
+      @{
+        haha += foo (z, z);
+        z--;
+      @}
+    return ++x + bar ();
+  @}
+@end example
+
+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:
+
+@example
+if (foo_this_is_long && bar > win (x, y, z)
+    && remaining_condition)
+@end example
+
+Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+
+@example
+mode = (inmode[j] == VOIDmode
+        || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+        ? outmode[j] : inmode[j]);
+@end example
+
+Instead, use extra parentheses so that the indentation shows the nesting:
+
+@example
+mode = ((inmode[j] == VOIDmode
+         || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+        ? outmode[j] : inmode[j]);
+@end example
+
+Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+but Emacs would mess it up:
+
+@example
+v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+    + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+@end example
+
+But adding a set of parentheses solves the problem:
+
+@example
+v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+     + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+@end example
+
+Format do-while statements like this:
+
+@example
+do
+  @{
+    a = foo (a);
+  @}
+while (a > 0);
+@end example
+
+Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+
+
+@node Comments
+@chapter Commenting Your Work
+
+Every program should start with a comment saying briefly what it is for.
+Example: @samp{fmt - filter for simple filling of text}.
+
+Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for.  It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion.  If there is anything nonstandard about
+its use (such as an argument of type @code{char *} which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+Also explain the significance of the return value, if there is one.
+
+Please put two spaces after the end of a sentence in your comments, so
+that the Emacs sentence commands will work.  Also, please write
+complete sentences and capitalize the first word.  If a lower-case
+identifer comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier.  If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., ``The identifier lower-case is @dots{}'').
+
+The comment on a function is much clearer if you use the argument
+names to speak about the argument values.  The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself.  Thus, ``the inode
+number NODE_NUM'' rather than ``an inode''.
+
+There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the function
+itself would be off the bottom of the screen.
+
+There should be a comment on each static variable as well, like this:
+
+@example
+/* Nonzero means truncate lines in the display;
+   zero means continue them.  */
+int truncate_lines;
+@end example
+
+Every @samp{#endif} should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested.  The comment should
+state the condition of the conditional that is ending, @emph{including
+its sense}.  @samp{#else} should have a comment describing the condition
+@emph{and sense} of the code that follows.  For example:
+
+@example
+#ifdef foo
+  @dots{}
+#else /* not foo */
+  @dots{}
+#endif /* not foo */
+@end example
+
+@noindent
+but, by contrast, write the comments this way for a @samp{#ifndef}:
+
+@example
+#ifndef foo
+  @dots{}
+#else /* foo */
+  @dots{}
+#endif /* foo */
+@end example
+
+
+@node Syntactic Conventions
+@chapter Clean Use of C Constructs
+
+Please explicitly declare all arguments to functions.
+Don't omit them just because they are @code{int}s.
+
+Declarations of external functions and functions to appear later in the
+source file should all go in one place near the beginning of the file
+(somewhere before the first function definition in the file), or else
+should go in a header file.  Don't put @code{extern} declarations inside
+functions.
+
+It used to be common practice to use the same local variables (with
+names like @code{tem}) over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+
+Don't use local variables or parameters that shadow global identifiers.
+
+Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead
+of this:
+
+@example
+int    foo,
+       bar;
+@end example
+
+@noindent
+write either this:
+
+@example
+int foo, bar;
+@end example
+
+@noindent
+or this:
+
+@example
+int foo;
+int bar;
+@end example
+
+@noindent
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+When you have an @code{if}-@code{else} statement nested in another
+@code{if} statement, always put braces around the @code{if}-@code{else}.
+Thus, never write like this:
+
+@example
+if (foo)
+  if (bar)
+    win ();
+  else
+    lose ();
+@end example
+
+@noindent
+always like this:
+
+@example
+if (foo)
+  @{
+    if (bar)
+      win ();
+    else
+      lose ();
+  @}
+@end example
+
+If you have an @code{if} statement nested inside of an @code{else}
+statement, either write @code{else if} on one line, like this,
+
+@example
+if (foo)
+  @dots{}
+else if (bar)
+  @dots{}
+@end example
+
+@noindent
+with its @code{then}-part indented like the preceding @code{then}-part,
+or write the nested @code{if} within braces like this:
+
+@example
+if (foo)
+  @dots{}
+else
+  @{
+    if (bar)
+      @dots{}
+  @}
+@end example
+
+Don't declare both a structure tag and variables or typedefs in the
+same declaration.  Instead, declare the structure tag separately
+and then use it to declare the variables or typedefs.
+
+Try to avoid assignments inside @code{if}-conditions.  For example,
+don't write this:
+
+@example
+if ((foo = (char *) malloc (sizeof *foo)) == 0)
+  fatal ("virtual memory exhausted");
+@end example
+
+@noindent
+instead, write this:
+
+@example
+foo = (char *) malloc (sizeof *foo);
+if (foo == 0)
+  fatal ("virtual memory exhausted");
+@end example
+
+Don't make the program ugly to placate @code{lint}.  Please don't insert any
+casts to @code{void}.  Zero without a cast is perfectly fine as a null
+pointer constant.
+
+@node  Names
+@chapter Naming Variables and Functions
+
+Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them.  Stick to lower case; reserve
+upper case for macros and @code{enum} constants, and for name-prefixes
+that follow a uniform convention.
+
+For example, you should use names like @code{ignore_space_change_flag};
+don't use names like @code{iCantReadThis}.
+
+Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter.  A comment should state both the exact meaning of
+the option and its letter.  For example,
+
+@example
+/* Ignore changes in horizontal whitespace (-b).  */
+int ignore_space_change_flag;
+@end example
+
+When you want to define names with constant integer values, use
+@code{enum} rather than @samp{#define}.  GDB knows about enumeration
+constants.
+
+Use file names of 14 characters or less, to avoid creating gratuitous
+problems on System V.  You can use the program @code{doschk} to test for
+this.  @code{doschk} also tests for potential name conflicts if the
+files were loaded onto an MS-DOS file system---something you may or may
+not care about.
+
+
+@node Using Extensions
+@chapter 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'' @code{INLINE}
+and define that as a macro to expand into either @code{inline} or
+nothing, depending on the compiler.
+
+In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+An exception to this rule are the large, established programs (such as
+Emacs) which run on a great variety of systems.  Such programs would
+be broken by use of GNU extensions.
+
+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 no good.
+
+Since most computer systems do not yet implement @sc{ANSI} C, using the
+@sc{ANSI} C features is effectively using a GNU extension, so the
+same considerations apply.  (Except for @sc{ANSI} features that we
+discourage, such as trigraphs---don't ever use them.)
+
+
+@node System Functions
+@chapter Calling System Functions
+
+C implementations differ substantially.  ANSI C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-ANSI compilers.  This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+
+@itemize @bullet
+@item
+Don't use the value of @code{sprintf}.  It returns the number of
+characters written on some systems, but not on all systems.
+
+@item
+Don't declare system functions explicitly.
+
+Almost any declaration for a system function is wrong on some system.
+To minimize conflicts, leave it to the system header files to declare
+system functions.  If the headers don't declare a function, let it
+remain undeclared.
+
+While it may seem unclean to use a function without declaring it, in
+practice this works fine for most system library functions on the
+systems where this really happens.  The problem is only theoretical.  By
+contrast, actual declarations have frequently caused actual conflicts.
+
+@item
+If you must declare a system function, don't specify the argument types.
+Use an old-style declaration, not an ANSI prototype.  The more you
+specify about the function, the more likely a conflict.
+
+@item
+In particular, don't unconditionally declare @code{malloc} or
+@code{realloc}.
+
+Most GNU programs use those functions just once, in functions
+conventionally named @code{xmalloc} and @code{xrealloc}.  These
+functions call @code{malloc} and @code{realloc}, respectively, and
+check the results.
+
+Because @code{xmalloc} and @code{xrealloc} are defined in your program,
+you can declare them in other files without any risk of type conflict.
+
+On most systems, @code{int} is the same length as a pointer; thus, the
+calls to @code{malloc} and @code{realloc} work fine.  For the few
+exceptional systems (mostly 64-bit machines), you can use
+@strong{conditionalized} declarations of @code{malloc} and
+@code{realloc}---or put these declarations in configuration files
+specific to those systems.
+
+@item
+The string functions require special treatment.  Some Unix systems have
+a header file @file{string.h}; other have @file{strings.h}.  Neither
+file name is portable.  There are two things you can do: use Autoconf to
+figure out which file to include, or don't include either file.
+
+@item
+If you don't include either strings file, you can't get declarations for
+the string functions from the header file in the usual way.
+
+That causes less of a problem than you might think.  The newer ANSI
+string functions are off-limits anyway because many systems still don't
+support them.  The string functions you can use are these:
+
+@example
+strcpy   strncpy   strcat   strncat
+strlen   strcmp   strncmp
+strchr   strrchr
+@end example
+
+The copy and concatenate functions work fine without a declaration as
+long as you don't use their values.  Using their values without a
+declaration fails on systems where the width of a pointer differs from
+the width of @code{int}, and perhaps in other cases.  It is trivial to
+avoid using their values, so do that.
+
+The compare functions and @code{strlen} work fine without a declaration
+on most systems, possibly all the ones that GNU software runs on.
+You may find it necessary to declare them @strong{conditionally} on a
+few systems.
+
+The search functions must be declared to return @code{char *}.  Luckily,
+there is no variation in the data type they return.  But there is
+variation in their names.  Some systems give these functions the names
+@code{index} and @code{rindex}; other systems use the names
+@code{strchr} and @code{strrchr}.  Some systems support both pairs of
+names, but neither pair works on all systems.
+
+You should pick a single pair of names and use it throughout your
+program.  (Nowadays, it is better to choose @code{strchr} and
+@code{strrchr}.)  Declare both of those names as functions returning
+@code{char *}.  On systems which don't support those names, define them
+as macros in terms of the other pair.  For example, here is what to put
+at the beginning of your file (or in a header) if you want to use the
+names @code{strchr} and @code{strrchr} throughout:
+
+@example
+#ifndef HAVE_STRCHR
+#define strchr index
+#endif
+#ifndef HAVE_STRRCHR
+#define strrchr rindex
+#endif
+
+char *strchr ();
+char *strrchr ();
+@end example
+@end itemize
+
+Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
+macros defined in systems where the corresponding functions exist.
+One way to get them properly defined is to use Autoconf.
+
+@node Semantics
+@chapter Program Behavior for All Programs
+
+Avoid arbitrary limits on the length or number of @emph{any} data
+structure, including filenames, 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 @emph{including those with codes above 0177}.  The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of printers that can't handle those characters.
+
+Check every system call for an error return, unless you know you wish to
+ignore errors.  Include the system error text (from @code{perror} or
+equivalent) in @emph{every} error message resulting from a failing
+system call, as well as the name of the file if any and the name of the
+utility.  Just ``cannot open foo.c'' or ``stat failed'' is not
+sufficient.
+
+Check every call to @code{malloc} or @code{realloc} to see if it
+returned zero.  Check @code{realloc} even if you are making the block
+smaller; in a system that rounds block sizes to a power of 2,
+@code{realloc} may get a different block if you ask for less space.
+
+In Unix, @code{realloc} can destroy the storage block if it returns
+zero.  GNU @code{realloc} does not have this bug: if it fails, the
+original block is unchanged.  Feel free to assume the bug is fixed.  If
+you wish to run your program on Unix, and wish to avoid lossage in this
+case, you can use the GNU @code{malloc}.
+
+You must expect @code{free} to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling @code{free}.
+
+Use @code{getopt_long} to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+
+Try to avoid low-level interfaces to obscure Unix data structures (such
+as file directories, utmp, or the layout of kernel memory), since these
+are less likely to work compatibly.  If you need to find all the files
+in a directory, use @code{readdir} or some other high-level interface.
+These will be supported compatibly by GNU.
+
+By default, the GNU system will provide the signal handling functions of
+@sc{BSD} and of @sc{POSIX}.  So GNU software should be written to use
+these.
+
+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.
+
+
+@node Errors
+@chapter Formatting Error Messages
+
+Error messages from compilers should look like this:
+
+@example
+@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+Error messages from other noninteractive programs should look like this:
+
+@example
+@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
+@end example
+
+@noindent
+when there is an appropriate source file, or like this:
+
+@example
+@var{program}: @var{message}
+@end example
+
+@noindent
+when there is no relevant source file.
+
+In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+The string @var{message} should not begin with a capital letter when
+it follows a program name and/or filename.  Also, it should not end
+with a period.
+
+Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter.  But they should not
+end with a period.
+
+
+@node Libraries
+@chapter 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 @code{malloc} itself.
+
+Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this
+prefix.  In addition, there should only be one of these in any given
+library member.  This usually means putting each one in a separate
+source file.
+
+An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+External symbols that are not documented entry points for the user
+should have names beginning with @samp{_}.  They should also contain
+the chosen name prefix for the library, to prevent collisions with
+other libraries.  These can go in the same files with user entry
+points if you like.
+
+Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+
+@node Portability
+@chapter Portability As It Applies to GNU
+
+Much of what is called ``portability'' in the Unix world refers to
+porting to different Unix versions.  This is a secondary consideration
+for GNU software, because its primary purpose is to run on top of one
+and only one kernel, the GNU kernel, compiled with one and only one C
+compiler, the GNU C compiler.  The amount and kinds of variation among
+GNU systems on different cpu's will be like the variation among Berkeley
+4.3 systems on different cpu's.
+
+All users today run GNU software on non-GNU systems.  So supporting a
+variety of non-GNU systems is desirable; simply not paramount.
+The easiest way to achieve portability to a reasonable range of systems
+is to use Autoconf.  It's unlikely that your program needs to know more
+information about the host machine than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+It is difficult to be sure exactly what facilities the GNU kernel
+will provide, since it isn't finished yet.  Therefore, assume you can
+use anything in 4.3; just avoid using the format of semi-internal data
+bases (e.g., directories) when there is a higher-level alternative
+(@code{readdir}).
+
+You can freely assume any reasonably standard facilities in the C
+language, libraries or kernel, because we will find it necessary to
+support these facilities in the full GNU system, whether or not we
+have already done so.  The fact that there may exist kernels or C
+compilers that lack these facilities is irrelevant as long as the GNU
+kernel and C compiler support them.
+
+It remains necessary to worry about differences among cpu types, such
+as the difference in byte ordering and alignment restrictions.  It's
+unlikely that 16-bit machines will ever be supported by GNU, so there
+is no point in spending any time to consider the possibility that an
+int will be less than 32 bits.
+
+You can assume that all pointers have the same format, regardless
+of the type they point to, and that this is really an integer.
+There are some weird machines where this isn't true, but they aren't
+important; don't waste time catering to them.  Besides, eventually
+we will put function prototypes into all GNU programs, and that will
+probably make your program work even on weird machines.
+
+Since some important machines (including the 68000) are big-endian,
+it is important not to assume that the address of an @code{int} object
+is also the address of its least-significant byte.  Thus, don't
+make the following mistake:
+
+@example
+int c;
+@dots{}
+while ((c = getchar()) != EOF)
+        write(file_descriptor, &c, 1);
+@end example
+
+You can assume that it is reasonable to use a meg of memory.  Don't
+strain to reduce memory usage unless it can get to that level.  If
+your program creates complicated data structures, just make them in
+core and give a fatal error if malloc returns zero.
+
+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.
+
+
+@node User Interfaces
+@chapter Standards for Command Line Interfaces
+
+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.
+
+If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+Compatibility requires certain programs to depend on the type of output
+device.  It would be disastrous if @code{ls} or @code{sh} did not do so
+in the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a @code{dir} program much
+like @code{ls} except that its default output format is always
+multi-column format.
+
+It is a good idea to follow the @sc{POSIX} guidelines for the
+command-line options of a program.  The easiest way to do this is to use
+@code{getopt} to parse them.  Note that the GNU version of @code{getopt}
+will normally permit options anywhere among the arguments unless the
+special argument @samp{--} is used.  This is not what @sc{POSIX}
+specifies; it is a GNU extension.
+
+Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+@code{getopt_long}.
+
+One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the ``verbose'' option of any GNU program which has one, to be
+spelled precisely @samp{--verbose}.  To achieve this uniformity, look at
+the table of common long-option names when you choose the option names
+for your program.  The table appears below.
+
+If you use names not already in the table, please send
+@samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we
+can update the table.
+
+It is usually a good idea for file names given as ordinary arguments
+to be input files only; any output files would be specified using
+options (preferably @samp{-o}).  Even if you allow an output file name
+as an ordinary argument for compatibility, try to provide a suitable
+option as well.  This will lead to more consistency among GNU
+utilities, so that there are fewer idiosyncracies for users to
+remember.
+
+Programs should support an option @samp{--version} which prints the
+program's version number on standard output and exits successfully, and
+an option @samp{--help} which prints option usage information on
+standard output and exits successfully.  These options should inhibit
+the normal function of the command; they should do nothing except print
+the requested information.
+
+@c Please leave newlines between items in this table; it's much easier
+@c to update when it isn't completely squashed together and unreadable.
+@c When there is more than one short option for a long option name, put
+@c a semicolon between the lists of the programs that use them, not a
+@c period.   --friedman
+
+@table @samp
+
+@item auto-check
+@samp{-a} in @code{recode}.
+
+@item auto-reference
+@samp{-A} in @code{ptx}.
+
+@item after-date
+@samp{-N} in @code{tar}.
+
+@item all
+@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
+and @code{unexpand}.
+
+@item all-text
+@samp{-a} in @code{diff}.
+
+@item almost-all
+@samp{-A} in @code{ls}.
+
+@item append
+@samp{-a} in @code{etags}, @code{tee}, @code{time};
+@samp{-r} in @code{tar}.
+
+@item archive
+@samp{-a} in @code{cp}.
+
+@item arglength
+@samp{-l} in @code{m4}.
+
+@item ascii
+@samp{-a} in @code{diff}.
+
+@item assume-new
+@samp{-W} in Make.
+
+@item assume-old
+@samp{-o} in Make.
+
+@item backward-search
+@samp{-B} in etags.
+
+@item batch
+Used in GDB.
+
+@item baud
+Used in GDB.
+
+@item before
+@samp{-b} in @code{tac}.
+
+@item binary
+@samp{-b} in @code{cpio} and @code{diff}.
+
+@item block-size
+Used in @code{cpio} and @code{tar}.
+
+@item blocks
+@samp{-b} in @code{head} and @code{tail}.
+
+@item break-file
+@samp{-b} in @code{ptx}.
+
+@item brief
+Used in various programs to make output shorter.
+
+@item bytes
+@samp{-c} in @code{head}, @code{split}, and @code{tail}.
+
+@item c++
+@samp{-C} in @code{etags}.
+
+@item catenate
+@samp{-A} in @code{tar}.
+
+@item cd
+Used in various programs to specify the directory to use.
+
+@item changes
+@samp{-c} in @code{chgrp} and @code{chown}.
+
+@item classify
+@samp{-F} in @code{ls}.
+
+@item colons
+@samp{-c} in @code{recode}.
+
+@item command
+@samp{-c} in @code{su};
+@samp{-x} in GDB.
+
+@item compare
+@samp{-d} in @code{tar}.
+
+@item compress
+@samp{-Z} in @code{tar}.
+
+@item concatenate
+@samp{-A} in @code{tar}.
+
+@item confirmation
+@samp{-w} in @code{tar}.
+
+@item context
+Used in @code{diff}.
+
+@item copyright
+@samp{-C} in @code{ptx} and @code{recode}.
+
+@item core
+Used in GDB.
+
+@item count
+@samp{-q} in @code{who}.
+
+@item count-links
+@samp{-l} in @code{du}.
+
+@item create
+Used in @code{tar} and @code{cpio}.
+
+@item cxref
+@samp{-x} in @code{etags}.
+
+@item date
+@samp{-d} in @code{touch}.
+
+@item debug
+@samp{-d} in Make and @code{m4};
+@samp{-t} in Bison.
+
+@item define
+@samp{-D} in @code{m4}.
+
+@item defines
+@samp{-d} in Bison and @code{etags}.
+
+@item delete
+@samp{-D} in @code{tar}.
+
+@item dereference
+@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
+@code{ls}, and @code{tar}.
+
+@item dereference-args
+@samp{-D} in @code{du}.
+
+@item diacritics
+@samp{-d} in @code{recode}.
+
+@item dictionary-order
+@samp{-d} in @code{look}.
+
+@item diff
+@samp{-d} in @code{tar}.
+
+@item digits
+@samp{-n} in @code{csplit}.
+
+@item directory
+Specify the directory to use, in various programs.  In @code{ls}, it
+means to show directories themselves rather than their contents.  In
+@code{rm} and @code{ln}, it means to not treat links to directories
+specially.
+
+@item discard-all
+@samp{-x} in @code{strip}.
+
+@item discard-locals
+@samp{-X} in @code{strip}.
+
+@item diversions
+@samp{-N} in @code{m4}.
+
+@item dry-run
+@samp{-n} in Make.
+
+@item ed
+@samp{-e} in @code{diff}.
+
+@item elide-empty-files
+@samp{-z} in @code{csplit}.
+
+@item entire-new-file
+@samp{-N} in @code{diff}.
+
+@item environment-overrides
+@samp{-e} in Make.
+
+@item eof
+@samp{-e} in @code{xargs}.
+
+@item epoch
+Used in GDB.
+
+@item error-limit
+Used in Makeinfo.
+
+@item error-output
+@samp{-o} in @code{m4}.
+
+@item escape
+@samp{-b} in @code{ls}.
+
+@item exclude-from
+@samp{-X} in @code{tar}.
+
+@item exec
+Used in GDB.
+
+@item exit
+@samp{-x} in @code{xargs}.
+
+@item expand-tabs
+@samp{-t} in @code{diff}.
+
+@item expression
+@samp{-e} in @code{sed}.
+
+@item extern-only
+@samp{-g} in @code{nm}.
+
+@item extract
+@samp{-i} in @code{cpio};
+@samp{-x} in @code{tar}.
+
+@item faces
+@samp{-f} in @code{finger}.
+
+@item fast
+@samp{-f} in @code{su}.
+
+@item file
+@samp{-f} in @code{info}, Make, @code{mt}, and @code{tar};
+@samp{-n} in @code{sed};
+@samp{-r} in @code{touch}.
+
+@item file-prefix
+@samp{-b} in Bison.
+
+@item file-type
+@samp{-F} in @code{ls}.
+
+@item files-from
+@samp{-T} in @code{tar}.
+
+@item fill-column
+Used in Makeinfo.
+
+@item flag-truncation
+@samp{-F} in @code{ptx}.
+
+@item fixed-output-files
+@samp{-y} in Bison.
+
+@item follow
+@samp{-f} in @code{tail}.
+
+@item footnote-style
+Used in Makeinfo.
+
+@item force
+@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
+
+@item format
+Used in @code{ls}, @code{time}, and @code{ptx}.
+
+@item forward-search
+@samp{-F} in @code{etags}.
+
+@item fullname
+Used in GDB.
+
+@item gap-size
+@samp{-g} in @code{ptx}.
+
+@item get
+@samp{-x} in @code{tar}.
+
+@item graphic
+@samp{-i} in @code{ul}.
+
+@item graphics
+@samp{-g} in @code{recode}.
+
+@item group
+@samp{-g} in @code{install}.
+
+@item gzip
+@samp{-z} in @code{tar}.
+
+@item hashsize
+@samp{-H} in @code{m4}.
+
+@item header
+@samp{-h} in @code{objdump} and @code{recode}
+
+@item heading
+@samp{-H} in @code{who}.
+
+@item help
+Used to ask for brief usage information.
+
+@item hide-control-chars
+@samp{-q} in @code{ls}.
+
+@item idle
+@samp{-u} in @code{who}.
+
+@item ifdef
+@samp{-D} in @code{diff}.
+
+@item ignore
+@samp{-I} in @code{ls};
+@samp{-x} in @code{recode}.
+
+@item ignore-all-space
+@samp{-w} in @code{diff}.
+
+@item ignore-backups
+@samp{-B} in @code{ls}.
+
+@item ignore-blank-lines
+@samp{-B} in @code{diff}.
+
+@item ignore-case
+@samp{-f} in @code{look} and @code{ptx};
+@samp{-i} in @code{diff}.
+
+@item ignore-errors
+@samp{-i} in Make.
+
+@item ignore-file
+@samp{-i} in @code{ptx}.
+
+@item ignore-indentation
+@samp{-S} in @code{etags}.
+
+@item ignore-init-file
+@samp{-f} in Oleo.
+
+@item ignore-interrupts
+@samp{-i} in @code{tee}.
+
+@item ignore-matching-lines
+@samp{-I} in @code{diff}.
+
+@item ignore-space-change
+@samp{-b} in @code{diff}.
+
+@item ignore-zeros
+@samp{-i} in @code{tar}.
+
+@item include
+@samp{-i} in @code{etags};
+@samp{-I} in @code{m4}.
+
+@item include-dir
+@samp{-I} in Make.
+
+@item incremental
+@samp{-G} in @code{tar}.
+
+@item info
+@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
+
+@item initial
+@samp{-i} in @code{expand}.
+
+@item initial-tab
+@samp{-T} in @code{diff}.
+
+@item inode
+@samp{-i} in @code{ls}.
+
+@item interactive
+@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
+@samp{-e} in @code{m4};
+@samp{-p} in @code{xargs};
+@samp{-w} in @code{tar}.
+
+@item jobs
+@samp{-j} in Make.
+
+@item just-print
+@samp{-n} in Make.
+
+@item keep-going
+@samp{-k} in Make.
+
+@item keep-files
+@samp{-k} in @code{csplit}.
+
+@item kilobytes
+@samp{-k} in @code{du} and @code{ls}.
+
+@item line-bytes
+@samp{-C} in @code{split}.
+
+@item lines
+Used in @code{split}, @code{head}, and @code{tail}.
+
+@item link
+@samp{-l} in @code{cpio}.
+
+@item list
+@samp{-t} in @code{cpio};
+@samp{-l} in @code{recode}.
+
+@item list
+@samp{-t} in @code{tar}.
+
+@item literal
+@samp{-N} in @code{ls}.
+
+@item load-average
+@samp{-l} in Make.
+
+@item login
+Used in @code{su}.
+
+@item machine
+No listing of which programs already use this;
+someone should check to
+see if any actually do and tell @code{gnu@@prep.ai.mit.edu}.
+
+@item macro-name
+@samp{-M} in @code{ptx}.
+
+@item mail
+@samp{-m} in @code{hello} and @code{uname}.
+
+@item make-directories
+@samp{-d} in @code{cpio}.
+
+@item makefile
+@samp{-f} in Make.
+
+@item mapped
+Used in GDB.
+
+@item max-args
+@samp{-n} in @code{xargs}.
+
+@item max-chars
+@samp{-n} in @code{xargs}.
+
+@item max-lines
+@samp{-l} in @code{xargs}.
+
+@item max-load
+@samp{-l} in Make.
+
+@item max-procs
+@samp{-P} in @code{xargs}.
+
+@item mesg
+@samp{-T} in @code{who}.
+
+@item message
+@samp{-T} in @code{who}.
+
+@item minimal
+@samp{-d} in @code{diff}.
+
+@item mode
+@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
+
+@item modification-time
+@samp{-m} in @code{tar}.
+
+@item multi-volume
+@samp{-M} in @code{tar}.
+
+@item name-prefix
+@samp{-a} in Bison.
+
+@item new-file
+@samp{-W} in Make.
+
+@item no-builtin-rules
+@samp{-r} in Make.
+
+@item no-create
+@samp{-c} in @code{touch}.
+
+@item no-defines
+@samp{-D} in @code{etags}.
+
+@item no-dereference
+@samp{-d} in @code{cp}.
+
+@item no-keep-going
+@samp{-S} in Make.
+
+@item no-lines
+@samp{-l} in Bison.
+
+@item no-prof
+@samp{-e} in @code{gprof}.
+
+@item no-sort
+@samp{-p} in @code{nm}.
+
+@item no-split
+Used in Makeinfo.
+
+@item no-static
+@samp{-a} in @code{gprof}.
+
+@item no-time
+@samp{-E} in @code{gprof}.
+
+@item no-validate
+Used in Makeinfo.
+
+@item no-warn
+Used in various programs to inhibit warnings.
+
+@item node
+@samp{-n} in @code{info}.
+
+@item nodename
+@samp{-n} in @code{uname}.
+
+@item nonmatching
+@samp{-f} in @code{cpio}.
+
+@item nstuff
+@samp{-n} in @code{objdump}.
+
+@item null
+@samp{-0} in @code{xargs}.
+
+@item number
+@samp{-n} in @code{cat}.
+
+@item number-nonblank
+@samp{-b} in @code{cat}.
+
+@item numeric-sort
+@samp{-n} in @code{nm}.
+
+@item numeric-uid-gid
+@samp{-n} in @code{cpio} and @code{ls}.
+
+@item nx
+Used in GDB.
+
+@item old-archive
+@samp{-o} in @code{tar}.
+
+@item old-file
+@samp{-o} in Make.
+
+@item one-file-system
+@samp{-l} in @code{tar}, @code{cp}, and @code{du}.
+
+@item only-file
+@samp{-o} in @code{ptx}.
+
+@item only-prof
+@samp{-f} in @code{gprof}.
+
+@item only-time
+@samp{-F} in @code{gprof}.
+
+@item output
+In various programs, specify the output file name.
+
+@item override
+@samp{-o} in @code{rm}.
+
+@item owner
+@samp{-o} in @code{install}.
+
+@item paginate
+@samp{-l} in @code{diff}.
+
+@item paragraph-indent
+Used in Makeinfo.
+
+@item parents
+@samp{-p} in @code{mkdir} and @code{rmdir}.
+
+@item pass-all
+@samp{-p} in @code{ul}.
+
+@item pass-through
+@samp{-p} in @code{cpio}.
+
+@item port
+@samp{-P} in @code{finger}.
+
+@item portability
+@samp{-c} in @code{cpio} and @code{tar}.
+
+@item prefix-builtins
+@samp{-P} in @code{m4}.
+
+@item prefix
+@samp{-f} in @code{csplit}.
+
+@item preserve
+Used in @code{tar} and @code{cp}.
+
+@item preserve-environment
+@samp{-p} in @code{su}.
+
+@item preserve-modification-time
+@samp{-m} in @code{cpio}.
+
+@item preserve-order
+@samp{-s} in @code{tar}.
+
+@item preserve-permissions
+@samp{-p} in @code{tar}.
+
+@item print
+@samp{-l} in @code{diff}.
+
+@item print-chars
+@samp{-L} in @code{cmp}.
+
+@item print-data-base
+@samp{-p} in Make.
+
+@item print-directory
+@samp{-w} in Make.
+
+@item print-file-name
+@samp{-o} in @code{nm}.
+
+@item print-symdefs
+@samp{-s} in @code{nm}.
+
+@item question
+@samp{-q} in Make.
+
+@item quiet
+Used in many programs to inhibit the usual output.  @strong{Note:} every
+program accepting @samp{--quiet} should accept @samp{--silent} as a
+synonym.
+
+@item quote-name
+@samp{-Q} in @code{ls}.
+
+@item rcs
+@samp{-n} in @code{diff}.
+
+@item read-full-blocks
+@samp{-B} in @code{tar}.
+
+@item readnow
+Used in GDB.
+
+@item recon
+@samp{-n} in Make.
+
+@item record-number
+@samp{-R} in @code{tar}.
+
+@item recursive
+Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
+and @code{rm}.
+
+@item reference-limit
+Used in Makeinfo.
+
+@item references
+@samp{-r} in @code{ptx}.
+
+@item regex
+@samp{-r} in @code{tac}.
+
+@item release
+@samp{-r} in @code{uname}.
+
+@item relocation
+@samp{-r} in @code{objdump}.
+
+@item rename
+@samp{-r} in @code{cpio}.
+
+@item replace
+@samp{-i} in @code{xargs}.
+
+@item report-identical-files
+@samp{-s} in @code{diff}.
+
+@item reset-access-time
+@samp{-a} in @code{cpio}.
+
+@item reverse
+@samp{-r} in @code{ls} and @code{nm}.
+
+@item reversed-ed
+@samp{-f} in @code{diff}.
+
+@item right-side-defs
+@samp{-R} in @code{ptx}.
+
+@item same-order
+@samp{-s} in @code{tar}.
+
+@item same-permissions
+@samp{-p} in @code{tar}.
+
+@item save
+@samp{-g} in @code{stty}.
+
+@item se
+Used in GDB.
+
+@item sentence-regexp
+@samp{-S} in @code{ptx}.
+
+@item separate-dirs
+@samp{-S} in @code{du}.
+
+@item separator
+@samp{-s} in @code{tac}.
+
+@item sequence
+Used by @code{recode} to chose files or pipes for sequencing passes.
+
+@item shell
+@samp{-s} in @code{su}.
+
+@item show-all
+@samp{-A} in @code{cat}.
+
+@item show-c-function
+@samp{-p} in @code{diff}.
+
+@item show-ends
+@samp{-E} in @code{cat}.
+
+@item show-function-line
+@samp{-F} in @code{diff}.
+
+@item show-tabs
+@samp{-T} in @code{cat}.
+
+@item silent
+Used in many programs to inhibit the usual output.
+@strong{Note:} every program accepting
+@samp{--silent} should accept @samp{--quiet} as a synonym.
+
+@item size
+@samp{-s} in @code{ls}.
+
+@item sort
+Used in @code{ls}.
+
+@item sparse
+@samp{-S} in @code{tar}.
+
+@item speed-large-files
+@samp{-H} in @code{diff}.
+
+@item squeeze-blank
+@samp{-s} in @code{cat}.
+
+@item starting-file
+Used in @code{tar} and @code{diff} to specify which file within
+a directory to start processing with.
+
+@item stop
+@samp{-S} in Make.
+
+@item strict
+@samp{-s} in @code{recode}.
+
+@item strip
+@samp{-s} in @code{install}.
+
+@item strip-all
+@samp{-s} in @code{strip}.
+
+@item strip-debug
+@samp{-S} in @code{strip}.
+
+@item suffix
+@samp{-S} in @code{cp}, @code{ln}, @code{mv}.
+
+@item suffix-format
+@samp{-b} in @code{csplit}.
+
+@item sum
+@samp{-s} in @code{gprof}.
+
+@item summarize
+@samp{-s} in @code{du}.
+
+@item symbolic
+@samp{-s} in @code{ln}.
+
+@item symbols
+Used in GDB and @code{objdump}.
+
+@item synclines
+@samp{-s} in @code{m4}.
+
+@item sysname
+@samp{-s} in @code{uname}.
+
+@item tabs
+@samp{-t} in @code{expand} and @code{unexpand}.
+
+@item tabsize
+@samp{-T} in @code{ls}.
+
+@item terminal
+@samp{-T} in @code{tput} and @code{ul}.
+
+@item text
+@samp{-a} in @code{diff}.
+
+@item time
+Used in @code{ls} and @code{touch}.
+
+@item to-stdout
+@samp{-O} in @code{tar}.
+
+@item total
+@samp{-c} in @code{du}.
+
+@item touch
+@samp{-t} in Make, @code{ranlib}, and @code{recode}.
+
+@item trace
+@samp{-t} in @code{m4}.
+
+@item traditional
+@samp{-t} in @code{hello};
+@samp{-G} in @code{m4} and @code{ptx}.
+
+@item tty
+Used in GDB.
+
+@item typedefs
+@samp{-t} in @code{etags}.
+
+@item typedefs-and-c++
+@samp{-T} in @code{etags}.
+
+@item typeset-mode
+@samp{-t} in @code{ptx}.
+
+@item uncompress
+@samp{-z} in @code{tar}.
+
+@item unconditional
+@samp{-u} in @code{cpio}.
+
+@item undefine
+@samp{-U} in @code{m4}.
+
+@item undefined-only
+@samp{-u} in @code{nm}.
+
+@item update
+@samp{-u} in @code{cp}, @samp{etags}, @samp{mv}, @samp{tar}.
+
+@item verbose
+Print more information about progress.  Many programs support this.
+
+@item verify
+@samp{-W} in @code{tar}.
+
+@item version
+Print the version number.
+
+@item version-control
+@samp{-V} in @code{cp}, @code{ln}, @code{mv}.
+
+@item vgrind
+@samp{-v} in @code{etags}.
+
+@item volume
+@samp{-V} in @code{tar}.
+
+@item what-if
+@samp{-W} in Make.
+
+@item width
+@samp{-w} in @code{ls} and @code{ptx}.
+
+@item word-regexp
+@samp{-W} in @code{ptx}.
+
+@item writable
+@samp{-T} in @code{who}.
+
+@item zeros
+@samp{-z} in @code{gprof}.
+
+@end table
+
+@node Documentation
+@chapter Documenting Programs
+
+Please use Texinfo for documenting GNU programs.  See the Texinfo
+manual, either the hardcopy or the version in the GNU Emacs Info
+subsystem (@kbd{C-h i}).  See existing GNU Texinfo files (e.g., those
+under the @file{man/} directory in the GNU Emacs distribution) for
+examples.
+
+The title page of the manual should state the version of the program
+which the manual applies to.  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.
+
+The manual should document all command-line arguments and all
+commands.  It should give examples of their use.  But don't organize
+the manual as a list of features.  Instead, organize it by the
+concepts a user will have before reaching that point in the manual.
+Address the goals that a user will have in mind, and explain how to
+accomplish them.  Don't use Unix man pages as a model for how to
+write GNU documentation; they are a bad example to follow.
+
+The manual should have a node named @samp{@var{program} Invocation} or
+@samp{Invoking @var{program}}, where @var{program} stands for the name
+of the program being described, as you would type it in the shell to run
+the program.  This node (together with its subnodes, if any) should
+describe the program's command line arguments and how to run it (the
+sort of information people would look in a man page for).  Start with an
+@samp{@@example} containing a template for all the options and arguments
+that the program uses.
+
+Alternatively, put a menu item in some menu whose item name fits one of
+the above patterns.  This identifies the node which that item points to
+as the node for this purpose, regardless of the node's actual name.
+
+There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+If one manual describes several programs, it should have such a node for
+each program described.
+
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning.  In each new release, add items to the front of the file and
+identify the version they pertain to.  Don't discard old items; leave
+them in the file after the newer items.  This way, a user upgrading from
+any previous version can see what is new.
+
+If the @file{NEWS} file gets very long, move some of the older items
+into a file named @file{ONEWS} and put a note at the end referring the
+user to that file.
+
+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 file names.
+
+It is ok to supply a man page for the program as well as a Texinfo
+manual if you wish to.  But keep in mind that supporting a man page
+requires continual effort, each time the program is changed.  Any time
+you spend on the man page is time taken away from more useful things you
+could contribute.
+
+Thus, even if a user volunteers to donate a man page, you may find this
+gift costly to accept.  Unless you have time on your hands, it may be
+better to refuse the man page unless the same volunteer agrees to take
+full responsibility for maintaining it---so that you can wash your hands
+of it entirely.  If the volunteer ceases to do the job, then don't feel
+obliged to pick it up yourself; it may be better to withdraw the man
+page until another volunteer offers to carry on with it.
+
+Alternatively, if you expect the discrepancies to be small enough that
+the man page remains useful, 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, and describing how to access the Texinfo
+documentation.
+
+@node Releases
+@chapter Making Releases
+
+Package the distribution of Foo version 69.96 in a gzipped tar file
+named @file{foo-69.96.tar.gz}.  It should unpack into a subdirectory
+named @file{foo-69.96}.
+
+Building and installing the program should never modify any of the files
+contained in the distribution.  This means that all the files that form
+part of the program in any way must be classified into @dfn{source
+files} and @dfn{non-source files}.  Source files are written by humans
+and never changed automatically; non-source files are produced from
+source files by programs under the control of the Makefile.
+
+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 @strong{never} be included in the
+distribution.  So if you do distribute non-source files, always make
+sure they are up to date when you make a new distribution.
+
+Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of @code{tar} which preserve the
+ownership and permissions of the files from the tar archive will be
+able to extract all the files even if the user is unprivileged.
+
+Make sure that all the files in the distribution are world-readable.
+
+Make sure that no file name in the distribution is more than 14
+characters long.  Likewise, no file created by building the program
+should have a name longer than 14 characters.  The reason for this is
+that some systems adhere to a foolish interpretation of the 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-DOG.  A
+name on MS-DOG consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOG will truncate extra
+characters both before and after the period.  Thus,
+@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
+distinct.
+
+Include in your distribution a copy of the @file{texinfo.tex} you used
+to test print any @file{*.texinfo} 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.
+
+@contents
+
+@bye