--- a/man/internals/internals.texi	Thu Mar 10 09:19:16 2005 +0000
+++ b/man/internals/internals.texi	Thu Mar 10 11:44:22 2005 +0000
@@ -4159,11 +4159,10 @@
 @cindex build configuration
 @cindex configuration, build
 
-@strong{Please write this node!} @c ####
-
-This node should describe XEmacs-specific techniques and idioms in the
-configuration system.  A particular example is the set of @samp{XE_}
-macros in @file{configure.in} and @file{configure.ac}.
+XEmacs makes extensive use of the external features provided by the
+system it is running on.  Determining which features are present and
+where they are located is the responsibility of the build configuration
+system.
 
 @menu
 * The version.sh Script::
@@ -4271,11 +4270,17 @@
 @cindex configurable features, adding
 @cindex features, adding configurable
 
-Adding a configurable feature requires at least adding an option to the
-@file{configure} script and a macro definition to @file{src/config.h.in}
-(@pxref{The configure Script}), and often changes to Makefile precursors
-(@pxref{The Makefile Precursors}).
-
+Adding a configurable feature requires at the very least adding an
+option to the @file{configure} script and a macro definition to
+@file{src/config.h.in} (@pxref{The configure Script}), and often changes
+to Makefile precursors (@pxref{The Makefile Precursors}).
+
+Be prepared for the feature to be absent (even if you think that is
+always present for a particular OS release) and work with
+@code{--with-site-prefixes} to handle libraries and headers that are in
+unusual locations.  There is no end to the strange ways in which systems
+can be configured and XEmacs is expected to cope with anything thrown at
+it.
 
 
 @node The configure Script, The Makefile Precursors, Adding Configurable Features, The Build Configuration System
@@ -4286,26 +4291,37 @@
 At the heart of the XEmacs build configuration system is the
 @file{configure} script.  This beast is maintained using the Autoconf
 system, which is a truly terrifying monstrosity based on a fundamentally
-flawed programming model (extensive use of macros), with an
-implementation about which I've never heard a nice word (GNU @file{m4}),
-used to string together a large set of @emph{ad hoc} tests, to implement
-a configuration language with conventions that are unimportant in simple
-cases and counterintuitive when things get complicated.  If that doesn't
-scare you off, Welcome! I think you're ready to become a configure
-hacker!  (But be prepared for things to go downhill from here.)
+flawed programming model (extensive use of macros), with an unpleasant
+implementation (GNU @file{m4}), used to string together a large set of
+@emph{ad hoc} tests, to implement a configuration language with
+conventions that are unimportant in simple cases and counterintuitive
+when things get complicated.  If that doesn't scare you off, Welcome! I
+think you're ready to become a configure hacker!  (But be prepared for
+things to go downhill from here.)
+
+Unless you plan to develop autoconf macros, much of this complexity can
+be removed by following the following rule:
+
+@quotation
+Always quote (ie surround with @samp{[]}) every argument to every
+macro.  This includes macros that appear in the argument list of other
+macros.
+@end quotation
+
+If this rule is followed and the macro produces incorrect results then
+the macro is buggy.
 
 @file{configure} is, of course, is written in POSIX shell language, and
-autogenerated from a precursor (see? the first step was a doozy!)
-Currently that precursor is called @file{configure.ac}, but in the
-previous generation it was called @file{configure.in}.  As of February
-2005, @file{configure.ac} is used in the development mainline, but
-because the semantics of many predefined macros changed drastically
-between @file{autoconf} 2.13 and @file{autoconf} 2.50 (why not ``3.0''? 
-you got me), the XEmacs Project chose to stick with the devil it knew
-for the stable line of XEmacs 21.4 releases.
-
-One reason for worrying about the semantic changes is the fact that
-XEmacs uses a lot of homebrew code, including @file{m4} macros, to
+autogenerated from a precursor.  As of March 2005 on the mainline the
+precursor is called @file{configure.ac} and it is built using
+@code{autoconf} 2.59.  Prior to that, and with XEmacs 21.4 and earlier
+it was called @file{configure.in} and build using @code{autoconf} 2.13.
+@code{autoconf} 2.5X is not completely backward compatible with
+@code{autoconf} 2.13 so the XEmacs Project chose to stick with the devil
+it knew for the stable line of XEmacs 21.4 releases.
+
+One reason for worrying about the level of compatibility is the fact
+that XEmacs uses a lot of homebrew code, including @file{m4} macros, to
 implement special features in its @file{configure} script.  Here are
 some of the important features:
 
