update.
[chise/xemacs-chise.git-] / info / standards.info-3
index 426dd71..5a6af11 100644 (file)
@@ -1,12 +1,12 @@
-This is Info file ../info/standards.info, produced by Makeinfo version
-1.68 from the input file standards.texi.
+This is ../info/standards.info, produced by makeinfo version 4.0 from
+standards.texi.
 
 START-INFO-DIR-ENTRY
 * Standards: (standards).        GNU coding standards.
 END-INFO-DIR-ENTRY
 
-   GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
-Software Foundation, Inc.
+   GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
+1997, 1998, 1999 Free Software Foundation, Inc.
 
    Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are
@@ -23,7 +23,389 @@ versions, except that this permission notice may be stated in a
 translation approved by the Free Software Foundation.
 
 \1f
-File: standards.info,  Node: Standard Targets,  Prev: Directory Variables,  Up: Makefile Conventions
+File: standards.info,  Node: Utilities in Makefiles,  Next: Command Variables,  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 diff echo egrep expr false grep install-info
+     ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+   The compression program `gzip' can be used in the `dist' rule.
+
+   Stick to the generally supported options for these programs.  For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+   It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+   The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives.  Here are some of the
+programs we mean:
+
+     ar bison cc flex install ld ldconfig lex
+     make makeinfo ranlib texi2dvi yacc
+
+   Use the following `make' variables to run those programs:
+
+     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+   When you use `ranlib' or `ldconfig', you should make sure nothing
+bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem.  (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+   If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+   Additional utilities that can be used via Make variables are:
+
+     chgrp chmod chown mknod
+
+   It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+\1f
+File: standards.info,  Node: Command Variables,  Next: Directory Variables,  Prev: Utilities in Makefiles,  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 names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.)  Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+   If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'.  Users
+expect to be able to specify `CFLAGS' freely themselves.  Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+     CFLAGS = -g
+     ALL_CFLAGS = -I. $(CFLAGS)
+     .c.o:
+             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+   Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation.  You can consider it a default that
+is only recommended.  If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+   Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+   `CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+   Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+   Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'.  (The default for 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
+
+   Optionally, you may prepend the value of `DESTDIR' to the target
+filename.  Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later.  Do not
+set the value of `DESTDIR' in your Makefile, and do not include it in
+any installed files.  With support for `DESTDIR', the above examples
+become:
+
+     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+\1f
+File: standards.info,  Node: Directory Variables,  Next: Standard Targets,  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 described below.  They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
+other modern operating systems.
+
+   These two variables set the root for the installation.  All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+     A prefix used in constructing the default values of the variables
+     listed below.  The default value of `prefix' should be
+     `/usr/local'.  When building the complete GNU system, the prefix
+     will be empty and `/usr' will be a symbolic link to `/'.  (If you
+     are using Autoconf, write it as `@prefix@'.)
+
+     Running `make install' with a different value of `prefix' from the
+     one used to build the program should NOT recompile the program.
+
+`exec_prefix'
+     A prefix used in constructing the default values of some of the
+     variables listed below.  The default value of `exec_prefix' should
+     be `$(prefix)'.  (If you are using Autoconf, write it as
+     `@exec_prefix@'.)
+
+     Generally, `$(exec_prefix)' is used for directories that contain
+     machine-specific files (such as executables and subroutine
+     libraries), while `$(prefix)' is used directly for other
+     directories.
+
+     Running `make install' with a different value of `exec_prefix'
+     from the one used to build the program should NOT recompile the
+     program.
+
+   Executable programs are installed in one of the following
+directories.
+
+`bindir'
+     The directory for installing executable programs that users can
+     run.  This should normally be `/usr/local/bin', but write it as
+     `$(exec_prefix)/bin'.  (If you are using Autoconf, write it as
+     `@bindir@'.)
+
+`sbindir'
+     The directory for installing executable programs that can be run
+     from the shell, but are only generally useful to system
+     administrators.  This should normally be `/usr/local/sbin', but
+     write it as `$(exec_prefix)/sbin'.  (If you are using Autoconf,
+     write it as `@sbindir@'.)
+
+`libexecdir'
+     The directory for installing executable programs to be run by other
+     programs rather than by users.  This directory should normally be
+     `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+     (If you are using Autoconf, write it as `@libexecdir@'.)
+
+   Data files used by the program during its execution are divided into
+categories in two ways.
+
+   * Some files are normally modified by programs; others are never
+     normally modified (though users may edit some of these).
+
+   * Some files are architecture-independent and can be shared by all
+     machines at a site; some are architecture-dependent and can be
+     shared only by machines of the same kind and operating system;
+     others may never be shared between two machines.
+
+   This makes for six different possibilities.  However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries.  It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+   Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+     The directory for installing read-only architecture independent
+     data files.  This should normally be `/usr/local/share', but write
+     it as `$(prefix)/share'.  (If you are using Autoconf, write it as
+     `@datadir@'.)  As a special exception, see `$(infodir)' and
+     `$(includedir)' below.
+
+`sysconfdir'
+     The directory for installing read-only data files that pertain to a
+     single machine-that is to say, files for configuring a host.
+     Mailer and network configuration files, `/etc/passwd', and so
+     forth belong here.  All the files in this directory should be
+     ordinary ASCII text files.  This directory should normally be
+     `/usr/local/etc', but write it as `$(prefix)/etc'.  (If you are
+     using Autoconf, write it as `@sysconfdir@'.)
+
+     Do not install executables here in this directory (they probably
+     belong in `$(libexecdir)' or `$(sbindir)').  Also do not install
+     files that are modified in the normal course of their use (programs
+     whose purpose is to change the configuration of the system
+     excluded).  Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+     The directory for installing architecture-independent data files
+     which the programs modify while they run.  This should normally be
+     `/usr/local/com', but write it as `$(prefix)/com'.  (If you are
+     using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+     The directory for installing data files which the programs modify
+     while they run, and that pertain to one specific machine.  Users
+     should never need to modify files in this directory to configure
+     the package's operation; put such configuration information in
+     separate files that go in `$(datadir)' or `$(sysconfdir)'.
+     `$(localstatedir)' should normally be `/usr/local/var', but write
+     it as `$(prefix)/var'.  (If you are using Autoconf, write it as
+     `@localstatedir@'.)
+
+`libdir'
+     The directory for object files and libraries of object code.  Do
+     not install executables here, they probably ought to go in
+     `$(libexecdir)' instead.  The value of `libdir' should normally be
+     `/usr/local/lib', but write it as `$(exec_prefix)/lib'.  (If you
+     are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+     The directory for installing the Info files for this package.  By
+     default, it should be `/usr/local/info', but it should be written
+     as `$(prefix)/info'.  (If you are using Autoconf, write it as
+     `@infodir@'.)
+
+`lispdir'
+     The directory for installing any Emacs Lisp files in this package.
+     By default, it should be `/usr/local/share/emacs/site-lisp', but
+     it should be written as `$(prefix)/share/emacs/site-lisp'.
+
+     If you are using Autoconf, write the default as `@lispdir@'.  In
+     order to make `@lispdir@' work, you need the following lines in
+     your `configure.in' file:
+
+          lispdir='${datadir}/emacs/site-lisp'
+          AC_SUBST(lispdir)
+
+`includedir'
+     The directory for installing header files to be included by user
+     programs with the C `#include' preprocessor directive.  This
+     should normally be `/usr/local/include', but write it as
+     `$(prefix)/include'.  (If you are using Autoconf, write it as
+     `@includedir@'.)
+
+     Most compilers other than GCC do not look for header files in
+     directory `/usr/local/include'.  So installing the header files
+     this way is only useful with GCC.  Sometimes this is not a problem
+     because some libraries are only really intended to work with GCC.
+     But some libraries are intended to work with other compilers.
+     They should install their header files in two places, one
+     specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+     The directory for installing `#include' header files for use with
+     compilers other than GCC.  This should normally be `/usr/include'.
+     (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+     The Makefile commands should check whether the value of
+     `oldincludedir' is empty.  If it is, they should not try to use
+     it; they should cancel the second installation of the header files.
+
+     A package should not replace an existing header in this directory
+     unless the header came from the same package.  Thus, if your Foo
+     package provides a header file `foo.h', then it should install the
+     header file in the `oldincludedir' directory if either (1) there
+     is no `foo.h' there or (2) the `foo.h' that exists came from the
+     Foo package.
+
+     To tell whether `foo.h' came from the Foo package, put a magic
+     string in the file--part of a comment--and `grep' for that string.
+
+   Unix-style man pages are installed in one of the following:
+
+`mandir'
+     The top-level directory for installing the man pages (if any) for
+     this package.  It will normally be `/usr/local/man', but you should
+     write it as `$(prefix)/man'.  (If you are using Autoconf, write it
+     as `@mandir@'.)
+
+`man1dir'
+     The directory for installing section 1 man pages.  Write it as
+     `$(mandir)/man1'.
+
+`man2dir'
+     The directory for installing section 2 man pages.  Write it as
+     `$(mandir)/man2'
+
+`...'
+     *Don't make the primary documentation for any GNU software be a
+     man page.  Write a manual in Texinfo instead.  Man pages are just
+     for the sake of people running GNU software on Unix, which is a
+     secondary application only.*
+
+`manext'
+     The file name extension for the installed man page.  This should
+     contain a period followed by the appropriate digit; it should
+     normally be `.1'.
+
+`man1ext'
+     The file name extension for installed section 1 man pages.
+
+`man2ext'
+     The file name extension for installed section 2 man pages.
+
+`...'
+     Use these names instead of `manext' if the package needs to
+     install man pages in more than one section of the manual.
+
+   And finally, you should set the following variable:
+
+`srcdir'
+     The directory for the sources being compiled.  The value of this
+     variable is normally inserted by the `configure' shell script.
+     (If you are using Autoconf, use `srcdir = @srcdir@'.)
+
+   For example:
+
+     # Common prefix for installation directories.
+     # NOTE: This directory must exist when you start the install.
+     prefix = /usr/local
+     exec_prefix = $(prefix)
+     # Where to put the executable for the command `gcc'.
+     bindir = $(exec_prefix)/bin
+     # Where to put the directories used by the compiler.
+     libexecdir = $(exec_prefix)/libexec
+     # Where to put the Info files.
+     infodir = $(prefix)/info
+
+   If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the `install' rule to create these subdirectories.
+
+   Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above.  The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+\1f
+File: standards.info,  Node: Standard Targets,  Next: Install Command Categories,  Prev: Directory Variables,  Up: Makefile Conventions
 
 Standard Targets for Users
 --------------------------
@@ -68,17 +450,18 @@ Makefiles:
      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
+     with `$(INSTALL_DATA)' (*note Command Variables::), and then run
      the `install-info' program if it is present.  `install-info' is a
      program that edits the Info `dir' file to add or update the menu
      entry for the given Info file; it is part of the Texinfo package.
      Here is a sample rule to install an Info file:
 
-          $(infodir)/foo.info: foo.info
+          $(DESTDIR)$(infodir)/foo.info: foo.info
+                  $(POST_INSTALL)
           # There may be a newer info file in . than in srcdir.
                   -if test -f foo.info; then d=.; \
                    else d=$(srcdir); fi; \
-                  $(INSTALL_DATA) $$d/foo.info $@; \
+                  $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
           # Run install-info only if it exists.
           # Use `if' instead of just prepending `-' to the
           # line so we notice real errors from install-info.
@@ -86,21 +469,30 @@ Makefiles:
           # fail gracefully when there is an unknown command.
                   if $(SHELL) -c 'install-info --version' \
                      >/dev/null 2>&1; then \
-                    install-info --dir-file=$(infodir)/dir \
-                                 $(infodir)/foo.info; \
+                    install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+                                 $(DESTDIR)$(infodir)/foo.info; \
                   else true; fi
 
+     When writing the `install' target, you must classify all the
+     commands into three categories: normal ones, "pre-installation"
+     commands and "post-installation" commands.  *Note Install Command
+     Categories::.
+
 `uninstall'
-     Delete all the installed files that the `install' target would
-     create (but not the noninstalled files such as `make all' would
-     create).
+     Delete all the installed files--the copies that the `install'
+     target creates.
 
      This rule should not modify the directories where compilation is
      done, only the directories where files are installed.
 
+     The uninstallation commands are divided into three categories,
+     just like the installation commands.  *Note Install Command
+     Categories::.
+
 `install-strip'
      Like `install', but strip the executable files while installing
-     them.  The definition of this target can be very simple:
+     them.  In many cases, the definition of this target can be very
+     simple:
 
           install-strip:
                   $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
@@ -177,6 +569,12 @@ Makefiles:
      run the `makeinfo' program, which is part of the Texinfo
      distribution.
 
+     Normally a GNU distribution comes with Info files, and that means
+     the Info files are present in the source directory.  Therefore,
+     the Make rule for an info file should update it in the source
+     directory.  When users build the package, ordinarily Make will not
+     update the Info files because they will already be up to date.
+
 `dvi'
      Generate DVI files for all Texinfo documentation.  For example:
 
@@ -203,7 +601,7 @@ Makefiles:
      appropriately named, use `ln' or `cp' to install the proper files
      in it, and then `tar' that subdirectory.
 
-     Compress the tar file with `gzip'.  For example, the actual
+     Compress the tar file file with `gzip'.  For example, the actual
      distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
 
      The `dist' target should explicitly depend on all non-source files
@@ -247,14 +645,120 @@ programs in which they are useful.
 not distributed with Texinfo.
 
 \1f
+File: standards.info,  Node: Install Command Categories,  Prev: Standard Targets,  Up: Makefile Conventions
+
+Install Command Categories
+--------------------------
+
+   When writing the `install' target, you must classify all the
+commands into three categories: normal ones, "pre-installation"
+commands and "post-installation" commands.
+
+   Normal commands move files into their proper places, and set their
+modes.  They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+   Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+   Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+   The most common use for a post-installation command is to run
+`install-info'.  This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed.  It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+   Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+   To classify the commands in the `install' rule into these three
+categories, insert "category lines" among them.  A category line
+specifies the category for the commands that follow.
+
+   A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end.  There are three
+variables you can use, one for each category; the variable name
+specifies the category.  Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+   Here are the three possible category lines, each with a comment that
+explains what it means:
+
+             $(PRE_INSTALL)     # Pre-install commands follow.
+             $(POST_INSTALL)    # Post-install commands follow.
+             $(NORMAL_INSTALL)  # Normal commands follow.
+
+   If you don't use a category line at the beginning of the `install'
+rule, all the commands are classified as normal until the first category
+line.  If you don't use any category lines, all the commands are
+classified as normal.
+
+   These are the category lines for `uninstall':
+
+             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
+             $(POST_UNINSTALL)    # Post-uninstall commands follow.
+             $(NORMAL_UNINSTALL)  # Normal commands follow.
+
+   Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+   If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also.  This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+   Pre-installation and post-installation commands should not run any
+programs except for these:
+
+     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+     egrep expand expr false fgrep find getopt grep gunzip gzip
+     hostname install install-info kill ldconfig ln ls md5sum
+     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+     test touch true uname xargs yes
+
+   The reason for distinguishing the commands in this way is for the
+sake of making binary packages.  Typically a binary package contains
+all the executables and other files that need to be installed, and has
+its own method of installing them--so it does not need to run the normal
+installation commands.  But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+   Programs to build binary packages work by extracting the
+pre-installation and post-installation commands.  Here is one way of
+extracting the pre-installation commands:
+
+     make -n install -o all \
+           PRE_INSTALL=pre-install \
+           POST_INSTALL=post-install \
+           NORMAL_INSTALL=normal-install \
+       | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+     $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+     on {print $0}
+     $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+   The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+\1f
 File: standards.info,  Node: Releases,  Prev: Makefile Conventions,  Up: Managing Releases
 
 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'.
+   Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'.  It should unpack into a
+subdirectory named `foo-69.96'.
 
    Building and installing the program should never modify any of the
 files contained in the distribution.  This means that all the files
@@ -263,6 +767,21 @@ files" and "non-source files".  Source files are written by humans and
 never changed automatically; non-source files are produced from source
 files by programs under the control of the Makefile.
 
+   The distribution should contain a file named `README' which gives
+the name of the package, and a general description of what it does.  It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any.  The `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+   The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+   The `README' file should also refer to the file which contains the
+copying conditions.  The GNU GPL, if used, should be in a file called
+`COPYING'.  If the GNU LGPL is used, it should be in a file called
+`COPYING.LIB'.
+
    Naturally, all the source files must be in the distribution.  It is
 okay to include non-source files in the distribution, provided they are
 up-to-date and machine-independent, so that building the distribution
@@ -313,4 +832,32 @@ 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.
 
+\1f
+File: standards.info,  Node: References,  Prev: Managing Releases,  Up: Top
+
+References to Non-Free Software and Documentation
+*************************************************
+
+   A GNU program should not recommend use of any non-free program.  We
+can't stop some people from writing proprietary programs, or stop other
+people from using them.  But we can and should avoid helping to
+advertise them to new customers.
+
+   Sometimes it is important to mention how to build your package on
+top of some non-free operating system or other non-free base package.
+In such cases, please mention the name of the non-free package or
+system in the briefest possible way.  Don't include any references for
+where to find more information about the proprietary program.  The goal
+should be that people already using the proprietary program will get
+the advice they need about how to use your free program, while people
+who don't already use the proprietary program will not see anything to
+encourage them to take an interest in it.
+
+   Likewise, a GNU package should not refer the user to any non-free
+documentation for free software.  The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+