Changeset 9200 for release

Timestamp:

Apr 20, 2008, 12:41:46 AM (17 years ago)

Author:

Gary Byers

Message:

synch with trunk

Location:

release/1.2/source

Files:

• cocoa-ide/cocoa-backtrace.lisp (modified) (1 diff)
• cocoa-ide/cocoa-typeout.lisp (modified) (1 diff)
• cocoa-ide/hemlock/src/key-event.lisp (modified) (1 diff)
• cocoa-ide/processes-window.lisp (modified) (1 diff)
• compiler/PPC/ppc2.lisp (modified) (2 diffs)
• compiler/X86/x862.lisp (modified) (2 diffs)
• compiler/nx-basic.lisp (modified) (3 diffs)
• compiler/nx0.lisp (modified) (9 diffs)
• doc/ccl-documentation.html (copied) (copied from trunk/source/doc/ccl-documentation.html )
• doc/release-notes.txt (modified) (1 diff)
• doc/src/build.xml (modified) (19 diffs)
• doc/src/ide.xml (modified) (2 diffs)
• doc/src/implementation.xml (modified) (10 diffs)
• doc/src/install.xml (modified) (11 diffs)
• doc/src/modifying.xml (modified) (7 diffs)
• doc/src/using.xml (modified) (7 diffs)
• examples/cocoa/tiny.lisp (copied) (copied from trunk/source/examples/cocoa/tiny.lisp )
• examples/hons-example.lisp (deleted)
• examples/opengl-ffi.lisp (modified) (1 diff)
• examples/rubix/rubix.lisp (modified) (1 diff)
• examples/tiny.lisp (deleted)
• level-1/l1-clos-boot.lisp (modified) (1 diff)
• level-1/l1-clos.lisp (modified) (7 diffs)
• level-1/l1-dcode.lisp (modified) (3 diffs)
• level-1/l1-streams.lisp (modified) (1 diff)
• lib/compile-ccl.lisp (modified) (2 diffs)
• lib/macros.lisp (modified) (20 diffs)
• lib/nfcomp.lisp (modified) (1 diff)
• lib/pprint.lisp (modified) (1 diff)
• library/chud-metering.lisp (modified) (4 diffs)
• library/chud-metering.txt (modified) (2 diffs)
• library/oprofile.txt (copied) (copied from trunk/source/library/oprofile.txt )
• objc-bridge/objc-clos.lisp (modified) (1 diff)
• objc-bridge/objc-support.lisp (modified) (2 diffs)

release/1.2/source/cocoa-ide/cocoa-backtrace.lisp

@@ -154 +154 @@
                  (setq val-p t value (cddr rawval))))))
         (if val-p
-          (cinspect value))))))
+          (inspect value))))))
 
 

release/1.2/source/cocoa-ide/cocoa-typeout.lisp

@@ -38 +38 @@
 
 (objc:defmethod #/initWithFrame: ((self typeout-view) (frame :<NSR>ect))
+  (declare (special *default-font-name* *default-font-size*))
   (call-next-method frame)
   (let* ((scrollview (make-instance 'ns:ns-scroll-view

release/1.2/source/cocoa-ide/hemlock/src/key-event.lisp

@@ -120 +120 @@
 ;;; signals an error.
 ;;;
+#+unused
 (defun mouse-translation-info (button event-key info)
   (let ((event-dispatch (svref *mouse-translation-info* button)))

release/1.2/source/cocoa-ide/processes-window.lisp

@@ -98 +98 @@
       (unless (minusp row)
         (setq p (svref processes row))
-        (cinspect p)
+        (inspect p)
         (#/refresh: self self)))))
 

release/1.2/source/compiler/PPC/ppc2.lisp

@@ -2019 +2019 @@
                           (eql (hard-regspec-value unscaled-idx) ppc::arg_y)
                           (eql (hard-regspec-value val-reg) ppc::arg_z))
-               (nx-error "Bug: invalid register targeting for gvset: ~s" (list src unscaled-idx val-reg)))
+               (compiler-bug "Bug: invalid register targeting for gvset: ~s" (list src unscaled-idx val-reg)))
              (! call-subprim-3 val-reg (subprim-name->offset '.SPgvset) src unscaled-idx val-reg))
             (is-node
@@ -5003 +5003 @@
                 (! unbind-interrupt-level-inline)
                 (! unbind-interrupt-level)))
-            (nx-error "unknown payback token ~s" r)))))))
+            (compiler-bug "unknown payback token ~s" r)))))))
 
 (defun ppc2-spread-lambda-list (seg listform whole req opt rest keys 

release/1.2/source/compiler/X86/x862.lisp

@@ -2167 +2167 @@
                           (eql (hard-regspec-value unscaled-idx) x8664::arg_y)
                           (eql (hard-regspec-value val-reg) x8664::arg_z))
-               (nx-error "Bug: invalid register targeting for gvset: ~s" (list src unscaled-idx val-reg)))
+               (compiler-bug "Bug: invalid register targeting for gvset: ~s" (list src unscaled-idx val-reg)))
              (! call-subprim-3 val-reg (subprim-name->offset '.SPgvset) src unscaled-idx val-reg))
             (is-node
@@ -5028 +5028 @@
                   (! unbind-interrupt-level-inline))
                 (! unbind-interrupt-level)))
-            (nx-error "unknown payback token ~s" r)))))))
+            (compiler-bug "unknown payback token ~s" r)))))))
 
 (defun x862-spread-lambda-list (seg listform whole req opt rest keys 

release/1.2/source/compiler/nx-basic.lisp

@@ -488 +488 @@
             (ecase (compiler-warning-warning-type condition)       
               (:global-mismatch "the current global definition of ~s")
-              (:environment-mismatch "the definition of ~s visible in the current compilation unit")
+              (:environment-mismatch "the definition of ~s visible in the current compilation unit.")
               (:lexical-mismatch "the lexically visible definition of ~s"))
             callee)))
-
 
 (defparameter *compiler-warning-formats*
   '((:special . "Undeclared free variable ~S")
     (:unused . "Unused lexical variable ~S")
-    (:ignore . "Variable ~S not ignored")
+    (:ignore . "Variable ~S not ignored.")
     (:undefined-function . "Undefined function ~S")
     (:unknown-declaration . "Unknown declaration ~S")
     (:unknown-type-declaration . "Unknown type ~S")
-    (:macro-used-before-definition . "Macro function ~S was used before it was defined")
+    (:macro-used-before-definition . "Macro function ~S was used before it was defined.")
     (:unsettable . "Shouldn't assign to variable ~S")
     (:global-mismatch . report-compile-time-argument-mismatch)
@@ -507 +506 @@
     (:type . "Type declarations violated in ~S")
     (:type-conflict . "Conflicting type declarations for ~S")
-    (:special-fbinding . "Attempt to bind compiler special name: ~s. Result undefined")
+    (:special-fbinding . "Attempt to bind compiler special name: ~s. Result undefined.")
     (:lambda . "Suspicious lambda-list: ~s")
-    (:result-ignored . "Function result ignored in call to ~s")))
+    (:result-ignored . "Function result ignored in call to ~s")
+    (:program-error . "~a")))
+
 
 (defun report-compiler-warning (condition stream)
@@ -520 +521 @@
       (apply #'format stream format-string (compiler-warning-args condition))
       (funcall format-string condition stream))
-    (format stream ".")
+    ;(format stream ".")
     (let ((nrefs (compiler-warning-nrefs condition)))
       (when (and nrefs (neq nrefs 1))

release/1.2/source/compiler/nx0.lisp

@@ -1255 +1255 @@
                                 (%i+ (%i- boundtocount 1) varcount)))))))))
 
