manual: reorganize autoconf, pkg-config info

* doc/ref/libguile-parallel.texi: New file, documenting parallel
  installation and the use of pkg-config.

* doc/ref/libguile-linking.texi: Adapt.

* doc/ref/libguile-autoconf.texi: Rename from autoconf.texi.  Lower
  sections, and integrate in the "Programming in C" chapter.

* doc/ref/guile.texi: Adapt.

doc/ref/guile.texi

@@ -182,8 +182,6 @@ x
 
 * Guile Implementation::
 
-* Autoconf Support::
-
 Appendices
 
 * GNU Free Documentation License::  The license of this manual.
@@ -264,20 +262,25 @@ etc. that make up Guile's application programming interface (API),
 @xref{API Reference}.
 
 @menu
+* Parallel Installations::      Finding the right Guile.
 * Linking Programs With Guile:: More precisely, with the libguile library.
 * Linking Guile with Libraries::  To extend Guile itself. 
 * General Libguile Concepts::   General concepts for using libguile.
 * Defining New Types (Smobs)::  Adding new types to Guile.
 * Function Snarfing::           A way to define new functions.
 * Programming Overview::        An overview of Guile programming.
+* Autoconf Support::            Putting m4 to good use.
 @end menu
 
+@include libguile-parallel.texi
 @include libguile-linking.texi
 @include libguile-extensions.texi
 @include libguile-concepts.texi
 @include libguile-smobs.texi
 @include libguile-snarf.texi
 @include libguile-program.texi
+@include libguile-autoconf.texi
+
 
 @node API Reference
 @chapter API Reference
@@ -426,8 +429,6 @@ merely familiar with Scheme to being a real hacker.
 @include vm.texi
 @include compiler.texi
 
-@include autoconf.texi
-
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 

doc/ref/libguile-autoconf.texi

@@ -6,11 +6,10 @@
 
 @page
 @node Autoconf Support
-@chapter Autoconf Support
+@section Autoconf Support
 
-When Guile is installed, a pkg-config description file and a set of
+Autoconf, a part of the GNU build system, makes it easy for users to
-Autoconf macros is installed.  This chapter documents pkg-config and
+build your package.  This section documents Guile's Autoconf support.
-Autoconf support, as well as the high-level guile-tool Autofrisk.
 
 @menu
 * Autoconf Background::         Why use autoconf?
@@ -20,7 +19,7 @@ Autoconf support, as well as the high-level guile-tool Autofrisk.
 
 
 @node Autoconf Background
