Steel Bank Common Lisp

Update of /cvsroot/sbcl/sbcl/doc/manual
In directory fdv4jf1.ch3.sourceforge.com:/tmp/cvs-serv28702/doc/manual

Modified Files:
	beyond-ansi.texinfo docstrings.lisp 
	package-locks-extended.texinfo sbcl.texinfo 
Log Message:
1.0.28.63: SB-EXT:DEFINE-HASH-TABLE-TEST

 * Based on old SB-INT:DEFINE-HASH-TABLE-TEST, but:
   ** macro, not a function.
   ** only two arguments: name of the test function, and the hash function
      (which can also be a lambda form.)
   ** :TEST accepts both 'NAME, and #'NAME as well.
   ** pick up redefinitions of the test and hash-function without
      re-executing the D-H-T-T form.
   ** protected by package locks.

 * MAKE-HASH-TABLE :HASH-FUNCTION supported as well. EQ-based hashing
   not legal for user-provided hash functions, accidents prevented by
   wrapping functions which may return a true secondary value in
   a closure.

 * Documentation -- other hash-table extensions as well.

 * Documentation generation improvements:
   ** use the shortest package name available -- CL:FOO, not
      COMMON-LISP:FOO.
   ** kludge around texi2pdf making &key and company bold
   ** add exceptions so that we don't format words ANSI and CLHS
      as lowecase symbols.


Index: beyond-ansi.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/beyond-ansi.texinfo,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -d -r1.36 -r1.37
--- beyond-ansi.texinfo	5 Dec 2008 11:31:39 -0000	1.36
+++ beyond-ansi.texinfo	21 May 2009 09:56:16 -0000	1.37
@@ -13,6 +13,7 @@
 * Customization Hooks for Users::
 * Tools To Help Developers::
 * Resolution of Name Conflicts::
+* Hash Table Extensions::
 * Miscellaneous Extensions::
 * Stale Extensions::
 * Efficiency Hacks::
@@ -27,7 +28,8 @@
 maintained without keeping them from being garbage collected, and
 ``finalization'' hooks are available to cause code to be executed when
 an object has been garbage collected. Additionally users can specify
-their own cleanup actions to be executed with garbage collection.
+their own cleanup actions to be executed with garbage collection. See
+also @code{make-hash-table} for information on weak hash tables.
 
 @include fun-sb-ext-finalize.texinfo
 @include fun-sb-ext-cancel-finalization.texinfo
@@ -376,6 +378,23 @@
 argument, which should be a member of the list returned by the condition
 accessor @code{sb-ext:name-conflict-symbols}.
 
+@node    Hash Table Extensions
+@comment  node-name,  next,  previous,  up
+@section Hash Table Extensions
+
+Hash table extensions supported by SBCL are all controlled by keyword
+arguments to @code{make-hash-table}.
+
+@include fun-common-lisp-make-hash-table.texinfo
+
+@include macro-sb-ext-define-hash-table-test.texinfo
+
+@include macro-sb-ext-with-locked-hash-table.texinfo
+
+@include fun-sb-ext-hash-table-synchronized-p.texinfo
+
+@include fun-sb-ext-hash-table-weakness.texinfo
+
 @node    Miscellaneous Extensions
 @comment  node-name,  next,  previous,  up
 @section Miscellaneous Extensions

Index: docstrings.lisp
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/docstrings.lisp,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -d -r1.19 -r1.20
--- docstrings.lisp	2 Jan 2009 14:24:03 -0000	1.19
+++ docstrings.lisp	21 May 2009 09:56:16 -0000	1.20
@@ -83,7 +83,7 @@
   "Characters that might start an itemization in docstrings when
   at the start of a line.")
 
-(defparameter *symbol-characters* "ABCDEFGHIJKLMNOPQRSTUVWXYZ*:-+&"
+(defparameter *symbol-characters* "ABCDEFGHIJKLMNOPQRSTUVWXYZ*:-+&#'"
   "List of characters that make up symbols in a docstring.")
 
 (defparameter *symbol-delimiters* " ,.!?;")
@@ -226,6 +226,10 @@
   (let ((kind (get-kind doc)))
     (format nil "~:(~A~) ~(~A~)" kind (name-using-kind/name kind (get-name doc) doc))))
 
+(defun short-package-name (package)
+  (car (sort (copy-list (cons (package-name package) (package-nicknames package)))
+             #'< :key #'length)))
+
 ;;; Definition titles for DOCUMENTATION instances
 
 (defgeneric title-using-kind/name (kind name doc))
@@ -236,12 +240,12 @@
 
 (defmethod title-using-kind/name (kind (name symbol) doc)
   (declare (ignore kind))
-  (format nil "~A:~A" (package-name (get-package doc)) name))
+  (format nil "~A:~A" (short-package-name (get-package doc)) name))
 
 (defmethod title-using-kind/name (kind (name list) doc)
   (declare (ignore kind))
   (assert (setf-name-p name))
-  (format nil "(setf ~A:~A)" (package-name (get-package doc)) (second name)))
+  (format nil "(setf ~A:~A)" (short-package-name (get-package doc)) (second name)))
 
 (defmethod title-using-kind/name ((kind (eql 'method)) name doc)
   (format nil "~{~A ~}~A"
@@ -390,11 +394,22 @@
                       (clean (cdr x) :key key :optional optional))))))
          (clean (sb-introspect:function-lambda-list (get-name doc))))))))
 