@@ -4326,85 +4342,116 @@
 @c #### @var{}-ize the formal parameters of these functions?
 @table @code
 @item USAGE_ERROR(string)
-prints a usage error and dies
+Prints a usage error and dies.
 
 @item PRINT_VAR(var var ...)
-prints values of shell variables
-
-@item XE_ADD_OBJS(foo.o ...)
-@strong{#### Please document me!}
+Prints the name and value of the list of shell variables.
+
+@item XE_ADD_OBJS(foo.o)
+Appends the argument to the variable @code{extra_objs}.  This variable
+goes to make up part of the link command line.  If the command line
+argument @code{--verbose} is supplied a message is printed out.
 
 @item XE_APPEND(value, varname)
-@strong{#### Please document me!}
+Append the value (separated by a space) to the shell variable
+@var{varname}.  @var{varname} should not be prefixed with a @samp{$}.
+If the command line argument @code{--verbose} is supplied a message is
+printed out.
 
 @item XE_PREPEND(value, varname)
-@strong{#### Please document me!}
+Prepend the value (separated by a space) to the shell variable
+@var{varname}.  @var{varname} should not be prefixed with a @samp{$}.
+If the command line argument @code{--verbose} is supplied a message is
+printed out.
 
 @item XE_DIE(message)
-used for situations that can't lead to a successful build, such as
+Used for situations that can't lead to a successful build, such as
 missing include files or conflicts between requested features.
 
 @item XE_CHECK_FEATURE_DEPENDENCY(feature1, feature2)
-@strong{#### Please document me!}
+@code{--with-@var{feature1}} requires that @code{--with-@var{feature2}}
+be also set and will die if the latter is not specified.
 
 @item XE_STRIP_4TH_COMPONENT(var)
-@strong{#### Please document me!}
+Converts the four part system name (eg @code{i986-pc-linux-gnu}) in
+@var{var} to a three part names (eg @code{i986-pc-linux}).
 
 @item CANONICALIZE_PATH(varname)
-@strong{#### Please document me!}
+Strips automount brokenness from the path in @var{varname}.
 
 @item XE_PROTECT_LINKER_FLAGS(shell_var)
-@strong{#### Please document me!}
+Wrap the command line arguments in @var{shell_var} with suitable
+incantations to ensure that the compiler front end passes them to the
+linker.  Currently the magic is added only for gcc.
 
 @item COLON_TO_SPACE(path)
-Allow use of either @samp{:} or spaces for lists of directories.
+Converts a colon separated list of paths into a space separated list of paths.
 
 @item XE_ADD_RUNPATH_DIR(directory)
-@strong{#### Please document me!}
+Internal function used by @code{XE_COMPUTE_RUNPATH}.
 
 @item XE_COMPUTE_RUNPATH()
-@strong{#### Please document me!}
+Calculate the appropriate dynamic library run path for XEmacs and the
+value to the shell variable @code{ld_switch_run}.
 
 @item XE_SPACE(var, words)
-@strong{#### Please document me!}
+Append to @code{var} a space separated list of @code{words}.  
 
 @item XE_SHLIB_STUFF
-See @file{aclocal.m4}.
+Generate the appropriate shared library support black magic. This is
+implemented in the file @file{aclocal.m4}.
 @end table
 
 @heading XEmacs keyword option support
 
 A @dfn{keyword} option is one that accepts one of a number of
-pre-defined values (if support for sets of values is needed, see
+pre-defined values (if support for sets of values is needed, x1see
 ``complex options'' below).  For example,
 @samp{--with-mail-locking=flock}.
 
-Keyword options use expanded forms of @samp{AC_ARG_[WITH|ENABLE]} called
-@samp{XE_KEYWORD_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
-first 4 parameters of these macros are the same as original macros with
-the exception that all four parameters are @strong{required}.  The
-@var{action-if-true} code is run after the argument list has been
-parsed.
+Keyword options are defined with expanded forms of
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_KEYWORD_ARG_[WITH|ENABLE]},
+both taking 5 parameters.  The first 4 parameters of these macros are
+the same as original macros with the exception that all four parameters
+are @strong{required}.  The @var{action-if-true} code is run after the
+argument list has been parsed.
 
 The 5th parameter is a list of supported keywords.  The whole list must
-be quoted but the individual keywords should not.
+be quoted but the individual keywords should not.  Here is how the
+@samp{mail-locking} flag is defined:
+
+@example
+XE_KEYWORD_ARG_WITH([mail-locking],
+	AC_HELP_STRING([--with-mail-locking],[Specify the locking to be
+                        used by movemail to prevent concurrent updates
+                        of mail spool files. Valid types are `lockf',
+                        `flock', `dot', `locking' or `mmdf'.]),
+        [],
+        [],
+        [lockf,flock,file,locking,mmdf,pop])
+@end example
+
+(Note that the help string will be reformatted by @file{autoconf} so
+that all whitespace is first compressed to a single space, then folded
+to appear in the right-hand column as above.  Thus the help string may
+appear differently when @code{./configure --help} is invoked.)
 
 If the option value is a not a valid keyword then an error message is
 generated, otherwise the value is left untouched.
 
 This support is implemented via the following @file{GNU m4} macros.
-Macros labelled @dfn{internal} are not expected to be used by
+Macros labeled @dfn{internal} are not expected to be used by
 @file{configure.ac} programmers; they are part of the implementation of
 higher-level features.
 
 @table @code
 @item XE_KEYWORD_ARG_WITH(package, help-string, action-if-true, action-if-false, [keyword1, keyword2, ....])
-Expanded version of @samp{AC_ARG_WITH} for keyword options.  All the
+Expanded version of @code{AC_ARG_WITH} for keyword options.  All the
 parameters are required.  The last argument is a comma-separated list of
 supported keywords, @file{m4}-quoted with @samp{[]}.
 
 @item XE_KEYWORD_ARG_ENABLE(feature, help-string, action-if-true, action-if-false, [keyword1, keyword2, ....])
-Expanded version of @samp{AC_ARG_ENABLE} for keyword options.  All the
+Expanded version of @code{AC_ARG_ENABLE} for keyword options.  All the
 parameters are required.  The last argument is a comma-separated list of
 supported keywords, @file{m4}-quoted with @samp{[]}.
 
@@ -4413,26 +4460,25 @@
 found then an error is generated.
 
 @item XE_KEYWORD(keyword)
-Internal macro to declare an option value.
+Internal macro to convert the keyword list into the various forms needed
+by @code{XE_PARSE_KEYWORD_OPTION}.
 
 @end table
 
 @heading XEmacs complex option support
 
 A @dfn{complex option} is one that takes a number of related values, as
-a set.  For example, we might use "--with-xft=all,nomenubars" for
-compatibility with XFontSet i18n of menubars.  (The example is
-contrived, Xft looks much better than XFS.)  Processing such an option
-requires a number of auxiliary variables.
-
-Complex options use expanded forms of @samp{AC_ARG_[WITH|ENABLE]} called
-@samp{XE_COMPLEX_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
-first 4 parameters of these macros are the same as original macros with
-the exception that all four parameters are @strong{required}.  The
-@var{action-if-true} code is run after the argument list has been
-parsed.
-
-The 5th parameter is a list of @samp{XE_COMPLEX_OPTION} macro calls that
+a set.  For example, we might use @code{--with-sound=native,nas} to play
+sounds using the native libraries and via NAS.
+
+Complex options are defined with expanded forms of
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_COMPLEX_ARG_[WITH|ENABLE]},
+both taking 5 parameters.  The first 4 parameters of these macros are
+the same as original macros with the exception that all four parameters
+are @strong{required}.  The @var{action-if-true} code is run after the
+argument list has been parsed.
+
+The 5th parameter is a list of @code{XE_COMPLEX_OPTION} macro calls that
 define the valid components and their default values.  The list must be
 quoted but the individual macro calls should not.  Here is how the
 @samp{sound} flag is defined:
@@ -4454,23 +4500,18 @@
 	 XE_COMPLEX_OPTION([esd],[no])])
 @end example
 
-(Note that the help string will be reformatted by @file{autoconf} so
-that all whitespace is first compressed to a single space, then folded
-to appear in the right-hand column as above.  Thus the help string may
-appear differently when @code{./configure --help} is invoked.)
-
 @c #### verify for INSTALL and xemacs Texinfo.
-Each component is interpreted as a separate feature to be enabled or
+Each option is interpreted as a separate feature to be enabled or
 disabled.  As usual, the distinction between ``with'' and ``enable'' is
 that ``with'' features require specific support from the system, usually
 one or more optional libraries, and ``enable'' features are supported
 entirely by code in XEmacs, but the user might want to switch it off for
 some reason.  Option values are stored in the variables
-@samp{with_@var{package}_@var{component}} or
-@samp{enable_@var{feature}_@var{component}} (@i{e.g.} 
-@samp{with_xft_menubars}).
-
-The user of @file{configure} specifies the configuration by providing a
+@code{with_@var{package}_@var{component}} or
+@code{enable_@var{feature}_@var{component}} (@i{e.g.} 
+@code{enable_sound_native}).
+
+The user of @code{configure} specifies the configuration by providing a
 list of components.  The special components @samp{all} and @samp{none}
 may occur first in the list, setting the defaults for all components to
 @samp{yes} or @samp{no} respectively.
@@ -4482,7 +4523,7 @@
 value can also be the null string @samp{""}, usually meaning that
 @file{configure} will attempt to find support for the feature on the
 system, and will enable the configuration if it is available.  Sometimes
-the null string means that @file{configure}'s default is
+the null string means that @code{configure}'s default is
 system-dependent.  (This usage is not consistent, and depends on the
 implementation of the feature detector rather than the argument parser.)
 Users cannot specify the null string for an individual component from
@@ -4494,7 +4535,7 @@
 library which may or may not be supported by multiple components of
 XEmacs, as exemplified by Xft.  This latter usage may be more common
 during development of a feature.  Perhaps specialized APIs should be
-provided, see comment on @samp{XE_COMPLEX_OPTION_HELP_STRING} below.
+provided, see comment on @code{XE_COMPLEX_OPTION_HELP_STRING} below.
 
 @table @code
 @item XE_COMPLEX_OPTION(option, yesno)
@@ -4513,11 +4554,11 @@
 the API may be enhanced to deal with this in the future.
 
 @item XE_COMPLEX_ARG_WITH(PACKAGE, HELP-STRING, ACTION-IF-TRUE, ACTION-IF-FALSE, [XE_COMPLEX_OPTION(a,yes), ....])
-Extended version of @samp{AC_ARG_WITH} for complex options.  All the
+Extended version of @code{AC_ARG_WITH} for complex options.  All the
 parameters are required.
 
 @item XE_COMPLEX_ARG_ENABLE(FEATURE, HELP-STRING, ACTION-IF-TRUE, ACTION-IF-FALSE, [XE_COMPLEX_OPTION(a,yes), ....])
-Expanded version of @samp{AC_ARG_ENABLE} for complex options.  All the
+Expanded version of @code{AC_ARG_ENABLE} for complex options.  All the
 parameters are required.
 
 @item XE_EXPAND_COMPLEX_OPTION(prefix, component, yesno)
@@ -4548,21 +4589,22 @@
 @cindex Makefile precursors
 @cindex precursors, Makefile
 
-@strong{Please write this node!} @c ####
-
-As in other programs using a @file{configure} program, XEmacs's
-Makefiles are not written, they are generated.  The @file{configure}
-program uses Makefile precursors, or templates, to generate the actual
-Makefiles.  In fact, it is a multistage process.  The developer changes
-the file @file{Makefile.in.in}, then @file{configure} first generates an
+As with other @code{autoconf} based programs, XEmacs's Makefiles are not
+written, they are generated.  The @code{configure} program uses Makefile
+precursors, or templates, to generate the actual Makefiles.  Unlike
+other programs this is a multistage process.  The developer changes the
+file @file{Makefile.in.in}, then @code{configure} first generates an
 intermediate file @file{Makefile.in}, and finally produces a portable
-Makefile called @file{Makefile}, and a Makefile optimized for @file{GNU
+Makefile called @file{Makefile}, and a Makefile optimized for @code{GNU
 make} called @file{GNUmakefile}.
 
-This node describes XEmacs-specific techniques and idioms used in the
-@file{Makefile.in.in} files.
-
-
+@file{Makefile.in.in} is run through the C preprocessor as part of this
+process. This means that common files can be included and conditional
+construction of the Makefile can occur.  When @file{GNUmakefile} is
+being produced @code{USE_GNU_MAKE} is defined.
+
+Comments in @file{Makefile.in.in} must start with @samp{##} to avoid
+confusing the preprocessor.
 
 @node Rules When Writing New C Code, Regression Testing XEmacs, The Build Configuration System, Top
 @chapter Rules When Writing New C Code