-@section Autoconf Background
+@subsection Autoconf Background
 
 As explained in the @cite{GNU Autoconf Manual}, any package needs
 configuration at build-time (@pxref{Top, ,Introduction,autoconf,The GNU
@@ -42,29 +41,14 @@ checks.
 
 
 @node Autoconf Macros
-@section Autoconf Macros
+@subsection Autoconf Macros
 
-@cindex pkg-config
+As mentioned earlier in this chapter, Guile supports parallel
-@cindex autoconf
+installation, and uses @code{pkg-config} to let the user choose which
-
+version of Guile they are interested in.  @code{pkg-config} has its own
-GNU Guile provides a @dfn{pkg-config} description file, which contains
+set of Autoconf macros that are probably installed on most every
-all the information necessary to compile and link C applications that
+development system.  The most useful of these macros is
-use Guile.  The @code{pkg-config} program is able to read this file
+@code{PKG_CHECK_MODULES}.
-and provide this information to application programmers; it can be
-obtained at @url{http://pkg-config.freedesktop.org/}.
-
-The following command lines give respectively the C compilation and link
-flags needed to build Guile-using programs:
-
-@example
-pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
-pkg-config guile-@value{EFFECTIVE-VERSION} --libs
-@end example
-
-To ease use of pkg-config with Autoconf, pkg-config comes with a
-convenient Autoconf macro.  The following example looks for Guile and
-sets the @code{GUILE_CFLAGS} and @code{GUILE_LIBS} variables
-accordingly, or prints an error and exits if Guile was not found:
 
 @findex PKG_CHECK_MODULES
 
@@ -72,6 +56,10 @@ accordingly, or prints an error and exits if Guile was not found:
 PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
 @end example
 
+This example looks for Guile and sets the @code{GUILE_CFLAGS} and
+@code{GUILE_LIBS} variables accordingly, or prints an error and exits if
+Guile was not found.
+
 Guile comes with additional Autoconf macros providing more information,
 installed as @file{@var{prefix}/share/aclocal/guile.m4}.  Their names
 all begin with @code{GUILE_}.
@@ -81,7 +69,7 @@ all begin with @code{GUILE_}.
 
 
 @node Using Autoconf Macros
-@section Using Autoconf Macros
+@subsection Using Autoconf Macros
 
 Using the autoconf macros is straightforward: Add the macro "calls" (actually
 instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,

doc/ref/libguile-linking.texi

@@ -16,23 +16,15 @@ head of any C source file that uses identifiers described in this
 manual.  Once you've compiled your source files, you need to link them
 against the Guile object code library, @code{libguile}.
 
-@code{<libguile.h>} is not in the default search path for headers,
+As noted in the previous section, @code{<libguile.h>} is not in the
-because Guile supports parallel installation of multiple versions of
+default search path for headers.  The following command lines give
-Guile, with each version's headers under their own directories.  This is
+respectively the C compilation and link flags needed to build programs
-to allow development against, say, both Guile 2.0 and 2.2.
+using Guile @value{EFFECTIVE-VERSION}:
 
-To compile code that includes @code{<libguile.h>}, or links to
+@example
-@code{libguile}, you need to select the effective version you are
+pkg-config guile-@value{EFFECTIVE-VERSION} --cflags
-interested in, and then ask @code{pkg-config} for the compilation flags
+pkg-config guile-@value{EFFECTIVE-VERSION} --libs
-or linking instructions.  For effective version
+@end example
-@value{EFFECTIVE-VERSION}, for example, you would invoke
-@code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}} to get
-the compilation and linking flags necessary to link to version
-@value{EFFECTIVE-VERSION} of Guile.  You would typically run
-@code{pkg-config} during the configuration phase of your program and
-use the obtained information in the Makefile.
-
-See the @code{pkg-config} man page, for more information.
 
 @menu
 * Guile Initialization Functions::  What to call first.

doc/ref/libguile-parallel.texi

@@ -0,0 +1,48 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
+@c   Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Parallel Installations
+@section Parallel Installations
+
+@cindex pkg-config
+@cindex effective version
+
+Guile provides strong API and ABI stability guarantees during stable
+series, so that if a user writes a program against Guile version 2.0.3,
+it will be compatible with some future version 2.0.7.  We say in this
+case that 2.0 is the @dfn{effective version}, composed of the major and
+minor versions, in this case 2 and 0.
+
+Users may install multiple effective versions of Guile, with each
+version's headers, libraries, and Scheme files under their own
+directories.  This provides the necessary stability guarantee for users,
+while also allowing Guile developers to evolve the language and its
+implementation.
+
+However, parallel installability does have a down-side, in that users
+need to know which version of Guile to ask for, when they build against
+Guile.  Guile solves this problem by installing a file to be read by the
+@code{pkg-config} utility, a tool to query installed packages by name.
+Guile encodes the version into its pkg-config name, so that users can
+ask for @code{guile-2.0} or @code{guile-2.2}, as appropriate.
+
+For effective version @value{EFFECTIVE-VERSION}, for example, you would
+invoke @code{pkg-config --cflags --libs guile-@value{EFFECTIVE-VERSION}}
+to get the compilation and linking flags necessary to link to version
+@value{EFFECTIVE-VERSION} of Guile.  You would typically run
+@code{pkg-config} during the configuration phase of your program and use
+the obtained information in the Makefile.
+
+See the @code{pkg-config} man page, for more information, or its web
+site, @url{http://pkg-config.freedesktop.org/}.
+
+@xref{Autoconf Support}, for more on checking for Guile from within a
+@code{configure.ac} file.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: