fold in ludovic's suggestions for new manual sections

* INSTALL: Update from newest merge

* doc/ref/compiler.texi:
* doc/ref/vm.texi: Fold in Ludovic's suggestions

INSTALL

@@ -2,7 +2,7 @@ Installation Instructions
 *************************
 
 Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
-2006, 2007, 2008 Free Software Foundation, Inc.
+2006, 2007 Free Software Foundation, Inc.
 
 This file is free documentation; the Free Software Foundation gives
 unlimited permission to copy, distribute and modify it.
@@ -73,9 +73,9 @@ The simplest way to compile this package is:
 Compilers and Options
 =====================
 
-   Some systems require unusual options for compilation or linking that
-the `configure' script does not know about.  Run `./configure --help'
-for details on some of the pertinent environment variables.
+Some systems require unusual options for compilation or linking that the
+`configure' script does not know about.  Run `./configure --help' for
+details on some of the pertinent environment variables.
 
    You can give `configure' initial values for configuration parameters
 by setting variables in the command line or in the environment.  Here
@@ -100,20 +100,6 @@ architecture at a time in the source code directory.  After you have
 installed the package for one architecture, use `make distclean' before
 reconfiguring for another architecture.
 
-   On MacOS X 10.5 and later systems, you can create libraries and
-executables that work on multiple system types--known as "fat" or
-"universal" binaries--by specifying multiple `-arch' options to the
-compiler but only a single `-arch' option to the preprocessor.  Like
-this:
-
-     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-                 CPP="gcc -E" CXXCPP="g++ -E"
-
-   This is not guaranteed to produce working output in all cases, you
-may have to build one architecture at a time and combine the results
-using the `lipo' tool if you have problems.
-
 Installation Names
 ==================
 
@@ -152,36 +138,14 @@ find the X include and library files automatically, but if it doesn't,
 you can use the `configure' options `--x-includes=DIR' and
 `--x-libraries=DIR' to specify their locations.
 
-Particular systems
-==================
-
-   On HP-UX, the default C compiler is not ANSI C compatible.  If GNU
-CC is not installed, it is recommended to use the following options in
-order to use an ANSI C compiler:
-
-     ./configure CC="cc -Ae"
-
-and if that doesn't work, install pre-built binaries of GCC for HP-UX.
-
-   On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
-parse its `<wchar.h>' header file.  The option `-nodtk' can be used as
-a workaround.  If GNU CC is not installed, it is therefore recommended
-to try
-
-     ./configure CC="cc"
-
-and if that doesn't work, try
-
-     ./configure CC="cc -nodtk"
-
 Specifying the System Type
 ==========================
 
-   There may be some features `configure' cannot figure out
-automatically, but needs to determine by the type of machine the package
-will run on.  Usually, assuming the package is built to be run on the
-_same_ architectures, `configure' can figure that out, but if it prints
-a message saying it cannot guess the machine type, give it the
+There may be some features `configure' cannot figure out automatically,
+but needs to determine by the type of machine the package will run on.
+Usually, assuming the package is built to be run on the _same_
+architectures, `configure' can figure that out, but if it prints a
+message saying it cannot guess the machine type, give it the
 `--build=TYPE' option.  TYPE can either be a short name for the system
 type, such as `sun4', or a canonical name which has the form:
 
@@ -207,9 +171,9 @@ eventually be run) with `--host=TYPE'.
 Sharing Defaults
 ================
 
-   If you want to set default values for `configure' scripts to share,
-you can create a site shell script called `config.site' that gives
-default values for variables like `CC', `cache_file', and `prefix'.
+If you want to set default values for `configure' scripts to share, you
+can create a site shell script called `config.site' that gives default
+values for variables like `CC', `cache_file', and `prefix'.
 `configure' looks for `PREFIX/share/config.site' if it exists, then
 `PREFIX/etc/config.site' if it exists.  Or, you can set the
 `CONFIG_SITE' environment variable to the location of the site script.
@@ -237,19 +201,11 @@ an Autoconf bug.  Until the bug is fixed you can use this workaround:
 `configure' Invocation
 ======================
 
-   `configure' recognizes the following options to control how it
-operates.
+`configure' recognizes the following options to control how it operates.
 
 `--help'
 `-h'
-     Print a summary of all of the options to `configure', and exit.
-
-`--help=short'
-`--help=recursive'
-     Print a summary of the options unique to this package's
-     `configure', and exit.  The `short' variant lists options used
-     only in the top level, while the `recursive' variant lists options
-     also present in any nested packages.
+     Print a summary of the options to `configure', and exit.
 
 `--version'
 `-V'