+(defun get-string-name (x)
+  (let ((name (get-name x)))
+    (cond ((symbolp name)
+           (symbol-name name))
+          ((and (consp name) (eq 'setf (car name)))
+           (symbol-name (second name)))
+          ((stringp name)
+           name)
+          (t
+           (error "Don't know which symbol to use for name ~S" name)))))
+
 (defun documentation< (x y)
   (let ((p1 (position (get-kind x) *ordered-documentation-kinds*))
         (p2 (position (get-kind y) *ordered-documentation-kinds*)))
     (if (or (not (and p1 p2)) (= p1 p2))
-        (string< (string (get-name x)) (string (get-name y)))
+        (string< (get-string-name x) (get-string-name y))
         (< p1 p2))))
 
 ;;;; turning text into texinfo
@@ -415,39 +430,44 @@
 
 ;;; line markups
 
+(defvar *not-symbols* '("ANSI" "CLHS"))
+
 (defun locate-symbols (line)
   "Return a list of index pairs of symbol-like parts of LINE."
   ;; This would be a good application for a regex ...
-  (do ((result nil)
-       (begin nil)
-       (maybe-begin t)
-       (i 0 (1+ i)))
-      ((= i (length line))
-       ;; symbol at end of line
-       (when (and begin (or (> i (1+ begin))
-                            (not (member (char line begin) '(#\A #\I)))))
-         (push (list begin i) result))
-       (nreverse result))
-    (cond
-      ((and begin (find (char line i) *symbol-delimiters*))
-       ;; symbol end; remember it if it's not "A" or "I"
-       (when (or (> i (1+ begin)) (not (member (char line begin) '(#\A #\I))))
-         (push (list begin i) result))
-       (setf begin nil
-             maybe-begin t))
-      ((and begin (not (find (char line i) *symbol-characters*)))
-       ;; Not a symbol: abort
-       (setf begin nil))
-      ((and maybe-begin (not begin) (find (char line i) *symbol-characters*))
-       ;; potential symbol begin at this position
-       (setf begin i
-             maybe-begin nil))
-      ((find (char line i) *symbol-delimiters*)
-       ;; potential symbol begin after this position
-       (setf maybe-begin t))
-      (t
-       ;; Not reading a symbol, not at potential start of symbol
-       (setf maybe-begin nil)))))
+  (let (result)
+    (flet ((grab (start end)
+             (unless (member (subseq line start end) '("ANSI" "CLHS"))
+               (push (list start end) result))))
+      (do ((begin nil)
+           (maybe-begin t)
+           (i 0 (1+ i)))
+          ((= i (length line))
+           ;; symbol at end of line
+           (when (and begin (or (> i (1+ begin))
+                                (not (member (char line begin) '(#\A #\I)))))
+             (grab begin i))
+           (nreverse result))
+        (cond
+          ((and begin (find (char line i) *symbol-delimiters*))
+           ;; symbol end; remember it if it's not "A" or "I"
+           (when (or (> i (1+ begin)) (not (member (char line begin) '(#\A #\I))))
+             (grab begin i))
+           (setf begin nil
+                 maybe-begin t))
+          ((and begin (not (find (char line i) *symbol-characters*)))
+           ;; Not a symbol: abort
+           (setf begin nil))
+          ((and maybe-begin (not begin) (find (char line i) *symbol-characters*))
+           ;; potential symbol begin at this position
+           (setf begin i
+                 maybe-begin nil))
+          ((find (char line i) *symbol-delimiters*)
+           ;; potential symbol begin after this position
+           (setf maybe-begin t))
+          (t
+           ;; Not reading a symbol, not at potential start of symbol
+           (setf maybe-begin nil)))))))
 
 (defun texinfo-line (line)
   "Format symbols in LINE texinfo-style: either as code or as
@@ -686,7 +706,14 @@
                "deffn"))
             (map 'string (lambda (char) (if (eql char #\-) #\Space char)) (string kind))
             (title-name doc)
-            (lambda-list doc))))
+            ;; &foo would be amusingly bold in the pdf thanks to TeX/Texinfo
+            ;; interactions,so we escape the ampersand -- amusingly for TeX.
+            ;; sbcl.texinfo defines macros that expand @&key and friends to &key.
+            (mapcar (lambda (name)
+                      (if (member name lambda-list-keywords)
+                          (format nil "@~A" name)
+                          name))
+                    (lambda-list doc)))))
 
 (defun texinfo-index (doc)
   (let ((title (title-name doc)))

Index: package-locks-extended.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/package-locks-extended.texinfo,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- package-locks-extended.texinfo	7 Nov 2007 07:24:55 -0000	1.9
+++ package-locks-extended.texinfo	21 May 2009 09:56:16 -0000	1.10
@@ -292,6 +292,9 @@
 @item
 Using it as the class-name argument to setf of find-class.
 
+@item
+Defining it as a hash table test using @code{sb-ext:define-hash-table-test}.
+
 @end enumerate
 
 @node Package Lock Dictionary

Index: sbcl.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/sbcl.texinfo,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- sbcl.texinfo	30 Apr 2007 11:26:09 -0000	1.18
+++ sbcl.texinfo	21 May 2009 09:56:16 -0000	1.19
@@ -46,6 +46,21 @@
 
 @ifnottex
 
+@c We use @&key, etc to escape & from TeX in lambda lists --
+@c so we need to define them for info as well.
+@macro &optional
+&optional
+@end macro
+@macro &rest
+&rest
+@end macro
+@macro &key
+&key
+@end macro
+@macro &body
+&body
+@end macro
+
 @node Top
 @comment  node-name,  next,  previous,  up
 @top sbcl