more documentation on the process of loading source and compiled files

* doc/ref/api-evaluation.texi (Load Paths): Move documentation of
  %load-path and related procedures here, from Build Config.  Add docs
  for %load-compiled-path.

* doc/ref/api-foreign.texi:
* doc/ref/api-modules.texi:
* doc/ref/api-options.texi:
* doc/ref/scheme-using.texi: Update xrefs.

doc/ref/api-evaluation.texi

@@ -808,7 +808,15 @@ The procedure in the previous section look for Scheme code in the file
 system at specific location.  Guile also has some procedures to search
 the load path for code.
 
-For more on the @code{%load-path} variable, @xref{Build Config}.
+@cindex @env{GUILE_LOAD_PATH}
+@defvar %load-path
+List of directories which should be searched for Scheme modules and
+libraries.  @code{%load-path} is initialized when Guile starts up to
+@code{(list (%site-dir) (%library-dir) (%package-data-dir))}, prepended
+with the contents of the @env{GUILE_LOAD_PATH} environment variable, if
+it is set.  @xref{Build Config}, for more on @code{%site-dir} and
+related procedures.
+@end defvar
 
 @deffn {Scheme Procedure} load-from-path filename
 Similar to @code{load}, but searches for @var{filename} in the load
@@ -820,6 +828,7 @@ A user can extend the load path by calling @code{add-to-load-path}.
 
 @deffn {Scheme Syntax} add-to-load-path dir
 Add @var{dir} to the load path.
+@end deffn
 
 For example, a script might include this form to add the directory that
 it is in to the load path:
@@ -827,7 +836,6 @@ it is in to the load path:
 @example
 (add-to-load-path (dirname (current-filename)))
 @end example
-@end deffn
 
 It's better to use @code{add-to-load-path} than to modify
 @code{%load-path} directly, because @code{add-to-load-path} takes care
@@ -851,12 +859,11 @@ the C function takes only one argument, which can be either a string
 
 @deffn {Scheme Procedure} %search-load-path filename
 @deffnx {C Function} scm_sys_search_load_path (filename)