@@ -276,16 +232,6 @@ operates.
      Look for the package's source code in directory DIR.  Usually
      `configure' can determine that directory automatically.
 
-`--prefix=DIR'
-     Use DIR as the installation prefix.  *Note Installation Names::
-     for more details, including other options available for fine-tuning
-     the installation locations.
-
-`--no-create'
-`-n'
-     Run the configure checks, but stop before creating any output
-     files.
-
 `configure' also accepts some other, not widely useful, options.  Run
 `configure --help' for more details.
 

doc/ref/compiler.texi

@@ -120,7 +120,7 @@ fast.
 
 There is a notion of a ``current language'', which is maintained in
 the @code{*current-language*} fluid. This language is normally Scheme,
-and may be rebound by the user. The runtime compilation interfaces
+and may be rebound by the user. The run-time compilation interfaces
 (@pxref{Read/Load/Eval/Compile}) also allow you to choose other source
 and target languages.
 
@@ -319,7 +319,7 @@ Return an existing or new toplevel variable named @var{sym}.
 @var{toplevel-env} must be a toplevel environment.
 @end deffn
 @deffn {Scheme Procedure} ghil-var-at-module! env modname sym interface?
-Return a variable that will be resolved at runtime with respect to a
+Return a variable that will be resolved at run-time with respect to a
 specific module named @var{modname}. If @var{interface?} is true, the
 variable will be of type @code{public}, otherwise @code{private}.
 @end deffn
@@ -459,7 +459,7 @@ Like Scheme's @code{values}.
 @var{vals})}.
 @end deftp
 @deftp {Scheme Variable} <ghil-reified-env> env loc
-Produces, at runtime, a reification of the environment at compile
+Produces, at run-time, a reification of the environment at compile
 time. Used in the implementation of Scheme's
 @code{compile-time-environment}.
 @end deftp
@@ -476,7 +476,7 @@ Just as the Scheme to GHIL compiler introduced new hidden state---the
 environment---the GHIL to GLIL compiler introduces more state, the
 stack. While not represented explicitly, the stack is present in the
 compilation of each GHIL expression: compiling a GHIL expression
-should leave the runtime value stack in the same state. For example,
+should leave the run-time value stack in the same state. For example,
 if the intermediate value stack has two elements before evaluating an
 @code{if} expression, it should have two elements after that
 expression.
@@ -495,7 +495,7 @@ Its expression types are defined in @code{(language glil)}, and as
 with GHIL, some of its fields parse as rest arguments.
 
 @deftp {Scheme Variable} <glil-program> nargs nrest nlocs nexts meta . body
-A unit of code that at runtime will correspond to a compiled
+A unit of code that at run-time will correspond to a compiled
 procedure. @var{nargs} @var{nrest} @var{nlocs}, and @var{nexts}
 collectively define the program's arity; see @ref{Compiled
 Procedures}, for more information. @var{meta} should be an alist of
@@ -681,7 +681,7 @@ Probably the most important improvement, speed-wise, will be some form
 of native compilation, both just-in-time and ahead-of-time. This could
 be done in many ways. Probably the easiest strategy would be to extend
 the compiled procedure structure to include a pointer to a native code
-vector, and compile from bytecode to native code at runtime after a
+vector, and compile from bytecode to native code at run-time after a
 procedure is called a certain number of times.
 
 The name of the game is a profiling-based harvest of the low-hanging

doc/ref/vm.texi

@@ -8,7 +8,7 @@
 @section A Virtual Machine for Guile
 
 Guile has both an interpreter and a compiler. To a user, the
-difference is largely transparent -- interpreted and compiled
+difference is largely transparent---interpreted and compiled
 procedures can call each other as they please.
 
 The difference is that the compiler creates and interprets bytecode
@@ -32,9 +32,11 @@ machine.
 @node Why a VM?
 @subsection Why a VM?
 
-For a long time, Guile only had an interpreter, called the evaluator.
-Guile's evaluator operates directly on the S-expression representation
-of Scheme source code.
+@cindex interpreter
+@cindex evaluator
+For a long time, Guile only had an interpreter, called the
+@dfn{evaluator}. Guile's evaluator operates directly on the
+S-expression representation of Scheme source code.
 
 But while the evaluator is highly optimized and hand-tuned, and
 contains some extensive speed trickery (@pxref{Memoization}), it still
