updated to July 1

standards.texi

@@ -34,7 +34,7 @@ by the Free Software Foundation.
 @sp 10
 @titlefont{GNU Coding Standards}
 @author{Richard Stallman}
-@author{last updated 16 May 1992}
+@author{last updated 1 Jul 1992}
 @c Note date also appears below.
 @page
 
@@ -57,16 +57,10 @@ by Free Software Foundation.
 @end titlepage
 
 @ifinfo
-@format
-START-INFO-DIR-ENTRY
-* standards: (standards.info).	GNU Project Coding Standards
-END-INFO-DIR-ENTRY
-@end format
-
 @node Top, Reading Non-Free Code, (dir), (dir)
 @top Version
 
-Last updated 16 May 1992.
+Last updated 1 Jul 1992.
 @c Note date also appears above.
 @end ifinfo
 
@@ -74,7 +68,7 @@ Last updated 16 May 1992.
 * Reading Non-Free Code::	Referring to Proprietary Programs
 * Contributions::		Accepting Contributions
 * Change Logs::			Recording Changes
-* Compatibility::		Compatibility with Other Implementations 
+* Compatibility::		Compatibility with Other Implementations
 * Makefiles::			Makefile Conventions
 * Configuration::		How Configuration Should Work
 * Source Language::		Using Languages Other Than C
@@ -223,7 +217,7 @@ need not know the history of the erroneous passage.
 
 
 @node Compatibility
-@chapter Compatibility with Other Implementations 
+@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
@@ -315,6 +309,7 @@ should instead be written as
 foo.o : bar.c
 	$(CC) $(CFLAGS) $< -o $@
 @end example
+
 @noindent
 in order to allow @samp{VPATH} to work correctly.  When the target has
 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
@@ -326,8 +321,6 @@ foo.1 : foo.man sedscript
 	sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
 @end example
 
-
-
 @node Standard Targets
 @section Standard Targets for Users
 
@@ -411,15 +404,38 @@ 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.)
+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}.
 
-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.
+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:
+
+@example
+CFLAGS = -g
+ALL_CFLAGS = $(CFLAGS) -I.
+.c.o:
+	$(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $<
+@end example
+
+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.
 
 Every Makefile should define the variable @code{INSTALL}, which is the
 basic command for installing a file into the system.
@@ -431,13 +447,14 @@ 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
+$(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.
-Use a separate command for each file to be installed.)
+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
@@ -499,8 +516,8 @@ Most compilers other than GCC do not look for header files in
 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
+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
@@ -557,6 +574,18 @@ libdir = $(exec_prefix)/lib
 infodir = $(prefix)/info
 @end example
 
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above.  The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
 @node Configuration
 @chapter How Configuration Should Work
 
@@ -1060,7 +1089,7 @@ 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 
+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.
@@ -1212,7 +1241,7 @@ 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 
+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