+;; Home-baked handler-case replacement.  About 10 times as fast as full handler-case.
+;;(LET ((S 0)) (DOTIMES (I 1000000) (INCF S))) took 45,678 microseconds
+;;(LET ((S 0)) (DOTIMES (I 1000000) (BLOCK X (ERROR (CATCH 'X (RETURN-FROM X (INCF S))))))) took 57,485
+;;(LET ((S 0)) (DOTIMES (I 1000000) (HANDLER-CASE (INCF S) (ERROR (C) C)))) took 168,947
+(defmacro with-program-error-handler (handler &body body)
+  (let ((tag (gensym)))
+    `(block ,tag
+       (,handler (catch 'program-error-handler (return-from ,tag (progn ,@body)))))))
+
 (defun nx1-compile-lambda (name lambda-form &optional
                                  (p (make-afunc))
@@ -1307 +1316 @@
     (if (%non-empty-environment-p *nx-lexical-environment*)
       (setf (afunc-bits p) (logior (ash 1 $fbitnonnullenv) (the fixnum (afunc-bits p)))))
-    (multiple-value-bind (body decls)
-                         (parse-body (%cddr lambda-form) *nx-lexical-environment* t)
-      (setf (afunc-lambdaform p) lambda-form)
-      (setf (afunc-acode p) (nx1-lambda (%cadr lambda-form) body decls))
-      (nx1-transitively-punt-bindings *nx-punted-vars*)
-      (setf (afunc-blocks p) *nx-blocks*)
-      (setf (afunc-tags p) *nx-tags*)
-      (setf (afunc-inner-functions p) *nx-inner-functions*)
-      (setf (afunc-all-vars p) *nx-all-vars*)
-      (setf (afunc-vcells p) *nx1-vcells*)
-      (setf (afunc-fcells p) *nx1-fcells*)
-      (let* ((warnings (merge-compiler-warnings *nx-warnings*))
-             (name *nx-cur-func-name*))        
-        (dolist (inner *nx-inner-functions*)
-          (dolist (w (afunc-warnings inner))
-            (push name (compiler-warning-function-name w))
-            (push w warnings)))
-        (setf (afunc-warnings p) warnings))
-      p)))
+
+    (setf (afunc-lambdaform p) lambda-form)
+    (with-program-error-handler
+        (lambda (c)
+          (setf (afunc-acode p) (nx1-lambda () `((error ',c)) nil)))
+      (handler-bind ((warning (lambda (c)
+                                (nx1-whine :program-error c)
+                                (muffle-warning c)))
+                     (program-error (lambda (c)
+                                      (when (typep c 'compile-time-program-error)
+                                        (setq c (make-condition 'simple-program-error
+                                                  :format-control (simple-condition-format-control c)
+                                                  :format-arguments (simple-condition-format-arguments c))))
+                                      (nx1-whine :program-error c)
+                                      (throw 'program-error-handler c))))
+        (multiple-value-bind (body decls)
+            (with-program-error-handler (lambda (c) `(error ',c))
+              (parse-body (%cddr lambda-form) *nx-lexical-environment* t))
+          (setf (afunc-acode p) (nx1-lambda (%cadr lambda-form) body decls)))))
+
+    (nx1-transitively-punt-bindings *nx-punted-vars*)
+    (setf (afunc-blocks p) *nx-blocks*)
+    (setf (afunc-tags p) *nx-tags*)
+    (setf (afunc-inner-functions p) *nx-inner-functions*)
+    (setf (afunc-all-vars p) *nx-all-vars*)
+    (setf (afunc-vcells p) *nx1-vcells*)
+    (setf (afunc-fcells p) *nx1-fcells*)
+    (let* ((warnings (merge-compiler-warnings *nx-warnings*))
+           (name *nx-cur-func-name*))        
+      (dolist (inner *nx-inner-functions*)
+        (dolist (w (afunc-warnings inner))
+          (push name (compiler-warning-function-name w))
+          (push w warnings)))
+      (setf (afunc-warnings p) warnings))
+    p))
 
 (defun method-lambda-p (form)
@@ -1591 +1616 @@
 
 (defun nx1-typed-form (original env)
-  (nx1-transformed-form (nx-transform original env) env))
+  (let ((form (with-program-error-handler
+                  (lambda (c)
+                    (nx-transform `(error ',c) env))
+                (nx-transform original env))))
+    (nx1-transformed-form form env)))
 
 (defun nx1-transformed-form (form &optional (env *nx-lexical-environment*))
@@ -1801 +1830 @@
 
 (defun nx1-typed-call (sym args)
-  (let ((type (nx1-call-result-type sym args))
-        (form (nx1-call sym args)))
-    (if (eq type t)
-      form
-      (list (%nx1-operator typed-form) type form))))
+  (multiple-value-bind (type errors-p) (nx1-call-result-type sym args)
+    (let ((form (nx1-call sym args nil nil errors-p)))
+      (if (eq type t)
+        form
+        (list (%nx1-operator typed-form) type form)))))
 
 ;;; Wimpy.
@@ -1813 +1842 @@
          (lexenv-def nil)
          (defenv-def nil)
-         (somedef nil))
+         (somedef nil)
+         (whined nil))
     (when (and sym 
                (symbolp sym)
@@ -1823 +1853 @@
       (if args-p
         (nx1-whine :undefined-function sym args spread-p)
-        (nx1-whine :undefined-function sym)))
+        (nx1-whine :undefined-function sym))
+      (setq whined t))
     (when (and args-p (setq somedef (or lexenv-def defenv-def global-def)))
       (multiple-value-bind (deftype  reason)
           (nx1-check-call-args somedef args spread-p)
         (when deftype
-          (nx1-whine deftype sym reason args spread-p))))
-    (nx-target-type *nx-form-type*)))
+          (nx1-whine deftype sym reason args spread-p)
+          (setq whined t))))
+    (values (nx-target-type *nx-form-type*) whined)))
 
 (defun find-ftype-decl (sym env)
@@ -1943 +1975 @@
 ;;; If "sym" is an expression (not a symbol which names a function),
 ;;; the caller has already alphatized it.
-(defun nx1-call (sym args &optional spread-p global-only)
+(defun nx1-call (sym args &optional spread-p global-only inhibit-inline)
   (nx1-verify-length args 0 nil)
   (let ((args-in-regs (if spread-p 1 (backend-num-arg-regs *target-backend*))))
@@ -1954 +1986 @@
         (make-acode (%nx1-operator self-call) (nx1-arglist args args-in-regs) spread-p))
       (multiple-value-bind (lambda-form containing-env token) (nx-inline-expansion sym *nx-lexical-environment* global-only)
-        (or (nx1-expand-inline-call lambda-form containing-env token args spread-p *nx-lexical-environment*)
+        (or (and (not inhibit-inline)
+                 (nx1-expand-inline-call lambda-form containing-env token args spread-p *nx-lexical-environment*))
             (multiple-value-bind (info afunc) (if (and  (symbolp sym) (not global-only)) (nx-lexical-finfo sym))
               (when (eq 'macro (car info))
@@ -1978 +2011 @@
   (if (and (or (null spread-p) (eq (length args) 1)))
     (if (and token (not (memq token *nx-inline-expansions*)))
-      (let* ((*nx-inline-expansions* (cons token *nx-inline-expansions*))
-             (lambda-list (cadr lambda-form))
-             (body (cddr lambda-form))
-             (new-env (new-lexical-environment env)))
-        (setf (lexenv.mdecls new-env)
+      (with-program-error-handler (lambda (c) (declare (ignore c)) nil)
+        (let* ((*nx-inline-expansions* (cons token *nx-inline-expansions*))
+               (lambda-list (cadr lambda-form))
+               (body (cddr lambda-form))
+               (new-env (new-lexical-environment env)))
+          (setf (lexenv.mdecls new-env)
                 `((speed . ,(speed-optimize-quantity old-env))
-                           (space . ,(space-optimize-quantity old-env))
-                           (safety . ,(space-optimize-quantity old-env))
-                           (compilation-speed . ,(compilation-speed-optimize-quantity old-env))
-                           (debug . ,(debug-optimize-quantity old-env))))
-        (if spread-p
-          (nx1-destructure lambda-list (car args) nil nil body new-env)
-          (nx1-lambda-bind lambda-list args body new-env))))))
+                  (space . ,(space-optimize-quantity old-env))
+                  (safety . ,(space-optimize-quantity old-env))
+                  (compilation-speed . ,(compilation-speed-optimize-quantity old-env))
+                  (debug . ,(debug-optimize-quantity old-env))))
+          (if spread-p
+            (nx1-destructure lambda-list (car args) nil nil body new-env)
+            (nx1-lambda-bind lambda-list args body new-env)))))))
              
 ; note that regforms are reversed: arg_z is always in the car

release/1.2/source/doc/release-notes.txt

@@ +1 @@
+ClozureCL 1.2
+=============
+
+Welcome to the first ClozureCL (aka OpenMCL) release in about 2.5 years!
+(There have been a lot of 1.1-prerelease snapshots in that time frame,
+and there's been a lot of development activity; hopefully, it'll be
+a little easier for people who wish to use a relatively stable version
+to do so and still make it easy for those who want to track the bleeding
+edge of development to do so.)
+
+[In the fall of 2007, Alice Hartley of Digitool announced that MCL (the
+commercial product from which OpenMCL was derived) would be opensourced.
+In order to reduce potential confusion between the new "open MCL" and
+"OpenMCL" - and to coincidentally make the primary implementation package
+and default installation directory name ("ccl") meaningful again - we
+decided to rename OpenMCL to "Clozure CL" (or "CCL").  There are still
+references to the old name in URLs, bits and pieces of the lisp itself,
+mailing lists, and elsewhere.]
+
+Obtaining Clozure CL
+--------------------
+Gzip'ed tar archives of Clozure CL 1.2  are available via anonymous FTP
+from:
+
+<ftp://clozure.com/pub/release/1.2>
+
+in files whose names are of the form
+clozurecl-1.2-[RELEASE-LEVEL-]PLATFORM.tar.gz
+
+where
+RELEASE-LEVEL may be "rcN" to indicate "release candidate N", or absent, and
+PLATFORM is one of "linuxppc", "darwinppc", "linuxx8664", "darwinx8664", or
+"freebsdx8664".  The "ppc" archives contain 32- and 64-bit binaries and
+interfaces; the x8664 archives are (still) 64-bit only.  All archives
+contain full sources and documentation, and also svn 1.4x metainformation
+(see below.)
+
+It's also possible to check out content equivalent to any of these
+archives by using an "svn" client (again, see below.).  The URL is of the
+form:
+
+http://svn.clozure.com/publicsvn/openmcl/release/1.2/PLATFORM/ccl
+
+where PLATFORM is defined as above.
+
+To check out a fresh copy of the current CCL 1.2 distribution for DarwinPPC,
+one would do something like:
+
+shell> cd some-directory-that-doesn't-have-a-ccl-subdirectory
+shell> svn co http://svn.clozure.com/publicsvn/openmcl/release/1.2/darwinppc/ccl
+
+We plan on making disk images (.dmg files) containing the Cocaa IDE and
+the full CCL distribution available in the near future.
+
+Documentation
+-------------
+
+Documentation is available online at: 
+
+<http://ccl.clozure.com/ccl-documentation.html>
+
+A recent version of the HTML documentation is also included in the
+distribution, along with the DocBook source from which it's derived.
+These release notes describe some important recent (for some value
+of "recent") changes.
+
+Bug Reporting
+-------------
+
+Please use the trac instance at 
+
+<http://trac.clozure.com/openmcl>
+
+to review existing bug reports and submit new ones.
+
+CVS out, SVN in:
+---------------
+
+Until the spring of 2007, ClozureCL used CVS for revision control;
+tar archives for the 1.0 release and 1.1 snapshots contained CVS
+metainformation, and it was generally possible to use "cvs update"
+and related commands to update an installation to the latest version.
+
+At that time, we switched to using the Subversion ("SVN") revision
+control system, but continued to mirror the main line of development
+in CVS (to the extent that this was possible, given some limitations
+of CVS.)
+
+This release is entirely SVN-based and makes use of Subversion features
+that can't be supported in CVS. Subversion clients are widely available
+for all platforms that ClozureCL runs on:
+
+ - FreeBSD and Linux users will likely find that subversion packages
+   are readily available through their distribution's package management
+   systems.
+
+ - 'svn' is preinstalled on OSX Leopard
+
+ - OSX Tiger users can install Subversion via Fink or MacPorts, or
+   look at <http://downloads.open.collab.net/binaries.html> for other
+   options.
+
+It should be possible to use GUI svn clients if you prefer.
+
+Note that the tar archives that contain ClozureCL distributions
+contain svn metainformation that assumes the use of a version 1.4 or
+later svn client; the format of some of that metainformation isn't
+understood by older clients.  If you have an older client (and can't
+install something more up-to-date), you ignore the tarballs and just
+check out the full CCL distribution (sources, binaries, interfaces
+...) via svn.
+
+Quick guide to svn:
+------------------
+shell> cd ccl           # wherever that is ...
+shell> svn update       # try to synch working copy with svn repository
+
+shell> svn revert <files> # discard local changes to <files>, recover
+                          # versions from last update.
+
+svn notes/issues
+----------------
+
+svn does a fairly good job of handling binary files, and in fact the
+CCL lisp kernel, heap image, and interface database files are maintained
+in svn.  (One benefit of this scheme is that it may be a little easier
+to distribute modified heap images that reflect changes that may be hard
+to bootstrap from source.)  Occasionally, an "svn update" operation may
+fail to replace a locally-modified copy of a binary file; when this
+happens, one way to recover is to use "svn revert" to discard local
+changes.
+
+The "Welcome ..." banner (and the string returned by
+LISP-IMPLEMENTATION-VERSION) contain the repository's revision number
+(an integer that increases whenever any file in the CCL repository
+changes) as of the time that the lisp image is built.  If there are
+locally-modified files (including re-compiled kernels or heap images)
+in the working copy, the revision number may contain a trailing "M"
+character; this isn't very significant, but might be a little mysterious.
+
+1.1 release notes
+-----------------
+All of the information contained in the file ccl/doc/release-notes-1.1.txt
+should be incorporated into the documentation; people who didn't use
+the 1.1 "snapshot" releases might find that file to be worth skimming.
+Some highlights include:
+
+ - use of Unicode internally, and support for reading and writing streams
+encoded in many commonly-used character encoding schemes.
+ - support for 64-bit x86 (amd64/x86-64) hardware (32-bit Intel support
+is under active development, but is not yet ready for public consumption.)
+ - many changes to the Cocoa Bridge, lots of enhancements to the Cocoa-based
+IDE (which runs on 32-bit DarwinPPC under Tiger and Leopard and on 64-bit
+DarwinX8664 on Leopard.
+ - lots of other changes (didn't I already write down descriptions of
+them somewhere ?
+
+More recent changes
+-------------------
+
+- The keywords :MCL and :OPENMCL-HASH-CONSING have been removed from
+*FEATURES*, and the keywords :CLOZURE-COMMON-LISP, :CCL and :CCL-1.2
+have been added.  :OPENMCL-HASH-CONSING denoted an experimental
+feature that was never used, and the presence of :MCL created some
+confusion (OpenMCL/CCL and commercial MCL have been diverging for
+about 10 years now, and many of the things that typically need read-time
+conditionalization - pathname syntax, threading, networking ... - need
+to be conditionalized differently for the two implementations.)  Code
+that has used the presence/absence of the :MCL feature to conditionalize
+for OpenMCL may need to be reviewed.
+
+The presence of :CCL-1.2 should be viewed as "features described in the
+Clozure CL 1.2 documentation are present", i.e., "this is at least version
+1.2 of CCL".
+
+There should also be a "simple" keyword denoting the OS name - :LINUX,
+:DARWIN, or :FREEBSD.
+
+- sockets support :CONNECT-TIMEOUT arguments and streams (including sockets)
+support :READ-TIMEOUT and :WRITE-TIMEOUT arguments in their creation functions
+(OPEN, MAKE-SOCKET, etc.)  An active socket connect operation that takes
+longer than the number of seconds specified in the socket's :CONNECT-TIMEOUT
+argument - or an I/O operation that takes longer than the applicable
+:READ-TIMEOUT or :WRITE-TIMEOUT's argument - will cause an error to be
+signaled.
+
+- profiling via Apple's CHUD tools (finally) works on 64-bit versions of
+CCL.  See ccl/library/chud-metering.txt for details.
+
+- profiling on x86-64 Linux - using the 'oprofile' profiler - is now 
+supported (or, more accurately, it's possible to generate symbolic 
+information that allows 'oprofile' and related tools to give meaningful
+names to lisp functions.)  See ccl/library/oprofile.txt for details.
+
+- on OSX/Darwin, pathnames are now recognized as being encoded in
+"decomposed UTF-8", which isn't quite as bad as it sounds.  (This
+should mean that pathnames that contain non-ASCII characters should
+be handled correctly.)
+
+- in the Cocoa IDE, Hemlock editor commands now run in the main event
+thread (they used to run in a dedicated, per-window thread), and many
+other aspects of Hemlock/Cocoa integration have been simplified and
+improved.  Aside from offering greater stability, these changes make
+the Hemlock programming interface a lot more tractable.  People
+interested in writing Hemlock editor commands for use in the IDE may
+find a revised version of the Hemlock Command Implementor's Manual
+<http://trac.clozure.com/openmcl/wiki/HemlockProgrammer> useful.
+
+When run as a standalone application, the IDE provides a "console"
+window which displays diagnostic output that otherwise only appears
+in the system logs.
+
+- lots of bug fixes, smaller changes, and performance improvements.
+
+

release/1.2/source/doc/src/build.xml

@@ -1 +1 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY rest "<varname>&amp;rest</varname>">
-<!ENTITY key "<varname>&amp;key</varname>">
-<!ENTITY optional "<varname>&amp;optional</varname>">
-<!ENTITY body "<varname>&amp;body</varname>">
-<!ENTITY aux "<varname>&amp;aux</varname>">
-<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
-<!ENTITY CCL "Clozure CL">
-]>
-  <chapter><title>Building &CCL; from its Source Code</title>
-    <anchor id="Building-CCL"/>
-    <para>&CCL;, like many other Lisp implementations, consists of a
+          <!ENTITY rest "<varname>&amp;rest</varname>">
+          <!ENTITY key "<varname>&amp;key</varname>">
+          <!ENTITY optional "<varname>&amp;optional</varname>">
+          <!ENTITY body "<varname>&amp;body</varname>">
+          <!ENTITY aux "<varname>&amp;aux</varname>">
+          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
+          <!ENTITY CCL "Clozure CL">
+          ]>
+<chapter><title>Building &CCL; from its Source Code</title>
+  <anchor id="Building-CCL"/>
+  <para>&CCL;, like many other Lisp implementations, consists of a
     kernel and a heap image.  The kernel is an ordinary C program, and
     is built with a C compiler.  It provides very basic and
@@ -20 +20 @@
     nor the heap image can stand alone.</para>
 
-    <para>You may already know that, when you have a C compiler which
+  <para>You may already know that, when you have a C compiler which
     is written in C, you need a working C compiler to build the
     compiler. Similarly, the &CCL; heap image includes a Lisp
     compiler, which is written in Lisp. You therefore need a working
     Lisp compiler in order to build the Lisp heap image.</para>
-    
-    <para>Where will you get a working Lisp compiler?  No worries; you
+  
+  <para>Where will you get a working Lisp compiler?  No worries; you
     can use a precompiled copy of a (slightly older and compatible)
     version of &CCL;. This section explains how to do all this.</para>
 
-    <para>In principle it should be possible to use another
+  <para>In principle it should be possible to use another
     implementation of Common Lisp as the host compiler, rather than an
     older &CCL;; this would be a challenging and experimental way to
     build, and is not described here.</para>
 
-    <sect1 id="building-definitions"><title>Building Definitions</title>
-      <para>The following terms are used in subsequent sections; it
+  <sect1 id="building-definitions"><title>Building Definitions</title>
+    <para>The following terms are used in subsequent sections; it
       may be helpful to refer to these definitions.</para>
 
-      <para><indexterm><primary>fasl
-      files</primary></indexterm><glossterm linkend="fasl-file">fasl
-      files</glossterm> are the object files produced
+    <para><indexterm><primary>fasl
+          files</primary></indexterm><glossterm linkend="fasl-file">fasl
+        files</glossterm> are the object files produced
       by <literal>compile-file</literal>.  fasl files store the
       machine code associated with function definitions and the
@@ -52 +52 @@
       <xref linkend="Platform-specific-filename-conventions"/> </para>
 
-      <para>The <indexterm><primary>lisp
-      kernel</primary></indexterm> <glossterm linkend="lisp_kernel">Lisp
-      kernel</glossterm> is a C program with a fair amount of
+    <para>The <indexterm><primary>lisp
+          kernel</primary></indexterm> <glossterm linkend="lisp_kernel">Lisp
+        kernel</glossterm> is a C program with a fair amount of
       platform-specific assembly language code. Its basic job is to
       map a lisp heap image into memory, transfer control to some
@@ -64 +64 @@
       <xref linkend="Platform-specific-filename-conventions"/>.</para>
 
-      <para>A <indexterm><primary>heap
-      image</primary></indexterm> <glossterm linkend="lisp_image">heap
-      image</glossterm> is a file that can be quickly mapped into a
+    <para>A <indexterm><primary>heap
+          image</primary></indexterm> <glossterm linkend="lisp_image">heap
+        image</glossterm> is a file that can be quickly mapped into a
       process' address space. Conceptually, it's not too different
       from an executable file or shared library in the OS's native
@@ -77 +77 @@
       <xref linkend="Platform-specific-filename-conventions"/>.</para>
 
-      <para>A <indexterm><primary>bootstrapping
-      image</primary></indexterm> bootstrapping image is a minimal
+    <para>A <indexterm><primary>bootstrapping
+          image</primary></indexterm> bootstrapping image is a minimal
       heap image used in the process of building &CCL; itself.  The
       bootstrapping image contains just enough code to load the rest
@@ -88 +88 @@
       .</para>
 
-      <para>Each supported platform (and possibly a few
+    <para>Each supported platform (and possibly a few
       as-yet-unsupported ones) has a uniquely named subdirectory of
       <literal>ccl/lisp-kernel/</literal>; each such
@@ -98 +98 @@
       <xref linkend="Platform-specific-filename-conventions"/>.</para>
 
-      <sect2 id="filename_conventions">
-       <title>Platform-specific filename conventions</title>
-       <table id ="Platform-specific-filename-conventions">
-         <title>Platform-specific filename conventions</title>
-         <tgroup cols="6">
-           <thead>
+    <sect2 id="filename_conventions">
+      <title>Platform-specific filename conventions</title>
+      <table id ="Platform-specific-filename-conventions">
+            <title>Platform-specific filename conventions</title>
+            <tgroup cols="6">
+              <thead>
             <row>
-                <entry>Platform</entry>
-                <entry>kernel</entry>
-                <entry>full-image</entry>
-                <entry>boot-image</entry>
-                <entry>fasl extension</entry>
-                <entry>kernel-build directory</entry>
-            </row>
-           </thead>
-           <tbody>
-             <row>
-               <entry>DarwinPPC32</entry>
-                <entry>dppccl</entry>
-                <entry>dppccl.image</entry>
-                <entry>ppc-boot.image</entry>
-                <entry>.dfsl</entry>
-                <entry>darwinppc</entry>
-             </row>
-             <row>
-               <entry>LinuxPPC32</entry>
-                <entry>ppccl</entry>
-                <entry>PPCCL</entry>
-                <entry>ppc-boot</entry>
-                <entry>.pfsl</entry>
-                <entry>linuxppc</entry>
-             </row>
-             <row>
-               <entry>DarwinPPC64</entry>
-               <entry>dppccl64</entry>
-               <entry>dppccl64.image</entry>
-               <entry>ppc-boot64.image</entry>
-               <entry>.d64fsl</entry>
-               <entry>darwinppc64</entry>
-             </row>
-              <row>
-                <entry>LinuxPPC64</entry>
-                <entry>ppccl64</entry>
-                <entry>PPCCL64</entry>
-                <entry>ppc-boot64</entry>
-                <entry>.p64fsl</entry>
-                <entry>linuxppc64</entry>
-              </row>
-              <row>
-                <entry>LinuxX8664</entry>
-                <entry>lx86cl64</entry>
-                <entry>LX86CL64</entry>
-                <entry>x86-boot64</entry>
-                <entry>.lx64fsl</entry>
-                <entry>linuxx8664</entry>
-              </row>
-              <row>
-                <entry>DarwinX8664</entry>
-                <entry>dx86cl64</entry>
-                <entry>dx86cl64.image</entry>
-                <entry>x86-boot64.image</entry>
-                <entry>.dx64fsl</entry>
-                <entry>darwinx8664</entry>
-              </row>
-              <row>
-                <entry>FreeBSDX8664</entry>
-                <entry>fx86cl64</entry>
-                <entry>FX86CL64</entry>
-                <entry>fx86-boot64</entry>
-                <entry>.fx64fsl</entry>
-                <entry>freebsdx8664</entry>
-              </row>
-           </tbody>
-         </tgroup>
-       </table>
-      </sect2>
-    </sect1>
-
-    <sect1 id="Setting-Up-to-Build">
-      <title>Setting Up to Build</title>
-      <para>There are currently three versions of &CCL; that you
+              <entry>Platform</entry>
+              <entry>kernel</entry>
+              <entry>full-image</entry>
+              <entry>boot-image</entry>
+              <entry>fasl extension</entry>
+              <entry>kernel-build directory</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>DarwinPPC32</entry>
+              <entry>dppccl</entry>
+              <entry>dppccl.image</entry>
+              <entry>ppc-boot.image</entry>
+              <entry>.dfsl</entry>
+              <entry>darwinppc</entry>
+                </row>
+                <row>
+                  <entry>LinuxPPC32</entry>
+              <entry>ppccl</entry>
+                      <entry>PPCCL</entry>
+              <entry>ppc-boot</entry>
+              <entry>.pfsl</entry>
+              <entry>linuxppc</entry>
+                </row>
+                <row>
+                  <entry>DarwinPPC64</entry>
+                  <entry>dppccl64</entry>
+                  <entry>dppccl64.image</entry>
+                  <entry>ppc-boot64.image</entry>
+                  <entry>.d64fsl</entry>
+                  <entry>darwinppc64</entry>
+            </row>
+            <row>
+                      <entry>LinuxPPC64</entry>
+              <entry>ppccl64</entry>
+              <entry>PPCCL64</entry>
+              <entry>ppc-boot64</entry>
+              <entry>.p64fsl</entry>
+              <entry>linuxppc64</entry>
+            </row>
+                <row>
+                      <entry>LinuxX8664</entry>
+              <entry>lx86cl64</entry>
+              <entry>LX86CL64</entry>
+              <entry>x86-boot64</entry>
+              <entry>.lx64fsl</entry>
+              <entry>linuxx8664</entry>
+            </row>
+                <row>
+                      <entry>DarwinX8664</entry>
+                      <entry>dx86cl64</entry>
+              <entry>dx86cl64.image</entry>
+              <entry>x86-boot64.image</entry>
+              <entry>.dx64fsl</entry>
+              <entry>darwinx8664</entry>
+            </row>
+                <row>
+                      <entry>FreeBSDX8664</entry>
+              <entry>fx86cl64</entry>
+              <entry>FX86CL64</entry>
+              <entry>fx86-boot64</entry>
+              <entry>.fx64fsl</entry>
+              <entry>freebsdx8664</entry>
+            </row>
+              </tbody>
+            </tgroup>
+      </table>
+    </sect2>
+  </sect1>
+
+  <sect1 id="Setting-Up-to-Build">
+    <title>Setting Up to Build</title>
+    <para>There are currently three versions of &CCL; that you
       might want to use (and therefore might want to build from
       source):</para>
-      <itemizedlist>
-        <listitem><para>Version 1.0 - the more stable version</para></listitem>
-        <listitem><para>Version 1.1 - the more recent version, which
-        runs on more platforms (including x86-64 platforms) and
-        supports Unicode</para></listitem>
-        <listitem><para>Version 1.2 - supports (at least) all of the
-        features and platforms as 1.1, but is distributed and updated
-        differently</para></listitem>
-      </itemizedlist>
-      <para>All versions are available for download from the &CCL;
+    <itemizedlist>
+      <listitem><para>Version 1.0 - the more stable version</para></listitem>
+      <listitem><para>Version 1.1 - the more recent version, which
+          runs on more platforms (including x86-64 platforms) and
+          supports Unicode</para></listitem>
+          <listitem><para>Version 1.2 - supports (at least) all of the
+              features and platforms as 1.1, but is distributed and updated
+              differently</para></listitem>
+    </itemizedlist>
+    <para>All versions are available for download from the &CCL;
       website in the form of archives that contain everything you need
       to work with &CCL;, including the complete sources, a full
       heap image, and the foreign-function interface database.</para>
-      <para>Version 1.0 archives are named
+    <para>Version 1.0 archives are named
       <literal>openmcl-</literal><replaceable>platform</replaceable><literal>-all-1.0.tar.gz</literal>,
       where <replaceable>platform</replaceable> is either
@@ -201 +201 @@
       undergoing active development, you won't ever need to update
       these sources.</para>
-      <para>Version 1.1 archives are named
+    <para>Version 1.1 archives are named
       <literal>openmcl-</literal><replaceable>platform</replaceable><literal>-snapshot-</literal><replaceable>yymmdd</replaceable><literal>.tar.gz</literal>,
       where <replaceable>platform</replaceable> is either
@@ -209 +209 @@
       <replaceable>yymmdd</replaceable> is the year, month, and day
       the snapshot was released.</para>
-      <para>Because version 1.1 is undergoing active development,
+    <para>Because version 1.1 is undergoing active development,
       there may be times when you want to get sources that are more
       recent than the most recent snapshot and use them to build
@@ -218 +218 @@
       working-copy information in it, so all you need to do to update
       is</para>
-      <programlisting>
+    <programlisting>
 $ cd ccl
 $ cvs login             # password is "cvs"
-                        # this step only needs to be done once,
-                        # that'll store the trivially encrypted
-                        # password in ~/.cvspas
+# this step only needs to be done once,
+# that'll store the trivially encrypted
+# password in ~/.cvspas
 $ cvs update
-      </programlisting>
-      <para>Unless you tell it to, cvs won't delete ("prune") empty
+    </programlisting>
+    <para>Unless you tell it to, cvs won't delete ("prune") empty
       directories or create new ones when the repository changes.
       It's generally a good habit to use</para>
-      <programlisting>
+    <programlisting>
 $ cvs update -d -P      # create dirs as needed, prune empty ones
-      </programlisting>
-      <para>Version 1.2 archives follow naming conventions that are
+    </programlisting>
+    <para>Version 1.2 archives follow naming conventions that are
       similar to those used by 1.0 (though more platforms are supported.)
       However, rather than containing CVS working-copy information, the
       1.2 (and, presumably, later) archives contain metainformation used
       by the Subversion (svn) source-code control system.</para>
-      <para>Subversion client programs are pre-installed on OSX 10.5 and
+    <para>Subversion client programs are pre-installed on OSX 10.5 and
       later and are typically either pre-installed or readily available
       on Linux and FreeBSD platforms.  The <ulink url="http://subversion.tigris.org">Subversion web page</ulink> contains links to subversion client programs
       for many platforms; users of OSX versions 10.4 and earlier can also
       install Subversion clients via Fink or MacPorts.</para>
-      
-    </sect1>
-
-    <sect1 id="Building-Everything">
-      <title>Building Everything</title>
-      <para>Given that you now have everything you need, do the
+    
+  </sect1>
+
+  <sect1 id="Building-Everything">
+    <title>Building Everything</title>
+    <para>Given that you now have everything you need, do the
       following in a running &CCL; to bring your Lisp system
       completely up to date.</para>
-      <programlisting>
+    <programlisting>
 ? (ccl:rebuild-ccl :full t)
-      </programlisting>
-      <para>That call to the function <literal>rebuild-ccl</literal>
-      will perform the following steps:</para>
-      <itemizedlist>
-        <listitem>
-          <para>Deletes all fasl files and other object files in the
-          <literal>ccl</literal>directory tree</para>
-        </listitem>
-        <listitem>
-          <para>Runs an external process which does a
-          <literal>make</literal> in the currentplatform's kernel
-          build directory to create a new kernel</para>
-        </listitem>
-        <listitem>
-          <para>Does <literal>(compile-ccl t)</literal> in the running
-          lisp, to produce aset of fasl files from the &ldquo;higher
-          level&rdquo; lisp sources.</para>
-        </listitem>
-        <listitem>
-          <para>Does <literal>(xload-level-0 :force)</literal> in the
-          running lisp, to compile thelisp sources in the
-          &ldquo;ccl:level-0;&rdquo; directory into fasl files and
-          then createa bootstrapping image from those fasl
-          files.</para>
-        </listitem>
-        <listitem>
-          <para>Runs another external process, which causes the newly
-          compiled lispkernel to load the new bootstrapping image.
-          The bootsrtrapping image then loadsthe &ldquo;higher
-          level&rdquo; fasl files and a new copy of the platform's
-          full heap imageis then saved.</para>
-        </listitem>
-      </itemizedlist>
-      <para>If all goes well, it'll all happen without user
+    </programlisting>
+    <para>That call to the function <literal>rebuild-ccl</literal>
+      performs the following steps:</para>
+    <itemizedlist>
+      <listitem>
+            <para>Deletes all fasl files and other object files in the
+              <literal>ccl</literal> directory tree</para>
+          </listitem>
+      <listitem>
+            <para>Runs an external process that does a
+              <literal>make</literal> in the current platform's kernel
+              build directory to create a new kernel</para>
+          </listitem>
+      <listitem>
+            <para>Does <literal>(compile-ccl t)</literal> in the running
+              lisp, to produce a set of fasl files from the &ldquo;higher
+              level&rdquo; lisp sources.</para>
+          </listitem>
+      <listitem>
+            <para>Does <literal>(xload-level-0 :force)</literal> in the
+              running lisp, to compile the lisp sources in the
+              &ldquo;ccl:level-0;&rdquo; directory into fasl files and
+              then create a bootstrapping image from those fasl
+              files.</para>
+          </listitem>
+      <listitem>
+            <para>Runs another external process, which causes the newly
+              compiled lisp kernel to load the new bootstrapping image.
+              The bootsrtrapping image then loads the &ldquo;higher
+              level&rdquo; fasl files and a new copy of the platform's
+              full heap image is then saved.</para>
+          </listitem>
+    </itemizedlist>
+    <para>If all goes well, it'll all happen without user
       intervention and with some simple progress messages.  If
       anything goes wrong during execution of either of the external
       processes, the process output is displayed as part of a lisp
       error message.</para>
-      <para><literal>rebuild-ccl</literal> is essentially just a short
+    <para><literal>rebuild-ccl</literal> is essentially just a short
       cut for running all the individual steps involved in rebuilding
       the system.  You can also execute these steps individually, as
       described below.</para>
-    </sect1>
-
-    <sect1 id="Building-the-kernel">
-      <title>Building the kernel</title>
-      <para>The Lisp kernel is the executable which you run to use
+  </sect1>
+
+  <sect1 id="Building-the-kernel">
+    <title>Building the kernel</title>
+    <para>The Lisp kernel is the executable that you run to use
       Lisp.  It doesn't actually contain the entire Lisp
       implementation; rather, it loads a heap image which contains the
-      specifics - the "library", as it might be called if this was a C
+      specifics&mdash;the "library", as it might be called if this was a C
       program.  The kernel also provides runtime support to the heap
       image, such as garbage collection, memory allocation, exception
       handling, and the OS interface.</para>
 
-      <para>The Lisp kernel file has different names on different
-      platforms. See FIXTHIS . On all platforms the lisp kernel sources reside
+    <para>The Lisp kernel file has different names on different
+      platforms. See
+      <xref linkend="Platform-specific-filename-conventions"/>. On all
+      platforms the lisp kernel sources reside
       in <literal>ccl/lisp-kernel</literal>.</para>
 
-      <para>This section gives directions on how to rebuild the Lisp
+    <para>This section gives directions on how to rebuild the Lisp
       kernel from its source code.  Most &CCL; users will rarely
       have to do this.  You probably will only need to do it if you are
@@ -319 +321 @@
 ? (rebuild-ccl :full t)
       </programlisting>
-      </para>
-
-
-      <sect2 id="Kernel-build-prerequisites">
-        <title>Kernel build prerequisites</title>
-        <para>The &CCL; kernel can be bult with the following widely
-        available tools:</para>
-        <itemizedlist>
-          <listitem><para>cc or gcc- the GNU C compiler</para></listitem>
-          <listitem><para>ld - the GNU linker</para></listitem>
-          <listitem><para>m4 or gm4- the GNU m4 macro processor</para></listitem>
-          <listitem><para>as - the GNU assembler (version 2.10.1 or later)</para></listitem>
-          <listitem><para>make - either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
-        </itemizedlist>
-        <para> In general, the more recent the versions of those
-        tools, the better; some versions of gcc 3.x on Linux have
-        difficulty compiling some of the kernel source code correctly
-        (so gcc 4.0 should be used, if possible.)  On OSX, the
-        versions of the tools distributed with XCode should work fine;
-        on Linux, the versions of the tools installed with the OS (or
-        available through its package management system) should work
-        fine if they're "recent enough".  On FreeBSD, the installed
-        version of the <literal>m4</literal> program doesn't support
-        some features that the kernel build process depends on; the
-        GNU version of the m4 macroprocessor (called
-        <literal>gm4</literal> on FreeBSD) should be installed
-
-        </para>
-      </sect2>
-      <sect2 id="kernel-build-command">
-        <title>Using "make" to build the lisp kernel</title>
-        <para>With those tools in place, do:
+    </para>
+
+
+    <sect2 id="Kernel-build-prerequisites">
+      <title>Kernel build prerequisites</title>
+          <para>The &CCL; kernel can be bult with the following widely
+            available tools:</para>
+      <itemizedlist>
+        <listitem><para>cc or gcc- the GNU C compiler</para></listitem>
+        <listitem><para>ld - the GNU linker</para></listitem>
+        <listitem><para>m4 or gm4- the GNU m4 macro processor</para></listitem>
+        <listitem><para>as - the GNU assembler (version 2.10.1 or later)</para></listitem>
+            <listitem><para>make - either GNU make or, on FreeBSD, the default BSD make program</para></listitem>
+          </itemizedlist>
+          <para> In general, the more recent the versions of those
+            tools, the better; some versions of gcc 3.x on Linux have
+            difficulty compiling some of the kernel source code correctly
+            (so gcc 4.0 should be used, if possible.)  On OSX, the
+            versions of the tools distributed with XCode should work fine;
+            on Linux, the versions of the tools installed with the OS (or
+            available through its package management system) should work
+            fine if they're "recent enough".  On FreeBSD, the installed
+            version of the <literal>m4</literal> program doesn't support
+            some features that the kernel build process depends on; the
+            GNU version of the m4 macroprocessor (called
+            <literal>gm4</literal> on FreeBSD) should be installed.
+
+          </para>
+    </sect2>
+    <sect2 id="kernel-build-command">
+          <title>Using "make" to build the lisp kernel</title>
+      <para>With those tools in place, do:
         <programlisting>
 shell> cd ccl/lisp-kernel/<replaceable>PLATFORM</replaceable>
 shell> make
-        </programlisting>
-        </para>
-        <para>That'll assemble several assembly language source files,
+            </programlisting>
+          </para>
+      <para>That'll assemble several assembly language source files,
         compile several C source files, and link
         ../../<replaceable>the kernel</replaceable>.
-        </para>
-      </sect2>
-    </sect1>
-    <sect1 id="Building-the-heap-image">
-      <title>Building the heap image</title>
-      <para>The initial heap image is loaded by the Lisp kernel, and
-      provides most all of the language implementation The heap image
+          </para>
+    </sect2>
+  </sect1>
+  <sect1 id="Building-the-heap-image">
+    <title>Building the heap image</title>
+    <para>The initial heap image is loaded by the Lisp kernel, and
+      provides most of the language implementation The heap image
       captures the entire state of a running Lisp (except for external
       resources, such as open files and TCP sockets).  After it is
@@ -371 +373 @@
       exactly the same as those of the old Lisp process when the image
       was created.</para>
-      <para>The heap image is how we get around the fact that we can't
+    <para>The heap image is how we get around the fact that we can't
       run Lisp code until we have a working Lisp implementation, and
       we can't make our Lisp implementation work until we can run Lisp
@@ -377 +379 @@
       implementation, all we need to do is load it into memory and
       start using it.</para>
-      <para>If you're building a new version of &CCL;, you need to
+    <para>If you're building a new version of &CCL;, you need to
       build a new heap image.</para>
-      <para>(You might also wish to build a heap image if you have a
-      large program which it is very complicated or time-consuming to
+    <para>(You might also wish to build a heap image if you have a
+      large program that is very complicated or time-consuming to
       load, so that you will be able to load it once, save an image,
       and thenceforth never have to load it again. At any time, a heap
@@ -387 +389 @@
       <literal>ccl:save-application</literal>.)</para>
 
-      <sect2 id="Development-cycle">
-        <title>Development cycle</title>
-        <para>Creating a new &CCL; full heap image consists of the
+    <sect2 id="Development-cycle">
+          <title>Development cycle</title>
+      <para>Creating a new &CCL; full heap image consists of the
         following steps:</para>
-        <orderedlist>
-          <listitem><para>Using your existing &CCL;, create a
-          bootstrapping image</para></listitem>
-          <listitem><para>Using your existing &CCL;, recompile your
-          updated &CCL; sources</para></listitem>
-          <listitem><para>Invoke &CCL; with the bootstrapping image
-          you just created (rather than with the existing full heap
-          image).</para></listitem>
-        </orderedlist>
-        <para>When you invoke &CCL; with the bootstrapping image, it
-        will start up, load al of the &CCL; fasl files, and save out
-        a new full heap image.  Voila.  You've created a new heap
-        image.</para>
-        <para>A few points worth noting:</para>
-        <itemizedlist>
-          <listitem>
-            <para>There's a circular dependency between the full heap
-            image and thebootstrapping image, in that each is used to
-            build the other.</para>
-          </listitem>
-          <listitem>
-            <para>There are some minor implementation
-            differences, but the environment in effect after the
-            bootstrapping image has loaded its fasl files is essentially
-            equivalent to the environment provided by the full heap
-            image; the latter loads a lot faster and is easier to
-            distribute, of course.</para>
-          </listitem>
-          <listitem>
-            <para>If the full heap image doesn't work (because
-            of an OScompatibilty problem or other bug), it's very likely
-            that thebootstrapping image will suffer the same
-            problems.</para>
-          </listitem>
-        </itemizedlist>
-        <para>Given a bootstrapping image and a set of up-to-date fasl
+      <orderedlist>
+        <listitem><para>Using your existing &CCL;, create a
+            bootstrapping image</para></listitem>
+        <listitem><para>Using your existing &CCL;, recompile your
+            updated &CCL; sources</para></listitem>
+        <listitem><para>Invoke &CCL; with the bootstrapping image
+            you just created (rather than with the existing full heap
+            image).</para></listitem>
+          </orderedlist>
+          <para>When you invoke &CCL; with the bootstrapping image, it
+            starts up, loads all of the &CCL; fasl files, and saves out a
+            new full heap image.  Voila.  You've created a new heap
+            image.</para>
+      <para>A few points worth noting:</para>
+          <itemizedlist>
+        <listitem>
+              <para>There's a circular dependency between the full heap
+                image and the bootstrapping image, in that each is used to
+                build the other.</para>
+            </listitem>
+        <listitem>
+              <para>There are some minor implementation
+                differences, but the environment in effect after the
+                bootstrapping image has loaded its fasl files is essentially
+                equivalent to the environment provided by the full heap
+                image; the latter loads a lot faster and is easier to
+                distribute, of course.</para>
+            </listitem>
+        <listitem>
+              <para>If the full heap image doesn't work (because
+                of an OS compatibilty problem or other bug), it's very likely
+                that the bootstrapping image will suffer the same
+                problems.</para>
+            </listitem>
+          </itemizedlist>
+      <para>Given a bootstrapping image and a set of up-to-date fasl
         files, the development cycle usually involves editing lisp
         sources (or updating those sources via cvs update),
         recompiling modified files, and using the bootstrapping image
         to produce a new heap image.</para>
-      </sect2>
-
-      <sect2 id="Generating-a-bootstrapping-image">
-        <title>Generating a bootstrapping image</title>
-        <para>The bootstrapping image isn't provided in &CCL;
+    </sect2>
+
+    <sect2 id="Generating-a-bootstrapping-image">
+      <title>Generating a bootstrapping image</title>
+      <para>The bootstrapping image isn't provided in &CCL;
         distributions. It can be built from the source code provided
         in distributions (using a lisp image and kernel provided in
@@ -441 +443 @@
         below.</para>
 
-        <para>The bootstrapping image is built by invoking a special
+      <para>The bootstrapping image is built by invoking a special
         utility inside a running &CCL; heap image to load files
         contained in the <literal>ccl/level-0</literal> directory. The
@@ -449 +451 @@
         "cross-dumping".</para>
 
-        <para>Given a source distribution, a lisp kernel, and aheap
-        image, one can produce a bootstapping image by first invoking
+      <para>Given a source distribution, a lisp kernel, and a heap
+        image, one can produce a bootstrapping image by first invoking
         &CCL; from the shell:</para>
-        <programlisting>
+      <programlisting>
 shell&gt; openmcl
 Welcome to &CCL; .... !
 ?
-        </programlisting>
-        <para>then calling <literal>ccl:xload-level-0</literal> at the
-        lisp prompt</para>
-        <programlisting>
+          </programlisting>
+          <para>then calling <literal>ccl:xload-level-0</literal> at the
+            lisp prompt</para>
+          <programlisting>
 ? (ccl:xload-level-0)
-        </programlisting>
-        <para>This will compile the lisp sources in the ccl/level-0
+          </programlisting>
+      <para>This function compiles the lisp sources in the ccl/level-0
         directory if they're newer than the corresponding fasl files
-        and will then load the resulting fasl files into a simulated
-        lisp heap contained inside data structures inside the running
+        and then loads the resulting fasl files into a simulated lisp
+        heap contained in data structures inside the running
         lisp. That simulated heap image is then written to
         disk.</para>
-        <para><literal>xload-level-0</literal> should be called
+      <para><literal>xload-level-0</literal> should be called
         whenever your existing boot image is out-of-date with respect
         to the source files in <literal>ccl:level-0;</literal>
         :</para>
-        <programlisting>
+      <programlisting>
 ? (ccl:xload-level-0 :force)
-</programlisting>
-        <para>will force recompilation of the level-0 sources.</para>
-      </sect2>
-
-      <sect2 id="Generating-fasl-files">
-        <title>Generating fasl files</title>
-        <para> Calling:</para>
-        <programlisting>
+      </programlisting>
+      <para>forces recompilation of the level-0 sources.</para>
+    </sect2>
+
+    <sect2 id="Generating-fasl-files">
+      <title>Generating fasl files</title>
+          <para> Calling:</para>
+      <programlisting>
 ? (ccl:compile-ccl)
-        </programlisting>
-        <para>at the lisp prompt will compile any fasl files that are
-        out-of-date with respect to the corresponding lisp sources;
-        <literal>(ccl:compile-ccl t)</literal> will force
-        recompilation. <literal>ccl:compile-ccl</literal> will reload
-        newly-compiled versions of some files;
-        <literal>ccl:xcompile-ccl</literal> is analogous, but skips
-        this reloading step.</para>
-        <para>Unless there are bootstrapping considerations involved,
-        it usually doesn't matter whether these files reloaded after
+          </programlisting>
+          <para>at the lisp prompt compiles any fasl files that are
+            out-of-date with respect to the corresponding lisp sources;
+            <literal>(ccl:compile-ccl t)</literal> forces
+            recompilation. <literal>ccl:compile-ccl</literal> reloads
+            newly-compiled versions of some files;
+            <literal>ccl:xcompile-ccl</literal> is analogous, but skips
+            this reloading step.</para>
+      <para>Unless there are bootstrapping considerations involved, it
+        usually doesn't matter whether these files are reloaded after
         they're recompiled.</para>
-        <para>Calling <literal>compile-ccl</literal> or
+      <para>Calling <literal>compile-ccl</literal> or
         <literal>xcompile-ccl</literal> in an environment where fasl
         files don't yet exist may produce warnings to that effect
@@ -504 +506 @@
         warnings about undefined functions, etc. They should be
         cleaned up at some point.</para>
-      </sect2>
-
-      <sect2 id="Building-a-full-image-from-a-bootstrapping-image">
-        <title>Building a full image from a bootstrapping image</title>
-        <para>To build a full image from a bootstrapping image, just
-        invoke the kernel with the bootstrapping image is an
-        argument</para>
-        <programlisting>
+    </sect2>
+
+    <sect2 id="Building-a-full-image-from-a-bootstrapping-image">
+          <title>Building a full image from a bootstrapping image</title>
+          <para>To build a full image from a bootstrapping image, just
+            invoke the kernel with the bootstrapping image as an
+            argument</para>
+      <programlisting>
 $ cd ccl                        # wherever your ccl directory is
 $ ./KERNEL BOOT_IMAGE
-        </programlisting>
-        <para>Where <replaceable>KERNEL</replaceable> and
+          </programlisting>
+      <para>Where <replaceable>KERNEL</replaceable> and
         <replaceable>BOOT_IMAGE</replaceable> are the names of
         the kernel and boot image appropriate to the platform you are
-        running on.  See FIXTHIS</para>
-        <para>That should load a few dozen fasl files (printing a
+        running on.  See <xref linkend="Platform-specific-filename-conventions"/></para>
+      <para>That should load a few dozen fasl files (printing a
         message as each file is loaded.) If all of these files
         successfully load, the lisp will print a prompt. You should be
@@ -526 +528 @@
         you're confident that things loaded OK, you can save that
         image.</para>
-        <programlisting>
+      <programlisting>
 ? (ccl:save-application "<replaceable>image_name</replaceable>") ; Overwiting the existing heap image
-        </programlisting>
-        <para>Where <replaceable>image_name</replaceable> is the name
-        of the full heap image for your platform. See FIXTHIS.</para>
-        <para>If things go wrong in the early stages of the loading
+          </programlisting>
+          <para>Where <replaceable>image_name</replaceable> is the name of
+        the full heap image for your platform. See
+        <xref linkend="Platform-specific-filename-conventions"/>.</para>
+      <para>If things go wrong in the early stages of the loading
         sequence, errors are often difficult to debug; until a fair
         amount of code (CLOS, the CL condition system, streams, the
@@ -539 +542 @@
         cause the lisp kernel debugger (see ) to be invoked; it's
         primitive, but can sometimes help one to get oriented.</para>
-      </sect2>
-    </sect1>
-  </chapter>
+    </sect2>
+  </sect1>
+</chapter>

release/1.2/source/doc/src/ide.xml

@@ -43 +43 @@
       <listitem>
         <para>Run ccl from the shell. The easiest way to do this is
-          generally to execute the openmcl or openmcl64 command.</para>
+          generally to execute the ccl or ccl64 command.</para>
       </listitem>
       <listitem>
@@ -55 +55 @@
 
     <programlisting>
-      oshirion:ccl mikel$ openmcl64
-      Welcome to Clozure Common Lisp Version 1.2-r8516MS  (DarwinX8664)!
-      ? (require :cocoa-application)
-      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
-      ;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
-
-      [...many lines of "Compiling" and "Loading" omitted...]
-
-      Saving application to /usr/local/ccl/Clozure CL.app/
-
-      oshirion:ccl mikel$ 
+oshirion:ccl mikel$ ccl64
+Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk  (DarwinX8664)!
+? (require :cocoa-application)
+;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"...
+;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"...
+
+[...many lines of "Compiling" and "Loading" omitted...]
+
+Saving application to /usr/local/ccl/Clozure CL.app/
+
+oshirion:ccl mikel$ 
 
     </programlisting>

release/1.2/source/doc/src/implementation.xml

@@ -24 +24 @@
     <sect1 id="Threads-and-exceptions">
       <title>Threads and exceptions</title>
+
       <para>&CCL;'s threads are "native" (meaning that they're
-      scheduled and controlled by the operating system.)  Most of the
-      implications of this are discussed elsewhere; this section tries
-      to describe how threads look from the lisp kernel's perspective
-      (and especially from the GC's point of view.)</para>
+        scheduled and controlled by the operating system.)  Most of the
+        implications of this are discussed elsewhere; this section tries
+        to describe how threads look from the lisp kernel's perspective
+        (and especially from the GC's point of view.)</para>
       <para>&CCL;'s runtime system tries to use machine-level
-      exception mechanisms (conditional traps when available, illegal
-      instructions, memory access protection in some cases) to detect
-      and handle ...  exceptional situations.  These situations
-      include some TYPE-ERRORs and PROGRAM-ERRORS (notably
-      wrong-number-of-args errors), and also include cases like "not
-      being able to allocate memory without GCing or obtaining more
-      memory from the OS."  The general idea is that it's usually
-      faster to pay (very occasional) exception-processing overhead
-      and figure out what's going on in an exception handler than it
-      is to maintain enough state and context to handle an exceptional
-      case via a lighter-weight mechanism when that exceptional case
-      (by definition) rarely occurs.</para>
+        exception mechanisms (conditional traps when available,
+        illegal instructions, memory access protection in some cases)
+        to detect and handle exceptional situations.  These situations
+        include some TYPE-ERRORs and PROGRAM-ERRORS (notably
+        wrong-number-of-args errors), and also include cases like "not
+        being able to allocate memory without GCing or obtaining more
+        memory from the OS."  The general idea is that it's usually
+        faster to pay (very occasional) exception-processing overhead
+        and figure out what's going on in an exception handler than it
+        is to maintain enough state and context to handle an
+        exceptional case via a lighter-weight mechanism when that
+        exceptional case (by definition) rarely occurs.</para>
       <para>Some emulated execution environments (the Rosetta PPC
-      emulator on x86 versions of Mac OS X) don't provide accurate
-      exception information to exception handling functions. &CCL;
-      can't run in such environments.</para>
+        emulator on x86 versions of Mac OS X) don't provide accurate
+        exception information to exception handling functions. &CCL;
+        can't run in such environments.</para>
 
       <sect2 id="The-Thread-Context-Record">
-        <title>The Thread Context Record</title>
-
-        <para>When a lisp thread is first created (or when a thread
-        created by foreign code first calls back to lisp), a data
-        structure called a Thread Context Record (or TCR) is allocated
-        and initialized.  On modern versions of Linux and FreeBSD, the
-        allocation actually happens via a set of thread-local-storage
-        ABI extensions, so a thread's TCR is created when the thread
-        is created and dies when the thread dies.  (The World's Most
-        Advanced Operating System - as Apple's marketing literature
-        refers to Darwin - is not very advanced in this regard, and I
-        know of no reason to assume that advances will be made in this
-        area anytime soon.)</para>
+            <title>The Thread Context Record</title>
+
+            <para>When a lisp thread is first created (or when a thread
+          created by foreign code first calls back to lisp), a data
+          structure called a Thread Context Record (or TCR) is
+          allocated and initialized.  On modern versions of Linux and
+          FreeBSD, the allocation actually happens via a set of
+          thread-local-storage ABI extensions, so a thread's TCR is
+          created when the thread is created and dies when the thread
+          dies.  (The World's Most Advanced Operating System&mdash;as
+          Apple's marketing literature refers to Darwin&mdash;is not
+          very advanced in this regard, and I know of no reason to
+          assume that advances will be made in this area anytime
+          soon.)</para>
         <para>A TCR contains a few dozen fields (and is therefore a
-        few hundred bytes in size.)  The fields are mostly
-        thread-specific information about the thread's stacks'
-        locations and sizes, information about the underlying (POSIX)
-        thread, and information about the thread's dynamic binding
-        history and pending CATCH/UNWIND-PROTECTs.  Some of this
-        information could be kept in individual machine registers
-        while the thread is running (and the PPC - which has more
-        registers available - keeps a few things in registers that the
-        X86-64 has to access via the TCR), but it's important to
-        remember that the information is thread-specific and can't
-        (for instance) be kept in a fixed global memory
-        location.</para>
+          few hundred bytes in size.)  The fields are mostly
+          thread-specific information about the thread's stacks'
+          locations and sizes, information about the underlying (POSIX)
+          thread, and information about the thread's dynamic binding
+          history and pending CATCH/UNWIND-PROTECTs.  Some of this
+          information could be kept in individual machine registers
+          while the thread is running (and the PPC - which has more
+          registers available - keeps a few things in registers that the
+          X86-64 has to access via the TCR), but it's important to
+          remember that the information is thread-specific and can't
+          (for instance) be kept in a fixed global memory
+          location.</para>
         <para>When lisp code is running, the current thread's TCR is
-        kept in a register.  On PPC platforms, a general purpose
-        register is used; on x86-64, an (otherwise nearly useless)
-        segment register works well (prevents the expenditure of a
-        more generally useful general- purpose register for this
-        purpose.)</para>
+          kept in a register.  On PPC platforms, a general purpose
+          register is used; on x86-64, an (otherwise nearly useless)
+          segment register works well (prevents the expenditure of a
+          more generally useful general- purpose register for this
+          purpose.)</para>
         <para>The address of a TCR is aligned in memory in such a way
-        that a FIXNUM can be used to represent it.  The lisp function
-        CCL::%CURRENT-TCR returns the calling thread's TCR as a
-        fixnum; actual value of the TCR's address is 4 or 8 times the
-        value of this fixnum.</para>
+          that a FIXNUM can be used to represent it.  The lisp function
+          CCL::%CURRENT-TCR returns the calling thread's TCR as a
+          fixnum; actual value of the TCR's address is 4 or 8 times the
+          value of this fixnum.</para>
         <para>When the lisp kernel initializes a new TCR, it's added
-        to a global list maintained by the kernel; when a thread
-        exits, its TCR is removed from this list.</para>
+          to a global list maintained by the kernel; when a thread
+          exits, its TCR is removed from this list.</para>
         <para>When a thread calls foreign code, lisp stack pointers
-        are saved in its TCR, lisp registers (at least those whose
-        value should be preserved across the call) are saved on the
-        thread's value stack, and (on x86-64) RSP is switched to the
-        control stack.  A field in the TCR (tcr.valence) is then set
-        to indicate that the thread is running foreign code, foreign
-        argument registers are loaded from a frame on the foreign
-        stack, and the foreign function is called. (That's a little
-        oversimplified and possibly inaccurate, but the important
-        things to note are that the thread "stops following lisp stack
-        and register usage conventions" and that it advertises the
-        fact that it's done so.  Similar transitions in a thread's
-        state ("valence") occur when it enters of exits an exception
-        handler (which is sort of an OS/hardware-mandated foreign
-        function call where the OS thoughtfully saves the thread's
-        register state for it beforehand.)</para>
+          are saved in its TCR, lisp registers (at least those whose
+          value should be preserved across the call) are saved on the
+          thread's value stack, and (on x86-64) RSP is switched to the
+          control stack.  A field in the TCR (tcr.valence) is then set
+          to indicate that the thread is running foreign code, foreign
+          argument registers are loaded from a frame on the foreign
+          stack, and the foreign function is called. (That's a little
+          oversimplified and possibly inaccurate, but the important
+          things to note are that the thread "stops following lisp
+          stack and register usage conventions" and that it advertises
+          the fact that it's done so.  Similar transitions in a
+          thread's state ("valence") occur when it enters or exits an
+          exception handler (which is sort of an OS/hardware-mandated
+          foreign function call where the OS thoughtfully saves the
+          thread's register state for it beforehand.)</para>
       </sect2>
 
       <sect2 id="Exception-contexts-comma---and-exception-handling-in-general">
-        <title>Exception contexts, and exception-handling in general</title>
+            <title>Exception contexts, and exception-handling in general</title>
         <para>Unix-like OSes tend to refer to exceptions as "signals";
-        the same general mechanism ("signal handling") is used to
-        process both asynchronous OS-level events (such as the result
-        of the keyboard driver noticing that ^C or ^Z has been
-        pressed) and synchronous hardware-level events (like trying to
-        execute an illegal instruction or access protected memory.)
-        It makes some sense to defer ("block") handling of
-        asynchronous signals so that some critical code sequences
-        complete without interruption; since it's generally not
-        possible for a thread to proceed after a synchronous exception
-        unless and until its state is modified by an exception
-        handler, it makes no sense to talk about blocking synchronous
-        signals (though some OSes will let you do so and doing so can
-        have mysterious effects.)</para>
+          the same general mechanism ("signal handling") is used to
+          process both asynchronous OS-level events (such as the result
+          of the keyboard driver noticing that ^C or ^Z has been
+          pressed) and synchronous hardware-level events (like trying to
+          execute an illegal instruction or access protected memory.)
+          It makes some sense to defer ("block") handling of
+          asynchronous signals so that some critical code sequences
+          complete without interruption; since it's generally not
+          possible for a thread to proceed after a synchronous exception
+          unless and until its state is modified by an exception
+          handler, it makes no sense to talk about blocking synchronous
+          signals (though some OSes will let you do so and doing so can
+          have mysterious effects.)</para>
         <para>On OSX/Darwin, the POSIX signal handling facilities
-        coexist with lower-level Mach-based exception handling
-        facilities.  Unfortunately, the way that this is implemented
-        interacts poorly with debugging tools: GDB will generally stop
-        whenever the target program encounters a Mach-level exception
-        and offers no way to proceed from that point (and let the
-        program's POSIX signal handler try to handle the exception);
-        Apple's CrashReporter program has had a similar issue and,
-        depending on how it's configured, may bombard the user with
-        alert dialogs which falsely claim that an application has
-        crashed (when in fact the application in question has
-        routinely handled a routine exception.)  On Darwin/OSX,
-        &CCL; uses Mach thread-level exception handling facilities
-        which run before GDB or CrashReporter get a chance to confuse
-        themselves; &CCL;'s Mach exception handling tries to force
-        the thread which received a synchronous exception to invoke a
-        signal handling function ("as if" signal handling worked more
-        usefully under Darwin.)  Mach exception handlers run in a
-        dedicated thread (which basically does nothing but wait for
-        exception messages from the lisp kernel, obtain and modify
-        information about the state of threads in which exceptions
-        have occurred, and reply to the exception messages with an
-        indication that the exception has been handled.  The reply
-        from a thread-level exception handler keeps the exception from
-        being reported to GDB or CrashReporter and avoids the problems
-        related to those programs.  Since &CCL;'s Mach exception
-        handler doesn't claim to handle debugging-related exceptions
-        (from breakpoints or single-step operations), it's possible to
-        use GDB to debug &CCL;.</para>
+          coexist with lower-level Mach-based exception handling
+          facilities.  Unfortunately, the way that this is implemented
+          interacts poorly with debugging tools: GDB will generally stop
+          whenever the target program encounters a Mach-level exception
+          and offers no way to proceed from that point (and let the
+          program's POSIX signal handler try to handle the exception);
+          Apple's CrashReporter program has had a similar issue and,
+          depending on how it's configured, may bombard the user with
+          alert dialogs which falsely claim that an application has
+          crashed (when in fact the application in question has
+          routinely handled a routine exception.)  On Darwin/OSX,
+          &CCL; uses Mach thread-level exception handling facilities
+          which run before GDB or CrashReporter get a chance to confuse
+          themselves; &CCL;'s Mach exception handling tries to force
+          the thread which received a synchronous exception to invoke a
+          signal handling function ("as if" signal handling worked more
+          usefully under Darwin.)  Mach exception handlers run in a
+          dedicated thread (which basically does nothing but wait for
+          exception messages from the lisp kernel, obtain and modify
+          information about the state of threads in which exceptions
+          have occurred, and reply to the exception messages with an
+          indication that the exception has been handled.  The reply
+          from a thread-level exception handler keeps the exception from
+          being reported to GDB or CrashReporter and avoids the problems
+          related to those programs.  Since &CCL;'s Mach exception
+          handler doesn't claim to handle debugging-related exceptions
+          (from breakpoints or single-step operations), it's possible to
+          use GDB to debug &CCL;.</para>
         <para>On platforms where signal handling and debugging don't
-        get in each other's way, a signal handler is entered with all
-        signals blocked.  (This behavior is specified in the call to
-        the sigaction() function which established the signal
-        handler.)  The signal handler receives three arguments from
-        the OS kernel; the first is an integer which identifies the
-        signal, the second is a pointer to an object of type
-        "siginfo_t", which may or may not contain a few fields that
-        would help to identify the cause of the exception, and the
-        third argument is a pointer to a data structure (called a
-        "ucontext" or something similar) which contains
-        machine-dependent information about the state of the tread at
-        the time that the exception/signal occurred.  While
-        asynchronous signals are blocked, the signal handler stores
-        the pointer to its third argument (the "signal context") in a
-        field in the current thread's TCR, sets some bits in another
-        TCR field to indicate that the thread is now waiting to handle
-        an exception, unblocks asynchronous signals, and waits for a
-        global exception lock which serializes exception
-        processing.</para>
+          get in each other's way, a signal handler is entered with
+          all signals blocked.  (This behavior is specified in the
+          call to the sigaction() function which established the
+          signal handler.)  The signal handler receives three
+          arguments from the OS kernel; the first is an integer that
+          identifies the signal, the second is a pointer to an object
+          of type "siginfo_t", which may or may not contain a few
+          fields that would help to identify the cause of the
+          exception, and the third argument is a pointer to a data
+          structure (called a "ucontext" or something similar), which
+          contains machine-dependent information about the state of
+          the thread at the time that the exception/signal occurred.
+          While asynchronous signals are blocked, the signal handler
+          stores the pointer to its third argument (the "signal
+          context") in a field in the current thread's TCR, sets some
+          bits in another TCR field to indicate that the thread is now
+          waiting to handle an exception, unblocks asynchronous
+          signals, and waits for a global exception lock that
+          serializes exception processing.</para>
         <para>On Darwin, the Mach exception thread creates a signal
-        context (and maybe a siginfo_t structure), stores the signal
-        context in the thread's TCR, sets the TCR field which describes
-        the thread's state, and arranges that the thread resume
-        execution at its signal handling function (with a signal
-        handler, possibly NULL siginfo_t, and signal context as
-        arguments.  When the thread resumes, it waits for the global
-        exception lock.</para>
+          context (and maybe a siginfo_t structure), stores the signal
+          context in the thread's TCR, sets the TCR field which describes
+          the thread's state, and arranges that the thread resume
+          execution at its signal handling function (with a signal
+          handler, possibly NULL siginfo_t, and signal context as
+          arguments.  When the thread resumes, it waits for the global
+          exception lock.</para>
         <para>On x86-64 platforms where signal handing can be used to
-        handle synchronous exceptions, there's an additional
-        complication: the OS kernel ordinarily allocates the signal
-        context and siginfo structures on the stack of the thread
-        which received the signal; in practice, that means "wherever
-        RSP is pointing."  &CCL;'s <xref
-        linkend="Register-and-stack-usage-conventions"/> require that
-        the thread's value stack - where RSP is usually pointing while
-        lisp code is running - contain only "nodes" (properly tagged
-        lisp objects), and scribbling a signal context all over the
-        value stack would violate this requirement.  To maintain
-        consistency, the sigaltstack() mechanism is used to cause the
-        signal to be delivered on (and the signal context and siginfo
-        to be allocated on) a special stack area (the last few pages
-        of the thread's control stack, in practice.  When the signal
-        handler runs, it (carefully) copies the signal context and
-        siginfo to the thread's control stack and makes RSP point into
-        that stack before invoking the "real" signal handler.  (The
-        effect of this hack is that the "real" signal handler always
-        runs on the thread's control stack.)</para>
+          handle synchronous exceptions, there's an additional
+          complication: the OS kernel ordinarily allocates the signal
+          context and siginfo structures on the stack of the thread
+          that received the signal; in practice, that means "wherever
+          RSP is pointing."  &CCL;'s
+          <xref linkend="Register-and-stack-usage-conventions"/>
+          require that the thread's value stack&mdash;where RSP is
+          usually pointing while lisp code is running&mdash;contain
+          only "nodes" (properly tagged lisp objects), and scribbling
+          a signal context all over the value stack would violate this
+          requirement.  To maintain consistency, the sigaltstack()
+          mechanism is used to cause the signal to be delivered on
+          (and the signal context and siginfo to be allocated on) a
+          special stack area (the last few pages of the thread's
+          control stack, in practice).  When the signal handler runs,
+          it (carefully) copies the signal context and siginfo to the
+          thread's control stack and makes RSP point into that stack
+          before invoking the "real" signal handler. The effect of
+          this hack is that the "real" signal handler always runs on
+          the thread's control stack.</para>
         <para>Once the exception handler has obtained the global
-        exception lock, it uses the values of the signal number,
-        siginfo_t, and signal context arguments to determine the
-        (logical) cause of the exception.  Some exceptions may be
-        caused by factors that should generate lisp errors or other
-        serious conditions (stack overflow); if this is the case, the
-        kernel code may release the global exception lock and call out
-        to lisp code.  (The lisp code in question may need to repeat
-        some of the exception decoding process; in particular, it
-        needs to be able to interpret register values in the signal
-        context that it receives as an argument.)</para>
+          exception lock, it uses the values of the signal number,
+          siginfo_t, and signal context arguments to determine the
+          (logical) cause of the exception.  Some exceptions may be
+          caused by factors that should generate lisp errors or other
+          serious conditions (stack overflow); if this is the case, the
+          kernel code may release the global exception lock and call out
+          to lisp code.  (The lisp code in question may need to repeat
+          some of the exception decoding process; in particular, it
+          needs to be able to interpret register values in the signal
+          context that it receives as an argument.)</para>
         <para>In some cases, the lisp kernel exception handler may not
-        be able to recover from the exception (this is currently true
-        of some types of memory-access fault and is also true of traps
-        or illegal instructions that occur during foreign code
-        execution.  In such cases, the kernel exception handler
-        reports the exception as "unhandled", and the kernel debugger
-        is invoked.</para>
+          be able to recover from the exception (this is currently true
+          of some types of memory-access fault and is also true of traps
+          or illegal instructions that occur during foreign code
+          execution.  In such cases, the kernel exception handler
+          reports the exception as "unhandled", and the kernel debugger
+          is invoked.</para>
         <para>If the kernel exception handler identifies the
-        exception's cause as being a transient out-of-memory condition
-        (indicating that the current thread needs more memory to cons
-        in), it tries to make that memory available.  In some cases,
-        doing so involves invoking the GC.</para>
+          exception's cause as being a transient out-of-memory condition
+          (indicating that the current thread needs more memory to cons
+          in), it tries to make that memory available.  In some cases,
+          doing so involves invoking the GC.</para>
       </sect2>
 
       <sect2 id="Threads-comma---exceptions-comma---and-the-GC">
-        <title>Threads, exceptions, and the GC</title>
+            <title>Threads, exceptions, and the GC</title>
         <para>&CCL;'s GC is not concurrent: when the GC is invoked in
-        response to an exception in a particular thread, all other
-        lisp threads must stop until the GC's work is done.  The
-        thread that triggered the GC iterates over the global TCR
-        list, sending each other thread a distinguished "suspend"
-        signal, then iterates over the list again, waiting for a
-        per-thread semaphore that indicates that the thread has
-        received the "suspend" signal and responded appropriately.
-        Once all other threads have acknowledged the request to
-        suspend themselves, the GC thread can run the GC proper (after
-        doing any necessary <xref linkend="PC-lusering"/>.)  Once the
-        GC's completed its work, the thread that invoked the GC
-        iterates over the global TCR list, raising a per-thread
-        "resume" semaphore for each other thread.</para>
+          response to an exception in a particular thread, all other
+          lisp threads must stop until the GC's work is done.  The
+          thread that triggered the GC iterates over the global TCR
+          list, sending each other thread a distinguished "suspend"
+          signal, then iterates over the list again, waiting for a
+          per-thread semaphore that indicates that the thread has
+          received the "suspend" signal and responded appropriately.
+          Once all other threads have acknowledged the request to
+          suspend themselves, the GC thread can run the GC proper (after
+          doing any necessary <xref linkend="PC-lusering"/>.)  Once the
+          GC's completed its work, the thread that invoked the GC
+          iterates over the global TCR list, raising a per-thread
+          "resume" semaphore for each other thread.</para>
         <para>The signal handler for the asynchronous "suspend" signal
-        is entered with all asynchronous signals blocked.  It saves
-        its signal-context argument in a TCR slot, raises the tcr's
-        "suspend" semaphore, then waits on the TCR's "resume"
-        semaphore.</para>
+          is entered with all asynchronous signals blocked.  It saves
+          its signal-context argument in a TCR slot, raises the tcr's
+          "suspend" semaphore, then waits on the TCR's "resume"
+          semaphore.</para>
         <para>The GC thread has access to the signal contexts of all
-        TCRs (including its own) at the time when the thread received
-        an exception or acknowledged a request to suspend itself.
-        This information (and information about stack areas in the TCR
-        itself) allows the GC to identify the "stack locations and
-        register contents" that are elements of the GC's root
-        set.</para>
+          TCRs (including its own) at the time when the thread received
+          an exception or acknowledged a request to suspend itself.
+          This information (and information about stack areas in the TCR
+          itself) allows the GC to identify the "stack locations and
+          register contents" that are elements of the GC's root
+          set.</para>
       </sect2>
 
       <sect2 id="PC-lusering">
-        <title>PC-lusering</title>
+            <title>PC-lusering</title>
         <para>It's not quite accurate to say that &CCL;'s compiler
-        and runtime follow precise stack and register usage
-        conventions at all times; there are a few exceptions:</para>
-
-        <itemizedlist>
+          and runtime follow precise stack and register usage
+          conventions at all times; there are a few exceptions:</para>
+
+            <itemizedlist>
           <listitem>
-            <para>On both PPC and x86-64 platforms, consing isn't
-            fully atomic.It takes at least a few instructions to
-            allocate an object in memory(and slap a header on it if
-            necessary); if a thread is interrupted in the middle of
-            that instruction sequence, the new object may or may
-            not have been created or fully initialized at the point in
-            time that the interrupt occurred.  (There are actually a
-            few different states of partial initialization)</para>
-          </listitem>
-          <listitem>
-            <para>On the PPC, the common act of building a lisp
-            control stack frame involves allocating a four-word frame
-            and storing three register values into that frame.  (The
-            fourth word - the back pointer to the previous frame - is
-            automatically set when the frame is allocated.)  The
-            previous contents of those three words are unknown (there
-            might have been a foreign stack frame at the same address a
-            few instructions earlier),so interrupting a thread that's
-            in the process of initializing a PPC control stack frame
-            isn't GC-safe.</para>
-          </listitem>
+                <para>On both PPC and x86-64 platforms, consing isn't
+                  fully atomic.It takes at least a few instructions to
+                  allocate an object in memory(and slap a header on it if
+                  necessary); if a thread is interrupted in the middle of
+                  that instruction sequence, the new object may or may
+                  not have been created or fully initialized at the point in
+                  time that the interrupt occurred.  (There are actually a
+                  few different states of partial initialization)</para>
+              </listitem>
+              <listitem>
+                <para>On the PPC, the common act of building a lisp
+                  control stack frame involves allocating a four-word frame
+                  and storing three register values into that frame.  (The
+                  fourth word - the back pointer to the previous frame - is
+                  automatically set when the frame is allocated.)  The
+                  previous contents of those three words are unknown (there
+                  might have been a foreign stack frame at the same address a
+                  few instructions earlier),so interrupting a thread that's
+                  in the process of initializing a PPC control stack frame
+                  isn't GC-safe.</para>
+              </listitem>
           <listitem>
-            <para>There are similar problems with the initialization
-            of temp stackframes on the PPC.  (Allocation and
-            initialization doesn't happen atomically, and the newly
-            allocated stack memory may have undefined contents.)</para>
-          </listitem>
+                <para>There are similar problems with the initialization
+                  of temp stackframes on the PPC.  (Allocation and
+                  initialization doesn't happen atomically, and the newly
+                  allocated stack memory may have undefined contents.)</para>
+              </listitem>
           <listitem>
-            <para><xref linkend="The-ephemeral-GC"/>'s write barrier
-            has to be implemented atomically (i.e.,both an
-            intergenerational store and the update of a
-            corresponding reference bit has to happen without
-            interruption, or neither of these events can
-            happen.)</para>
-          </listitem>
+                <para><xref linkend="The-ephemeral-GC"/>'s write barrier
+                  has to be implemented atomically (i.e.,both an
+                  intergenerational store and the update of a
+                  corresponding reference bit has to happen without
+                  interruption, or neither of these events can
+                  happen.)</para>
+              </listitem>
           <listitem>
-            <para>There are a few more similar cases.</para>
-          </listitem>
+                <para>There are a few more similar cases.</para>
+              </listitem>
         </itemizedlist>
 
         <para>Fortunately, the number of these non-atomic instruction
-        sequences is small, and fortunately it's fairly easy for the
-        interrupting thread to recognize when the interrupted thread
-        is in the middle of such a sequence.  When this is detected,
-        the interrupting thread modifies the state of the interrupted
-        thread (modifying its PC and other registers) so that it is no
-        longer in the middle of such a sequence (it's either backed
-        out of it or the remaining instructions are emulated.)</para>
+          sequences is small, and fortunately it's fairly easy for the
+          interrupting thread to recognize when the interrupted thread
+          is in the middle of such a sequence.  When this is detected,
+          the interrupting thread modifies the state of the interrupted
+          thread (modifying its PC and other registers) so that it is no
+          longer in the middle of such a sequence (it's either backed
+          out of it or the remaining instructions are emulated.)</para>
         <para>This works because (a) many of the troublesome
-        instruction sequences are PPC-specific and it's relatively
-        easy to partially disassemble the instructions surrounding the
-        interrupted thread's PC on the PPC and (b) those instruction
-        sequences are heavily stylized and intended to be easily
-        recognized.</para>
+          instruction sequences are PPC-specific and it's relatively
+          easy to partially disassemble the instructions surrounding the
+          interrupted thread's PC on the PPC and (b) those instruction
+          sequences are heavily stylized and intended to be easily
+          recognized.</para>
       </sect2>
     </sect1>
@@ -321 +324 @@
     <sect1 id="Register-usage-and-tagging">
       <title>Register usage and tagging</title>
-
+      
       <sect2 id="Register-usage-and-tagging-overview">
-        <title>Overview</title>
-        <para>Regardless of other details of its implementation, a
-        garbage collector's job is to partition the set of all
-        heap-allocated lisp objects (CONSes, STRINGs, INSTANCEs, etc.)
-        into two subsets.  The first subset contains all objects that
-        are transitively referenced from a small set of "root" objects
-        (the contents of the stacks and registers of all active
-        threads at the time the GC occurs and the values of some
-        global variables.)  The second subset contains everything
-        else: those lisp objects that are not transitively reachable
-        from the roots are garbage, and the memory occupied by garbage
-        objects can be reclaimed (since the GC has just proven that
-        it's impossible to reference them.)</para>
+            <title>Overview</title>
+            <para>Regardless of other details of its implementation, a
+              garbage collector's job is to partition the set of all
+              heap-allocated lisp objects (CONSes, STRINGs, INSTANCEs, etc.)
+              into two subsets.  The first subset contains all objects that
+              are transitively referenced from a small set of "root" objects
+              (the contents of the stacks and registers of all active
+              threads at the time the GC occurs and the values of some
+              global variables.)  The second subset contains everything
+              else: those lisp objects that are not transitively reachable
+              from the roots are garbage, and the memory occupied by garbage
+              objects can be reclaimed (since the GC has just proven that
+              it's impossible to reference them.)</para>
         <para>The set of live, reachable lisp objects basically form
-        the nodes of a (usually large) graph, with edges from each
-        node A to any other objects (nodes) that object A
-        references.</para>
+          the nodes of a (usually large) graph, with edges from each
+          node A to any other objects (nodes) that object A
+          references.</para>
         <para>Some nodes in this graph can never have outgoing edges:
-        an array with a specialized numeric or character type usually
-        represents its elements in some (possibly more compact)
-        specialized way.  Some nodes may refer to lisp objects that
-        are never allocated in memory (FIXNUMs, CHARACTERs,
-        SINGLE-FLOATs on 64-bit platforms ..)  This latter class of
-        objects are sometimes called "immediates", but that's a little
-        confusing because the term "immediate" is sometimes used to
-        refer to things that can never be part of the big connectivity
-        graph (e.g., the "raw" bits that make up a floating-point
-        value, foreign address, or numeric value that needs to be used
-        - at least fleetingly - in compiled code.)</para>
+          an array with a specialized numeric or character type usually
+          represents its elements in some (possibly more compact)
+          specialized way.  Some nodes may refer to lisp objects that
+          are never allocated in memory (FIXNUMs, CHARACTERs,
+          SINGLE-FLOATs on 64-bit platforms ..)  This latter class of
+          objects are sometimes called "immediates", but that's a little
+          confusing because the term "immediate" is sometimes used to
+          refer to things that can never be part of the big connectivity
+          graph (e.g., the "raw" bits that make up a floating-point
+          value, foreign address, or numeric value that needs to be used
+          - at least fleetingly - in compiled code.)</para>
         <para>For the GC to be able to build the connectivity graph
-        reliably, it's necessary for it to be able to reliably tell
-        (a) whether or not a "potential root" - the contents of a
-        machine register or stack location - is in fact a node and (b)
-        for any node, whether it may have components that refer to
-        other nodes.</para>
+          reliably, it's necessary for it to be able to reliably tell
+          (a) whether or not a "potential root" - the contents of a
+          machine register or stack location - is in fact a node and (b)
+          for any node, whether it may have components that refer to
+          other nodes.</para>
         <para>There's no reliable way to answer the first question on
-        stock hardware.  (If everything was a node, as might be the
-        case on specially microcoded "lisp machine" hardware, it
-        wouldn't even need to be asked.)  Since there's no way to just
-        look at a machine word (the contents of a machine register or
-        stack location) and tell whether or not it's a node or just
-        some random non-node value, we have to either adopt and
-        enforce strict conventions on register and stack usage or
-        tolerate ambiguity.</para>
+          stock hardware.  (If everything was a node, as might be the
+          case on specially microcoded "lisp machine" hardware, it
+          wouldn't even need to be asked.)  Since there's no way to just
+          look at a machine word (the contents of a machine register or
+          stack location) and tell whether or not it's a node or just
+          some random non-node value, we have to either adopt and
+          enforce strict conventions on register and stack usage or
+          tolerate ambiguity.</para>
         <para>"Tolerating ambiguity" is an approach taken by some
-        ("conservative") GC schemes; by contrast, &CCL;'s GC is
-        "precise", which in this case means that it believes that the
-        contents of certain machine registers and stack locations are
-        always nodes and that other registers and stack locations are
-        never nodes and that these conventions are never violated by
-        the compiler or runtime system.  The fact that threads are
-        preemptively scheduled means that a GC could occur (because of
-        activity in some other thread) on any instruction boundary,
-        which in turn means that the compiler and runtime system must
-        follow precise <xref
-        linkend="Register-and-stack-usage-conventions"/> at all
-        times.</para>
+          ("conservative") GC schemes; by contrast, &CCL;'s GC is
+          "precise", which in this case means that it believes that the
+          contents of certain machine registers and stack locations are
+          always nodes and that other registers and stack locations are
+          never nodes and that these conventions are never violated by
+          the compiler or runtime system.  The fact that threads are
+          preemptively scheduled means that a GC could occur (because of
+          activity in some other thread) on any instruction boundary,
+          which in turn means that the compiler and runtime system must
+          follow precise <xref
+                            linkend="Register-and-stack-usage-conventions"/> at all
+          times.</para>
         <para>Once we've decided that a given machine word is a node,
-        a <xref linkend="Tagging-scheme"/> describes how the node's
-        value and type are encoded in that machine word.</para>
-        <para>Most of this - so far - has discussed things from the
-        GC's very low-level perspective.  From a much higher point of
-        view, lisp functions accept nodes as arguments, return nodes
-        as values, and (usually) perform some operations on those
-        arguments in order to produce those results.  (In many cases,
-        the operations in question involve raw non-node values.)
-        Higher-level parts of the lisp type system (functions like
-        TYPE-OF and CLASS-OF, etc.) depend on the <xref
-        linkend="Tagging-scheme"/>.</para>
+          a <xref linkend="Tagging-scheme"/> describes how the node's
+          value and type are encoded in that machine word.</para>
+        <para>Most of this discussion&mdash;so far&mdash;has treated
+          things from the GC's very low-level perspective. From a much
+          higher point of view, lisp functions accept nodes as
+          arguments, return nodes as values, and (usually) perform
+          some operations on those arguments in order to produce those
+          results.  (In many cases, the operations in question involve
+          raw non-node values.)  Higher-level parts of the lisp type
+          system (functions like TYPE-OF and CLASS-OF, etc.) depend on
+          the <xref linkend="Tagging-scheme"/>.</para>
       </sect2>
 
       <sect2 id="pc-locatives-on-the-PPC">
-        <title>pc-locatives on the PPC</title>
+            <title>pc-locatives on the PPC</title>
         <para>On the PPC, there's a third case (besides "node" and
-        "immediate" values).  As discussed below, a node that denotes
-        a memory-allocated lisp object is a biased (tagged) pointer
-        -to- that object; it's not generally possible to point -into-
-        some composite (multi-element) object (such a pointer would
-        not be a node, and the GC would have no way to update the
-        pointer if it were to move the underlying object.)</para>
+          "immediate" values).  As discussed below, a node that denotes
+          a memory-allocated lisp object is a biased (tagged) pointer
+          -to- that object; it's not generally possible to point -into-
+          some composite (multi-element) object (such a pointer would
+          not be a node, and the GC would have no way to update the
+          pointer if it were to move the underlying object.)</para>
         <para>Such a pointer ("into" the interior of a heap-allocated
-        object) is often called a <emphasis>locative</emphasis>; the
-        cases where locatives are allowed in &CCL; mostly involve
-        the behavior of function call and return instructions.  (To be
-        technically accurate, the other case also arises on x86-64, but
-        that case isn't as user-visible.)</para>
+          object) is often called a <emphasis>locative</emphasis>; the
+          cases where locatives are allowed in &CCL; mostly involve
+          the behavior of function call and return instructions.  (To be
+          technically accurate, the other case also arises on x86-64, but
+          that case isn't as user-visible.)</para>
         <para>On the PowerPC (both PPC32 and PPC64), all machine
-        instructions are 32 bits wide and all instruction words are
-        allocated on 32-bit boundaries.  In PPC &CCL;, a CODE-VECTOR
-        is a specialized type of vector-like object; its elements are
-        32-bit PPC machine instructions.  A CODE-VECTOR is an
-        attribute of FUNCTION object; a function call involves
-        accessing the function's code-vector and jumping to the
-        address of its first instruction.</para>
+          instructions are 32 bits wide and all instruction words are
+          allocated on 32-bit boundaries.  In PPC &CCL;, a CODE-VECTOR
+          is a specialized type of vector-like object; its elements
+          are 32-bit PPC machine instructions.  A CODE-VECTOR is an
+          attribute of a FUNCTION object; a function call involves
+          accessing the function's code-vector and jumping to the
+          address of its first instruction.</para>
         <para>As each instruction in the code vector sequentially
-        executes, the hardware program counter (PC) register advances
-        to the address of the next instruction (a locative into the
-        code vector); since PPC instructions are always 32 bits wide
-        and aligned on 32-bit boundaries, the low two bits of the PC
-        are always 0.  If the function executes a call (simple call
-        instructions have the mnemonic "bl" on the PPC, which stands
-        for "branch and link"), the address of the next instruction
-        (also a word-aligned locative into a code-vector) is copied
-        into the special- purpose PPC "link register" (lr); a function
-        returns to its caller via a "branch to link register" (blr)
-        instruction.  Some cases of function call and return might
-        also use the PPC's "count register" (ctr), and if either the
-        lr or ctr needs to be stored in memory it needs to first be
-        copied to a general-purpose register.</para>
+          executes, the hardware program counter (PC) register advances
+          to the address of the next instruction (a locative into the
+          code vector); since PPC instructions are always 32 bits wide
+          and aligned on 32-bit boundaries, the low two bits of the PC
+          are always 0.  If the function executes a call (simple call
+          instructions have the mnemonic "bl" on the PPC, which stands
+          for "branch and link"), the address of the next instruction
+          (also a word-aligned locative into a code-vector) is copied
+          into the special- purpose PPC "link register" (lr); a function
+          returns to its caller via a "branch to link register" (blr)
+          instruction.  Some cases of function call and return might
+          also use the PPC's "count register" (ctr), and if either the
+          lr or ctr needs to be stored in memory it needs to first be
+          copied to a general-purpose register.</para>
         <para>&CCL;'s GC understands that certain registers contain
-        these special "pc-locatives" (locatives that point into
-        CODE-VECTOR objects); it contains special support for finding
-        the containing CODE-VECTOR object and for adjusting all of
-        these "pc-locatives" if the containing object is moved in
-        memory.  The first part of that - finding the containing
-        object - is possible and practical on the PPC because of
-        architectural artifacts (fixed-width instructions and arcana
-        of instruction encoding.)  It's not possible on x86-64, but
-        fortunately not necessary either (though the second part -
-        adjusting the PC/RIP when the containing object moves) is both
-        necessary and simple.</para>
+          these special "pc-locatives" (locatives that point into
+          CODE-VECTOR objects); it contains special support for
+          finding the containing CODE-VECTOR object and for adjusting
+          all of these "pc-locatives" if the containing object is
+          moved in memory.  The first part of that
+          operation&mdash;finding the containing object&mdash;is
+          possible and practical on the PPC because of architectural
+          artifacts (fixed-width instructions and arcana of
+          instruction encoding.)  It's not possible on x86-64, but
+          fortunately not necessary either (though the second part -
+          adjusting the PC/RIP when the containing object moves) is
+          both necessary and simple.</para>
       </sect2>
 
       <sect2 id="Register-and-stack-usage-conventions">
         <title>Register and stack usage conventions</title>
-
+        
         <sect3 id="Stack-conventions">
-          <title>Stack conventions</title>
+              <title>Stack conventions</title>
           <para>On both PPC and X86 platforms, each lisp thread uses 3
-          stacks; the ways in which these stacks are used differs
-          between the PPC and X86.</para>
+            stacks; the ways in which these stacks are used differs
+            between the PPC and X86.</para>
           <para>Each thread has:</para>
-          <itemizedlist>
+              <itemizedlist>
             <listitem>
-              <para>A "control stack".  On both platforms, this is
-              "the stack" used by foreign code.  On the PPC, it
-              consists of a linked list of frames where the first word
-              in each frame points to the first word in the previous
-              frame (and the outermost frame points to 0.)  Some
-              frames on a PPC control stack are lisp frames; lisp
-              frames are always 4 words in size and contain (in
-              addition to the back pointer to the previous frame) the
-              calling function (a node), the return address (a
-              "locative" into the calling function's code-vector), and
-              the value to which the value-stack pointer (see below)
-              should be restored on function exit.  On the PPC, the GC
-              has to look at control-stack frames, identify which of
-              those frames are lisp frames, and treat the contents of
-              the saved function slot as a node (and handle the return
-              address locative specially.)  On x86-64, the control
-              stack is used for dynamic-extent allocation of immediate
-              objects.  Since the control stack never contains nodes
-              on x86-64, the GC ignores it on that platform.
-              Alignment of the control stack follows the ABI
-              conventions of the platform (at least at any point in
-              time where foreign code could run.)  On PPC, the r1
-              register always points to the top of the current
-              thread's control stack; on x86-64, the RSP register
-              points to the top of the current thread's control stack
-              when the thread is running foreign code and the address
-              of the top of the control stack is kept in the thread's
-              TCR (see <xref linkend="The-Thread-Context-Record"/>
-              when not running foreign code.  The control stack "grows
-              down."</para>
-            </listitem>
+                  <para>A "control stack".  On both platforms, this is
+                    "the stack" used by foreign code.  On the PPC, it
+                    consists of a linked list of frames where the first word
+                    in each frame points to the first word in the previous
+                    frame (and the outermost frame points to 0.)  Some
+                    frames on a PPC control stack are lisp frames; lisp
+                    frames are always 4 words in size and contain (in
+                    addition to the back pointer to the previous frame) the
+                    calling function (a node), the return address (a
+                    "locative" into the calling function's code-vector), and
+                    the value to which the value-stack pointer (see below)
+                    should be restored on function exit.  On the PPC, the GC
+                    has to look at control-stack frames, identify which of
+                    those frames are lisp frames, and treat the contents of
+                    the saved function slot as a node (and handle the return
+                    address locative specially.)  On x86-64, the control
+                    stack is used for dynamic-extent allocation of immediate
+                    objects.  Since the control stack never contains nodes
+                    on x86-64, the GC ignores it on that platform.
+                    Alignment of the control stack follows the ABI
+                    conventions of the platform (at least at any point in
+                    time where foreign code could run.)  On PPC, the r1
+                    register always points to the top of the current
+                    thread's control stack; on x86-64, the RSP register
+                    points to the top of the current thread's control stack
+                    when the thread is running foreign code and the address
+                    of the top of the control stack is kept in the thread's
+                    TCR (see <xref linkend="The-Thread-Context-Record"/>
+                    when not running foreign code.  The control stack "grows
+                    down."</para>
+                </listitem>
             <listitem>
-              <para>A "value stack".  On both platforms, all values on
-              the value stack are nodes (including "tagged return
-              addresses" on x86-64.)  The value stack is always
-              aligned to the native word size; objects are always
-              pushed on the value stack using atomic instructions
-              ("stwu"/"stdu" on PPC, "push" on x86-64), so the
-              contents of the value stack between its bottom and top
-              are always unambiguously nodes; the compiler usually
-              tries to pop or discard nodes from the value stack as
-              soon as possible after their last use (as soon as they
-              may have become garbage.)  On x86-64, the RSP register
-              addresses the top of the value stack when running lisp
-              code; that address is saved in the TCR when running
-              foreign code.  On the PPC, a dedicated register (VSP,
-              currently r15) is used to address the top of the value
-              stack when running lisp code, and the VSP value is saved
-              in the TCR when running foreign code.  The value stack
-              grows down.</para>
-            </listitem>
-            <listitem>
-              <para>A "temp stack".  The temp stack consists of a
-              linked list of frames, each of which points to the
-              previous temp stack frame.  The number of native machine
-              words in each temp stack frame is always even, so the
-              temp stack is aligned on a two-word (64- or 128-bit)
-              boundary.  The temp stack is used for dynamic-extent
-              objects on both platforms; on the PPC, it's used for
-              essentially all such objects (regardless of whether or
-              not the objects contain nodes); on the x86-64, immediate
-              dynamic-extent objects (strings, foreign pointers, etc.)
-              are allocated on the control stack and only
-              node-containing dynamic-extent objects are allocated on
-              the temp stack.  Data structures used to implement CATCH
-              and UNWIND-PROTECT are stored on the temp stack on both
-              ppc and x86-64.  Temp stack frames are always doublenode
-              aligned and objects within a temp stack frame are
-              aligned on doublenode boundaries.  The first word in
-              each frame contains a back pointer to the previous
-              frame; on the PPC, the second word is used to indicate
-              to the GC whether the remaining objects are nodes (if
-              the second word is 0) or immediate (otherwise.)  On
-              x86-64, where temp stack frames always contain nodes,
-              the second word is always 0.  The temp stack grows down.
-              It usually takes several instructions to allocate and
-              safely initialize a temp stack frame that's intended to
-              contain nodes, and the GC has to recognize the case
-              where a thread is in the process of allocating and
-              initializing a temp stack frame and take care not to
-              interpret any uninitialized words in the frame as nodes.
-              See (someplace).  The PPC keeps the current top of the
-              temp stack in a dedicated register (TSP, currently r12)
-              when running lisp code and saves this register's value
-              in the TCR when running foreign code.  The x86-64 keeps
-              the address of the top of each thread's temp stack in
-              the thread's TCR.</para>
-            </listitem>
+                  <para>A "value stack".  On both platforms, all values on
+                    the value stack are nodes (including "tagged return
+                    addresses" on x86-64.)  The value stack is always
+                    aligned to the native word size; objects are always
+                    pushed on the value stack using atomic instructions
+                    ("stwu"/"stdu" on PPC, "push" on x86-64), so the
+                    contents of the value stack between its bottom and top
+                    are always unambiguously nodes; the compiler usually
+                    tries to pop or discard nodes from the value stack as
+                    soon as possible after their last use (as soon as they
+                    may have become garbage.)  On x86-64, the RSP register
+                    addresses the top of the value stack when running lisp
+                    code; that address is saved in the TCR when running
+                    foreign code.  On the PPC, a dedicated register (VSP,
+                    currently r15) is used to address the top of the value
+                    stack when running lisp code, and the VSP value is saved
+                    in the TCR when running foreign code.  The value stack
+                    grows down.</para>
+                </listitem>
+                <listitem>
+                  <para>A "temp stack".  The temp stack consists of a
+                    linked list of frames, each of which points to the
+                    previous temp stack frame.  The number of native
+                    machine words in each temp stack frame is always even,
+                    so the temp stack is aligned on a two-word (64- or
+                    128-bit) boundary.  The temp stack is used for
+                    dynamic-extent objects on both platforms; on the PPC,
+                    it's used for essentially all such objects (regardless
+                    of whether or not the objects contain nodes); on the
+                    x86-64, immediate dynamic-extent objects (strings,
+                    foreign pointers, etc.)  are allocated on the control
+                    stack and only node-containing dynamic-extent objects
+                    are allocated on the temp stack.  Data structures used
+                    to implement CATCH and UNWIND-PROTECT are stored on
+                    the temp stack on both ppc and x86-64.  Temp stack
+                    frames are always doublenode aligned and objects
+                    within a temp stack frame are aligned on doublenode
+                    boundaries.  The first word in each frame contains a
+                    back pointer to the previous frame; on the PPC, the
+                    second word is used to indicate to the GC whether the
+                    remaining objects are nodes (if the second word is 0)
+                    or immediate (otherwise.)  On x86-64, where temp stack
+                    frames always contain nodes, the second word is always
+                    0.  The temp stack grows down.  It usually takes
+                    several instructions to allocate and safely initialize
+                    a temp stack frame that's intended to contain nodes,
+                    and the GC has to recognize the case where a thread is
+                    in the process of allocating and initializing a temp
+                    stack frame and take care not to interpret any
+                    uninitialized words in the frame as nodes. The PPC
+                    keeps the current top of the temp stack in a dedicated
+                    register (TSP, currently r12) when running lisp code
+                    and saves this register's value in the TCR when
+                    running foreign code.  The x86-64 keeps the address of
+                    the top of each thread's temp stack in the thread's
+                    TCR.</para>
+                </listitem>
           </itemizedlist>
         </sect3>
 
         <sect3 id="Register-conventions">
-          <title>Register conventions</title>
+              <title>Register conventions</title>
           <para>If there are a "reasonable" (for some value of
-          "reasonable") number or general-purpose registers and the
-          instruction set is "reasonably" orthogonal (most
-          instructions that operate on GPRs can operate on any GPR),
-          then it's possible to statically partition the GPRs into at
-          least two sets: "immediate registers" never contain nodes,
-          and "node registers" always contain nodes.  (On the PPC, a
-          few registers are members of a third set of "PC locatives",
-          and on both platforms some registers may have dedicated
-          roles as stack or heap pointers; the latter class is treated
-          as immediates by the GC proper but may be used to help
-          determine the bounds of stack and heap memory areas.)</para>
-          <para>The ultimate definition of register partitioning is
-          hardwired into the GC in functions like "mark_xp()" and
-          "forward_xp()", which process the values of some of the
-          registers in an exception frame as nodes and may give some
-          sort of special treatment to other register values they
-          encounter there.)</para>
+            "reasonable") number of general-purpose registers and the
+            instruction set is "reasonably" orthogonal (most
+            instructions that operate on GPRs can operate on any GPR),
+            then it's possible to statically partition the GPRs into at
+            least two sets: "immediate registers" never contain nodes,
+            and "node registers" always contain nodes.  (On the PPC, a
+            few registers are members of a third set of "PC locatives",
+            and on both platforms some registers may have dedicated
+            roles as stack or heap pointers; the latter class is treated
+            as immediates by the GC proper but may be used to help
+            determine the bounds of stack and heap memory areas.)</para>
+              <para>The ultimate definition of register partitioning is
+            hardwired into the GC in functions like "mark_xp()" and
+            "forward_xp()", which process the values of some of the
+            registers in an exception frame as nodes and may give some
+            sort of special treatment to other register values they
+            encounter there.)</para>
           <para>On x86-64, the static register partitioning scheme involves:</para>
-          <itemizedlist>
+              <itemizedlist>
             <listitem>
-              <para>(only) three "immediate" registers.</para>
-              <para>The RAX, RCX, and RDX registers are used as the
-              implicit operands and results of some extended-precision
-              multiply and divide instructions which generally involve
-              non-node values; since their use in these instructions
-              means that they can't be guaranteed to contain node
-              values at all times, it's natural to put these registers
-              in the "immediate" set. RAX is generally given the
-              symbolic name "imm0", RDX is given the symbolic name
-              "imm1" and RCX is given the symbolic name "imm2"; you
-              may see these names in disassembled code, usually in
-              operations involving type checking, array indexing, and
-              foreign memory and function access.</para>
-            </listitem>
+                  <para>(only) three "immediate" registers.</para>
+                  <para>The RAX, RCX, and RDX registers are used as the
+                    implicit operands and results of some extended-precision
+                    multiply and divide instructions which generally involve
+                    non-node values; since their use in these instructions
+                    means that they can't be guaranteed to contain node
+                    values at all times, it's natural to put these registers
+                    in the "immediate" set. RAX is generally given the
+                    symbolic name "imm0", RDX is given the symbolic name
+                    "imm1" and RCX is given the symbolic name "imm2"; you
+                    may see these names in disassembled code, usually in
+                    operations involving type checking, array indexing, and
+                    foreign memory and function access.</para>
+                </listitem>
             <listitem>
-              <para>(only) two "dedicated" registers.</para>
-              <para>RSP and RBP have
-              dedicated functionality dictated by the hardware and
-              calling conventions.</para>
-            </listitem>
+                  <para>(only) two "dedicated" registers.</para>
+                  <para>RSP and RBP have
+                    dedicated functionality dictated by the hardware and
+                    calling conventions.</para>
+                </listitem>
             <listitem>
-              <para>11 "node" registers.</para>
-              <para>All other registers (RBX, RSI, RDI, and R8-R15)
-              are asserted to contain node values at (almost) all
-              times; legacy "string" operations that implicitly use RSI
-              and/or RDI are not used.</para>
-            </listitem>
-          </itemizedlist>
+                  <para>11 "node" registers.</para>
+                  <para>All other registers (RBX, RSI, RDI, and R8-R15)
+                    are asserted to contain node values at (almost) all
+                    times; legacy "string" operations that implicitly use RSI
+                    and/or RDI are not used.</para>
+                </listitem>
+              </itemizedlist>
+
           <para>On the PPC, the static register partitioning scheme
-          involves:</para>
-
-          <itemizedlist>
+            involves:</para>
+              <itemizedlist>
             <listitem>
-              <para>6 "immediate" registers.</para>
-              <para>Registers r3-r8 are given
-              the symbolic names imm0-imm5.  As a RISC architecture
-              with simpler addressing modes, the PPC probably
-              uses immediate registers a bit more often than the CISC
-              x86-64 does, but they're generally used for the same sort
-              of things (type checking, array indexing, FFI,
-              etc.)</para>
-            </listitem>
-            <listitem>
-              <para>9 dedicated registers
-              <itemizedlist>
-                <listitem>
-                  <para>r0 (symbolic name rzero) always contains the
-                  value 0 when running lisp code.  Its value is
-                  sometimes read as 0 when it's used as the base
-                  register in a memory address; keeping the value 0
-                  there is sometimes convenient and avoids
-                  asymmetry.</para>
-                </listitem>
-                <listitem>
-                  <para>r1 (symbolic name sp) is the control stack
-                  pointer, by PPC convention.</para>
-                </listitem>
-                <listitem>
-                  <para>r2 is used to hold the current thread's TCR on
-                  ppc64 systems; it's not used on ppc32.</para>
-                </listitem>
-                <listitem>
-                  <para>r9 and r10 (symbolic names allocptr and
-                  allocbase) are used to do per-thread memory
-                  allocation</para>
-                </listitem>
-                <listitem>
-                  <para>r11 (symbolic name nargs) contains the number
-                  of function arguments on entry and the number of
-                  return values in multiple-value returning
-                  constructs.  It's not used more generally as either
-                  a node or immediate register because of the way that
-                  certain trap instruction encodings are
-                  interpreted.</para>
-                </listitem>
-                <listitem>
-                  <para>r12 (symbolic name tsp) holds the top of the
-                  current thread's temp stack.</para>
-                </listitem>
-                <listitem>
-                  <para>r13 is used to hold the TCR on PPC32 systems;
-                  it's not used on PPC64.</para>
-                </listitem>
-                <listitem>
-                  <para>r14 (symbolic name loc-pc) is used to copy
-                  "pc-locative" values between main memory and
-                  special-purpose PPC registers (LR and CTR) used in
-                  function-call and return instructions.</para>
-                </listitem>
-                <listitem>
-                  <para>r15 (symbolic name vsp) addresses the top of
-                  the current thread's value stack.</para>
-                </listitem>
-                <listitem>
-                  <para>lr and ctr are PPC branch-unit registers used
-                  in function call and return instructions; they're
-                  always treated as "pc-locatives", which precludes
-                  the use of the ctr in some PPC looping
-                  constructs.</para>
-                </listitem>
-              
-              </itemizedlist>
-              </para>
-            </listitem>
+                  <para>6 "immediate" registers.</para>
+                  <para>Registers r3-r8 are given
+                    the symbolic names imm0-imm5.  As a RISC architecture
+                    with simpler addressing modes, the PPC probably
+                    uses immediate registers a bit more often than the CISC
+                    x86-64 does, but they're generally used for the same sort
+                    of things (type checking, array indexing, FFI,
+                    etc.)</para>
+                </listitem>
+                <listitem>
+                  <para>9 dedicated registers
+                    <itemizedlist>
+                          <listitem>
+                            <para>r0 (symbolic name rzero) always contains the
+                              value 0 when running lisp code.  Its value is
+                              sometimes read as 0 when it's used as the base
+                              register in a memory address; keeping the value 0
+                              there is sometimes convenient and avoids
+                              asymmetry.</para>
+                          </listitem>
+                          <listitem>
+                            <para>r1 (symbolic name sp) is the control stack
+                              pointer, by PPC convention.</para>
+                          </listitem>
+                  <listitem>
+                            <para>r2 is used to hold the current thread's TCR on
+                              ppc64 systems; it's not used on ppc32.</para>
+                          </listitem>
+                  <listitem>
+                            <para>r9 and r10 (symbolic names allocptr and
+                              allocbase) are used to do per-thread memory
+                              allocation</para>
+                          </listitem>
+                  <listitem>
+                            <para>r11 (symbolic name nargs) contains the number
+                              of function arguments on entry and the number of
+                              return values in multiple-value returning
+                              constructs.  It's not used more generally as either
+                              a node or immediate register because of the way that
+                              certain trap instruction encodings are
+                              interpreted.</para>
+                          </listitem>
+                  <listitem>
+                            <para>r12 (symbolic name tsp) holds the top of the
+                              current thread's temp stack.</para>
+                          </listitem>
+                          <listitem>
+                            <para>r13 is used to hold the TCR on PPC32 systems;
+                              it's not used on PPC64.</para>
+                          </listitem>
+                          <listitem>
+                            <para>r14 (symbolic name loc-pc) is used to copy
+                              "pc-locative" values between main memory and
+                              special-purpose PPC registers (LR and CTR) used in
+                              function-call and return instructions.</para>
+                          </listitem>
+                  <listitem>
+                            <para>r15 (symbolic name vsp) addresses the top of
+                              the current thread's value stack.</para>
+                          </listitem>
+                          <listitem>
+                            <para>lr and ctr are PPC branch-unit registers used
+                              in function call and return instructions; they're
+                              always treated as "pc-locatives", which precludes
+                              the use of the ctr in some PPC looping
+                              constructs.</para>
+                          </listitem>
+                  
+                    </itemizedlist>
+                  </para>
+                </listitem>
             <listitem>
-              <para>17 "node" registers</para>
-              <para>r15-r31 are always treated as node
-              registers</para>
-            </listitem>
-            
+                  <para>17 "node" registers</para>
+                  <para>r15-r31 are always treated as node
+                    registers</para>
+                </listitem>
+                
           </itemizedlist>
         </sect3>
@@ -686 +691 @@
 
       <sect2 id="Tagging-scheme">
-        <title>Tagging scheme</title>
+            <title>Tagging scheme</title>
         <para>&CCL; always allocates lisp objects on double-node
-        (64-bit for 32-bit platforms, 128-bit for 64-bit platforms)
-        boundaries; this mean that the low 3 bits (32-bit lisp) or 4
-        bits (64-bit lisp) are always 0 and are therefore redundant
-        (we only really need to know the upper 29 or 60 bits in order
-        to identify the aligned object address.)  The extra bits in a
-        lisp node can be used to encode at least some information
-        about the node's type, and the other 29/60 bits represent
-        either an immediate value or a doublenode-aligned memory
-        address.  The low 3 or 4 bits of a node are called the node's
-        "tag bits", and the conventions used to encode type
-        information in those tag bits are called a "tagging
-        scheme."</para>
+          (64-bit for 32-bit platforms, 128-bit for 64-bit platforms)
+          boundaries; this mean that the low 3 bits (32-bit lisp) or 4
+          bits (64-bit lisp) are always 0 and are therefore redundant
+          (we only really need to know the upper 29 or 60 bits in order
+          to identify the aligned object address.)  The extra bits in a
+          lisp node can be used to encode at least some information
+          about the node's type, and the other 29/60 bits represent
+          either an immediate value or a doublenode-aligned memory
+          address.  The low 3 or 4 bits of a node are called the node's
+          "tag bits", and the conventions used to encode type
+          information in those tag bits are called a "tagging
+          scheme."</para>
         <para>It might be possible to use the same tagging scheme on
-        all platforms (at least on all platforms with the same word
-        size and/or the same number of available tag bits), but there
-        are often some strong reasons for not doing so.  These
-        arguments tend to be very machine-specific: sometimes, there
-        are fairly obvious machine-dependent tricks that can be
-        exploited to make common operations on some types of tagged
-        objects faster; other times, there are architectural
-        restrictions that make it impractical to use certain tags for
-        certain types.  (On PPC64, the "ld" (load doubleword) and
-        "std" (store doubleword) instructions - which load and store a
-        GPR operand at the effective address formed by adding the
-        value of another GPR operand and a 16-bit constant operand -
-        require that the low two bits of that constant operand be 0.
-        Since such instructions would typically be used to access the
-        fields of things like CONS cells and structures, it's
-        desirable that that the tags chosen for CONS cells and
-        structures allow the use of these instructions as opposed to
-        more expensive alternatives.)</para>
+          all platforms (at least on all platforms with the same word
+          size and/or the same number of available tag bits), but there
+          are often some strong reasons for not doing so.  These
+          arguments tend to be very machine-specific: sometimes, there
+          are fairly obvious machine-dependent tricks that can be
+          exploited to make common operations on some types of tagged
+          objects faster; other times, there are architectural
+          restrictions that make it impractical to use certain tags for
+          certain types.  (On PPC64, the "ld" (load doubleword) and
+          "std" (store doubleword) instructions - which load and store a
+          GPR operand at the effective address formed by adding the
+          value of another GPR operand and a 16-bit constant operand -
+          require that the low two bits of that constant operand be 0.
+          Since such instructions would typically be used to access the
+          fields of things like CONS cells and structures, it's
+          desirable that that the tags chosen for CONS cells and
+          structures allow the use of these instructions as opposed to
+          more expensive alternatives.)</para>
         <para>One architecture-dependent tagging trick that works well
-        on all architectures is to use a tag of 0 for FIXNUMs: a
-        fixnum basically encodes its value shifted left a few bits and
-        keeps those low bits clear. FIXNUM addition, subtraction, and
-        binary logical operations can operate directly on the node
-        operands, addition and subtraction can exploit hardware-based
-        overflow detection, and (in the absence of overflow) the
-        hardware result of those operations is a node (fixnum).  Some
-        other slightly-less-common operations may require a few extra
-        instructions, but arithmetic operations on FIXNUMs should be
-        as cheap as possible and using a tag of zero for FIXNUMs helps
-        to ensure that it will be.</para> 
-        <para>If we have N available tag bits (N = 3 for 32-bit
-        &CCL; and N = 4 for 64-bit &CCL;), this way of
-        representing fixnums with the low M bits forced to 0 works as
-        long as M &lt;= N.  The smaller we make M, the larger the
-        values of MOST-POSITIVE-FIXNUM and MOST-NEGATIVE become; the
-        larger we make N, the more distinct non-FIXNUM tags become
-        available.  A reasonable compromise is to choose M = N-1; this
-        basically yields two distinct FIXNUM tags (one for even
-        fixnums, one for odd fixnums), gives 30-bit fixnums on 32-bit
-        platforms and 61-bit fixnums on 64-bit platforms, and leaves
-        us with 6 or 14 tags to encoded other types.</para>
+          on all architectures is to use a tag of 0 for FIXNUMs: a
+          fixnum basically encodes its value shifted left a few bits
+          and keeps those low bits clear. FIXNUM addition,
+          subtraction, and binary logical operations can operate
+          directly on the node operands, addition and subtraction can
+          exploit hardware-based overflow detection, and (in the
+          absence of overflow) the hardware result of those operations
+          is a node (fixnum).  Some other slightly-less-common
+          operations may require a few extra instructions, but
+          arithmetic operations on FIXNUMs should be as cheap as
+          possible and using a tag of zero for FIXNUMs helps to ensure
+          that it will be.</para>
+            <para>If we have N available tag bits (N = 3 for 32-bit &CCL;
+              and N = 4 for 64-bit &CCL;), this way of representing
+              fixnums with the low M bits forced to 0 works as long as M
+              &lt;= N.  The smaller we make M, the larger the values of
+              MOST-POSITIVE-FIXNUM and MOST-NEGATIVE become; the larger we
+              make N, the more distinct non-FIXNUM tags become available.
+              A reasonable compromise is to choose M = N-1; this basically
+              yields two distinct FIXNUM tags (one for even fixnums, one
+              for odd fixnums), gives 30-bit fixnums on 32-bit platforms
+              and 61-bit fixnums on 64-bit platforms, and leaves us with 6
+              or 14 tags to encoded other types.</para>
         <para>Once we get past the assignment of FIXNUM tags, things
-        quickly devolve into machine-dependencies.  We can fairly
-        easily see that we can't directly all other primitive lisp
-        object types with only 6 or 14 available tag values; the
-        details of how types are encoded vary between the ppc32,
-        ppc64, and x86-64 implementations, but there are some general
-        common principles:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>CONS cells always contain exactly 2 elements and are
-            usually fairly common.It therefore makes sense to give
-            CONS cells their own tag.  Unlike the fixnum case - where a
-            tag value of 0 had positive implications - there doesn't
-            seem to be any advantage to using any particular value.
-            (A longtime ago - in the case of 68K MCL - the CONS tag
-            and the order of CAR and CDR in memory were chosen to allow
-            smaller, cheaper addressing modes to be used to "cdr down a
-            list."  That's not a factor on ppc or x86-64,but all
-            versions of &CCL; still store the CDR of a CONS cell
-            first in memory.  It doesn't matter, but doing it the way
-            that the host system did made boostrapping to a new target
-            system a little easier.)
-            </para>
-          </listitem>
-          <listitem>
-            <para>Any way you look at it, NIL is a bit ... unusual. NIL
-            is both a SYMBOL and a LIST (as well as being a canonical
-            truth value and probably a few other things.)  Its role as
-            a LIST is probably much more important to most programs
-            than its role as a SYMBOL is:LISTP has to be true of NIL
-            and primitives like CAR and CDR do LISTP implicitly when
-            safe and want that operation to be fast.There are several
-            possible approaches to this; &CCL; uses two of them. On
-            PPC32 and X86-64, NIL is basically a weird CONS cell that
-            straddles two doublenodes; the tag of NIL is unique and
-            congruent modulo 4 (modulo 8 on 64-bit) with the tag used
-            for CONS cells.  LISTP is therefore true of any node whose
-            low 2 (or 3) bits contain the appropriate tag value (it's
-            not otherwise necessary to special-case NIL.)
-            SYMBOL accessors (SYMBOL-NAME, SYMBOL-VALUE, SYMBOL-PLIST
-            ..) -do- have to special-case NIL (and access the
-            components of an internal proxy symbol.) On PPC64 (where
-            architectural restrictions dictate the set of tags that can
-            be used to access fixed components of an object),
-            that approach wasn't practical.  NIL is just a
-            distinguished SYMBOL,and it just happens to be the case
-            that its pname slot and values lots are at the same offsets
-            from a tagged pointer as a CONS cell's CDR and CAR would be.
-            NIL's pname is set to NIL (SYMBOL-NAME checks for this and
-            returns the string "NIL"), and LISTP (and therefore safe
-            CAR and CDR) have to check for (OR NULL CONSP). At least in
-            the case of CAR and CDR, the fact that the PPC has multiple
-            condition-code fields keeps that extra test from
-            being prohibitively expensive.</para>
-          </listitem>
-          <listitem>
-            <para>Some objects are immediate (but not FIXNUMs).This is
-            true of CHARACTERs and, on 64-bit platforms,
-            SINGLE-FLOATs.It's also true of some nodes used in the
-            runtime system (special values used to indicate unbound
-            variables and slots, for instance.) On 64-bit platforms,
-            SINGLE-FLOATs have their own unique tag (making them a
-            little easier to recognize; on all platforms, CHARACTERs
-            share a tag with other immediate objects (unbound markers)
-            but are easy to recognize (by looking at several of their
-            low bits.)  The GC treats any node with an immediate tag
-            (and any node with a fixnum tag) as a leaf.</para>
-          </listitem>
+          quickly devolve into machine-dependencies.  We can fairly
+          easily see that we can't directly tag all other primitive
+          lisp object types with only 6 or 14 available tag values;
+          the details of how types are encoded vary between the ppc32,
+          ppc64, and x86-64 implementations, but there are some
+          general common principles:</para>
+
+            <itemizedlist>
+              <listitem>
+                <para>CONS cells always contain exactly 2 elements and are
+                  usually fairly common.It therefore makes sense to give
+                  CONS cells their own tag.  Unlike the fixnum case -
+                  where a tag value of 0 had positive implications - there
+                  doesn't seem to be any advantage to using any particular
+                  value.  (A longtime ago - in the case of 68K MCL - the
+                  CONS tag and the order of CAR and CDR in memory were
+                  chosen to allow smaller, cheaper addressing modes to be
+                  used to "cdr down a list."  That's not a factor on ppc
+                  or x86-64, but all versions of &CCL; still store the CDR
+                  of a CONS cell first in memory.  It doesn't matter, but
+                  doing it the way that the host system did made
+                  boostrapping to a new target system a little easier.)
+                </para>
+              </listitem>
+              <listitem>
+                <para>Any way you look at it, NIL is a bit
+                  ... unusual. NIL is both a SYMBOL and a LIST (as well as
+                  being a canonical truth value and probably a few other
+                  things.)  Its role as a LIST is probably much more
+                  important to most programs than its role as a SYMBOL is:
+                  LISTP has to be true of NIL and primitives like CAR and
+                  CDR do LISTP implicitly when safe and want that
+                  operation to be fast. There are several possible
+                  approaches to this problem; &CCL; uses two of them. On
+                  PPC32 and X86-64, NIL is basically a weird CONS cell
+                  that straddles two doublenodes; the tag of NIL is unique
+                  and congruent modulo 4 (modulo 8 on 64-bit) with the tag
+                  used for CONS cells.  LISTP is therefore true of any
+                  node whose low 2 (or 3) bits contain the appropriate tag
+                  value (it's not otherwise necessary to special-case
+                  NIL.)  SYMBOL accessors (SYMBOL-NAME, SYMBOL-VALUE,
+                  SYMBOL-PLIST ..) -do- have to special-case NIL (and
+                  access the components of an internal proxy symbol.) On
+                  PPC64 (where architectural restrictions dictate the set
+                  of tags that can be used to access fixed components of
+                  an object), that approach wasn't practical.  NIL is just
+                  a distinguished SYMBOL,and it just happens to be the
+                  case that its pname slot and values slot are at the same
+                  offsets from a tagged pointer as a CONS cell's CDR and
+                  CAR would be.  NIL's pname is set to NIL (SYMBOL-NAME
+                  checks for this and returns the string "NIL"), and LISTP
+                  (and therefore safe CAR and CDR) has to check for (OR
+                  NULL CONSP). At least in the case of CAR and CDR, the
+                  fact that the PPC has multiple condition-code fields
+                  keeps that extra test from being prohibitively
+                  expensive.</para>
+              </listitem>
+              <listitem>
+                <para>Some objects are immediate (but not FIXNUMs). This
+                  is true of CHARACTERs and, on 64-bit platforms,
+                  SINGLE-FLOATs. It's also true of some nodes used in the
+                  runtime system (special values used to indicate unbound
+                  variables and slots, for instance.) On 64-bit platforms,
+                  SINGLE-FLOATs have their own unique tag (making them a
+                  little easier to recognize; on all platforms, CHARACTERs
+                  share a tag with other immediate objects (unbound
+                  markers) but are easy to recognize (by looking at
+                  several of their low bits.)  The GC treats any node with
+                  an immediate tag (and any node with a fixnum tag) as a
+                  leaf.</para>
+              </listitem>
           <listitem>
-            <para>There are some advantages to treating everything
-            else - memory-allocated objects that aren't CONS cells -
-            uniformly.There are some disadvantages to that uniform
-            treatment as well, and the treatment of "memory-allocated
-            non-CONS objects" isn't entirely uniform across all
-            &CCL; implementations.  Let's first pretend that
-            the treatment is uniform, then discuss the ways in which it
-            isn't.The "uniform approach" is to treat all
-            memory-allocated non-CONS objects as if they were vectors;
-            this use of the term is a little looser than what's implied
-            by the CL VECTOR type.  &CCL; actually uses the
-            term "uvector" to mean "a memory-allocated lisp object
-            other than a CONS cell,whose first word is a header which
-            describes the object's type and the number of elements that
-            it contains."  In this view, a SYMBOL is a UVECTOR, as is a
-            STRING, a STANDARD-INSTANCE, a CL array or vector,a
-            FUNCTION, and even a DOUBLE-FLOAT.In the PPC
-            implementations (where things are a little more
-            ... uniform),a single tag value is used to denote any
-            uvector; in order to determine something more specific
-            about the type of the object in question, it's necessary to
-            fetch the low byte of the header word from memory.  On
-            the x86-64 platform, certain types of uvectors - SYMBOLs
-            and FUNCTIONs -are given their own unique tags.  The good
-            news about the x86-64 approach is that SYMBOLs and
-            FUNCTIONs can be recognized without referencing memory; the
-            slightly bad news is that primitive operations that work on
-            UVECTOR-tagged objects - like the function CCL:UVREF -
-            don't work on SYMBOLs or FUNCTIONs on x86-64 (but -do- work
-            on those types of objects in the PPC ports.) The header word
-            which precedes a UVECTOR's data in memory contains 8 bits
-            of type information in the low byte and either 24 or 56
-            bits of"element-count" information in the rest of the
-            word.  (This is where the sometimes-limiting value of 2^24
-            for ARRAY-TOTAL-SIZE-LIMIT on PPC32 platforms comes from.)
-            The low byte of the header - sometimes called the uvector's
-            subtag - is itself tagged (which means that the header is
-            tagged.)  The (3 or 4) tag bits in the subtag are used to
-            determine whether the uvector's elements are nodes or
-            immediates.(A UVECTOR whose elements are nodes is called a
-            GVECTOR; a UVECTOR whose elements are immediates is called
-            an IVECTOR.  This terminology came from Spice Lisp, which
-            was a predecessor of CMUCL.)  Even though a uvector header
-            is tagged, a header is not a node.  There's no (supported)
-            way to get your hands on one in lisp and doing so could be
-            dangerous.  (If the value of a header wound up in a lisp
-            node register and that register wound up getting pushed on
-            a thread's value stack, the GC might misinterpret that
-            situation to mean that there was a stack-allocated UVECTOR
-            on the value stack.)</para>
-          </listitem>
-        
-        </itemizedlist>
+                <para>There are some advantages to treating everything
+                  else&mdash;memory-allocated objects that aren't CONS
+                  cells&mdash;uniformly.There are some disadvantages to
+                  that uniform treatment as well, and the treatment of
+                  "memory-allocated non-CONS objects" isn't entirely
+                  uniform across all &CCL; implementations.  Let's first
+                  pretend that the treatment is uniform, then discuss the
+                  ways in which it isn't.The "uniform approach" is to
+                  treat all memory-allocated non-CONS objects as if they
+                  were vectors; this use of the term is a little looser
+                  than what's implied by the CL VECTOR type.  &CCL;
+                  actually uses the term "uvector" to mean "a
+                  memory-allocated lisp object other than a CONS cell,
+                  whose first word is a header that describes the object's
+                  type and the number of elements that it contains."  In
+                  this view, a SYMBOL is a UVECTOR, as is a STRING, a
+                  STANDARD-INSTANCE, a CL array or vector, a FUNCTION, and
+                  even a DOUBLE-FLOAT. In the PPC implementations (where
+                  things are a little more ... uniform), a single tag
+                  value is used to denote any uvector; in order to
+                  determine something more specific about the type of the
+                  object in question, it's necessary to fetch the low byte
+                  of the header word from memory.  On the x86-64 platform,
+                  certain types of uvectors - SYMBOLs and FUNCTIONs -are
+                  given their own unique tags.  The good news about the
+                  x86-64 approach is that SYMBOLs and FUNCTIONs can be
+                  recognized without referencing memory; the slightly bad
+                  news is that primitive operations that work on
+                  UVECTOR-tagged objects&mdash;like the function
+                  CCL:UVREF&mdash;don't work on SYMBOLs or FUNCTIONs on
+                  x86-64 (but -do- work on those types of objects in the
+                  PPC ports.) The header word that precedes a UVECTOR's
+                  data in memory contains 8 bits of type information in
+                  the low byte and either 24 or 56 bits of "element-count"
+                  information in the rest of the word.  (This is where the
+                  sometimes-limiting value of 2^24 for
+                  ARRAY-TOTAL-SIZE-LIMIT on PPC32 platforms comes from.)
+                  The low byte of the header&mdash;sometimes called the
+                  uvector's subtag&mdash;is itself tagged (which means
+                  that the header is tagged.)  The (3 or 4) tag bits in
+                  the subtag are used to determine whether the uvector's
+                  elements are nodes or immediates. (A UVECTOR whose
+                  elements are nodes is called a GVECTOR; a UVECTOR whose
+                  elements are immediates is called an IVECTOR.  This
+                  terminology came from Spice Lisp, which was a
+                  predecessor of CMUCL.)  Even though a uvector header is
+                  tagged, a header is not a node.  There's no (supported)
+                  way to get your hands on one in lisp and doing so could
+                  be dangerous.  (If the value of a header wound up in a
+                  lisp node register and that register wound up getting
+                  pushed on a thread's value stack, the GC might
+                  misinterpret that situation to mean that there was a
+                  stack-allocated UVECTOR on the value stack.)</para>
+              </listitem>
+          
+            </itemizedlist>
       </sect2>
     </sect1>
@@ -870 +882 @@
     <sect1 id="Heap-Allocation">
       <title>Heap Allocation</title> <para>When the &CCL; kernel first
-      starts up, a large contiguous chunk of the process's address
-      space is mapped as "anonymous, no access" memory. ("Large" means
-      different things in different contexts; on LinuxPPC32, it means
-      "about 1 gigabyte", on DarwinPPC32, it means "about 2
-      gigabytes", and on current 64-bit platforms it ranges from 128
-      to 512 gigabytes, depending on OS. These values are both
-      defaults and upper limits; the --heap-reserve argument can be
-      used to try to reserve less than the default.)</para>
+        starts up, a large contiguous chunk of the process's address
+        space is mapped as "anonymous, no access" memory. ("Large"
+        means different things in different contexts; on LinuxPPC32,
+        it means "about 1 gigabyte", on DarwinPPC32, it means "about 2
+        gigabytes", and on current 64-bit platforms it ranges from 128
+        to 512 gigabytes, depending on OS. These values are both
+        defaults and upper limits;
+        the <literal>--heap-reserve</literal> argument can be used to
+        try to reserve less than the default.)</para>
       <para>Reserving address space that can't (yet) be read or
-      written to doesn't cost much; in particular, it doesn't require
-      that corresponding swap space or physical memory be available.
-      Marking the address range as being "mapped" helps to ensure that
-      other things (results from random calls to malloc(), dynamically
-      loaded shared libraries) won't be allocated in this region that
-      lisp has reserved for its own heap growth.</para>
+        written to doesn't cost much; in particular, it doesn't require
+        that corresponding swap space or physical memory be available.
+        Marking the address range as being "mapped" helps to ensure that
+        other things (results from random calls to malloc(), dynamically
+        loaded shared libraries) won't be allocated in this region that
+        lisp has reserved for its own heap growth.</para>
       <para>A small portion (around 1/32 on 32-bit platforms and 1/64
-      on 64-bit platforms) of that large chunk of address space is
-      reserved for GC data structures.  Memory pages reserved for
-      these data structures are mapped read-write as pages made
-      writable in the main portion of the heap.</para>
+        on 64-bit platforms) of that large chunk of address space is
+        reserved for GC data structures.  Memory pages reserved for
+        these data structures are mapped read-write as pages are made
+        writable in the main portion of the heap.</para>
       <para>The initial heap image is mapped into this reserved
-      address space and an additional (LISP-HEAP-GC-THRESHOLD) bytes
-      are mapped read-write.  GC data structures grow to match the
-      amount of GC-able memory in the initial image + the gc
-      threshold, and control is transferred to lisp code.  Inevitably,
-      that code spoils everything and starts consing; there are
-      basically three layers of memory allocation that can go
-      on.</para>
+        address space and an additional (LISP-HEAP-GC-THRESHOLD) bytes
+        are mapped read-write.  GC data structures grow to match the
+        amount of GC-able memory in the initial image plus the gc
+        threshold, and control is transferred to lisp code.
+        Inevitably, that code spoils everything and starts consing;
+        there are basically three layers of memory allocation that can
+        go on.</para>
 
       <sect2 id="Per-thread-object-allocation">
-        <title>Per-thread object allocation</title>
+            <title>Per-thread object allocation</title>
         <para>Each lisp thread has a private "reserved memory
-        segment"; when a thread starts up, its reserved memory segment
-        is empty.  PPC ports maintain the highest unallocated address
-        and the lowest allocatable address in the current segment in
-        registers when running lisp code; on x86-664, these values are
-        maintained in the current threads's TCR.  (An "empty" heap
-        segment is one whose high pointer and low pointer are equal.)
-        When a thread is not in the middle of allocating something, the
-        low 3 or 4 bits of the high and low pointers are clear (the
-        pointers are doublenode-aligned.)</para>
+          segment"; when a thread starts up, its reserved memory segment
+          is empty.  PPC ports maintain the highest unallocated address
+          and the lowest allocatable address in the current segment in
+          registers when running lisp code; on x86-664, these values are
+          maintained in the current threads's TCR.  (An "empty" heap
+          segment is one whose high pointer and low pointer are equal.)
+          When a thread is not in the middle of allocating something, the
+          low 3 or 4 bits of the high and low pointers are clear (the
+          pointers are doublenode-aligned.)</para>
         <para>A thread tries to allocate an object whose physical size
-        in bytes is X and whose tag is Y by:</para>
-        <orderedlist>
-          <listitem>
-            <para>decrementing the "high" pointer by (- X Y)</para>
-          </listitem>
-          <listitem>
-            <para>trapping if the high pointer is less than the low
-            pointer</para>
-          </listitem>
-          <listitem>
-            <para>using the (tagged) high pointer to initialize the
-            object, if necessary</para>
-          </listitem>
-          <listitem>
-            <para>clearing the low bits of the high pointer</para>
-          </listitem>
-        </orderedlist>
+          in bytes is X and whose tag is Y by:</para>
+            <orderedlist>
+              <listitem>
+                <para>decrementing the "high" pointer by (- X Y)</para>
+              </listitem>
+              <listitem>
+                <para>trapping if the high pointer is less than the low
+                  pointer</para>
+              </listitem>
+              <listitem>
+                <para>using the (tagged) high pointer to initialize the
+                  object, if necessary</para>
+              </listitem>
+              <listitem>
+                <para>clearing the low bits of the high pointer</para>
+              </listitem>
+            </orderedlist>
         <para>On PPC32, where the size of a CONS cell is 8 bytes and
-        the tag of a CONS cell is 1, machine code which sets the arg_z
-        register to the result of doing (CONS arg_y arg_z) looks
-        like:</para>
+          the tag of a CONS cell is 1, machine code which sets the arg_z
+          register to the result of doing (CONS arg_y arg_z) looks
+          like:</para>
         <programlisting>
   (SUBI ALLOCPTR ALLOCPTR 7)    ; decrement the high pointer by (- 8 1)
@@ -940 +953 @@
   (MR ARG_Z ALLOCPTR)           ; arg_z is the new CONS cell
   (RLWINM ALLOCPTR ALLOCPTR 0 0 28)     ; clear tag bits
-        </programlisting>
-        <para>On x86-64, the idea's similar but the implementation is
-        different.  The high and low pointers to the current thread's
-        reserved segment are kept in the TCR, which is addressed by
-        the gs segment register. An x86-64 CONS cell is 16 bytes wide
-        and has a tag of 3; we canonically use the temp0 register to
-        initialize the object</para>
+            </programlisting>
+            <para>On x86-64, the idea's similar but the implementation is
+          different.  The high and low pointers to the current thread's
+          reserved segment are kept in the TCR, which is addressed by
+          the gs segment register. An x86-64 CONS cell is 16 bytes wide
+          and has a tag of 3; we canonically use the temp0 register to
+          initialize the object</para>
         <programlisting>
   (subq ($ 13) ((% gs) 216))    ; decrement allocptr
@@ -958 +971 @@
   (movq (% arg_z) (-3 (% temp0))); set the cdr
   (movq (% temp0) (% arg_z))    ; return the cons
-        </programlisting>
+            </programlisting>
         <para>If we don't take the trap (if allocating 8-16 bytes
-        doesn't exhaust the thread's reserved memory segment), that's
-        a fairly short and simple instruction sequence.  If we do take
-        the trap, we'll have to do some additional work in order to
-        get a new segment for the current thread.</para>
+          doesn't exhaust the thread's reserved memory segment), that's
+          a fairly short and simple instruction sequence.  If we do take
+          the trap, we'll have to do some additional work in order to
+          get a new segment for the current thread.</para>
       </sect2>
 
       <sect2 id="Allocation-of-reserved-heap-segments">
-        <title>Allocation of reserved heap segments</title>
+            <title>Allocation of reserved heap segments</title>
         <para>After the lisp image is first mapped into memory - and after
-        each full GC - the lisp kernel ensures that
-        (LISP-HEAP-GC-TRESHOLD) additional bytes beyond the current
-        end of the heap are mapped read-write.</para>
+          each full GC - the lisp kernel ensures that
+          (LISP-HEAP-GC-TRESHOLD) additional bytes beyond the current
+          end of the heap are mapped read-write.</para>
         <para>If a thread traps while trying to allocate memory, the
-        thread goes through the usual exception-handling protocol (to
-        ensure that any other thread that GCs "sees" the state of the
-        trapping thread and to serialize exception handling.)  When
-        the exception handler runs, it determines the nature and size
-        of the failed allocation and tries to complete the allocation
-        on the thread's behalf (and leave it with a reasonably large
-        thread-specific memory segment so that the next small
-        allocation is unlikely to trap.</para>
+          thread goes through the usual exception-handling protocol (to
+          ensure that any other thread that GCs "sees" the state of the
+          trapping thread and to serialize exception handling.)  When
+          the exception handler runs, it determines the nature and size
+          of the failed allocation and tries to complete the allocation
+          on the thread's behalf (and leave it with a reasonably large
+          thread-specific memory segment so that the next small
+          allocation is unlikely to trap.</para>
         <para>Depending on the size of the requested segment
-        allocation, the number of segment allocations that have
-        occurred since the last GC, and the EGC and GC thresholds, the
-        segment allocation trap handler may invoke a full or ephemeral
-        GC before returning a new segment.  It's worth noting that the
-        [E]GC is triggered based on the number of and size of these
-        segments that have been allocated since the last GC; it doesn't
-        have much to do with how "full" each of those per-thread
-        segments are.  It's possible for a large number of threads to
-        do fairly incidental memory allocation and trigger the GC as a
-        result; avoiding this involves tuning the per-thread
-        allocation quantum and the GC/EGC thresholds
-        appropriately.</para>
+          allocation, the number of segment allocations that have
+          occurred since the last GC, and the EGC and GC thresholds, the
+          segment allocation trap handler may invoke a full or ephemeral
+          GC before returning a new segment.  It's worth noting that the
+          [E]GC is triggered based on the number of and size of these
+          segments that have been allocated since the last GC; it doesn't
+          have much to do with how "full" each of those per-thread
+          segments are.  It's possible for a large number of threads to
+          do fairly incidental memory allocation and trigger the GC as a
+          result; avoiding this involves tuning the per-thread
+          allocation quantum and the GC/EGC thresholds
+          appropriately.</para>
       </sect2>
 
       <sect2 id="Heap-growth">
-        <title>Heap growth</title>
+            <title>Heap growth</title>
         <para>All OSes on which &CCL; currently runs use an
-        "overcommit" memory allocation strategy by default (though
-        some of them provide ways of overriding that default.)  What
-        this means in general is that the OS doesn't necessarily
-        ensure that backing store is available when asked to map pages
-        as read-write; it'll often return a success indicator from the
-        mapping attempt (mapping the pages as "zero-fill,
-        copy-on-write"), and only try to allocate the backing store
-        (swap space and/or physical memory) when non-zero contents are
-        written to the pages.</para>
+          "overcommit" memory allocation strategy by default (though
+          some of them provide ways of overriding that default.)  What
+          this means in general is that the OS doesn't necessarily
+          ensure that backing store is available when asked to map pages
+          as read-write; it'll often return a success indicator from the
+          mapping attempt (mapping the pages as "zero-fill,
+          copy-on-write"), and only try to allocate the backing store
+          (swap space and/or physical memory) when non-zero contents are
+          written to the pages.</para>
         <para>It -sounds- like it'd be better to have the mmap() call
-        fail immediately, but it's actually a complicated issue.
-        (It's possible that other applications will stop using some
-        backing store before lisp code actually touches the pages that
-        need it, for instance.)  It's also not guaranteed that lisp
-        code would be able to "cleanly" signal an out-of-memory
-        condition if lisp is ... out of memory</para>
-        <para>I don't know that I've ever seen an abrupt out-of-memory
-        failure that wasn't preceded by several minutes of excessive
-        paging activity.  The most expedient course in cases like this
-        is to either (a) use less memory or (b) get more memory; it's
-        generally hard to use memory that you don't have.</para>
+          fail immediately, but it's actually a complicated issue.
+          (It's possible that other applications will stop using some
+          backing store before lisp code actually touches the pages that
+          need it, for instance.)  It's also not guaranteed that lisp
+          code would be able to "cleanly" signal an out-of-memory
+          condition if lisp is ... out of memory</para>
+            <para>I don't know that I've ever seen an abrupt out-of-memory
+              failure that wasn't preceded by several minutes of excessive
+              paging activity.  The most expedient course in cases like this
+              is to either (a) use less memory or (b) get more memory; it's
+              generally hard to use memory that you don't have.</para>
       </sect2>
     </sect1>
@@ -1026 +1039 @@
       <title>GC details</title>
       <para>The GC uses a Mark/Compact algorithm; its
-      execution time is essentially a factor of the amount of live
-      data in the heap. (The somewhat better-known Mark/Sweep
-      algorithms don't compact the live data but instead traverse the
-      garbage to rebuild free-lists; their execution time is therefore
-      a factor of the total heap size.)</para>
+        execution time is essentially a factor of the amount of live
+        data in the heap. (The somewhat better-known Mark/Sweep
+        algorithms don't compact the live data but instead traverse the
+        garbage to rebuild free-lists; their execution time is therefore
+        a factor of the total heap size.)</para>
       <para>As mentioned in <xref linkend="Heap-Allocation"/>, two
-      auxiliary data structures (proportional to the size of the lisp
-      heap) are maintained. These are</para>
+        auxiliary data structures (proportional to the size of the lisp
+        heap) are maintained. These are</para>
       <orderedlist>
-        <listitem>
-          <para>the markbits bitvector, which contains a bit for
-          every doublenode in the dynamic heap (plus a few extra words
-          for alignment and so that sub-bitvectors can start on word
-          boundaries.)</para>
-        </listitem>
-        <listitem>
-          <para>the relocation table, which contains a native word for
-          every 32 or 64 doublenodes in the dynamic heap, plus an
-          extra word used to keep track of the end of the heap.</para>
-        </listitem>
+            <listitem>
+              <para>the markbits bitvector, which contains a bit for
+                every doublenode in the dynamic heap (plus a few extra words
+                for alignment and so that sub-bitvectors can start on word
+                boundaries.)</para>
+            </listitem>
+            <listitem>
+              <para>the relocation table, which contains a native word for
+                every 32 or 64 doublenodes in the dynamic heap, plus an
+                extra word used to keep track of the end of the heap.</para>
+            </listitem>
       </orderedlist>
       <para>The total GC space overhead is therefore on the order of
-      3% (2/64 or 1/32).</para>
+        3% (2/64 or 1/32).</para>
       <para>The general algorithm proceeds as follows:</para>
 
       <sect2 id="Mark-phase">
-        <title>Mark phase</title>
+            <title>Mark phase</title>
         <para>Each doublenode in the dynamic heap has a corresponding
-        bit in the markbits vector. (For any doublenode in the heap,
-        the index of its mark bit is determined by subtracting the
-        address of the start of the heap from the address of the
-        object and dividing the result by 8 or 16.) The GC knows the
-        markbit index of the free pointer, so determining that the
-        markbit index of a doubleword address is between the start of
-        the heap and the free pointer can be done with a single
-        unsigned comparison.</para>
+          bit in the markbits vector. (For any doublenode in the heap,
+          the index of its mark bit is determined by subtracting the
+          address of the start of the heap from the address of the
+          object and dividing the result by 8 or 16.) The GC knows the
+          markbit index of the free pointer, so determining that the
+          markbit index of a doubleword address is between the start of
+          the heap and the free pointer can be done with a single
+          unsigned comparison.</para>
         <para>The markbits of all doublenodes in the dynamic heap are
-        zeroed before the mark phase begins. An object is
-        <emphasis>marked</emphasis> if the markbits of all of its
-        constituent doublewords are set and unmarked otherwise;
-        setting an object's markbits involves setting the corresponding
-        markbits of all constituent doublenodes in the object.</para>
+          zeroed before the mark phase begins. An object is
+          <emphasis>marked</emphasis> if the markbits of all of its
+          constituent doublewords are set and unmarked otherwise;
+          setting an object's markbits involves setting the corresponding
+          markbits of all constituent doublenodes in the object.</para>
         <para>The mark phase traverses each root. If the tag of the
-        value of the root indicates that it's a non-immediate node
-        whose address lies in the lisp heap, then:</para>
-        <orderedlist>
-          <listitem>
-            <para>If the object is already marked, do nothing.</para>
-          </listitem>
-          <listitem>
-            <para>Set the object's markbit(s).</para>
-          </listitem>
-          <listitem>
-            <para>If the object is an ivector, do nothing further.</para>
-          </listitem>
-          <listitem>
-            <para>If the object is a cons cell, recursively mark its
-            car and cdr.</para>
-          </listitem>
-          <listitem>
-            <para>Otherwise, the object is a gvector. Recursively mark
-            its elements.</para>
-          </listitem>
-        </orderedlist>
+          value of the root indicates that it's a non-immediate node
+          whose address lies in the lisp heap, then:</para>
+            <orderedlist>
+              <listitem>
+                <para>If the object is already marked, do nothing.</para>
+              </listitem>
+              <listitem>
+                <para>Set the object's markbit(s).</para>
+              </listitem>
+              <listitem>
+                <para>If the object is an ivector, do nothing further.</para>
+              </listitem>
+              <listitem>
+                <para>If the object is a cons cell, recursively mark its
+                  car and cdr.</para>
+              </listitem>
+              <listitem>
+                <para>Otherwise, the object is a gvector. Recursively mark
+                  its elements.</para>
+              </listitem>
+            </orderedlist>
         <para>Marking an object thus involves ensuring that its mark
-        bits are set and then recursively marking any pointers
-        contained within the object if the object was originally
-        unmarked. If this recursive step was implemented in the
-        obvious manner, marking an object would take stack space
-        proportional to the length of the pointer chain from some root
-        to that object. Rather than storing that pointer chain
-        implicitly on the stack (in a series of recursive calls to the
-        mark subroutine), the &CCL; marker uses mixture of recursion
-        and a technique called <emphasis>link inversion</emphasis> to
-        store the pointer chain in the objects themselves.  (Recursion
-        tends to be simpler and faster; if a recursive step notes that
-        stack space is becoming limited, the link-inversion technique
-        is used.)</para>
+          bits are set and then recursively marking any pointers
+          contained within the object if the object was originally
+          unmarked. If this recursive step was implemented in the
+          obvious manner, marking an object would take stack space
+          proportional to the length of the pointer chain from some root
+          to that object. Rather than storing that pointer chain
+          implicitly on the stack (in a series of recursive calls to the
+          mark subroutine), the &CCL; marker uses mixture of recursion
+          and a technique called <emphasis>link inversion</emphasis> to
+          store the pointer chain in the objects themselves.  (Recursion
+          tends to be simpler and faster; if a recursive step notes that
+          stack space is becoming limited, the link-inversion technique
+          is used.)</para>
         <para>Certain types of objects are treated a little specially:</para>
-        <orderedlist>
-        <listitem>
-          <para>To support a feature called <emphasis>GCTWA
-              <footnote>
-                <para>I believe that the acronym comes from MACLISP,
-                where it stood for "Garbage Collection of Truly
-                Worthless Atoms".</para>
-              </footnote>
-              , </emphasis>the vector which contains the
-              internal symbols of the current package is marked on
-              entry to the mark phase, but the symbols themselves are
-              not marked at this time. Near the end of the mark phase,
-              symbols referenced from this vector which are
-              not otherwise marked are marked if and only if they're
-              somehow distinguishable from newly created symbols (by
-              virtue of their having function bindings, value bindings,
-              plists, or other attributes.)</para>
-        </listitem>
-        <listitem>
-          <para>Pools have their first element set to NIL before any
-          other elements are marked.</para>
-        </listitem>
-        <listitem>
-          <para>All hash tables have certain fields (used to cache
-          previous results) invalidated.</para>
-        </listitem>
-        <listitem>
-          <para>Weak Hash Tables and other weak objects are put on a
-          linkedlist as they're encountered; their contents are only
-          retained if there are other (non-weak) references to
-          them.</para>
-        </listitem>
-        </orderedlist>
+            <orderedlist>
+              <listitem>
+                <para>To support a feature called <emphasis>GCTWA
+                <footnote>
+                          <para>I believe that the acronym comes from MACLISP,
+                            where it stood for "Garbage Collection of Truly
+                            Worthless Atoms".</para>
+                </footnote>
+                    , </emphasis>the vector that contains the internal
+                  symbols of the current package is marked on entry to the
+                  mark phase, but the symbols themselves are not marked at
+                  this time. Near the end of the mark phase, symbols
+                  referenced from this vector which are not otherwise
+                  marked are marked if and only if they're somehow
+                  distinguishable from newly created symbols (by virtue of
+                  their having function bindings, value bindings, plists,
+                  or other attributes.)</para>
+              </listitem>
+              <listitem>
+                <para>Pools have their first element set to NIL before any
+                  other elements are marked.</para>
+              </listitem>
+              <listitem>
+                <para>All hash tables have certain fields (used to cache
+                  previous results) invalidated.</para>
+              </listitem>
+              <listitem>
+                <para>Weak Hash Tables and other weak objects are put on a
+                  linkedlist as they're encountered; their contents are only
+                  retained if there are other (non-weak) references to
+                  them.</para>
+              </listitem>
+            </orderedlist>
         <para>At the end of the mark phase, the markbits of all
-        objects which are transitively reachable from the roots are
-        set and all other markbits are clear.</para>
+          objects that are transitively reachable from the roots are
+          set and all other markbits are clear.</para>
       </sect2>
 
       <sect2 id="Relocation-phase">
-        <title>Relocation phase</title>
-        <para>The <emphasis>forwarding address</emphasis> of a
-        doublenode in the dynamic heap is (&lt;its current address> -
-        (size_of_doublenode * &lt;the number of unmarked markbits that
-        precede it>)) or alternately (&lt;the base of the heap> +
-        (size_of_doublenode * &lt;the number of marked markbits that
-        precede it &gt;)). Rather than count the number of preceding
-        markbits each time, the relocation table is used to precompute
-        an approximation of the forwarding addresses for all
-        doublewords. Given this approximate address and a pointer into
-        the markbits vector, it's relatively easy to compute the exact
-        forwarding address.</para>
-        <para>The relocation table contains the forwarding addresses
-        of each <emphasis>pagelet</emphasis>, where a pagelet is 256
-        bytes (or 32 doublenodes). The forwarding address of the first
-        pagelet is the base of the heap. The forwarding address of the
-        second pagelet is the sum of the forwarding address of the
-        first and 8 bytes for each mark bit set in the first 32-bit
-        word in the markbits table. The last entry in the relocation
-        table contains the forwarding address that the freepointer
-        would have, e.g., the new value of the freepointer after
-        compaction.</para>
-        <para>In many programs, old objects rarely become garbage and
-        new objects often do. When building the relocation table, the
-        relocation phase notes the address of the first unmarked
-        object in the dynamic heap. Only the area of the heap between
-        the first unmarked object and the freepointer needs to be
-        compacted; only pointers to this area will need to be
-        forwarded (the forwarding address of all other pointers to the
-        dynamic heap is the address of that pointer.)  Often, the
-        first unmarked object is much nearer the free pointer than it
-        is to the base of the heap.</para>
+            <title>Relocation phase</title>
+            <para>The <emphasis>forwarding address</emphasis> of a
+              doublenode in the dynamic heap is (&lt;its current address> -
+              (size_of_doublenode * &lt;the number of unmarked markbits that
+              precede it>)) or alternately (&lt;the base of the heap> +
+              (size_of_doublenode * &lt;the number of marked markbits that
+              precede it &gt;)). Rather than count the number of preceding
+              markbits each time, the relocation table is used to precompute
+              an approximation of the forwarding addresses for all
+              doublewords. Given this approximate address and a pointer into
+              the markbits vector, it's relatively easy to compute the exact
+              forwarding address.</para>
+            <para>The relocation table contains the forwarding addresses
+              of each <emphasis>pagelet</emphasis>, where a pagelet is 256
+              bytes (or 32 doublenodes). The forwarding address of the first
+              pagelet is the base of the heap. The forwarding address of the
+              second pagelet is the sum of the forwarding address of the
+              first and 8 bytes for each mark bit set in the first 32-bit
+              word in the markbits table. The last entry in the relocation
+              table contains the forwarding address that the freepointer
+              would have, e.g., the new value of the freepointer after
+              compaction.</para>
+            <para>In many programs, old objects rarely become garbage and
+              new objects often do. When building the relocation table, the
+              relocation phase notes the address of the first unmarked
+              object in the dynamic heap. Only the area of the heap between
+              the first unmarked object and the freepointer needs to be
+              compacted; only pointers to this area will need to be
+              forwarded (the forwarding address of all other pointers to the
+              dynamic heap is the address of that pointer.)  Often, the
+              first unmarked object is much nearer the free pointer than it
+              is to the base of the heap.</para>
       </sect2>
 
       <sect2 id="Forwarding-phase">
-        <title>Forwarding phase</title>
+            <title>Forwarding phase</title>
         <para>The forwarding phase traverses all roots and the "old"
-        part of the dynamic heap (the part between the base of the
-        heap and the first unmarked object.) All references to objects
-        whose address is between the first unmarked object and the
-        free pointer are updated to point to the address the object
-        will have after compaction by using the relocation table and
-        the markbits vector and interpolating.</para>
-        <para>The relocation table entry for the pagelet nearest the
-        object is found. If the pagelet's address is less than the
-        object's address, the number of set markbits that precede the
-        object on the pagelet is used to determine the object's
-        address; otherwise, the number of set markbits the follow the
-        object on the pagelet is used.</para>
+          part of the dynamic heap (the part between the base of the
+          heap and the first unmarked object.) All references to objects
+          whose address is between the first unmarked object and the
+          free pointer are updated to point to the address the object
+          will have after compaction by using the relocation table and
+          the markbits vector and interpolating.</para>
+            <para>The relocation table entry for the pagelet nearest the
+              object is found. If the pagelet's address is less than the
+              object's address, the number of set markbits that precede
+              the object on the pagelet is used to determine the object's
+              address; otherwise, the number of set markbits that follow
+              the object on the pagelet is used.</para>
         <para>Since forwarding views the heap as a set of doublewords,
-        locatives are (mostly) treated like any other pointers. (The
-        basic difference is that locatives may appear to be tagged as
-        fixnums, in which case they're treated as word-aligned
-        pointers into the object.)</para>
+          locatives are (mostly) treated like any other pointers. (The
+          basic difference is that locatives may appear to be tagged as
+          fixnums, in which case they're treated as word-aligned
+          pointers into the object.)</para>
         <para>If the forward phase changes the address of any hash
-        table key in a hash table that hashes by address (e.g., an EQ
-        hash table), it sets a bit in the hash table's header. The
-        hash table code will rehash the hash table's contents if it
-        tries to do a lookup on a key in such a table.</para>
+          table key in a hash table that hashes by address (e.g., an EQ
+          hash table), it sets a bit in the hash table's header. The
+          hash table code will rehash the hash table's contents if it
+          tries to do a lookup on a key in such a table.</para>
         <para>Profiling reveals that about half of the total time
-        spent in the GC is spent in the subroutine which determines a
-        pointer's forwarding address. Exploiting GCC-specific idioms,
-        hand-coding the routine, and inlining calls to it could all be
-        expected to improve GC performance.</para>
+          spent in the GC is spent in the subroutine which determines a
+          pointer's forwarding address. Exploiting GCC-specific idioms,
+          hand-coding the routine, and inlining calls to it could all be
+          expected to improve GC performance.</para>
       </sect2>
 
       <sect2 id="Compact-phase">
-        <title>Compact phase</title>
+            <title>Compact phase</title>
         <para>The compact phase compacts the area between the first
-        unmarked object and the freepointer so that it contains only
-        marked objects.  While doing so, it forwards any pointers it
-        finds in the objects it copies.</para>
+          unmarked object and the freepointer so that it contains only
+          marked objects.  While doing so, it forwards any pointers it
+          finds in the objects it copies.</para>
         <para>When the compact phase is finished, so is the GC (more
-        or less): the free pointer and some other data structures are
-        updated and control returns to the exception handler that
-        invoked the GC. If sufficient memory has been freed to satisfy
-        any allocation request that may have triggered the GC, the
-        exception handler returns; otherwise, a "seriously low on
-        memory" condition is signaled, possibly after releasing a
-        small emergency pool of memory.</para>
+          or less): the free pointer and some other data structures are
+          updated and control returns to the exception handler that
+          invoked the GC. If sufficient memory has been freed to satisfy
+          any allocation request that may have triggered the GC, the
+          exception handler returns; otherwise, a "seriously low on
+          memory" condition is signaled, possibly after releasing a
+          small emergency pool of memory.</para>
       </sect2>
     </sect1>
@@ -1230 +1243 @@
       <title>The ephemeral GC</title>
       <para>In the &CCL; memory management scheme, the relative age
-      of two objects in the dynamic heap can be determined by their
-      addresses: if addresses X and Y are both addresses in the
-      dynamic heap, X is younger than Y (X was created more recently
-      than Y) if it is nearer to the free pointer (and farther from
-      the base of the heap) than Y.</para>
+        of two objects in the dynamic heap can be determined by their
+        addresses: if addresses X and Y are both addresses in the
+        dynamic heap, X is younger than Y (X was created more recently
+        than Y) if it is nearer to the free pointer (and farther from
+        the base of the heap) than Y.</para>
       <para>Ephemeral (or generational) garbage collectors attempt to
-      exploit the following assumptions:</para>
+        exploit the following assumptions:</para>
       <itemizedlist>
-        <listitem>
-          <para>most newly created objects become garbage soon after
-          they'recreated.</para>
-        </listitem>
-        <listitem>
-          <para>most objects that have already survived several GCs
-          are unlikely to ever become garbage.</para>
-        </listitem>
-        <listitem>
-          <para>old objects can only point to newer objects as the
-          result of a destructive modification (e.g., via
-          SETF.)</para>
-        </listitem>
+            <listitem>
+              <para>most newly created objects become garbage soon after
+                they'recreated.</para>
+            </listitem>
+            <listitem>
+              <para>most objects that have already survived several GCs
+                are unlikely to ever become garbage.</para>
+            </listitem>
+            <listitem>
+              <para>old objects can only point to newer objects as the
+                result of a destructive modification (e.g., via
+                SETF.)</para>
+            </listitem>
       </itemizedlist>
 
       <para>By concentrating its efforts on (frequently and quickly)
-      reclaiming newly created garbage, an ephemeral collector hopes
-      to postpone the more costly full GC as long as possible. It's
-      important to note that most programs create some long-lived
-      garbage, so an EGC can't typically eliminate the need for full
-      GC.</para>
+        reclaiming newly created garbage, an ephemeral collector hopes
+        to postpone the more costly full GC as long as possible. It's
+        important to note that most programs create some long-lived
+        garbage, so an EGC can't typically eliminate the need for full
+        GC.</para>
       <para>An EGC views each object in the heap as belonging to
-      exactly one <emphasis>generation</emphasis>; generations are
-      sets of objects that are related to each other by age: some
-      generation is the youngest, some the oldest, and there's an age
-      relationship between any intervening generations. Objects are
-      typically assigned to the youngest generation when first
-      allocated; any object that has survived some number of GCs in
-      its current generation is promoted (or
-      <emphasis>tenured</emphasis>) into an older generation.</para>
+        exactly one <emphasis>generation</emphasis>; generations are
+        sets of objects that are related to each other by age: some
+        generation is the youngest, some the oldest, and there's an age
+        relationship between any intervening generations. Objects are
+        typically assigned to the youngest generation when first
+        allocated; any object that has survived some number of GCs in
+        its current generation is promoted (or
+        <emphasis>tenured</emphasis>) into an older generation.</para>
       <para>When a generation is GCed, the roots consist of the
-      stacks, registers, and global variables as always and also of
-      any pointers to objects in that generation from other
-      generations. To avoid the need to scan those (often large) other
-      generations looking for such intergenerational references, the
-      runtime system must note all such intergenerational references
-      at the point where they're created (via Setf).<footnote><para>This is
-      sometimes called "The Write Barrier": all assignments which
-      might result in intergenerational references must be noted, as
-      if the other generations were write-protected.</para></footnote> The
-      set of pointers that may contain intergenerational references is
-      sometimes called <emphasis>the remembered set</emphasis>.</para>
+        stacks, registers, and global variables as always and also of
+        any pointers to objects in that generation from other
+        generations. To avoid the need to scan those (often large) other
+        generations looking for such intergenerational references, the
+        runtime system must note all such intergenerational references
+        at the point where they're created (via Setf).<footnote><para>This is
+            sometimes called "The Write Barrier": all assignments which
+            might result in intergenerational references must be noted, as
+            if the other generations were write-protected.</para></footnote> The
+        set of pointers that may contain intergenerational references is
+        sometimes called <emphasis>the remembered set</emphasis>.</para>
       <para>In &CCL;'s EGC, the heap is organized exactly the same
-      as otherwise; "generations" are merely structures which contain
-      pointers to regions of the heap (which is already ordered by
-      age.) When a generation needs to be GCed, any younger generation
-      is incorporated into it; all objects which survive a GC of a
-      given generation are promoted into the next older
-      generation. The only intergenerational references that can exist
-      are therefore those where an old object is modified to contain a
-      pointer to a new object.</para>
+        as otherwise; "generations" are merely structures which contain
+        pointers to regions of the heap (which is already ordered by
+        age.) When a generation needs to be GCed, any younger generation
+        is incorporated into it; all objects which survive a GC of a
+        given generation are promoted into the next older
+        generation. The only intergenerational references that can exist
+        are therefore those where an old object is modified to contain a
+        pointer to a new object.</para>
       <para>The EGC uses exactly the same code as the full GC. When a
-      given GC is "ephemeral",</para>
+        given GC is "ephemeral",</para>
       <itemizedlist>
         <listitem>
-          <para>the "base of the heap" used to determine an object's
-          markbit address is the base of the generation
-          being collected;</para>
-        </listitem>
+              <para>the "base of the heap" used to determine an object's
+                markbit address is the base of the generation
+                being collected;</para>
+            </listitem>
         <listitem>
-          <para>the markbits vector is actually a pointer into the
-          middle of the global markbits table; preceding entries in
-          this table are used to note doubleword addresses in older
-          generations that (may) contain intergenerational
-          references;</para>
-        </listitem>
+              <para>the markbits vector is actually a pointer into the
+                middle of the global markbits table; preceding entries in
+                this table are used to note doubleword addresses in older
+                generations that (may) contain intergenerational
+                references;</para>
+            </listitem>
         <listitem>
-          <para>some steps (notably GCTWA and the handling of weak
-          objects) are not performed;</para>
-        </listitem>
+              <para>some steps (notably GCTWA and the handling of weak
+                objects) are not performed;</para>
+            </listitem>
         <listitem>
-          <para>the intergenerational references table is used to
-          find additional roots for the mark and forward phases. If a
-          bit is set inthe intergenerational references table, that
-          means that the corresponding doubleword (in some "old"
-          generation, in some "earlier" part of the heap) may have had
-          a pointer to an object in a younger generation stored into
-          it.</para>
-        </listitem>
-      
+              <para>the intergenerational references table is used to
+                find additional roots for the mark and forward phases. If a
+                bit is set in the intergenerational references table, that
+                means that the corresponding doubleword (in some "old"
+                generation, in some "earlier" part of the heap) may have had
+                a pointer to an object in a younger generation stored into
+                it.</para>
+            </listitem>
+        
       </itemizedlist>
       <para>With one exception (the implicit setfs that occur on entry
-      to and exit from the binding of a special variable), all setfs
-      that might introduce an intergenerational reference must be
-      memoized.@footnote{Note that the implicit setfs that occur when
-      initializing an object - as in the case of a call to cons or
-      vector - can't introduce intergenerational references, since the
-      newly created object is always younger than the objects used to
-      initialize it.} It's always safe to push any cons cell or
-      gvector locative onto the memo stack; it's never safe to push
-      anything else.
+        to and exit from the binding of a special variable), all setfs
+        that might introduce an intergenerational reference must be
+        memoized.
+        <footnote><para>Note that the implicit setfs that occur when
+        initializing an object - as in the case of a call to cons or
+        vector - can't introduce intergenerational references, since
+        the newly created object is always younger than the objects
+        used to initialize it.</para></footnote> It's always safe to
+        push any cons cell or gvector locative onto the memo stack;
+        it's never safe to push anything else.
       </para>
 
       <para>Typically, the intergenerational references bitvector is
-      sparse: a relatively small number of old locations are stored
-      into, although some of them may have been stored into many
-      times. The routine that scans the memoization buffer does a lot
-      of work and usually does it fairly often; it uses a simple,
-      brute-force method but might run faster if it was smarter about
-      recognizing addresses that it'd already seen.
+        sparse: a relatively small number of old locations are stored
+        into, although some of them may have been stored into many
+        times. The routine that scans the memoization buffer does a lot
+        of work and usually does it fairly often; it uses a simple,
+        brute-force method but might run faster if it was smarter about
+        recognizing addresses that it'd already seen.
       </para>
 
       <para>When the EGC mark and forward phases scan the
-      intergenerational reference bits, they can clear any bits that
-      denote doublewords that definitely do not contain
-      intergenerational references.
+        intergenerational reference bits, they can clear any bits that
+        denote doublewords that definitely do not contain
+        intergenerational references.
       </para>
     </sect1>
@@ -1350 +1364 @@
       <title>Fasl files</title>
       <para>Saving and loading of Fasl files is implemented in
-      xdump/faslenv.lisp, level-0/nfasload.lisp, and lib/nfcomp.lisp.
-      The information here is only an overview, which might help when
-      reading the source.</para>
+        xdump/faslenv.lisp, level-0/nfasload.lisp, and lib/nfcomp.lisp.
+        The information here is only an overview, which might help when
+        reading the source.</para>
       <para>The &CCL; Fasl format is forked from the old MCL Fasl
-      format; there are a few differences, but they are minor.  The
-      name "nfasload" comes from the fact that this is the so-called
-      "new" Fasl system, which was true in 1986 or so.  </para>
+        format; there are a few differences, but they are minor.  The
+        name "nfasload" comes from the fact that this is the so-called
+        "new" Fasl system, which was true in 1986 or so.  </para>
       <para>A Fasl file begins with a "file header", which contains
-      version information and a count of the following "blocks".
-      There's typically only one "block" per Fasl file.  The blocks
-      are part of a mechanism for combining multiple logical files
-      into a single physical file, in order to simplify the
-      distribution of precompiled programs. </para>
+        version information and a count of the following "blocks".
+        There's typically only one "block" per Fasl file.  The blocks
+        are part of a mechanism for combining multiple logical files
+        into a single physical file, in order to simplify the
+        distribution of precompiled programs. </para>
       <para>Each block begins with a header for itself, which just
-      describes the size of the data that follows.</para>
+        describes the size of the data that follows.</para>
       <para>The data in each block is treated as a simple stream of
-      bytes, which define a bytecode program.  The actual bytecodes,
-      "fasl operators", are defined in xdump/faslenv.lisp.  The
-      descriptions in the source file are terse, but, according to
-      Gary, "probably accurate".</para>
+        bytes, which define a bytecode program.  The actual bytecodes,
+        "fasl operators", are defined in xdump/faslenv.lisp.  The
+        descriptions in the source file are terse, but, according to
+        Gary, "probably accurate".</para>
       <para>Some of the operators are used to create a per-block
-      "object table", which is a vector used to keep track of
-      previously-loaded objects and simplify references to them.  When
-      the table is created, an index associated with it is set to
-      zero; this is analogous to an array fill-pointer, and allows the
-      table to be treated like a stack.</para>
+        "object table", which is a vector used to keep track of
+        previously-loaded objects and simplify references to them.  When
+        the table is created, an index associated with it is set to
+        zero; this is analogous to an array fill-pointer, and allows the
+        table to be treated like a stack.</para>
       <para>The low seven bits of each bytecode are used to specify
-      the fasl operator; currently, about fifty operators are defined.
-      The high byte, when set, indicates that the result of the
-      operation should be pushed onto the object table.</para>
+        the fasl operator; currently, about fifty operators are defined.
+        The high byte, when set, indicates that the result of the
+        operation should be pushed onto the object table.</para>
       <para>Most bytecodes are followed by operands; the operand data
-      is byte-aligned.  How many operands there are, and their type,
-      depend on the bytecode.  Operands can be indices into the object
-      table, immediate values, or some combination of these.</para>
+        is byte-aligned.  How many operands there are, and their type,
+        depend on the bytecode.  Operands can be indices into the object
+        table, immediate values, or some combination of these.</para>
       <para>An exception is the bytecode #xFF, which has the symbolic
-      name ccl::$faslend; it is used to mark the end of the
-      block.</para>
+        name ccl::$faslend; it is used to mark the end of the
+        block.</para>
     </sect1>
 
@@ -1395 +1409 @@
 
       <sect2 id="How-CCL-Recognizes-Objective-C-Objects">
-        <title>How &CCL; Recognizes Objective-C Objects</title>
+            <title>How &CCL; Recognizes Objective-C Objects</title>
         <para>In most cases, pointers to instances of Objective-C
-        classes are recognized as such; the recognition is (and
-        probably always will be) slightly heuristic. Basically, any
-        pointer that passes basic sanity checks and whose first word
-        is a pointer to a known ObjC class is considered to be an
-        instance of that class; the Objective-C runtime system would
-        reach the same conclusion.</para>
+          classes are recognized as such; the recognition is (and
+          probably always will be) slightly heuristic. Basically, any
+          pointer that passes basic sanity checks and whose first word
+          is a pointer to a known ObjC class is considered to be an
+          instance of that class; the Objective-C runtime system would
+          reach the same conclusion.</para>
         <para>It's certainly possible that a random pointer to an
-        arbitrary memory address could look enough like an ObjC
-        instance to fool the lisp runtime system, and it's possible
-        that pointers could have their contents change so that
-        something that had either been a true ObjC instance (or had
-        looked a lot like one) is changed (possibly by virtue of
-        having been deallocated.)</para>
+          arbitrary memory address could look enough like an ObjC
+          instance to fool the lisp runtime system, and it's possible
+          that pointers could have their contents change so that
+          something that had either been a true ObjC instance (or had
+          looked a lot like one) is changed (possibly by virtue of
+          having been deallocated.)</para>
         <para>In the first case, we can improve the heuristics
-        substantially: we can make stronger assertions that a
-        particular pointer is really "of type :ID" when it's a
-        parameter to a function declared to take such a pointer as an
-        argument or a similarly declared function result; we can be
-        more confident of something we obtained via SLOT-VALUE of a
-        slot defined to be of type :ID than if we just dug a pointer
-        out of memory somewhere.</para>
+          substantially: we can make stronger assertions that a
+          particular pointer is really "of type :ID" when it's a
+          parameter to a function declared to take such a pointer as an
+          argument or a similarly declared function result; we can be
+          more confident of something we obtained via SLOT-VALUE of a
+          slot defined to be of type :ID than if we just dug a pointer
+          out of memory somewhere.</para>
         <para>The second case is a little more subtle: ObjC memory
-        management is based on a reference-counting scheme, and it's
-        possible for an object to ... cease to be an object while lisp
-        is still referencing it.  If we don't want to deal with this
-        possibility (and we don't), we'll basically have to ensure
-        that the object is not deallocated while lisp is still
-        thinking of it as a first-class object. There's some support
-        for this in the case of objects created with MAKE-INSTANCE,
-        but we may need to give similar treatment to foreign objects
-        that are introduced to the lisp runtime in other ways (as
-        function arguments, return values, SLOT-VALUE results, etc. as
-        well as those instances that are created under lisp
-        control.)</para>
+          management is based on a reference-counting scheme, and it's
+          possible for an object to ... cease to be an object while lisp
+          is still referencing it.  If we don't want to deal with this
+          possibility (and we don't), we'll basically have to ensure
+          that the object is not deallocated while lisp is still
+          thinking of it as a first-class object. There's some support
+          for this in the case of objects created with MAKE-INSTANCE,
+          but we may need to give similar treatment to foreign objects
+          that are introduced to the lisp runtime in other ways (as
+          function arguments, return values, SLOT-VALUE results, etc. as
+          well as those instances that are created under lisp
+          control.)</para>
         <para>This doesn't all work yet (in fact, not much of it works
-        yet); in practice, this has not yet been as much of a problem
-        as anticipated, but that may be because existing Cocoa code
-        deals primarily with relatively long-lived objects such as
-        windows, views, menus, etc.</para>
+          yet); in practice, this has not yet been as much of a problem
+          as anticipated, but that may be because existing Cocoa code
+          deals primarily with relatively long-lived objects such as
+          windows, views, menus, etc.</para>
       </sect2>
 
       <sect2>
-        <title>Recommended Reading</title>
-
-        <variablelist>
-          <varlistentry>
-            <term>
-              <ulink url="http://developer.apple.com/documentation/Cocoa/">Cocoa Documentation</ulink>
-            </term>
-            
-           <listitem>
-             <para>
-               This is the top page for all of Apple's documentation on
-               Cocoa.  If you are unfamiliar with Cocoa, it is a good
-               place to start.
-             </para>
-           </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term>
-            <ulink url="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html">Foundation Reference for Objective-C</ulink>
-          </term>
-
-          <listitem>
-            <para>
-              This is one of the two most important Cocoa references; it
-              covers all of the basics, except for GUI programming.  This is
-              a reference, not a tutorial.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
+            <title>Recommended Reading</title>
+
+            <variablelist>
+              <varlistentry>
+                <term>
+                  <ulink url="http://developer.apple.com/documentation/Cocoa/">Cocoa Documentation</ulink>
+                </term>
+                
+                <listitem>
+                  <para>
+                    This is the top page for all of Apple's documentation on
+                    Cocoa.  If you are unfamiliar with Cocoa, it is a good
+                    place to start.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term>
+                  <ulink url="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html">Foundation Reference for Objective-C</ulink>
+                </term>
+
+                <listitem>
+                  <para>
+                    This is one of the two most important Cocoa references; it
+                    covers all of the basics, except for GUI programming.  This is
+                    a reference, not a tutorial.
+                  </para>
+                </listitem>
+              </varlistentry>
+        </variablelist>
       </sect2>
     </sect1>

release/1.2/source/doc/src/install.xml

@@ -15 +15 @@
   <sect1><title>Releases and System Requirements</title>
     
-    <para>There are three active versions of &CCL;.  Version 1.0 was a
-      stable release (released in late 2005); it is no longer under
-      active development.  Version 1.1 has been under active
-      development since shortly after 1.0 was released; it's been
-      distributed as a series of development "snapshots" and CVS
-      updates.  1.1 snapshots have introduced support for x86-64
-      platforms, internal use of Unicode, and many other features, but
-      have presented something of a moving target.  Version 1.2
-      (released in early 2008) is intended to be a more stable release
-      and provide a more predictable release schedule, and to make it
-      a bit easier for users who wish to track the "bleeding edge" of
-      development to do so.</para>
-
-    <para>Version 1.0 is available for three platform configurations:</para>
-    <itemizedlist>
-      <listitem>
-        <para>Linux on PowerPC (32-bit implementation)</para>
-      </listitem>
-      <listitem>
-        <para>Mac OS X on PowerPC (32-bit implementation)</para>
-      </listitem>
-      <listitem>
-        <para>Mac OS X on PowerPC (64-bit implementation)</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>Versions 1.1 and 1.2 are available for five platform
-      configurations:</para>
+    <para>Version 1.2 is the latest release of &CCL; as of April
+    2008. It is intended to be a more stable release and follow a more
+    regular release schedule than previous versions.  It is easier for
+    users who wish to track the "bleeding edge" of development to do
+    so.</para>
+
+   <para>Versions 1.2 is available for five platform
+   configurations:</para>
     <itemizedlist>
       <listitem>
@@ -61 +41 @@
     <para>A 64-bit version of &CCL; requires a 64-bit processor
       running a 64-bit OS variant.</para>
-    
+      
     <para>There are ongoing efforts to port &CCL; to the Windows
       operating system and to 32-bit x86 processors.</para>
     
-    
     <para>Additional platform-specific information is given in the
       following subsections.</para>
 
+    <para>Older versions are still available for downloading as
+    tarballs.  Version 1.0 was a stable release released in late 2005.
+    Version 1.1 was under active development until late 2007.  A final
+    1.1 release was never made.  It was distributed as a series of
+    development "snapshots" and CVS updates.  1.1 snapshots introduced
+    support for x86-64 platforms, internal use of Unicode, and many
+    other features, but were a moving target. </para>
+
     <sect2><title>LinuxPPC</title> 
       
-      <para>&CCL; versions 1.0 and later run under relatively
-        recent versions of LinuxPPC. All versions of &CCL; require
-        version 2.2.13 (or later) of the Linux kernel and version
-        2.1.3 (or later) of the GNU C library (glibc) at a bare
-        minimum.</para>
+      <para>&CCL; requires version 2.2.13 (or later) of the Linux
+      kernel and version 2.1.3 (or later) of the GNU C library (glibc)
+      at a bare minimum.</para>
     </sect2>
 
     <sect2><title>Linux X8664</title> 
 
-      <para>Version 1.1 and later of &CCL; runs on relatively recent
-        Linux distributions for the x86-64 architecture.  It requires
-        a Linux with Thread Local Storage support in the toolchain and
-        standard libraries, and the New Posix Thread Library (NPTL).
-        Fortunately, these features seem to be present in all current
-        Linux distributions for x86-64, though there may be some
-        problems with early Linux distributions for x86-64. Some GCC
-        versions older than 4.0 on Linux have been known to have
-        problems compiling some of the C code in the kernel; some very
-        old Linux distributions don't follow the current ABI standards
-        wrt segment register usage; some early Linux kernels for
-        x86-64 had problems mapping large regions of the address
-        space; and so on. It's difficult to enumerate exactly what
-        versions of what Linux distributions have what problems.  A
-        rule of thumb is that&mdash;because much of the development of
-        &CCL; for x86-64 took place in that time frame&mdash;Linux
-        distributions released earlier than early 2006 may have
-        problems running &CCL;. </para>
-    </sect2>
-
-    <sect2><title>FreeBSD-amd64</title>
-      <para>Versions 1.1 and later of &CCL; runs on FreeBSD on x86-64
-        (FreeBSD releases generally call the platform "amd64").  &CCL;
-        should run under FreeBSD 6.0 or later; as of this writing,
-        FreeBSD 7.0 is about to be released and it may be necessary
-        for FreeBSD 7 users to install the "compat6x" package in order
-        to use a version of &CCL; built on FreeBSD 6.x.</para>
+      <para>&CCL; runs on relatively recent Linux distributions for
+      the x86-64 architecture.  It requires a Linux with Thread Local
+      Storage support in the toolchain and standard libraries, and the
+      New Posix Thread Library (NPTL).  Fortunately, these features
+      seem to be present in all current Linux distributions for
+      x86-64, though there may be some problems with early Linux
+      distributions for x86-64. Some GCC versions older than 4.0 on
+      Linux have been known to have problems compiling some of the C
+      code in the kernel; some very old Linux distributions don't
+      follow the current ABI standards wrt segment register usage;
+      some early Linux kernels for x86-64 had problems mapping large
+      regions of the address space; and so on. It's difficult to
+      enumerate exactly what versions of what Linux distributions have
+      what problems.  A rule of thumb is that&mdash;because much of
+      the development of &CCL; for x86-64 took place in that time
+      frame&mdash;Linux distributions released earlier than early 2006
+      may have problems running &CCL;. </para>
+    </sect2>
+
+    <sect2><title>FreeBSD-amd64</title> <para>&CCL; runs on FreeBSD on
+    x86-64 (FreeBSD releases generally call the platform "amd64").
+    &CCL; should run under FreeBSD 6.0 or later; as of this writing,
+    FreeBSD 7.0 is about to be released and it may be necessary for
+    FreeBSD 7 users to install the "compat6x" package in order to use
+    a version of &CCL; built on FreeBSD 6.x.</para>
     </sect2>
 
     <sect2><title>DarwinPPC-MacOS-X</title>
 
-      <para> &CCL; 1.0 runs on MacOS X versions 10.2, 10.3 and
-        10.4 on the PowerPC.</para>
-
-      <para>Current development on version 1.1 and later takes place
-        under OS X versions 10.4 and 10.5 and requires at least
-        version 10.3.9</para>
+      <para> &CCL; runs under OS X versions 10.4 and 10.5 and requires
+      at least version 10.3.9</para>
 
       <para>The 64-bit DarwinPPC version of &CCL; requires
@@ -130 +109 @@
     </sect2>
 
-    <sect2><title>Darwinx8664-MacOS-X</title>
-      <para>Versions 1.1 and later of &CCL; run on 64-bit DarwinX86
-        (MacOS on Intel).</para>
+    <sect2><title>Darwinx8664-MacOS-X</title> <para>&CCL; runs on
+    64-bit DarwinX86 (Mac OS X on Intel).</para>
 
       <para>&CCL; Darwinx8664/MacOS X requires a 64-bit processor.
@@ -148 +126 @@
   <sect1><title>Obtaining Clozure CL</title>
     <para>There two main ways to obtain Clozure CL.  For Mac OS X,
-      there are disk images that can be used to install Clozure CL in
-      the usual Macintosh way. For other OSes, Subversion is the best
-      way to obtain Clozure CL, and Mac OS X users can also use
-      Subversion if they prefer to. Tarballs are available for those
-      who prefer them, but Subversion is simpler and more
-      flexible.</para>
+    there are disk images that can be used to install Clozure CL in
+    the usual Macintosh way. For other OSes, Subversion is the best
+    way to obtain Clozure CL.  Mac OS X users can also use Subversion
+    if they prefer. Tarballs are available for those who prefer them,
+    but if you have Subversion installed, it is simpler and more
+    flexible to use Subversion than tarballs.  It is easier to keep up
+    with the bleeding edge if you are using Subversion, since disk
+    images and tarballs are generated much less frequently than
+    changes to Subversion.
+    </para>
 
     <para> There are three popular ways to use Clozure CL: as a
@@ -168 +150 @@
          <ulink url="ftp://clozure.com/pub/testing/"/> </para>
 
-      <para>So that &CCL; can locate its source code (and for other
+      <para>So that &CCL; can locate its source code, and for other
         reasons explained in
-        <xref linkend="Predefined-Logical-Hosts"/>) you should either put the
+        <xref linkend="Predefined-Logical-Hosts"/>, you should either put the
         <literal>ccl</literal> directory in the same directory as the
         Clozure CL application, or else put the Clozure CL application
@@ -186 +168 @@
     <sect2><title>Getting Clozure CL with Subversion</title>
       <para>It is very easy to download, install, and build Clozure CL
-        using Subversion. Unless you're using the Mac Way, this is the
-        preferred way to get either the latest, or a specific version
-        of Clozure CL.  Subversion is a source code control system
-        that is in wide usage.  Most modern OSes come with subversion
-        pre-installed. A complete, buildable and runnable set of
-        Clozure CL sources and binaries can be retrieved by doing one
-        subversion checkout.</para>
-
-      <para>First, make sure that Subversion is installed on your
-        system.  Bring up a command line shell and type:
+      using Subversion. This is the preferred way to get either the
+      latest, or a specific version of Clozure CL, unless you prefer
+      the Mac Way.  Subversion is a source code control system that is
+      in wide usage.  Most modern OSes come with subversion
+      pre-installed. A complete, buildable and runnable set of Clozure
+      CL sources and binaries can be retrieved by doing one subversion
+      checkout.</para>
+
+
+      <para>One subversion command will create a
+      <literal>ccl</literal> directory with runnable binaries, and a
+      complete set of buildable sources.  To get the bleeding edge
+      Clozure CL for Darwin x8664, at the command line type:</para>
+
+        <programlisting>
+          <![CDATA[
+svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx8664/ccl]]>
+        </programlisting>
+
+        <para>To get the 1.2 version of Clozure CL type:</para>
+        <programlisting>
+          <![CDATA[
+svn co http://svn.clozure.com/publicsvn/openmcl/releases/1.2/darwinx8664/ccl]]>
+        </programlisting>
+
+        
+        <para>These examples fetch the complete sources and binaries
+        for the Darwin X8664 build of &CCL;. You can fetch a different
+        version by substituting its name in place of
+        "darwinx8664". Current available versions are:</para>
+
+        <itemizedlist>
+          <listitem><para>darwinppc</para></listitem>
+          <listitem><para>darwinx8664</para></listitem>
+          <listitem><para>freebsdx8664</para></listitem>
+          <listitem><para>linuxppc</para></listitem>
+          <listitem><para>linuxx8664</para></listitem>
+        </itemizedlist>
+
+        <para>These distributions contain complete sources and
+        binaries. They use Subversion's "externals" features to share
+        common sources; the majority of source code is the same across
+        all versions.</para> 
+
+        <para>Once the checkout is complete you can build Clozure CL by
+        running the lisp kernel and executing
+        the <literal>rebuild-ccl</literal> function. For
+        example:</para>
+
+        <programlisting>
+          <![CDATA[
+joe:ccl> ./dx86cl64
+Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
+? (rebuild-ccl :full t)
+<lots of compilation output>
+  ? (quit)
+  joe:ccl>]]>
+        </programlisting>
+        <sect3 id="Checking-Subversion-Installation"><title>Checking Subversion Installation</title>
+      <para>If <literal>svn co</literal> doesn't work, then make sure
+      that Subversion is installed on your system.  Bring up a command
+      line shell and type:
         <programlisting>
           <![CDATA[
@@ -215 +249 @@
         obtaining and installing Subversion at
         the <ulink url="http://subversion.tigris.org/project_packages.html">Subversion
-        Packages page</ulink>.</para>
-
-      <para>Create the directory where Clozure CL will live, <literal>cd</literal> to that directory, then type a Subversion checkout command.  For example:</para>
-
-        <programlisting>
-          <![CDATA[
-joe:~> mkdir ccl
-joe:~> cd ccl
-joe:ccl> svn co http://svn.clozure.com/publicsvn/openmcl/trunk/darwinx8664]]>
-        </programlisting>
-        
-        <para>This example fetches the complete sources and binaries
-        for the Darwin X8664 build of &CCL;. You can fetch a different
-        version by substituting its name in place of
-        "darwinx8664". Current available versions are:</para>
-
-        <itemizedlist>
-          <listitem><para>darwinppc</para></listitem>
-          <listitem><para>darwinx8664</para></listitem>
-          <listitem><para>freebsdx8664</para></listitem>
-          <listitem><para>linuxppc</para></listitem>
-          <listitem><para>linuxx8664</para></listitem>
-        </itemizedlist>
-
-        <para>These distributions contain complete sources and
-        binaries. They use Subversion's "externals" features to share
-        common sources; the majority of source code is the same across
-        all versions.</para>
-
-        <para>Once the checkout is complete you can build Clozure CL by
-        running the lisp kernel and executing
-        the <literal>rebuild-ccl</literal> function. For
-        example:</para>
-
-        <programlisting>
-          <![CDATA[
-joe:ccl> ./dx86cl64
-Welcome to Clozure Common Lisp Version 1.2  (DarwinX8664)!
-? (rebuild-ccl :full t)
-<lots of compilation output>
-  ? (quit)
-  joe:ccl>]]>
-        </programlisting>
+        Packages page</ulink>.</para></sect3>
+
     </sect2>
 
     <sect2><title>Tarballs</title>
-      <para>Tarballs are available at
-                                         <ulink url="ftp://clozure.com/pub/testing/"/>.
-                                         Download and extract one on
-                                         your local disk.  Then edit
-                                         the &CCL; shell script to set
-                                         the value of
-        <varname>CCL_DEFAULT_DIRECTORY</varname> and start up the
-        appropriate Clozure CL kernel. See
-        <xref linkend="The-ccl-Shell-Script"/> for more
-        information about the &CCL; shell scripts.</para>
+      <para>Tarballs are available at <ulink
+      url="ftp://clozure.com/pub/testing/"/>.  Download and extract
+      one on your local disk.  Then edit the &CCL; shell script to set
+      the value of <varname>CCL_DEFAULT_DIRECTORY</varname> and start
+      up the appropriate Clozure CL kernel. See <xref
+      linkend="The-ccl-Shell-Script"/> for more information about the
+      &CCL; shell scripts.</para>
     </sect2>
   </sect1>
@@ -307 +297 @@
       <para>To use the script:</para>
       <orderedlist>
+        <listitem>
+          <para>Copy the script to a directory that is on your
+          <varname>PATH</varname>.  This is often
+          <literal>/usr/local/bin</literal> or
+          <literal>~/bin</literal>.  It is better to do this than to
+          add <literal>ccl/scripts</literal> to your
+          <varname>PATH</varname> since the script needs to be edited,
+          it will show up as modified to Subversion.</para>
+        </listitem>
         <listitem>
           <para>Edit the definition of
@@ -346 +345 @@
           </warning></para>
         </listitem>
-        <listitem>
-          <para>Install the shell script somewhere on your shell's
-            search path, or add the location of the shell script to
-            your <literal>PATH</literal> environment variable.</para>
-        </listitem>
       </orderedlist>
+
+      <para>Note that most people won't need both
+      <literal>ccl</literal> and <literal>ccl64</literal> scripts.
+      You only need both if you sometimes run 32-bit Clozure CL and
+      sometimes run 64-bit Clozure CL.  You can rename the script that
+      you use to whatever you want.  For example, if you are on a
+      64-bit system, and you only use Clozure CL in 64-bit mode, then
+      you can rename <literal>ccl64</literal> to
+      <literal>ccl</literal> so that you only need to type
+      "<literal>ccl</literal>" to run it.</para>
 
       <para>Once this is done, it should be possible to invoke &CCL;
@@ -358 +362 @@
       <programlisting>
 &gt; ccl [args ...]
-Welcome to &CCL; Version whatever (DarwinPPC32)!
+Welcome to &CCL; Version 1.2 (DarwinPPC32)!
 ?
       </programlisting>
+      
       <para>The ccl shell script passes all of its arguments to the
-        &CCL; kernel.  See <xref linkend="Invocation"/> for more
-        information about these arguments.  When invoked this way, the
-        Lisp should be able to initialize the
-        <literal>"ccl:"</literal> logical host so that its
-        translations refer to the <literal>"ccl"</literal>
-        directory. To test this, you can call
-        <literal>probe-file</literal> in &CCL;'s read-eval-print
-        loop:</para>
+      &CCL; kernel.  See <xref linkend="Invocation"/> for more
+      information about these arguments.  When invoked this way, the
+      Lisp should be able to initialize the <literal>"ccl:"</literal>
+      logical host so that its translations refer to the
+      <literal>"ccl"</literal> directory. To test this, you can call
+      <literal>probe-file</literal> in &CCL;'s read-eval-print
+      loop:</para>
       <programlisting>
 ? (probe-file "ccl:level-1;level-1.lisp")  ;returns the physical pathname of the file
@@ -736 +740 @@
   <sect1 id="Example-Programs">
     <title>Example Programs</title>
-    <para>Beginning with release 0.9, a number (ok, a
-      <emphasis>small</emphasis> number, at least initially) of
-      example programs are distributed in the "ccl:examples;"
-      directory of the source distribution. See the
-      README-OPENMCL-EXAMPLES text file in that directory for
-      information about prerequisites and usage.</para>
+    <para>A number (ok, a <emphasis>small</emphasis> number), of
+    example programs are distributed in the "ccl:examples;" directory
+    of the source distribution. See the README-OPENMCL-EXAMPLES text
+    file in that directory for information about prerequisites and
+    usage.</para>
     <para>Some of the example programs are derived from C examples
       in textbooks, etc.; in those cases, the original author and work

release/1.2/source/doc/src/modifying.xml

@@ -1 +1 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY rest "<varname>&amp;rest</varname>">
-<!ENTITY key "<varname>&amp;key</varname>">
-<!ENTITY optional "<varname>&amp;optional</varname>">
-<!ENTITY body "<varname>&amp;body</varname>">
-<!ENTITY aux "<varname>&amp;aux</varname>">
-<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
-<!ENTITY CCL "Clozure CL">
-]>
-
-  <chapter id="Modifying-CCL">
-    <title>Modifying &CCL;</title>
-
-    <sect1 id="Contributing-Code-Back-to-the-CCL-Project">
-      <title>Contributing Code Back to the &CCL; Project</title>
-      <para>This section is a placeholder, added as of August 2004.  The
+          <!ENTITY rest "<varname>&amp;rest</varname>">
+          <!ENTITY key "<varname>&amp;key</varname>">
+          <!ENTITY optional "<varname>&amp;optional</varname>">
+          <!ENTITY body "<varname>&amp;body</varname>">
+          <!ENTITY aux "<varname>&amp;aux</varname>">
+          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
+          <!ENTITY CCL "Clozure CL">
+          ]>
+
+<chapter id="Modifying-CCL">
+  <title>Modifying &CCL;</title>
+
+  <sect1 id="Contributing-Code-Back-to-the-CCL-Project">
+    <title>Contributing Code Back to the &CCL; Project</title>
+    <para>This section is a placeholder, added as of August 2004.  The
       full text is being written, and will be added as soon as it is
       available.</para>
-    </sect1>
-
-    <sect1 id="Using-CCL-in--development--and-in--user--mode">
-      <title>Using &CCL; in "development" and in  "user" mode</title>
-
-      <para>As it's distributed, &CCL; starts up with *PACKAGE* set
-      to the CL-USER package and with most predefined functions and
+  </sect1>
+
+  <sect1 id="Using-CCL-in--development--and-in--user--mode">
+    <title>Using &CCL; in "development" and in  "user" mode</title>
+
+    <para>As it's distributed, &CCL; starts up with *PACKAGE* set to
+      the CL-USER package and with most predefined functions and
       methods protected against accidental redefinition.  The package
-      setting is of course a requirement of ANSI CL, while the
-      protection protection is intended to catch certain types of
-      programming errors (accidentally redefining a CL or CCL
-      function) before those errors have a chance to do much
-      damage.</para>
-      <para>These settings may make using &CCL; to develop &CCL; a
-      bit more awkward, since much of that process assumes that the
-      CCL package is current (and a primary purpose of that process is
-      to redefine some "predefined, builtin functions".) The standard,
-      "routine" ways of building &CCL; from sources (see ) -
-      COMPILE-CCL, XCOMPILE-CCL, and XLOAD-LEVEL-0 - bind *PACKAGE* to
-      the "CCL" package and enable the redefinition of predefined
-      functions; the symbols COMPILE-CCL, XCOMPILE-CCL, and
+      setting is of course a requirement of ANSI CL, and the
+      protection of predifined functions and methods is intended to
+      catch certain types of programming errors (accidentally
+      redefining a CL or CCL function) before those errors have a
+      chance to do much damage.</para>
+    <para>These settings may make using &CCL; to develop &CCL; a bit
+      awkward, because much of that process assumes you are working in
+      the CCL package is current, and a primary purpose of &CCL;
+      development is to redefine some predefined, builtin functions.
+      The standard, "routine" ways of building &CCL; from sources (see
+      ) - COMPILE-CCL, XCOMPILE-CCL, and XLOAD-LEVEL-0 - bind
+      *PACKAGE* to the "CCL" package and enable the redefinition of
+      predefined functions; the symbols COMPILE-CCL, XCOMPILE-CCL, and
       XLOAD-LEVEL-0 are additionally now exported from the "CCL"
       package.</para>
-      <para>Some other (more ad-hoc) ways of doing development on
-      &CCL; - compiling and/or loading individual files,
-      incrementally redefining individual functions - may be awkward
-      unless one reverts to the mode of operation which was
-      traditionally offered in &CCL;. (Some &CCL; source files -
+    <para>Some other (more ad-hoc) ways of doing development on
+      &CCL;&mdash;compiling and/or loading individual files,
+      incrementally redefining individual functions&mdash;may be
+      awkward unless one reverts to the mode of operation which was
+      traditionally offered in &CCL;. Some &CCL; source files -
       especially those that comprise the bootstrapping image sources
       and the first few files in the "cold load" sequence - are
       compiled and loaded in the "CCL" package but don't contain
       (IN-PACKAGE "CCL") forms, since IN-PACKAGE doesn't work until
-      later in the cold load sequence.)</para>
-      <para>The somewhat bizarre behavior of both SET-USER-ENVIRONMENT
+      later in the cold load sequence.</para>
+    <para>The somewhat bizarre behavior of both SET-USER-ENVIRONMENT
       and SET-DEVELOPMENT-ENVIRONMENT with respect to the special
       variables they affect is intended to allow those constructs to
@@ -59 +59 @@
       though using both constructs within the same LOAD call would
       likely be pretty confusing.</para>
-      <para>"user" and "development" are otherwise very generic terms;
+    <para>"user" and "development" are otherwise very generic terms;
       here they're intended to enforce the distinction between "using"
       &CCL; and "developing" it.</para>
-      <para>The initial environment from which &CCL; images are
+    <para>The initial environment from which &CCL; images are
       saved is one where (SET-USER-ENVIRONMENT T) has just been
       called; in previous versions, it was effectively as if
       (SET-DEVELOPMENT-ENVIRONMENT T) had just been called.</para>
-      <para>Hopefully, most users of &CCL; can safely ignore these
+    <para>Hopefully, most users of &CCL; can safely ignore these
       issues most of the time. Note that doing (SET-USER-ENVIRONMENT
       T) after loading one's own code (or 3rd-party code) into &CCL;
       would protect that code (as well as &CCL;'s) from accidental
       redefinition; that may be useful in some cases.</para>
-    </sect1>
-
-    <sect1 id="kernel-debugger">
-      <title>The Kernel Debugger</title>
-      <para> In a perfect world, something like this couldn't
+  </sect1>
+
+  <sect1 id="kernel-debugger">
+    <title>The Kernel Debugger</title>
+    <para> In a perfect world, something like this couldn't
       happen:</para>
-      <programlisting>
+    <programlisting>
 Welcome to &CCL; Version x.y!
 ? (defun foo (x)
@@ -87 +87 @@
 Unhandled exception 11 at 0x300e90c8, context->regs at #x7ffff6b8
 Continue/Debugger/eXit &lt;enter&gt;?
-</programlisting>
-
-      <para>As you may have noticed, it's not a perfect world; it's rare
-        that the cause (attempting to reference the CDR of -1, and therefore
-        accessing unmapped memory near location 0) of this effect (an
-        "Unhandled exception ..." message) is so obvious.</para>
-      <para>The addresses printed in the message above aren't very useful
-        unless you're debugging the kernel with GDB (and they're often
-        very useful if you are.)</para>
-      <para>Aside from causing an exception that the lisp kernel doesn't
-        know how to handle, one can also enter the kernel debugger (more)
-        deliberately:</para>
-
-      <programlisting>
+    </programlisting>
+
+    <para>As you may have noticed, it's not a perfect world; it's rare
+      that the cause (attempting to reference the CDR of -1, and therefore
+      accessing unmapped memory near location 0) of this effect (an
+      "Unhandled exception ..." message) is so obvious.</para>
+    <para>The addresses printed in the message above aren't very useful
+      unless you're debugging the kernel with GDB (and they're often
+      very useful if you are.)</para>
+    <para>Aside from causing an exception that the lisp kernel doesn't
+      know how to handle, one can also enter the kernel debugger (more)
+      deliberately:</para>
+
+    <programlisting>
 ? (defun classify (n)
-     (cond ((&gt; n 0) "Greater")
-           ((&lt; n 0) "Less")
-           (t
-            ;;; Sheesh ! What else could it be ?
-            (ccl::bug "I give up. How could this happen ?"))))
+    (cond ((&gt; n 0) "Greater")
+          ((&lt; n 0) "Less")
+          (t
+           ;; Sheesh ! What else could it be ?
+           (ccl::bug "I give up. How could this happen ?"))))
 CLASSIFY
 
@@ -114 +114 @@
 ? for help
 [12345] &CCL; kernel debugger:
-      </programlisting>
-
-      <para>CCL::BUG isn't quite the right tool for this example (a
-        call to BREAK or PRINT might do a better job of clearing up the
-        mystery), but it's sometimes helpful when those other tools
-        can't be used.  The lisp error system notices, for instance, if
-        attempts to signal errors themselves cause errors to be
-        signaled; this sort of thing can happen if CLOS or the I/O
-        system are broken or missing. After some small number of
-        recursive errors, the error system gives up and calls
-        CCL::BUG.</para>
-      <para>If one enters a '?' at the kernel debugger prompt, one
-        will see output like:</para>
-
-      <programlisting>
+    </programlisting>
+
+    <para>CCL::BUG isn't quite the right tool for this example (a
+      call to BREAK or PRINT might do a better job of clearing up the
+      mystery), but it's sometimes helpful when those other tools
+      can't be used.  The lisp error system notices, for instance, if
+      attempts to signal errors themselves cause errors to be
+      signaled; this sort of thing can happen if CLOS or the I/O
+      system are broken or missing. After some small number of
+      recursive errors, the error system gives up and calls
+      CCL::BUG.</para>
+    <para>If one enters a '?' at the kernel debugger prompt, one
+      will see output like:</para>
+
+    <programlisting>
 (S)  Find and describe symbol matching specified name
 (B)  Show backtrace
@@ -134 +134 @@
 (K)  Kill &CCL; process
 (?)  Show this help
-      </programlisting>
-
-      <para>CCL::BUG just does an FF-CALL into the lisp kernel.  If
-        the kernel debugger was invoked because of an unhandled
-        exception (such as an illegal memory reference) the OS kernel
-        saves the machine state ("context") in a data structure for us,
-        and in that case some additional options can be used to display
-        the contents of the registers at the point of the
-        exception. Another function - CCL::DBG - causes a special
-        exception to be generated and enters the lisp kernel debugger
-        with a non-null "context":</para>
-
-      <programlisting>
+    </programlisting>
+
+    <para>CCL::BUG just does an FF-CALL into the lisp kernel.  If
+      the kernel debugger was invoked because of an unhandled
+      exception (such as an illegal memory reference) the OS kernel
+      saves the machine state ("context") in a data structure for us,
+      and in that case some additional options can be used to display
+      the contents of the registers at the point of the
+      exception. Another function&mdash;CCL::DBG&mdash;causes a special
+      exception to be generated and enters the lisp kernel debugger
+      with a non-null "context":</para>
+
+    <programlisting>
 ? (defun classify2 (n)
-  (cond ((&gt; n 0) "Greater")
-        ((&lt; n 0) "Less")
-        (t (dbg n))))
+    (cond ((&gt; n 0) "Greater")
+          ((&lt; n 0) "Less")
+          (t (dbg n))))
 CLASSIFY2
 
 ? (classify2 0)
 Lisp Breakpoint
- While executing: #&lt;Function CLASSIFY2 #x08476cfe>
+While executing: #&lt;Function CLASSIFY2 #x08476cfe>
 ? for help
 [12345] &CCL; kernel debugger: ?
@@ -170 +170 @@
 (K)  Kill &CCL; process
 (?)  Show this help
-</programlisting>
-
-      <para>CCL::DBG takes an argument, whose value is copied into the register
-        that &CCL; uses to return a function's primary value (arg_z, which
-        is r23 on the PowerPC). If we were to choose the (L) option at this point,
-        we'd see a dislay like:</para>
-
-      <programlisting>
+    </programlisting>
+
+    <para>CCL::DBG takes an argument, whose value is copied into the register
+      that &CCL; uses to return a function's primary value (arg_z, which
+      is r23 on the PowerPC). If we were to choose the (L) option at this point,
+      we'd see a dislay like:</para>
+
+    <programlisting>
 rnil = 0x01836015
 nargs = 0
@@ -196 +196 @@
 r25 (save6) = ()
 r24 (save7) = ()
-      </programlisting>
-
-      <para>From this we can conclude that the problematic argument to CLASSIFY2
-        was 0 (see r23/arg_z), and that I need to work on a better example.</para>
-      <para>The R option shows the values of the ALU (and PPC branch unit)
-        registers in hex; the F option shows the values of the FPU registers.</para>
-      <para>The (B) option shows a raw stack backtrace; it'll try to
-        identify foreign functions as well as lisp functions. (Foreign function
-        names are guesses based on the nearest preceding exported symbol.)</para>
-      <para>If you ever unexpectedly find yourself in the "lisp kernel
-        debugger", the output of the (L) and (B) options are often the most
-        helpful things to include in a bug report.</para>
-    </sect1>
-
-    <sect1 id="Using-AltiVec-in-CCL-LAP-functions">
-      <title>Using AltiVec in &CCL; LAP functions</title>
-
-      <sect2 id="Overview--16-">
-        <title>Overview</title>
-    <para>It's now possible to use AltiVec instructions in PPC LAP
-      (assembler) functions.</para>
-    <para>The lisp kernel detects the presence or absence of
-      AltiVec and preserves AltiVec state on lisp thread switch and
-      in response to exceptions, but the implementation doesn't
-      otherwise use vector operations.</para>
-    <para>This document doesn't document PPC LAP programming in
-      general.  Ideally, there would be some document that
-      did.</para>
-    <para>This document does explain AltiVec register-usage
-      conventions in &CCL; and explains the use of some lap macros
-      that help to enforce those conventions.</para>
-    <para>All of the global symbols described below are exported
-      from the CCL package. Note that lap macro names, ppc
-      instruction names, and (in most cases) register names are
-      treated as strings, so this only applies to functions and
-      global variable names.</para>
-    <para>Much of the &CCL; support for AltiVec LAP programming
-      is based on work contributed to MCL by Shannon Spires.</para>
-      </sect2>
-
-      <sect2 id="Register-usage-conventions">
-        <title>Register usage conventions</title>
-    <para>&CCL; LAP functions that use AltiVec instructions must
-      interoperate with each other and with C functions; that
-      suggests that they follow C AltiVec register usage
-      conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
-      value, vr14-vr19 temporaries, vr20-vr31 callee-save
-      non-volatile registers.)</para>
-    <para>The EABI (Embedded Application Binary Interface) used in
-      LinuxPPC doesn't ascribe particular significance to the vrsave
-      special-purpose register; on other platforms (notably MacOS),
-      it's used as a bitmap which indicates to system-level code
-      which vector registers contain meaningful values.</para>
-    <para>The WITH-ALTIVEC-REGISTERS lapmacro generates code which
-      which saves, updates, and restores VRSAVE on platforms where
-      this is required (as indicated by the value of the special
-      variable which controls this) and ignores VRSAVE on platforms
-      that don't require it to be maintained.</para>
-    <para>On all PPC platforms, it's necessary to save any non-volatile
-      vector registers (vr20 .. vr31) before assigning to them and to restore
-      such registers before returning to the caller.</para>
-    <para>On platforms that require that VRSAVE be maintained, it's not
-      necessary to mention the "use" of vector registers that are
-      used as incoming parameters. It's not incorrect to mention their use
-      in a WITH-ALTIVEC-REGISTERS form, but it may be unnecessary in many
-      interesting cases. One can likewise assume that the caller of any function
-      that returns a vector value (in vr2 has already set the appropriate bit in
-      VRSAVE to indicate that this register is live. One could therefore write a
-      leaf function that added the bytes in vr3 and vr2 and returned the result
-      in vr2 as:</para>
-
-        <programlisting>
+    </programlisting>
+
+    <para>From this we can conclude that the problematic argument to CLASSIFY2
+      was 0 (see r23/arg_z), and that I need to work on a better example.</para>
+    <para>The R option shows the values of the ALU (and PPC branch unit)
+      registers in hex; the F option shows the values of the FPU registers.</para>
+    <para>The (B) option shows a raw stack backtrace; it'll try to
+      identify foreign functions as well as lisp functions. (Foreign function
+      names are guesses based on the nearest preceding exported symbol.)</para>
+    <para>If you ever unexpectedly find yourself in the "lisp kernel
+      debugger", the output of the (L) and (B) options are often the most
+      helpful things to include in a bug report.</para>
+  </sect1>
+
+  <sect1 id="Using-AltiVec-in-CCL-LAP-functions">
+    <title>Using AltiVec in &CCL; LAP functions</title>
+
+    <sect2 id="Overview--16-">
+          <title>Overview</title>
+      <para>It's now possible to use AltiVec instructions in PPC LAP
+        (assembler) functions.</para>
+      <para>The lisp kernel detects the presence or absence of
+        AltiVec and preserves AltiVec state on lisp thread switch and
+        in response to exceptions, but the implementation doesn't
+        otherwise use vector operations.</para>
+      <para>This document doesn't document PPC LAP programming in
+        general.  Ideally, there would be some document that
+        did.</para>
+      <para>This document does explain AltiVec register-usage
+        conventions in &CCL; and explains the use of some lap macros
+        that help to enforce those conventions.</para>
+      <para>All of the global symbols described below are exported
+        from the CCL package. Note that lap macro names, ppc
+        instruction names, and (in most cases) register names are
+        treated as strings, so this only applies to functions and
+        global variable names.</para>
+      <para>Much of the &CCL; support for AltiVec LAP programming
+        is based on work contributed to MCL by Shannon Spires.</para>
+    </sect2>
+
+    <sect2 id="Register-usage-conventions">
+          <title>Register usage conventions</title>
+      <para>&CCL; LAP functions that use AltiVec instructions must
+        interoperate with each other and with C functions; that fact
+        suggests that they follow C AltiVec register usage
+        conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return
+        value, vr14-vr19 temporaries, vr20-vr31 callee-save
+        non-volatile registers.)</para>
+      <para>The EABI (Embedded Application Binary Interface) used in
+        LinuxPPC doesn't ascribe particular significance to the vrsave
+        special-purpose register; on other platforms (notably MacOS),
+        it's used as a bitmap which indicates to system-level code
+        which vector registers contain meaningful values.</para>
+      <para>The WITH-ALTIVEC-REGISTERS lap macro generates code that
+        saves, updates, and restores VRSAVE on platforms where this is
+        required (as indicated by the value of the special variable
+        that controls this behavior) and ignores VRSAVE on platforms
+        that don't require it to be maintained.</para>
+      <para>On all PPC platforms, it's necessary to save any non-volatile
+        vector registers (vr20 .. vr31) before assigning to them and to restore
+        such registers before returning to the caller.</para>
+      <para>On platforms that require that VRSAVE be maintained, it's
+        not necessary to mention the "use" of vector registers that
+        are used as incoming parameters. It's not incorrect to mention
+        their use in a WITH-ALTIVEC-REGISTERS form, but it may be
+        unnecessary in many interesting cases. One can likewise assume
+        that the caller of any function that returns a vector value in
+        vr2 has already set the appropriate bit in VRSAVE to indicate
+        that this register is live. One could therefore write a leaf
+        function that added the bytes in vr3 and vr2 and returned the
+        result in vr2 as:</para>
+
+      <programlisting>
 (defppclapfunction vaddubs ((y vr3) (z vr2))
   (vaddubs z y z)
   (blr))
-</programlisting>
-
-        <para>When vector registers that aren't incoming parameters are used
-          in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
-          and of saving/restoring any non-volatile vector registers:</para>
-
-        <programlisting>
+      </programlisting>
+
+      <para>When vector registers that aren't incoming parameters are used
+        in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE
+        and of saving/restoring any non-volatile vector registers:</para>
+
+      <programlisting>
 (defppclapfunction load-array ((n arg_z))
   (check-nargs 1)
   (with-altivec-registers (vr1 vr2 vr3 vr27) ; Clobbers imm0
     (li imm0 arch::misc-data-offset)
-    (lvx vr1 arg_z imm0) ; load MSQ
-    (lvsl vr27 arg_z imm0) ; set the permute vector
-    (addi imm0 imm0 16) ; address of LSQ
-    (lvx vr2 arg_z imm0) ; load LSQ
-    (vperm vr3 vr1 vr2 vr27) ; aligned result appears in VR3
-    (dbg t)) ; Look at result in some debugger
+    (lvx vr1 arg_z imm0)                ; load MSQ
+    (lvsl vr27 arg_z imm0)              ; set the permute vector
+    (addi imm0 imm0 16)                 ; address of LSQ
+    (lvx vr2 arg_z imm0)                ; load LSQ
+    (vperm vr3 vr1 vr2 vr27)           ; aligned result appears in VR3
+    (dbg t))                         ; Look at result in some debugger
   (blr))
-        </programlisting>
-
-        <para>AltiVec registers are not preserved by CATCH and UNWIND-PROTECT.
-          Since AltiVec is only accessible from LAP in &CCL; and since LAP
-          functions rarely use high- level control structures, this should rarely be
-          a problem in practice.</para>
-        <para>LAP functions which use non-volatile vector registers and which call
-          (Lisp ?) code which may use CATCH or UNWIND-PROTECT should save those
-          vector registers before such a call and restore them on return. This is
-          one of the intended uses of the WITH-VECTOR-BUFFER lap macro.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 id="Development-Mode-Dictionary">
-      <title>Development-Mode Dictionary</title>
-
-      <refentry id="v_warn-if-redefine-kernel">
-            <indexterm zone="v_warn-if-redefine-kernel">
-              <primary>*warn-if-redefine-kernel</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
-              <refpurpose></refpurpose>
-              <refclass>Variable</refclass>
-            </refnamediv>
-
-            <refsect1>
-              <title>Description</title>
-
-              <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
-                functions and methods that are marked as being
-                &#34;predefined&#34; signal continuable errors.</para>
-
-              <para>Note that these are CERRORs, not warnings, and that
-                no lisp functions or methods have been defined in the kernel
-                in MCL or &CCL; since 1987 or so.</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="f_set-development-environment">
-            <indexterm zone="f_set-development-environment">
-              <primary>set-development-environment</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
-              <refpurpose></refpurpose>
-              <refclass>Function</refclass>
-            </refnamediv>
-
-            <refsynopsisdiv>
-              <synopsis><function>set-development-environment</function>
-                &optional;
-                unmark-builtin-functions</synopsis>
-            </refsynopsisdiv>
-
-            <refsect1>
-              <title>Description</title>
-
-              <para>Arranges that the outermost special bindings of *PACKAGE*
-                and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
-                package and NIL to these variables, respectively. If the optional
-                argument is true, marks all globally defined functions and methods
-                as being &#34;not predefined&#34; (this is a fairly expensive
-                operation.)</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="f_set-user-environment">
-            <indexterm zone="f_set-user-environment">
-              <primary>set-user-environment</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>SET-USER-ENVIRONMENT</refname>
-              <refpurpose></refpurpose>
-              <refclass>Function</refclass>
-            </refnamediv>
-
-            <refsynopsisdiv>
-              <synopsis><function>set-user-environment</function>
-                &optional; mark-builtin-functions</synopsis>
-            </refsynopsisdiv>
-
-            <refsect1>
-              <title>Description</title>
-
-              <para>Arranges that the outermost special bindings of *PACKAGE*
-                and *WARN-IF-REDEFINE-KERNEL* restore values of the
-                &#34;CL-USER&#34; package and T to these variables, respectively.
-                If the optional argument is true, marks all globally defined
-                functions and methods as being &#34;predefined&#34; (this is a
-                fairly expensive operation.)</para>
-            </refsect1>
-      </refentry>
-      <refentry id="v_altivec-available">
-            <indexterm zone="v_altivec-available">
-              <primary>*altivec-available*</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>*ALTIVEC-AVAILABLE*</refname>
-              <refpurpose></refpurpose>
-              <refclass>Variable</refclass>
-            </refnamediv>
-
-            <refsect1>
-              <title>Description</title>
-              <para>This variable is initialized each time an &CCL; session
-                starts based on information provided by the lisp kernel. Its value
-                is true if AltiVec is present and false otherwise. This variable
-                shouldn't be set by user code.</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="f_altivec-available-p">
-            <indexterm zone="f_altivec-available-p">
-              <primary>altivec-available-p</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>ALTIVEC-AVAILABLE-P</refname>
-              <refpurpose></refpurpose>
-              <refclass>Function</refclass>
-            </refnamediv>
-            
-            <refsynopsisdiv>
-              <synopsis><function>altivec-available-p</function></synopsis>
-            </refsynopsisdiv>
-
-            <refsect1>
-              <title>Description</title>
-
-              <para>Returns non-NIL if AltiVec is available.</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="v_altivec-lapmacros-maintain-vrsave-p">
-            <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
-              <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
-              <refpurpose></refpurpose>
-              <refclass>Variable</refclass>
-            </refnamediv>
-            
-            <refsect1>
-              <title>Description</title>
-
-              <para>Intended to control the expansion of certain lap macros.
-                Initialized to NIL on LinuxPPC; initialized to T on platforms
-                (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
-                a bitmask of active vector registers at all times.</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="lapm_with-altivec-registers">
-            <indexterm zone="lapm_with-altivec-registers">
-              <primary>with-altivec-registers</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>WITH-ALTIVEC-REGISTERS</refname>
-              <refpurpose></refpurpose>
-              <refclass>LAP Macro</refclass>
-            </refnamediv>
-
-            <refsynopsisdiv>
-              <synopsis><function>with-altivec-registers</function>
-                reglist &body; body</synopsis>
-            </refsynopsisdiv>
-
-            <refsect1>
-              <title>Arguments and Values</title>
-
-              <variablelist>
-                <varlistentry>
-                  <term>reglist</term>
-
-                  <listitem>
-                        <para>A list of vector register names (vr0 .. vr31).</para>
-                  </listitem>
-                </varlistentry>
-
-                <varlistentry>
-                  <term>body</term>
-
-                  <listitem>
-                        <para>A sequence of PPC LAP instructions.</para>
-                  </listitem>
-                </varlistentry>
-              </variablelist>
-            </refsect1>
-
-            <refsect1>
-              <title>Description</title>
-
-              <para>Specifies the set of AltiVec registers used in body. If
-                *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
-                expanded, generates code to save the VRSAVE SPR and updates VRSAVE
-                to include a bitmask generated from the specified register list.
-                Generates code which saves any non-volatile vector registers which
-                appear in the register list, executes body, and restores the saved
-                non-volatile vector registers (and, if
-                *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
-                well. Uses the IMM0 register (r3) as a temporary.</para>
-            </refsect1>
-      </refentry>
-
-      <refentry id="lapm_with-vector-buffer">
-            <indexterm zone="lapm_with-vector-buffer">
-              <primary>with-vector-buffer</primary>
-            </indexterm>
-
-            <refnamediv>
-              <refname>WITH-VECTOR-BUFFER</refname>
-              <refpurpose></refpurpose>
-              <refclass>LAP Macro</refclass>
-            </refnamediv>
-            
-            <refsynopsisdiv>
-              <synopsis>with-vector-buffer base n &body; body</synopsis>
-            </refsynopsisdiv>
-
-            <refsect1>
-              <title>Arguments and Values</title>
-
-              <variablelist>
-                <varlistentry>
-                  <term>base</term>
-
-                  <listitem>
-                        <para>Any available general-purpose register.</para>
-                  </listitem>
-                </varlistentry>
-
-                <varlistentry>
-                  <term>n</term>
-
-                  <listitem>
-                        <para>An integer between 1 and 254, inclusive. (Should
-                          typically be much, much closer to 1.) Specifies the size of
-                          the buffer, in 16-byte units.</para>
-                  </listitem>
-                </varlistentry>
-
-                <varlistentry>
-                  <term>body</term>
-
-                  <listitem>
-                        <para>A sequence of PPC LAP instructions.</para>
-                  </listitem>
-                </varlistentry>
-              </variablelist>
-            </refsect1>
-
-            <refsect1>
-              <title>Description</title>
-              <para>Generates code which allocates a 16-byte aligned buffer
-                large enough to contain N vector registers; the GPR base points to
-                the lowest address of this buffer. After processing body, the
-                buffer will be deallocated. The body should preserve the value of
-                base as long as it needs to reference the buffer. It's
-                intended that base be used as a base register in stvx and lvx
-                instructions within the body.</para>
-            </refsect1>
-      </refentry>
-    </sect1>
-  </chapter>
+      </programlisting>
+
+      <para>AltiVec registers are not preserved by CATCH and UNWIND-PROTECT.
+        Since AltiVec is only accessible from LAP in &CCL; and since LAP
+        functions rarely use high-level control structures, this should rarely be
+        a problem in practice.</para>
+      <para>LAP functions that use non-volatile vector registers and
+        that call (Lisp ?) code which may use CATCH or UNWIND-PROTECT
+        should save those vector registers before such a call and
+        restore them on return. This is one of the intended uses of
+        the WITH-VECTOR-BUFFER lap macro.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="Development-Mode-Dictionary">
+    <title>Development-Mode Dictionary</title>
+
+    <refentry id="v_warn-if-redefine-kernel">
+          <indexterm zone="v_warn-if-redefine-kernel">
+            <primary>*warn-if-redefine-kernel</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>*WARN-IF-REDEFINE-KERNEL*</refname>
+            <refpurpose></refpurpose>
+            <refclass>Variable</refclass>
+          </refnamediv>
+
+          <refsect1>
+            <title>Description</title>
+
+            <para>When true, attempts to redefine (via DEFUN or DEFMETHOD)
+              functions and methods that are marked as being
+              &#34;predefined&#34; signal continuable errors.</para>
+
+            <para>Note that these are CERRORs, not warnings, and that
+              no lisp functions or methods have been defined in the kernel
+              in MCL or &CCL; since 1987 or so.</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="f_set-development-environment">
+          <indexterm zone="f_set-development-environment">
+            <primary>set-development-environment</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>SET-DEVELOPMENT-ENVIRONMENT</refname>
+            <refpurpose></refpurpose>
+            <refclass>Function</refclass>
+          </refnamediv>
+
+          <refsynopsisdiv>
+            <synopsis><function>set-development-environment</function>
+              &optional;
+              unmark-builtin-functions</synopsis>
+          </refsynopsisdiv>
+
+          <refsect1>
+            <title>Description</title>
+
+            <para>Arranges that the outermost special bindings of *PACKAGE*
+              and *WARN-IF-REDEFINE-KERNEL* restore values of the &#34;CCL&#34;
+              package and NIL to these variables, respectively. If the optional
+              argument is true, marks all globally defined functions and methods
+              as being &#34;not predefined&#34; (this is a fairly expensive
+              operation.)</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="f_set-user-environment">
+          <indexterm zone="f_set-user-environment">
+            <primary>set-user-environment</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>SET-USER-ENVIRONMENT</refname>
+            <refpurpose></refpurpose>
+            <refclass>Function</refclass>
+          </refnamediv>
+
+          <refsynopsisdiv>
+            <synopsis><function>set-user-environment</function>
+              &optional; mark-builtin-functions</synopsis>
+          </refsynopsisdiv>
+
+          <refsect1>
+            <title>Description</title>
+
+            <para>Arranges that the outermost special bindings of *PACKAGE*
+              and *WARN-IF-REDEFINE-KERNEL* restore values of the
+              &#34;CL-USER&#34; package and T to these variables, respectively.
+              If the optional argument is true, marks all globally defined
+              functions and methods as being &#34;predefined&#34; (this is a
+              fairly expensive operation.)</para>
+          </refsect1>
+    </refentry>
+    <refentry id="v_altivec-available">
+          <indexterm zone="v_altivec-available">
+            <primary>*altivec-available*</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>*ALTIVEC-AVAILABLE*</refname>
+            <refpurpose></refpurpose>
+            <refclass>Variable</refclass>
+          </refnamediv>
+
+          <refsect1>
+            <title>Description</title>
+            <para>This variable is initialized each time an &CCL; session
+              starts based on information provided by the lisp kernel. Its value
+              is true if AltiVec is present and false otherwise. This variable
+              shouldn't be set by user code.</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="f_altivec-available-p">
+          <indexterm zone="f_altivec-available-p">
+            <primary>altivec-available-p</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>ALTIVEC-AVAILABLE-P</refname>
+            <refpurpose></refpurpose>
+            <refclass>Function</refclass>
+          </refnamediv>
+          
+          <refsynopsisdiv>
+            <synopsis><function>altivec-available-p</function></synopsis>
+          </refsynopsisdiv>
+
+          <refsect1>
+            <title>Description</title>
+
+            <para>Returns non-NIL if AltiVec is available.</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="v_altivec-lapmacros-maintain-vrsave-p">
+          <indexterm zone="v_altivec-lapmacros-maintain-vrsave-p">
+            <primary>*altivec-lapmacros-maintain-vrsave-p*</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*</refname>
+            <refpurpose></refpurpose>
+            <refclass>Variable</refclass>
+          </refnamediv>
+          
+          <refsect1>
+            <title>Description</title>
+
+            <para>Intended to control the expansion of certain lap macros.
+              Initialized to NIL on LinuxPPC; initialized to T on platforms
+              (such as MacOS X/Darwin) that require that the VRSAVE SPR contain
+              a bitmask of active vector registers at all times.</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="lapm_with-altivec-registers">
+          <indexterm zone="lapm_with-altivec-registers">
+            <primary>with-altivec-registers</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>WITH-ALTIVEC-REGISTERS</refname>
+            <refpurpose></refpurpose>
+            <refclass>LAP Macro</refclass>
+          </refnamediv>
+
+          <refsynopsisdiv>
+            <synopsis><function>with-altivec-registers</function>
+              reglist &body; body</synopsis>
+          </refsynopsisdiv>
+
+          <refsect1>
+            <title>Arguments and Values</title>
+
+            <variablelist>
+              <varlistentry>
+                <term>reglist</term>
+
+                <listitem>
+                      <para>A list of vector register names (vr0 .. vr31).</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>body</term>
+
+                <listitem>
+                      <para>A sequence of PPC LAP instructions.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect1>
+
+          <refsect1>
+            <title>Description</title>
+
+            <para>Specifies the set of AltiVec registers used in body. If
+              *altivec-lapmacros-maintain-vrsave-p* is true when the macro is
+              expanded, generates code to save the VRSAVE SPR and updates VRSAVE
+              to include a bitmask generated from the specified register list.
+              Generates code which saves any non-volatile vector registers which
+              appear in the register list, executes body, and restores the saved
+              non-volatile vector registers (and, if
+              *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as
+              well. Uses the IMM0 register (r3) as a temporary.</para>
+          </refsect1>
+    </refentry>
+
+    <refentry id="lapm_with-vector-buffer">
+          <indexterm zone="lapm_with-vector-buffer">
+            <primary>with-vector-buffer</primary>
+          </indexterm>
+
+          <refnamediv>
+            <refname>WITH-VECTOR-BUFFER</refname>
+            <refpurpose></refpurpose>
+            <refclass>LAP Macro</refclass>
+          </refnamediv>
+          
+          <refsynopsisdiv>
+            <synopsis>with-vector-buffer base n &body; body</synopsis>
+          </refsynopsisdiv>
+
+          <refsect1>
+            <title>Arguments and Values</title>
+
+            <variablelist>
+              <varlistentry>
+                <term>base</term>
+
+                <listitem>
+                      <para>Any available general-purpose register.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>n</term>
+
+                <listitem>
+                      <para>An integer between 1 and 254, inclusive. (Should
+                        typically be much, much closer to 1.) Specifies the size of
+                        the buffer, in 16-byte units.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>body</term>
+
+                <listitem>
+                      <para>A sequence of PPC LAP instructions.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect1>
+
+          <refsect1>
+            <title>Description</title>
+            <para>Generates code which allocates a 16-byte aligned buffer
+              large enough to contain N vector registers; the GPR base points to
+              the lowest address of this buffer. After processing body, the
+              buffer will be deallocated. The body should preserve the value of
+              base as long as it needs to reference the buffer. It's
+              intended that base be used as a base register in stvx and lvx
+              instructions within the body.</para>
+          </refsect1>
+    </refentry>
+  </sect1>
+</chapter>

release/1.2/source/doc/src/using.xml

@@ -514 +514 @@
 
     <para>&CCL; supports character names of the form
-    <literal>u+xxxx</literal> - where <literal>x</literal> is a
+    <literal>u+xxxx</literal>&mdash;where <literal>x</literal> is a
     sequence of one or more hex digits.  The value of the hex digits
     denotes the code of the character.  The <literal>+</literal>
@@ -530 +530 @@
     character names, look just below the definition for
     <function>register-character-name</function> in
-    <literal>ccl:level-1;l1-reader.lisp</literal> see the complete
-    list of char</para>
+    <literal>ccl:level-1;l1-reader.lisp</literal>.</para>
   </sect2>
 
@@ -545 +544 @@
     keyword (see <xref linkend="Character-Encodings"/>), an
     external-format object created using
-    <function>CCL::MAKE-EXTERNAL-FORMAT</function>(see <xref
+    <function>CCL::MAKE-EXTERNAL-FORMAT</function> (see <xref
     linkend="f_make-external-format"/>), or a plist with keys:
     <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
@@ -650 +649 @@
           </varlistentry>
           <varlistentry>
-            <term>[result]</term>
-            <listitem>
-              <para>[description]</para>
+            <term>external-format</term>
+            <listitem>
+              <para>An external-format object as described above.</para>
             </listitem>
           </varlistentry>
@@ -661 +660 @@
         <title>Description</title>
         
-        <para>Despite the function's name, it doesn't necessarily
-        create a new, unique EXTERNAL-FORMAT object: two calls to
-        MAKE-EXTERNAL-FORMAT with the same arguments made in the
-        same dynamic environment will return the same (eq) object.
+        <para>Despite the function's name, it doesn't necessarily create a
+        new, unique EXTERNAL-FORMAT object: two calls to
+        MAKE-EXTERNAL-FORMAT with the same arguments made in the same
+        dynamic environment return the same (eq) object.
         </para>
       </refsect1>
@@ -769 +768 @@
     <sect3><title>Encoding Problems</title>
       <para>On output to streams with character encodings that can
-      encode the full range of Unicode - and on input from any stream
-      - "unencodable characters" are represented using the Unicode
-      #\Replacement_Character (= #\U+fffd); the presence of such a
-      character usually indicates that something got lost in
+      encode the full range of Unicode&mdash;and on input from any
+      stream&mdash;"unencodable characters" are represented using the
+      Unicode #\Replacement_Character (= #\U+fffd); the presence of
+      such a character usually indicates that something got lost in
       translation.  Either data wasn't encoded properly or there was a
       bug in the decoding process.</para>
@@ -788 +787 @@
       indicate that the encoding is UTF-8.)</para>
 
-      <para>Clozure CL will write a byte order mark as the first
-      character of a file or socket stream when the endianness of the
-      character encoding is not explicit.  Clozure CL also expects a
-      byte order mark on input from streams where the endianness is
-      not explicit. If a byte order mark is missing from input data,
-      that data is assumed to be in big-endian order.</para>
+      <para>Clozure CL writes a byte order mark as the first character
+      of a file or socket stream when the endianness of the character
+      encoding is not explicit.  Clozure CL also expects a byte order
+      mark on input from streams where the endianness is not
+      explicit. If a byte order mark is missing from input data, that
+      data is assumed to be in big-endian order.</para>
 
       <para>A byte order mark from a UTF-8 encoded input stream is not
-      treated specially and and will just appear as normal character
-      from the input stream.  It is probably a good idea to skip over
-      this character.</para>
+      treated specially and just appears as a normal character from
+      the input stream.  It is probably a good idea to skip over this
+      character.</para>
     </sect3>
 

release/1.2/source/examples/opengl-ffi.lisp

@@ -135 +135 @@
        ;;; Set the OSX Window Server's notion of the name of the
        ;;; current process.
-       (%stack-block ((psn 8))
-         (ccl::external-call "_GetCurrentProcess" :address psn)
+       (rlet ((psn #>ProcessSerialNumber))
+         (#_GetCurrentProcess psn)
          (with-cstrs ((name "simple OpenGL example"))
-           (ccl::external-call "_CPSSetProcessName" :address psn :address name))))
+           (ccl::external-call "_CPSSetProcessName" :address psn :address name :void))))
      (main)))
 

release/1.2/source/examples/rubix/rubix.lisp

@@ -221 +221 @@
 
 (defun run-rubix-demo ()
-  (let* ((w (ccl::new-cocoa-window :class (find-class 'rubix-window)
+  (let* ((w (gui::new-cocoa-window :class (find-class 'rubix-window)
                                    :title "Rubix Cube"
                                    :height 250

release/1.2/source/level-1/l1-clos-boot.lisp

@@ -1053 +1053 @@
 
            
-(defparameter dcode-proto-alist
-  (list (cons #'%%one-arg-dcode *gf-proto-one-arg*)
-        (cons #'%%1st-two-arg-dcode *gf-proto-two-arg*)))
-    
 (defun compute-dcode (gf &optional dt)
   (setq gf (require-type gf 'standard-generic-function))

release/1.2/source/level-1/l1-clos.lisp

@@ -1810 +1810 @@
       (%slot-ref (instance.slots instance) location)
       (no-applicable-method (%gf-dispatch-table-gf dt) instance))))
+(register-dcode-proto #'singleton-reader-dcode *gf-proto-one-arg*)
 
 ;;; Dcode for a GF whose methods are all reader-methods which access a
@@ -1823 +1824 @@
       (%slot-ref (instance.slots instance) location)
       (no-applicable-method (%gf-dispatch-table-gf dt) instance))))
+(register-dcode-proto #'reader-constant-location-dcode *gf-proto-one-arg*)
 
 ;;; Dcode for a GF whose methods are all reader-methods which access a
@@ -1839 +1841 @@
       (%slot-ref (instance.slots instance) location)
       (no-applicable-method (%gf-dispatch-table-gf dt) instance))))
+(register-dcode-proto #'reader-constant-location-inherited-from-single-class-dcode *gf-proto-one-arg*)
 
 ;;; Dcode for a GF whose methods are all reader-methods which access a
@@ -1855 +1858 @@
       (%slot-ref (instance.slots instance) location)
       (no-applicable-method (%gf-dispatch-table-gf dt) instance))))
+(register-dcode-proto #'reader-constant-location-inherited-from-multiple-classes-dcode *gf-proto-one-arg*)
 
 
@@ -1870 +1874 @@
       (%slot-ref (instance.slots instance) location)
       (no-applicable-method (%gf-dispatch-table-gf dt) instance))))
+(register-dcode-proto #'reader-variable-location-dcode *gf-proto-one-arg*)
 
 (defun class-and-slot-location-alist (classes slot-name)
@@ -1994 +1999 @@
       (funcall mf arg1 arg2)
       (%%1st-two-arg-dcode dt arg1 arg2))))
+(register-dcode-proto #'reader-variable-location-dcode *gf-proto-two-arg*)
 
 (defun %%one-arg-eql-method-hack-dcode (dt arg)
@@ -1999 +2005 @@
     (if mf
       (funcall mf arg))))
+(register-dcode-proto #'%%one-arg-eql-method-hack-dcode *gf-proto-one-arg*)
 
 (defun install-eql-method-hack-dcode (gf)

release/1.2/source/level-1/l1-dcode.lisp

@@ -781 +781 @@
 ;;;;;;;;;;;;;;;;;;;;;;;;; generic-function dcode ;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+;; dcode functions using other than *gf-proto*
+(defparameter dcode-proto-alist ())
+
+(defun register-dcode-proto (dcode proto)
+  (let ((a (assoc dcode dcode-proto-alist)))
+    (if a
+      (setf (cdr a) proto)
+      (push (cons dcode proto) dcode-proto-alist))))
+
+
 ;;; Simple case for generic-functions with no specializers
 ;;; Why anyone would want to do this I can't imagine.
@@ -817 +827 @@
   (let ((method (%find-1st-arg-combined-method dt arg)))
     (funcall method arg)))
+(register-dcode-proto #'%%one-arg-dcode *gf-proto-one-arg*)
 
 ;;; two args - specialized on first
@@ -822 +833 @@
   (let ((method (%find-1st-arg-combined-method dt arg1)))
     (funcall method arg1 arg2)))
-
+(register-dcode-proto #'%%1st-two-arg-dcode *gf-proto-two-arg*)
 
 

release/1.2/source/level-1/l1-streams.lisp

@@ -4372 +4372 @@
             (incf (ioblock-charpos ioblock) num-chars))
           num-chars)
+      (declare (fixnum src dest end))
       (let* ((char (schar string src)))
         (if (eql char #\Newline)
-          (setq nlpos src))
+          (setq nlpos (the fixnum (1+ src))))
         (setf (schar out dest) char)))))
 

release/1.2/source/lib/compile-ccl.lisp

@@ -600 +600 @@
          (cwd ,wd)))))
 
-(defun ensure-tests-loaded (&key force full)
+(defun ensure-tests-loaded (&key force update)
   (unless (and (find-package "REGRESSION-TEST") (not force))
     (if (probe-file "ccl:tests;ansi-tests;")
-      (when full
+      (when update
         (cwd "ccl:tests;")
         (run-program "svn" '("update")))
       (let* ((svn (probe-file "ccl:.svn;entries"))
-             (repo (and svn
-                        (with-open-file (s svn)
-                          (loop as line =  (read-line s nil) while line
-                             do (when (search "://" line)
-                                  (setq line (read-line s))
-                                  (return (and (search "://" line) line)))))))
+             (repo (and svn (svn-repository)))
              (s (make-string-output-stream)))
         (when repo
@@ -631 +626 @@
     ;; it without making the test suite non-portable across platforms...
     (handler-bind ((warning (lambda (c)
-                              (when (and (typep c 'compiler-warning)
-                                         (eq (compiler-warning-warning-type c) :program-error)
-                                         (typep (car (compiler-warning-args c)) 'simple-warning)
-                                         (or
-                                          (string-equal
-                                           (simple-condition-format-control (car (compiler-warning-args c)))
-                                           "Clause ~S ignored in ~S form - shadowed by ~S .")
-                                          ;; Might as well ignore these as well, they're intentional.
-                                          (string-equal
-                                           (simple-condition-format-control (car (compiler-warning-args c)))
-                                           "Duplicate keyform ~s in ~s statement.")))
+                              (when (let ((w (or (and (typep c 'compiler-warning)
+                                                      (eq (compiler-warning-warning-type c) :program-error)
+                                                      (car (compiler-warning-args c)))
+                                                 c)))
+                                      (and (typep w 'simple-warning)
+                                           (or 
+                                            (string-equal
+                                             (simple-condition-format-control w)
+                                             "Clause ~S ignored in ~S form - shadowed by ~S .")
+                                            ;; Might as well ignore these as well, they're intentional.
+                                            (string-equal
+                                             (simple-condition-format-control w)
+                                             "Duplicate keyform ~s in ~s statement."))))
                                 (muffle-warning c)))))
       ;; This loads the infrastructure
       (load "ccl:tests;ansi-tests;gclload1.lsp")
       ;; This loads the actual tests
-      (load "ccl:tests;ansi-tests;gclload2.lsp"))))
-
-(defun test-ccl (&key force full verbose (catch-errors t))
+      (load "ccl:tests;ansi-tests;gclload2.lsp")
+      ;; And our own tests
+      (load "ccl:tests;ansi-tests;ccl.lsp"))))
+
+(defun test-ccl (&key force (update t) verbose (catch-errors t))
   (with-preserved-working-directory ()
-    (ensure-tests-loaded :force force :full full)
+    (ensure-tests-loaded :force force :update update)
     (cwd "ccl:tests;ansi-tests;")
     (let ((do-tests (find-symbol "DO-TESTS" "REGRESSION-TEST"))

release/1.2/source/lib/macros.lisp

@@ -543 +543 @@
                          (default-setf form value env))))))))))
           ((oddp temp)
-           (error "Odd number of args to SETF : ~s." args))
+           (signal-program-error "Odd number of args to SETF : ~s." args))
           (t (do* ((a args (cddr a)) (l nil))
                   ((null a) `(progn ,@(nreverse l)))
@@ -869 +869 @@
          otherwise-seen-p)
     (flet ((bad-clause (c) 
-             (error "Invalid clause ~S in ~S form." c construct)))
+             (signal-program-error "Invalid clause ~S in ~S form." c construct)))
       (dolist (clause clauses)
         (if (atom clause)
             (bad-clause clause))
         (if otherwise-seen-p
-            (error "OTHERWISE must be final clause in ~S form." construct))
+            (signal-program-error "OTHERWISE must be final clause in ~S form." construct))
         (destructuring-bind (typespec &body consequents) clause
           (when (eq construct 'typecase)
@@ -994 +994 @@
        (when (nth-value 1 (macroexpand-1 sym env))
          (return `(psetf ,@pairs))))
-     (error "Uneven number of args in the call ~S" call))))
+     (signal-program-error "Uneven number of args in the call ~S" call))))
 
 ; generates body for psetq.
@@ -1677 +1677 @@
 (defun with-specs-aux (name spec-list original-body)
   (multiple-value-bind (body decls) (parse-body original-body nil)
-    (when decls (error "declarations not allowed in ~s" original-body))
+    (when decls (signal-program-error "declarations not allowed in ~s" original-body))
     (setq body (cons 'progn body))
     (dolist (spec (reverse spec-list))
@@ -2098 +2098 @@
       (unless (and (consp option)
                    (consp (%cdr option)))
-        (error "Invalid option ~s ." option))
+        (signal-program-error "Invalid option ~s ." option))
       (ecase (%car option)
         (:default-initargs 
@@ -2108 +2108 @@
         (:documentation 
          (unless (null (%cddr option)) 
-           (error "Invalid option ~s ." option)) 
+           (signal-program-error "Invalid option ~s ." option)) 
          (if docp
            (setq duplicate t)
@@ -2114 +2114 @@
         (:report 
          (unless (null (%cddr option)) 
-           (error "Invalid option ~s ." option)) 
+           (signal-program-error "Invalid option ~s ." option)) 
          (if reporter
            (setq duplicate t)
@@ -2123 +2123 @@
                (if (stringp reporter)
                  (setq reporter `(function (lambda (c s) (declare (ignore c)) (write-string ,reporter s))))
-                 (error "~a expression is not a string, symbol, or lambda expression ." (%car option))))
+                 (signal-program-error "~a expression is not a string, symbol, or lambda expression ." (%car option))))
              (setq reporter `((defmethod report-condition ((c ,name) s)
                                 (funcall ,reporter c s))))))))
-      (if duplicate (error "Duplicate option ~s ." option)))
+      (if duplicate (signal-program-error "Duplicate option ~s ." option)))
     `(progn
        (defclass ,name ,(or supers '(condition)) ,slots ,@classopts)
@@ -2759 +2759 @@
                   (symbolp (car slot-entry)) (symbolp (cadr slot-entry)))
              (setq var (car slot-entry) slot-name (cadr slot-entry)))
-            (t (error "Malformed slot-entry: ~a to with-slot-values.~@
-                       Should be a symbol or a list of two symbols."
-                      slot-entry)))
+            (t (signal-program-error "Malformed slot-entry: ~a to with-slot-values.~@
+                                      Should be a symbol or a list of two symbols."
+                                     slot-entry)))
       (push `(,var (slot-value ,instance ',slot-name)) bindings))
     `(let ((,instance ,instance-form))
@@ -2780 +2780 @@
                   (symbolp (car slot-entry)) (symbolp (cadr slot-entry)))
              (setq var (car slot-entry) slot-name (cadr slot-entry)))
-            (t (error "Malformed slot-entry: ~a to with-slots.~@
-                       Should be a symbol or a list of two symbols."
-                      slot-entry)))
+            (t (signal-program-error "Malformed slot-entry: ~a to with-slots.~@
+                                      Should be a symbol or a list of two symbols."
+                                     slot-entry)))
       (push `(,var (slot-value ,instance ',slot-name)) bindings))
     `(let ((,instance ,instance-form))
@@ -2801 +2801 @@
                   (symbolp (car slot-entry)) (symbolp (cadr slot-entry)))
              (setq var (car slot-entry) reader (cadr slot-entry)))
-            (t (error "Malformed slot-entry: ~a to with-accessors.~@
-                       Should be a list of two symbols."
-                      slot-entry)))
+            (t (signal-program-error "Malformed slot-entry: ~a to with-accessors.~@
+                                     Should be a list of two symbols."
+                                     slot-entry)))
       (push `(,var (,reader ,instance)) bindings))
     `(let ((,instance ,instance-form))
@@ -2939 +2939 @@
                            `((setf ,(%foreign-access-form name ftype 0 nil)
                               ,(car inits)))))
-              (error "Unexpected or malformed initialization forms: ~s in field type: ~s"
-                     inits record-name))))))))
+              (signal-program-error "Unexpected or malformed initialization forms: ~s in field type: ~s"
+                                    inits record-name))))))))
 
 (defun %foreign-record-field-forms (ptr record-type record-name inits)
   (unless (evenp (length inits))
-    (error "Unexpected or malformed initialization forms: ~s in field type: ~s"
-                     inits record-name))
+    (signal-program-error "Unexpected or malformed initialization forms: ~s in field type: ~s"
+                          inits record-name))
   (let* ((result ()))
     (do* ()
@@ -2976 +2976 @@
          (bytes (if bits
                   (ceiling bits 8)
-                  (error "Unknown size for foreign type ~S."
-                         (unparse-foreign-type ftype))))
+                  (signal-program-error "Unknown size for foreign type ~S."
+                                        (unparse-foreign-type ftype))))
          (p (gensym))
          (bzero (read-from-string "#_bzero")))    
@@ -3154 +3154 @@
           (%symbol-binding-address ',place)
           (%atomic-incf-node ,delta ,base ,offset)))
-      (error "~S is not a special variable"  place))))
+      (signal-program-error "~S is not a special variable"  place))))
     
 (defmacro atomic-incf (place)
@@ -3173 +3173 @@
     (unless (and (listp x)
                  (= (length x) 2))
-      (error "Malformed iterate variable spec: ~S." x)))
+      (signal-program-error "Malformed iterate variable spec: ~S." x)))
 
   `(labels ((,name ,(mapcar #'first binds) ,@body))
@@ -3211 +3211 @@
       (let ((spec (first specs)))
         (when (/= (length spec) 2)
-          (error "Malformed Once-Only binding spec: ~S." spec))
+          (signal-program-error "Malformed ~s binding spec: ~S." 'once-only spec))
         (let ((name (first spec))
               (exp-temp (gensym)))
@@ -3272 +3272 @@
     (dolist (spec collections)
       (unless (<= 1 (length spec) 3)
-        (error "Malformed collection specifier: ~S." spec))
+        (signal-program-error "Malformed collection specifier: ~S." spec))
       (let ((n-value (gensym))
             (name (first spec))
@@ -3333 +3333 @@
                  (if (and (consp (%cdr p)) (null (%cddr p)))
                    (values (require-global-symbol (%car p) env) (%cadr p))
-                   (error "Invalid variable initialization form : ~s")))))
+                   (signal-program-error "Invalid variable initialization form : ~s")))))
         (declare (inline pair-name-value))
         (dolist (v vars)
@@ -3370 +3370 @@
           (ccl::%symbol-binding-address ',place)
           (ccl::%store-node-conditional ,offset ,base ,old-value ,new-value)))
-      (error "~s is not a special variable ." place))
+      (signal-program-error "~s is not a special variable ." place))
     (let* ((sym (car place))
            (struct-transform (or (ccl::environment-structref-info sym env)
@@ -3382 +3382 @@
             (ccl::store-gvector-conditional ,(caddr place)
              ,v ,old-value ,new-value)))
-        (error "Don't know how to do conditional store to ~s" place)))))
+        (signal-program-error "Don't know how to do conditional store to ~s" place)))))
 
 (defmacro step (form)

release/1.2/source/lib/nfcomp.lisp

@@ -907 +907 @@
   (let* ((*fasdump-hash* (make-hash-table :size (length forms)          ; Crude estimate
                                           :rehash-threshold 0.9
-                                          :test 'eq))
+                                          :test 'eq
+                                          :shared nil))
          (*make-load-form-hash* (make-hash-table :test 'eq))
          (*fasdump-read-package* nil)

release/1.2/source/lib/pprint.lisp

@@ -1563 +1563 @@
   (cond ((vectorp array) (pretty-vector xp array))
         ((zerop (array-rank array))
-         (write-string++ "#0A " xp 0 4)
+         (write-string++ "#0A" xp 0 3)
          (write+ (aref array) xp))
         (T (pretty-non-vector xp array))))

release/1.2/source/library/chud-metering.lisp

@@ -1 +1 @@
 ;;;-*-Mode: LISP; Package: (CHUD (:USE CL CCL)) -*-
 ;;;
-;;;   Copyright (C) 2005 Clozure Associates and contributors
+;;;   Copyright (C) 2005,2008 Clozure Associates and contributors
 ;;;   This file is part of OpenMCL.  
 ;;;
@@ -25 +25 @@
 (defpackage "CHUD"
   (:use "CL" "CCL")
-  (:export "METER" "PREPARE-METERING" "*SPATCH-DIRECTORY-PATH*"
-           "LAUNCH-SHARK" "CLEANUP-SPATCH-FILES" "RESET-METERING"))
+  (:export "METER" "*SHARK-CONFIG-FILE*"))
   
 (in-package "CHUD")
 
-
-(defparameter *CHUD-library-path*
-  "/System/Library/PrivateFrameworks/CHUD.Framework/CHUD"
-  "This seems to move around with every release.")
-
-(defparameter *shark-app-path* "/Developer/Applications/Performance\ Tools/Shark.app")
-
-(defparameter *spatch-directory-path* nil
-  "If non-NIL, should be a pathname whose directory component matches the
-\"Patch FIles\" search path in Shark's Preferences.  When this variable
-is NIL, USER-HOMEDIR-PATHNAME is used instead.")
-
-(eval-when (:load-toplevel :execute)
-  (open-shared-library (namestring *CHUD-library-path*)))
-
-(eval-when (:compile-toplevel :execute)
-  (use-interface-dir :chud))
-
-;;; CHUD apparently has this notion of global, persistent
-;;; "status" (the result returned by the last operation.)
-;;; I have not idea whether or not that's thread-specific;
-;;; there doesn't seem to be any other way of getting a
-;;; string that describes an error code.
-(defun chud-get-status-string ()
-  (with-macptrs ((s (#_chudGetStatusStr)))
-    (if (%null-ptr-p s)
-      ""
-      (%get-cstring s))))
-
-(defun chud-check-error (result context)
-  (or (eql result #$chudSuccess)
-      (error "CHUD error ~d (~a) while ~a. " result (chud-get-status-string) context)))
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (progn
+    #-darwin-target
+    (error "This code is Darwin/MacOSX-specific.")))
+
+
+(defparameter *shark-session-path* nil)
+
+(defloadvar *written-spatch-file* nil)
+
+(defparameter *shark-session-native-namestring* nil)
+
+(defparameter *shark-config-file* nil "Full pathname of .cfg file to use for profiling, or NIL.")
+
+(defun finder-open-file (namestring)
+  "Open the file named by NAMESTRING, as if it was double-clicked on
+in the finder"
+  (run-program "/usr/bin/open" (list namestring) :output nil))
+
+(defun ensure-shark-session-path ()
+  (unless *shark-session-path*
+    (multiple-value-bind (second minute hour date month year)
+        (decode-universal-time (get-universal-time))
+      (let* ((subdir (format nil "profiling-session-~A-~d_~d-~d-~d_~d.~d.~d"
+                             (pathname-name
+                              (car
+                               ccl::*command-line-argument-list*))
+                             (ccl::getpid)
+                             month
+                             date
+                             year
+                             hour
+                             minute
+                             second))
+             (dir (make-pathname :directory (append (pathname-directory (user-homedir-pathname)) (list subdir)) :defaults nil))
+             (native-name (ccl::native-untranslated-namestring dir)))
+        (ensure-directories-exist dir)
+        (setenv "SHARK_SEARCH_PATH_PATCH_FILES" native-name)
+        (setq *shark-session-native-namestring*
+              native-name
+              *shark-session-path* dir))))
+  *shark-session-path*)
+
+
   
-(defun chud-is-initialized ()
-  (not (eql (#_chudIsInitialized) 0)))
-
-(defparameter *chud-supported-major-version* 4)
-(defparameter *chud-supported-minor-version* 1)
-
-;; Don't know if it makes sense to worry about max supported versions
-;; as well.
-
-(defun check-chud-version ()
-  (let* ((version (#_chudFrameworkVersion))
-         (major (ldb (byte 8 24) version))
-         (minor (ldb (byte 8 12) version)))
-    (or (and (>= major *chud-supported-major-version*)
-             (when (= major *chud-supported-major-version*)
-               (>= minor *chud-supported-minor-version*)))
-        (warn "The installed CHUD framework is version ~d.~d.  ~
-The minimum version supported by this interface is ~d.~d."
-              major minor *chud-supported-major-version*
-              *chud-supported-minor-version*))))
-    
-
-(defun initialize-chud ()
-  (or (chud-is-initialized)
-      (and (check-chud-version)
-           (chud-check-error (#_chudInitialize) "initializing CHUD"))))
-
-(defun acquired-remote-access ()
-  (eql #$true (#_chudIsRemoteAccessAcquired)))
-  
-;;; If we've already successfully called (#_chudAcquireRemoteAccess),
-;;; we can call it again without error (e.g., it's a no-op in that
-;;; case.)  However, we can successfully release it at most once.
-
-(defun acquire-remote-access ()
-  (or (acquired-remote-access)
-      (chud-check-error (#_chudAcquireRemoteAccess) "acquiring remote access")))
-
-(defun release-remote-access ()
-  (chud-check-error (#_chudReleaseRemoteAccess) "releasing remote access"))
-
-(defun start-remote-perf-monitor (label)
-  (with-cstrs ((clabel (format nil "~a" label)))
-    (chud-check-error (#_chudStartRemotePerfMonitor clabel)
-                      "starting performance monitor")))
-
-(defun stop-remote-perf-monitor ()
-  (chud-check-error (#_chudStopRemotePerfMonitor)
-                    "stopping performance monitor"))
-
-(defun setup-timer (duration frequency)
-  (#_chudSetupTimer frequency
-                    #$chudMicroSeconds
-                    0
-                    #$chudMicroSeconds
-                    duration))
-
-(defun get-readonly-area-bounds ()
-  (ccl::do-gc-areas (a)
-    (when (eql(ccl::%fixnum-ref a target::area.code)
-              #+ppc-target ccl::area-readonly
-              #+x8664-target ccl::area-managed-static)
-      (return
-        (values (ash (ccl::%fixnum-ref a target::area.low) target::fixnumshift)
-                (ash (ccl::%fixnum-ref a target::area.active) target::fixnumshift))))))
+
+(defloadvar *shark-process* nil)
+(defloadvar *sampling* nil)
+
+(defloadvar *debug-shark-process-output* nil)
+
 
 (defun safe-shark-function-name (function)
@@ -134 +86 @@
 
 (defun print-shark-spatch-record (fn &optional (stream t))
-  (let* ((code-vector (uvref fn 0))
+  (let* ((code-vector #+ppc-target (uvref fn 0) #-ppc-target fn)
          (startaddr (+ (ccl::%address-of code-vector)
-                       target::misc-data-offset))
-         (endaddr (+ startaddr (* target::node-size (uvsize code-vector)))))
+                       #+x8664-target 0
+                       #+ppc32-target target::misc-data-offset
+                       #-ppc32-target 0))
+         (endaddr (+ startaddr
+                     #+x8664-target
+                     (1+ (ash (1- (ccl::%function-code-words fn)
+                                  ) target::word-shift))
+                     #+ppc-target
+                     (* 4 (- (uvsize code-vector)
+                                       #+ppc64-target 2
+                                       #-ppc64-target 1)))))
     ;; i hope all lisp sym characters are allowed... we'll see
     (format stream "{~%~@
@@ -150 +111 @@
             endaddr)))
 
-(defun identify-functions-with-pure-code (pure-low pure-high)
-  (let* ((hash (make-hash-table :test #'eq)))
-    (ccl::%map-lfuns #'(lambda (f)
-                         (let* ((code-vector #+ppc-target (ccl:uvref f 0)
-                                             #+x8664-target (ccl::function-to-function-vector f))
-                                (startaddr (+ (ccl::%address-of code-vector)
-                                              target::misc-data-offset)))
-                           (when (and (>= startaddr pure-low)
-                                      (< startaddr pure-high))
-                             (push f (gethash code-vector hash))))))
-    (let* ((n 0))
-      (declare (fixnum n))
-      (maphash #'(lambda (k v)
-                   (declare (ignore k))
-                   (if (null (cdr v))
-                     (incf n)))
-               hash)
-      (let* ((functions (make-array n))
-             (i 0))
+#+x8664-target
+(ccl::defx86lapfunction dynamic-dnode ((x arg_z))
+  (movq (% x) (% imm0))
+  (ref-global x86::heap-start arg_y)
+  (subq (% arg_y) (% imm0))
+  (shrq ($ x8664::dnode-shift) (% imm0))
+  (box-fixnum imm0 arg_z)
+  (single-value-return))
+
+#+x8664-target
+(defun identify-functions-with-pure-code ()
+  (ccl::freeze)
+  (ccl::collect ((functions))
+    (block walk
+      (let* ((frozen-dnodes (ccl::frozen-space-dnodes)))
+        (ccl::%map-areas (lambda (o)
+                           (when (>= (dynamic-dnode o) frozen-dnodes)
+                             (return-from walk nil))
+                           (when (typep o 'ccl::function-vector)
+                             (functions (ccl::function-vector-to-function o))))
+                         ccl::area-dynamic
+                         ccl::area-dynamic
+                         )))
+    (functions)))
+
+#+ppc-target
+(defun identify-functions-with-pure-code ()
+  (ccl:purify)
+  (multiple-value-bind (pure-low pure-high)
+                                 
+      (ccl::do-gc-areas (a)
+        (when (eql(ccl::%fixnum-ref a target::area.code)
+                  ccl::area-readonly)
+          (return
+            (values (ash (ccl::%fixnum-ref a target::area.low) target::fixnumshift)
+                    (ash (ccl::%fixnum-ref a target::area.active) target::fixnumshift)))))
+    (let* ((hash (make-hash-table :test #'eq)))
+      (ccl::%map-lfuns #'(lambda (f)
+                           (let* ((code-vector  (ccl:uvref f 0))
+                                  (startaddr (+ (ccl::%address-of code-vector)
+                                                target::misc-data-offset)))
+                             (when (and (>= startaddr pure-low)
+                                        (< startaddr pure-high))
+                               (push f (gethash code-vector hash))))))
+      (let* ((n 0))
+        (declare (fixnum n))
         (maphash #'(lambda (k v)
                      (declare (ignore k))
-                     (when (null (cdr v))
-                       (setf (svref functions i) (car v)
-                             i (1+ i))))
+                     (if (null (cdr v))
+                       (incf n)))
                  hash)
-        (sort functions
-              #'(lambda (x y)
-                  (< (ccl::%address-of #+ppc-target (uvref x 0)
-                                       #+x8664-target x)
-                     (ccl::%address-of #+ppc-target (uvref y 0)
-                                       #+x8664-target y))))))))
+        (let* ((functions ()))
+          (maphash #'(lambda (k v)
+                       (declare (ignore k))
+                       (when (null (cdr v))
+                         (push (car v) functions)))
+                   hash)
+          (sort functions
+                #'(lambda (x y)
+                    (< (ccl::%address-of (uvref x 0) )
+                       (ccl::%address-of  (uvref y 0))))))))))
         
                            
+
+
 (defun generate-shark-spatch-file ()
-  (ccl::purify)
-  (multiple-value-bind (pure-low pure-high)
-      (get-readonly-area-bounds)
-    (let* ((functions (identify-functions-with-pure-code pure-low pure-high)))
-      (with-open-file (f (make-pathname
-                          :host nil
-                          :directory (pathname-directory
-                                      (or *spatch-directory-path*
-                                          (user-homedir-pathname)))
-                          :name (format nil "~a_~D"
-                                        (pathname-name
-                                         (car
-                                          ccl::*command-line-argument-list*))
-                                        (ccl::getpid))
-                          :type "spatch")
-                         :direction :output
-                         :if-exists :supersede)
-        (format f "!SHARK_SPATCH_BEGIN~%")
-        (dotimes (i (length functions))
-          (print-shark-spatch-record (svref functions i) f))
-        (format f "!SHARK_SPATCH_END~%"))) t))
-
-(defun cleanup-spatch-files ()
-  (dolist (f (directory
-              (make-pathname
-               :host nil
-               :directory
-               (pathname-directory
-                (or *spatch-directory-path*
-                    (user-homedir-pathname)))
-               :name :wild
-               :type "spatch")))
-    (delete-file f)))
-
-
-(defun launch-shark ()
-  (run-program "/usr/bin/open" (list *shark-app-path*)))
-
-  
-(defun reset-metering ()
-  (when (acquired-remote-access)
-    (release-remote-access)
-    (format t "~&Note: it may be desirable to quit and restart Shark.")
-    t))
+  (let* ((functions (identify-functions-with-pure-code)))
+    (with-open-file (f (make-pathname
+                        :host nil
+                        :directory (pathname-directory
+                                    (ensure-shark-session-path))
+                        :name (format nil "~a_~D"
+                                      (pathname-name
+                                       (car
+                                        ccl::*command-line-argument-list*))
+                                      (ccl::getpid))
+                        :type "spatch")
+                       :direction :output
+                       :if-exists :supersede)
+      (format f "!SHARK_SPATCH_BEGIN~%")
+      (dolist (fun functions)
+        (print-shark-spatch-record fun f))
+      (format f "!SHARK_SPATCH_END~%"))))
+
+(defun terminate-shark-process ()
+  (when *shark-process*
+    (signal-external-process *shark-process* #$SIGUSR2))
+  (setq *shark-process* nil
+        *sampling* nil))
+
+(defun toggle-sampling ()
+  (if *shark-process*
+    (progn
+      (signal-external-process *shark-process* #$SIGUSR1)
+      (setq *sampling* (not *sampling*)))
+    (warn "No active shark procsss")))
+
+(defun enable-sampling ()
+  (unless *sampling* (toggle-sampling)))
+
+(defun disable-sampling ()
+  (when *sampling* (toggle-sampling)))
+
+(defun ensure-shark-process (reset hook)
+  (when (or (null *shark-process*) reset)
+    (terminate-shark-process)
+    (when (or reset (not *written-spatch-file*))
+      (generate-shark-spatch-file))
+    (let* ((args (list "-b" "-1" "-a" (format nil "~d" (ccl::getpid))
+                             "-d" *shark-session-native-namestring*)))
+      (when *shark-config-file*
+        (push (ccl::native-untranslated-namestring *shark-config-file*)
+              args)
+        (push "-m" args))
+      (setq *shark-process*
+            (run-program "/usr/bin/shark"
+                         args
+                         :output :stream
+                         :status-hook hook
+                         :wait nil))
+      (let* ((output (external-process-output-stream *shark-process*)))
+        (do* ((line (read-line output nil nil) (read-line output nil nil)))
+             ((null line))
+          (when *debug-shark-process-output*
+            (format t "~&~a" line))
+          (when (search "ready." line :key #'char-downcase)
+            (sleep 1)
+            (return)))))))
+
+(defun display-shark-session-file (line)
+  (let* ((last-quote (position #\' line :from-end t))
+         (first-quote (and last-quote (position #\' line :end (1- last-quote) :from-end t)))
+         (path (and first-quote  (subseq line (1+ first-quote) last-quote))))
+    (when path (finder-open-file path))))
     
-(defun prepare-metering ()
-  (launch-shark)
-  (generate-shark-spatch-file)
-  (initialize-chud)
-  (loop
-    (when (ignore-errors (acquire-remote-access))
-      (return))
-    ;; Yes, this is lame.
-    (loop (when (y-or-n-p "Is Shark in Remote mode yet?")
-            (return)))))
-
-(defmacro meter (form &key (duration 0) (frequency 1))
-  (let* ((started (gensym)))
-    `(let* ((,started nil))
-      (unless (and (chud-is-initialized)
-                   (acquired-remote-access))
-        (prepare-metering))
-      (setup-timer ,duration ,frequency)
-      (unwind-protect
-         (progn
-           (setq ,started (start-remote-perf-monitor ',form))
-           ,form)
-        (when ,started (stop-remote-perf-monitor))))))
-
-(defun chud-cleanup ()
-  (when (chud-is-initialized)
-    (when (acquired-remote-access)
-      (ignore-errors (release-remote-access)))
-    (#_chudCleanup))
-  (cleanup-spatch-files))
-  
-(pushnew 'chud-cleanup *lisp-cleanup-functions*)
+(defun scan-shark-process-output (p)
+  (with-interrupts-enabled 
+      (let* ((out (ccl::external-process-output p)))
+        (do* ((line (read-line out nil nil) (read-line out nil nil)))
+             ((null line))
+          (when *debug-shark-process-output*
+            (format t "~&~a" line))
+          (when (search "Created session file:" line)
+            (display-shark-session-file line)
+            (return))))))
+
+
+
+(defmacro meter (form &key reset debug-output)
+  (let* ((hook (gensym))
+         (block (gensym))
+         (process (gensym)))
+    `(block ,block
+      (flet ((,hook (p)
+               (when (or (eq (external-process-status p) :exited)
+                         (eq (external-process-status p) :signaled))
+                 (setq *shark-process* nil
+                       *sampling* nil))))
+        (let* ((*debug-shark-process-output* ,debug-output))
+          (ensure-shark-process ,reset #',hook)
+          (unwind-protect
+               (progn
+                 (enable-sampling)
+                 ,form)
+            (disable-sampling)
+            (let* ((,process *shark-process*))
+              (when ,process
+                (scan-shark-process-output ,process)))))))))
+
+;;; Try to clean up after ourselves when the lisp quits.
+(pushnew 'terminate-shark-process ccl::*save-exit-functions*)

release/1.2/source/library/chud-metering.txt

@@ -1 @@
-Using Apple's CHUD metering tools from OpenMCL
+Using Apple's CHUD metering tools from CCL
+==========================================
 
- Prerequisites
+Prerequisites
+-------------
 
 Apple's CHUD metering tools are available (as of this writing) from:
@@ -7 +9 @@
 <ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_Debugging/Performance_tools/>. 
 
-There are also some CHUD packages distributed with some recent
-versions of Xcode; the standalone versions available via FTP seem to
-work much better with the OpenMCL interface. Both versions 4.1.1 and
-4.2.2 of the CHUD tools seem to work reasonably well; earlier versions
-provide a different ABI, and it's not known whether any future
-versions will be compatible.
+The CHUD tools are also generally bundled with Apple's XCode tools.
+CBUD 4.5.0 (which seems to be bundled with XCode 3.0) seems to work
+well with this interface; later versions may have problems.
+Versions of CHUD as old as 4.1.1 may work with 32-bit PPC versions
+of CCL; later versions (not sure exactly -what- versions) added
+x86, ppc64, and x86-64 support.
 
-There don't seem to be any versions of CHUD that can deal with 64-bit
-processes.
+One way to tell whether any version of the CHUD tools is installed
+is to try to invoke the "shark" command-line program (/usr/bin/shark)
+from the shell:
 
-Ensure that either version 4.1.1 or 4.2.2 of the CHUD tools are
-installed. One side-effect of installation is that the folder "
-/Developer/Applications/Performance Tools" will have been created and
-will contain an application called "Shark". Double-click on Shark; in
-its "Preferences" window's "Search Paths" pane, use the "+" button to
-add your home directory to the "Patch Files" search path.
+shell> shark --help
 
- Background
+and verifying that that prints a usage summary.
 
-CHUD's Shark application is a user interface to its low-level
-performance monitoring facilities; those facilities provide access to
-high-resolution timers, on-chip debugging information, and OS
-performance counters. Shark allows the user to run sampling sessions,
-which record information about the context in which sampling events
-(such as timer interrupts) occur; at the end of the session, Shark
-processes the sampled data and presents a browsable interface which
-shows the processes, threads, and functions associated with those
-events.
+CHUD consists of several components, including command-line programs,
+GUI applications, kernel extensions, and "frameworks" (collections of
+libraries, headers, and other resources which applications can use to
+access functionality provided by the other components.)  Past versions
+of CCL/OpenMCL have used the CHUD framework libraries to control the
+CHUD profiler.  Even though the rest of CHUD is currently 64-bit aware,
+the frameworks are unfortunately still only available as 32-bit libraries,
+so the traditional way of controlling the profiling facility from OpenMCL
+has only worked from DarwinPPC32 versions.
 
-For many processes, Shark can identify functions (the range of
-addresses corresponding to the address of the first and last
-instructions in the function) by interpreting symbolic information
-contained in the executable file. This strategy enables it to identify
-C and assembler functions in OpenMCL's lisp kernel, but doesn't help
-much in identifying Lisp functions. Fortunately, Shark does have the
-ability to read "patch files" , which associate symbolic names to
-regions of a process's address space), and fortunately OpenMCL can be
-told to move the machine code (the "code vector") associated with a
-compiled function to a static memory area (so that the addresses of
-the first and last instructions in a compiled lisp function remain
-constant); it's possible to assign fixed addresses to the code vectors
-of all functions in the lisp at a given time, and to give symbolic
-names to the memory regions that delimit those code vectors.
+Two of the CHUD component programs are of particular interest:
 
-The process of moving code vectors to a static (and incidentally
-read-only) memory area is sometimes referred to as "purification".
+1) The "Shark" application (often installed in
+"/Developer/Applications/Performance Tools/Shark.app"), which provides
+a graphical user interface for exploring and analyzing profiling results
+and provides tools for creating "sampling configurations" (see below),
+among other things.
 
- A Sampling Sample
+2) the "shark" program ("/usr/bin/shark"), which can be used to control
+the CHUD profiling facility and to collect sampling data, which can then
+be displayed and analyzed in Shark.app.
 
-There's a little bit of flexibility in the order in which these steps
-are performed, but for the sake of argument we'll pretend here that
-there isn't.
+The fact that these two (substantially different) programs have names that
+differ only in alphabetic case may be confusing.  The discussion below
+tries to consistently distinguish between "the shark program" and "the
+Shark application".
 
-1) Run Shark, and put it in "remote" mode.
+Usage synopsis
+--------------
 
-Run Shark. Ensure that it's in "Programmatic (Remote)" mode by
-selecting that option from the "Sampling" menu, or by pressing the key
-equivalent "command-shift-R". In the main Shark window, ensure that
-the sampling type is set to "Time Profile", select "Process" (instead
-of "Everything" ) from the next popup, and doing so should cause the
-third popup to select "Remote Client".
+? (defun fact (n) (if (zerop n) 1 (* n (fact (1- n)))))
+FACT
+? (require "CHUD-METERING")
+"CHUD-METERING"
+("CHUD-METERING")
+? (chud:meter (null (fact 10000)))
+NIL           ; since that large number is not NULL
 
-2) Meter some code in OpenMCL.
+and, a few seconds after the result is returned, a file whose
+name is of the form "session_nnn.mshark" will open in Shark.app.
 
-In OpenMCL, do:
+The fist time that CHUD:METER is used in a lisp session, it'll do a
+few things to prepare subsequent profiling sessions.  Those things
+include:
 
-? (require "CHUD-METERING")
+1) creating a directory to store files that are related to using
+the CHUD tools in this lisp session.  This directory is created in
+the user's home directory and has a name of the form:
 
-and ensure that the code that you want to profile is defined.
+profiling-session-<lisp-kernel>-<pid>_<mm>-<dd>-<yyyy>_<h>.<m>.<s>
 
-? (defun fact (n)
-    (if (zerop n)
-      1
-      (* n (fact (1- n)))))
-FACT
-? (defun fact-n-m-times (m n)
-    (dotimes (i m)
-      (fact n)))
-FACT-N-M-TIMES
+where <pid> is the lisp's process id, <lisp-kernel> is the name of
+the lisp kernel (of all things ...), and the other values provide
+a timestamp.
 
-Then run something with metering enabled:
+2) does whatever needs to be done to ensure that currently-defined
+lisp functions don't move around as the result of GC activity, then
+writes a text file describing the names and addresses of those functions
+to the profiling-session directory created above.  (The naming conventions
+for and format of that file are described in
 
-? (CHUD:METER (fact-n-m-times 1000 1000))
+<http://developer.apple.com/documentation/DeveloperTools/Conceptual/SharkUserGuide/MiscellaneousTopics/chapter_951_section_4.html#//apple_ref/doc/uid/TP40005233-CH14-DontLinkElementID_42>
 
-The first time that CHUD:METER is invoked in a lisp session, it'll:
+3) run the shark program ("/usr/bin/shark") and wait until it's ready to
+receive signals that control its operation.
 
-1. Ensure that Shark is running
+This startup activity typically takes a few seconds; after it's been
+completed, subsequent use of CHUD:METER doesn't involve that overhead.
+(See the discussion of :RESET below.)
 
-2. Move the code vectors of all functions to a static 
-   memory area.
+After any startup activity is complete, CHUD:METER arranges to send
+a "start profiling" signal to the running shark program, executes
+the form, sends a "stop profiling" signal to the shark program, and
+reads its diagnostic output, looking for the name of the ".mshark"
+file it produces.  If it's able to find this filename, it arranges
+for "Shark.app" to open it
 
-3. Write a Shark "spatch" file to the user's home 
-   directory (which is where we configure Shark to look 
-   for such files back in the "Prerequisites" section.)
-   See also CHUD:*SPATCH-DIRECTORY-PATH*.
+Profiling "configurations".
+--------------------------
 
-4. Try to ensure that Shark is running in "remote" mode. 
-   (I don't know of any way in which this can be ensured 
-   programatically, so it'll just keep asking whether or 
-   not Shark's in remote mode until you say "y" and the 
-   lisp metering code detects that that's the case.)
+By default, a shark profiling session will:
+a) use "time based" sampling, to periodically interrupt the lisp
+   process and note the value of the program counter and at least
+   a few levels of call history.
+b) do this sampling once every millisecond
+c) run for up to 30 seconds, unless told to stop earlier.
 
-Those steps may take anywhere from "a few" to "several" seconds; steps
-2 and 3 are probably the most expensive and depend on how many
-functions are in the lisp image, how big they are, etc.
+This is known as "the default configuration"; it's possible to use
+items on the "Config" menu in the Shark application to create alternate
+configurations which provide different kinds of profiling parameters
+and to save these configurations in files for subsequent reuse.
+(The set of things that CHUD knows how to monitor is large and interesting.)
 
-On every invocation of CHUD:METER, it'll tell Shark to start a
-metering session, execute the form which is its required argument,
-tell Shark to stop the session, and return the form's result(s).
+You use alternate profiling configurations (created and "exported" via
+Shark.app) with CHUD:METER, but the interface is a little awkward.
 
-After it's been told to stop the sampling session, Shark will analyze
-the sampling data it obtained and display the results. In this
-example, it's reasonable to assume that some CCL package functions
-related to bignum multiplication dominate the execution time. Lisp
-functions that show up in Shark's session window will claim to be
-defined in the SPATCH library; their "names" will generally look like
-their printed representations.
+Reference
+---------
 
- Limitations
+CHUD:*SHARK-CONFIG-FILE*   [Variable]
 
-It's generally tempting to start redefining functions that have
-longer-than-expected execution times. That's possibly the right thing
-to do in general, but (because of the way that the spatch mechanism
-works) it's hard to get meaningful results: Shark can only give names
-to lisp functions that're in its .spatch file, and will continue to
-use cached informaton from that .spatch file until it quits. General
-(GC-able) lisp functions - whose code-vectors might move around in
-memory - tend to confuse Shark (and at least some versions get
-confused enough that they may crash while trying to report time spent
-in functions that aren't where they used to be ...)
+When non-null, this should be the pathname of an alternate profiling
+configuration file created by the "Config Editor" in Shark.app.
 
-After things get a little bit out-of-whack (in terms of newly defined
-lisp functions), it's often necessary to quit both Shark and OpenMCL,
-load the new-and-improved code into the lisp, and try again, hoping
-for better results.
+(CHUD:METER form &key (reset nil) (debug-output nil))  [Macro]
 
-After CHUD:METER has done its first-time setup, it's generally
-necessary to quit both Shark and OpenMCL if either quits in order to
-get them back in synch again.
+Executes FORM (an arbitrary lisp form) and returns whatever result(s)
+it returns, with CHUD profiling enabled during the form's execution.
+Tries to determine the name of the session file (*.mshark) to which
+the shark program wrote profiling data and opens this file in the
+Shark application.
 
-Despite these limitations, it's probably fair to say that this is way,
-way better than nothing.
+Arguments:
 
- Reference
+debug-output   - when non-nil, causes output generated by the shark program to
+                 be echoed to *TERMINAL-IO*.  For debugging.
+reset          - when non-nil, terminates any running instance of the
+                 shark program created by previous invocations of CHUD:METER
+                 in this lisp session, generates a new .spatch file 
+                 (describing the names and addresses of lisp functions),
+                 and starts a new instance of the shark program; if
+                 CHUD:*SHARK-CONFIG-FILE* is non-NIL when this new instance
+                 is started, that instance is told to use the specified
+                 config file for profiling (in lieu of the default profiling
+                 configuration.)
 
-(CHUD:METER form &key (duration 0) (frequency 1))  [Macro]
-
-Ensures that access to the "remote sampling facility" (Shark, usually)
-has been acquired, ensure that code vectors have been purified and
-that an spatch file for the current process is writen to the directory
-named by CHUD:*SPATCH-DIRECTORY-PATH* (or the user's home directory),
-and starts and stops the sampling facility around execution of <form>.
-Returns whatever values execution of <form> returns.
-
-Arguments
-  <form>        an arbitrary lisp expression
-  <frequency>   sampling frequency in milliseconds
-  <duration>    total number of sampling intervals, 0 implies "infinite".
-
-It seems that the <frequency> and <duration> arguments have no effect;
-the sampling frequency and duration can be set via Shark's "configuration
-editor" dialog.
-
-CHUD:*SPATCH-DIRECTORY-PATH*  [Special Variable]
-
-If non-NIL, should be a pathname whose directory component matches the
-"Patch FIles" search path in Shark's Preferences.  When this variable
-is NIL, USER-HOMEDIR-PATHNAME is used instead.
-
-
- Acknowledgments
+Acknowledgments
+---------------
 
 Both Dan Knapp and Hamilton Link have posted similar CHUD interfaces

release/1.2/source/objc-bridge/objc-clos.lisp

@@ -742 +742 @@
     instance))
 
-(defmethod terminate ((instance objc:objc-object))
-  (objc-message-send instance "release"))
 
 

release/1.2/source/objc-bridge/objc-support.lisp

@@ -187 +187 @@
   (#/retain instance))
 
-
+;;; May have to create/release autorelease pools before the bridge
+;;; is fully reinitialized, so use low-level OBJC-MESSAGE-SEND
+;;; and @class.
 (defun create-autorelease-pool ()
-  (#/init (#/alloc ns:ns-autorelease-pool)))
+  (objc-message-send
+   (objc-message-send (@class "NSAutoreleasePool") "alloc") "init"))
 
 (defun release-autorelease-pool (p)
-  (#/release p))
+  (objc-message-send p "release" :void))
 
 
@@ -486 +489 @@
 
                                          
+(defmethod terminate ((instance objc:objc-object))
+  (objc-message-send instance "release"))