@@ -47,7 +49,7 @@ be allocated on the heap. Et cetera.
 
 The solution to this problem is to compile the higher-level language,
 Scheme, into a lower-level language for which all of the checks and
-dispatching have already been done -- the code is instead stripped to
+dispatching have already been done---the code is instead stripped to
 the bare minimum needed to ``do the job''.
 
 The question becomes then, what low-level language to choose? There
@@ -63,8 +65,8 @@ present on all Guile installations.
 The easiest (and most fun) way to depend on a virtual machine is to
 implement the virtual machine within Guile itself. This way the
 virtual machine provides what Scheme needs (tail calls, multiple
-values, call/cc) and can provide optimized inline instructions for
-Guile (cons, struct-ref, etc.).
+values, @code{call/cc}) and can provide optimized inline instructions
+for Guile (@code{cons}, @code{struct-ref}, etc.).
 
 So this is what Guile does. The rest of this section describes that VM
 that Guile implements, and the compiled procedures that run on it.
@@ -72,7 +74,7 @@ that Guile implements, and the compiled procedures that run on it.
 Note that this decision to implement a bytecode compiler does not
 preclude native compilation. We can compile from bytecode to native
 code at runtime, or even do ahead of time compilation. More
-possibilities are discussed in @xref{Extending the Compiler}.
+possibilities are discussed in @ref{Extending the Compiler}.
 
 @node VM Concepts
 @subsection VM Concepts
@@ -84,7 +86,7 @@ virtual machine per thread. When a VM-compiled procedure is run, Guile
 looks up the virtual machine for the current thread and executes the
 procedure using that VM.
 
-Guile's virtual machine is a stack machine -- that is, it has few
+Guile's virtual machine is a stack machine---that is, it has few
 registers, and the instructions defined in the VM operate by pushing
 and popping values from a stack.
 
@@ -114,7 +116,7 @@ is described in the next section.
 A virtual machine executes by loading a compiled procedure, and
 executing the object code associated with that procedure. Of course,
 that procedure may call other procedures, tail-call others, ad
-infinitum -- indeed, within a guile whose modules have all been
+infinitum---indeed, within a guile whose modules have all been
 compiled to object code, one might never leave the virtual machine.
 
 @c wingo: I wish the following were true, but currently we just use
@@ -189,8 +191,8 @@ The @code{ip} to return to if this application returns multiple
 values. For continuations that only accept one value, this value will
 be @code{NULL}; for others, it will be an @code{ip} that points to a
 multiple-value return address in the calling code. That code will
-expect the top value on the stack to be an integer -- the number of
-values being returned -- and that below that integer there are the
+expect the top value on the stack to be an integer---the number of
+values being returned---and that below that integer there are the
 values being returned.
 
 @item Dynamic link
@@ -320,7 +322,7 @@ Bytecode:
 
 At @code{ip} 0 and 2, we do the copy from argument to heap for
 @code{a}. @code{Ip} 4 loads up the compiled lambda, and then at
-@code{ip} 6 we make a closure -- binding code (from the compiled
+@code{ip} 6 we make a closure---binding code (from the compiled
 lambda) with data (the heap-allocated variables). Finally we return
 the closure.
 
@@ -385,7 +387,7 @@ instructions. More instructions may be added over time.
 @subsubsection Environment Control Instructions
 
 These instructions access and mutate the environment of a compiled
-procedure -- the local bindings, the ``external'' bindings, and the
+procedure---the local bindings, the ``external'' bindings, and the
 toplevel bindings.
 
 @deffn Instruction local-ref index
@@ -575,7 +577,7 @@ procedure. This instruction pops the following values from the stack:
 
 @itemize
 @item Optionally, a thunk, which when called should return metadata
-associated with this program -- for example its name, the names of its
+associated with this program---for example its name, the names of its
 arguments, its documentation string, debugging information, etc.
 
 Normally, this thunk its itself a compiled procedure (with no
@@ -852,7 +854,7 @@ to avoid the overhead of creating new stack frames.
 
 Since most of these operations are historically implemented as C
 primitives, not inlining them would entail constantly calling out from
-the VM to the interpreter, which has some costs -- registers must be
+the VM to the interpreter, which has some costs---registers must be
 saved, the interpreter has to dispatch, called procedures have to do
 much typechecking, etc. It's much more efficient to inline these
 operations in the virtual machine itself.