--- a/doc/make-stds.texi
+++ b/doc/make-stds.texi
@@ -36,11 +36,12 @@
 conventions.
 
 @menu
-* Makefile Basics::             General Conventions for Makefiles
-* Utilities in Makefiles::      Utilities in Makefiles
-* Command Variables::           Variables for Specifying Commands
-* Directory Variables::         Variables for Installation Directories
-* Standard Targets::            Standard Targets for Users
+* Makefile Basics::             General conventions for Makefiles.
+* Utilities in Makefiles::      Utilities to be used in Makefiles.
+* Command Variables::           Variables for specifying commands.
+* Directory Variables::         Variables for installation directories.
+* DESTDIR::                     Supporting staged installs.
+* Standard Targets::            Standard targets for users.
 * Install Command Categories::  Three categories of commands in the `install'
                                   rule: normal, pre-install and post-install.
 @end menu
@@ -264,29 +265,78 @@
 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
 @code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
 commands for actual installation, for executables and nonexecutables
-respectively.  Use these variables as follows:
+respectively.  Minimal use of these variables is as follows:
 
 @example
 $(INSTALL_PROGRAM) foo $(bindir)/foo
 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
 @end example
 
-Optionally, you may prepend the value of @code{DESTDIR} to the target
-filename.  Doing this allows the installer to create a snapshot of the
-installation to be copied onto the real target file system later.  Do not
-set the value of @code{DESTDIR} in your Makefile, and do not include it
-in any installed files.  With support for @code{DESTDIR}, the above
-examples become:
+However, it is preferable to support a @code{DESTDIR} prefix on the
+target files, as explained in the next section.
+
+@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 DESTDIR
+@section @code{DESTDIR}: support for staged installs
+
+@vindex DESTDIR
+@cindex staged installs
+@cindex installations, staged
+
+@code{DESTDIR} is a variable prepended to each installed target file,
+like this:
 
 @example
 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
 @end example
 
+The @code{DESTDIR} variable is specified by the user, either to the
+@file{configure} script or, more commonly, on the @code{make} command
+line.  For example:
+
+@example
+make DESTDIR=/tmp/stage install
+@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.
+(Since the value of @code{DESTDIR} is only used during installation it
+is not necessary to provide it with other @code{make} commands.)
+
+If your installation step would normally install
+@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
+installation invoked as in the example above would install
+@file{/tmp/stage/usr/local/bin/foo} and
+@file{/tmp/stage/usr/local/lib/libfoo.a} instead.
+
+Prepending the variable @code{DESTDIR} to each target in this way
+provides for @dfn{staged installs}, where the installed files are not
+placed directly into their expected location but are instead copied
+into a temporary location (@code{DESTDIR}).  However, installed files
+maintain their relative directory structure and any embedded file names
+will not be modified.
+
+You should not set the value of @code{DESTDIR} in your @file{Makefile}
+at all; then the files are installed into their expected locations by
+default.  Also, specifying @code{DESTDIR} should not change the
+operation of the software in any way, so its value should not be
+included in any file contents.
+
+@code{DESTDIR} support is commonly used in package creation.  It is
+also helpful to users who want to understand what a given package will
+install where, and to allow users who don't normally have permissions
+to install into protected areas to build and install before gaining
+those permissions.  Finally, it can be useful with tools such as
+@code{stow}, where code is installed in one place but made to appear
+to be installed somewhere else using symbolic links or special mount
+operations.  So, we recommend GNU packages support @code{DESTDIR},
+though it is not an absolute requirement.
+
 
 @node Directory Variables
 @section Variables for Installation Directories
@@ -306,9 +356,10 @@
 default settings specified here so that all GNU packages behave
 identically, allowing the installer to achieve any desired layout.
 
-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.
+These first two variables set the root for the installation.  All the
+other installation directories should be subdirectories of one of
+these two, and nothing should be directly installed into these two
+directories.
 
 @table @code
 @item prefix
@@ -625,6 +676,15 @@
 order for this to be useful, all the packages must be designed so that
 they will work sensibly when the user does so.
 
+Not all of these variables may be implemented in the current release
+of Autoconf and/or Automake; right now, that includes at least
+@code{docdir}, @code{psdir}, @code{pdfdir}, @code{htmldir},
+@code{dvidir}.  In these cases, the descriptions here serve as
+specifications for what Autoconf will implement.  As a programmer, you
+can either use a development version of Autoconf or avoid using these
+variables until a stable release is made which supports them.
+
+
 @node Standard Targets
 @section Standard Targets for Users
 

--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
-@set lastupdate April 9, 2006
+@set lastupdate April 23, 2006
 @c %**end of header
 
 @dircategory GNU organization
@@ -3137,20 +3137,26 @@
 converted automatically into Texinfo.  It is ok to produce the Texinfo
 documentation by conversion this way, as long as it gives good results.
 
-Programmers often find it most natural to structure the documentation
-following the structure of the implementation, which they know.  But
-this structure is not necessarily good for explaining how to use the
-program; it may be irrelevant and confusing for a user.
-
-At every level, from the sentences in a paragraph to the grouping of
-topics into separate manuals, the right way to structure documentation
-is according to the concepts and questions that a user will have in mind
-when reading it.  Sometimes this structure of ideas matches the
+Make sure your manual is clear to a reader who knows nothing about the
+topic and reads it straight through.  This means covering basic topics
+at the beginning, and advanced topics only later.  This also means
+defining every specialized term when it is first used.
+
+Programmers tend to carry over the structure of the program as the
+structure for its documentation.  But this structure is not
+necessarily good for explaining how to use the program; it may be
+irrelevant and confusing for a user.
+
+Instead, the right way to structure documentation is according to the
+concepts and questions that a user will have in mind when reading it.
+This principle applies at every level, from the lowest (ordering
+sentences in a paragraph) to the highest (ordering of chapter topics
+within the manual).  Sometimes this structure of ideas matches the
 structure of the implementation of the software being documented---but
-often they are different.  Often the most important part of learning to
-write good documentation is learning to notice when you are structuring
-the documentation like the implementation, and think about better
-alternatives.
+often they are different.  An important part of learning to write good
+documentation is to learn to notice when you have unthinkingly
+structured the documentation like the implementation, stop yourself,
+and look for better alternatives.
 
 For example, each program in the GNU system probably ought to be
 documented in one manual; but this does not mean each program should
@@ -3220,6 +3226,10 @@
 a computer program.  Please use ``invalid'' for this, and reserve the
 term ``illegal'' for activities prohibited by law.
 
+Please do not write @samp{()} after a function name just to indicate
+it is a function.  @code{foo ()} is not a function, it is a function
+call with no arguments.
+
 @node Doc Strings and Manuals
 @section Doc Strings and Manuals