-Search @code{%load-path} for the file named @var{filename},
+Search @code{%load-path} for the file named @var{filename}, which must
-which must be readable by the current user.  If @var{filename}
+be readable by the current user.  If @var{filename} is found in the list
-is found in the list of paths to search or is an absolute
+of paths to search or is an absolute pathname, return its full pathname.
-pathname, return its full pathname.  Otherwise, return
+Otherwise, return @code{#f}.  Filenames may have any of the optional
-@code{#f}.  Filenames may have any of the optional extensions
+extensions in the @code{%load-extensions} list; @code{%search-load-path}
-in the @code{%load-extensions} list; @code{%search-load-path}
 will try each extension automatically.
 @end deffn
 
@@ -867,6 +874,61 @@ a file to load.  By default, @code{%load-extensions} is bound to the
 list @code{("" ".scm")}.
 @end defvar
 
+As mentioned above, when Guile searches the @code{%load-path} for a
+source file, it will also search the @code{%load-compiled-path} for a
+corresponding compiled file.  If the compiled file is as new or newer
+than the source file, it will be loaded instead of the source file,
+using @code{load-compiled}.
+
+@defvar %load-compiled-path
+Like @code{%load-path}, but for compiled files.  By default, this path
+has two entries: one for compiled files from Guile itself, and one for
+site packages.
+@end defvar
+
+When @code{primitive-load-path} searches the @code{%load-compiled-path}
+for a corresponding compiled file for a relative path it does so by
+appending @code{.go} to the relative path.  For example, searching for
+@code{ice-9/popen} could find
+@code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
+@code{/usr/share/guile/2.0/ice-9/popen.scm}.
+
+If @code{primitive-load-path} does not find a corresponding @code{.go}
+file in the @code{%load-compiled-path}, or the @code{.go} file is out of
+date, it will search for a corresponding auto-compiled file in the
+fallback path, possibly creating one if one does not exist.
+
+@xref{Installing Site Packages}, for more on how to correctly install
+site packages.  @xref{Modules and the File System}, for more on the
+relationship between load paths and modules.  @xref{Compilation}, for
+more on the fallback path and auto-compilation.
+
+Finally, there are a couple of helper procedures for general path
+manipulation.
+
+@deffn {Scheme Procedure} parse-path path [tail]
+@deffnx {C Function} scm_parse_path (path, tail)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{tail} appended. If
+@var{path} is @code{#f}, @var{tail} is returned.
+@end deffn
+
+@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
+@deffnx {C Function} scm_search_path (path, filename, rest)
+Search @var{path} for a directory containing a file named
+@var{filename}. The file must be readable, and not a directory.  If we
+find one, return its full filename; otherwise, return @code{#f}.  If
+@var{filename} is absolute, return it unchanged.  If given,
+@var{extensions} is a list of strings; for each directory in @var{path},
+we search for @var{filename} concatenated with each @var{extension}.  If
+@var{require-exts?}  is true, require that the returned file name have
+one of the given extensions; if @var{require-exts?} is not given, it
+defaults to @code{#f}.
+
+For compatibility with Guile 1.8 and earlier, the C function takes only
+three arguments.
+@end deffn
+
 
 @node Character Encoding of Source Files
 @subsection Character Encoding of Source Files

doc/ref/api-foreign.texi

@@ -425,11 +425,11 @@ its own @code{gettext} message catalogue
 (@pxref{Internationalization}).
 
 It will be noted all of the above requires that the Scheme code to be
-found in @code{%load-path} (@pxref{Build Config}).  Presently it's
+found in @code{%load-path} (@pxref{Load Paths}).  Presently it's left up
-left up to the system administrator or each user to augment that path
+to the system administrator or each user to augment that path when
-when installing Guile modules in non-default locations.  But having
+installing Guile modules in non-default locations.  But having reached
-reached the Scheme code, that code should take care of hitting any of
+the Scheme code, that code should take care of hitting any of its own
-its own private files etc.
+private files etc.
 
 
 @node Foreign Pointers

doc/ref/api-modules.texi

@@ -98,8 +98,8 @@ types of access are handled by the syntactic form @code{use-modules},
 which accepts one or more interface specifications and, upon evaluation,
 arranges for those interfaces to be available to the current module.
 This process may include locating and loading code for a given module if
-that code has not yet been loaded, following @code{%load-path} (@pxref{Build
+that code has not yet been loaded, following @code{%load-path}
-Config}).
+(@pxref{Modules and the File System}).
 
 An @dfn{interface specification} has one of two forms.  The first
 variation is simply to name the module, in which case its public
@@ -464,7 +464,7 @@ from in the @dfn{load path}.
 In this case, loading @code{(ice-9 popen)} will eventually cause Guile
 to run @code{(primitive-load-path "ice-9/popen")}.
 @code{primitive-load-path} will search for a file @file{ice-9/popen} in
-the @code{%load-path} (@pxref{Build Config}).  For each directory in
+the @code{%load-path} (@pxref{Load Paths}).  For each directory in
 @code{%load-path}, Guile will try to find the file name, concatenated
 with the extensions from @code{%load-extensions}.  By default, this will
 cause Guile to @code{stat} @file{ice-9/popen.scm}, and then

doc/ref/api-options.texi

@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011, 2012
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -59,14 +59,14 @@ The @code{effective-version} function returns the version name that
 should remain unchanged during a stable series.  Currently that means
 that it omits the micro version.  The effective version should be used
 for items like the versioned share directory name
-i.e.@: @file{/usr/share/guile/1.6/}
+i.e.@: @file{/usr/share/guile/2.0/}
 
 @lisp
-(version) @result{} "1.6.0"
+(version) @result{} "2.0.4"
-(effective-version) @result{} "1.6"
+(effective-version) @result{} "2.0"
-(major-version) @result{} "1"
+(major-version) @result{} "2"
-(minor-version) @result{} "6"
+(minor-version) @result{} "0"
-(micro-version) @result{} "0"
+(micro-version) @result{} "4"
 @end lisp
 @end deffn
 
@@ -86,7 +86,7 @@ party package) are installed.  On Unix-like systems this is usually
 @file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};
 
 @noindent
-for example @file{/usr/local/share/guile/1.6}.
+for example @file{/usr/local/share/guile/2.0}.
 @end deffn
 
 @deffn {Scheme Procedure} %site-dir
@@ -96,40 +96,6 @@ your site should be installed.  On Unix-like systems, this is usually
 @file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
 @end deffn
 
-@cindex @env{GUILE_LOAD_PATH}
-@defvar %load-path
-List of directories which should be searched for Scheme modules and
-libraries.  @code{%load-path} is initialized when Guile starts up to
-@code{(list (%site-dir) (%library-dir) (%package-data-dir))},
-prepended with the contents of the @env{GUILE_LOAD_PATH} environment variable,
-if it is set.
-@end defvar
-
-@deffn {Scheme Procedure} parse-path path [tail]
-@deffnx {C Function} scm_parse_path (path, tail)
-Parse @var{path}, which is expected to be a colon-separated
-string, into a list and return the resulting list with
-@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
-is returned.
-@end deffn
-
-@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
-@deffnx {C Function} scm_search_path (path, filename, rest)
-Search @var{path} for a directory containing a file named
-@var{filename}. The file must be readable, and not a directory.
-If we find one, return its full filename; otherwise, return
-@code{#f}.  If @var{filename} is absolute, return it unchanged.
-If given, @var{extensions} is a list of strings; for each
-directory in @var{path}, we search for @var{filename}
-concatenated with each @var{extension}.  If @var{require-exts?}
-is true, require that the returned file name have one of the
-given extensions; if @var{require-exts?} is not given, it
-defaults to @code{#f}.
-
-For compatibility with Guile 1.8 and earlier, the C function takes only
-three arguments
-@end deffn
-
 @defvar %guile-build-info
 Alist of information collected during the building of a particular
 Guile.  Entries can be grouped into one of several categories:

doc/ref/scheme-using.texi

@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2006, 2010, 2011
+@c Copyright (C) 2006, 2010, 2011, 2012
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -780,7 +780,8 @@ site packages will be
 
 Note that a @code{.go} file will only be loaded in preference to a
 @code{.scm} file if it is newer.  For that reason, you should install
-your Scheme files first, and your compiled files second.
+your Scheme files first, and your compiled files second.  @code{Load
+Paths}, for more on the loading process.
 
 Finally, although this section is only about Scheme, sometimes you need
 to install C extensions too.  Shared libraries should be installed in