1.0.36.20: prettier WITH-COMPILATION-UNIT documentation

 * Adjust the docstring for the benefit of the manual, and
   teach docstrings.lisp more about parsing embedded examples.

diff --git a/doc/manual/docstrings.lisp b/doc/manual/docstrings.lisp
index c258d20..27d23a1 100644 (file)
--- a/doc/manual/docstrings.lisp
+++ b/doc/manual/docstrings.lisp
@@ -499,11 +499,16 @@ semicolon, and the previous line is empty"
          (empty-p (1- line-number) lines))))
 
 (defun collect-lisp-section (lines line-number)
-  (let ((lisp (loop for index = line-number then (1+ index)
-                    for line = (and (< index (length lines)) (svref lines index))
-                    while (indentation line)
-                    collect line)))
-    (values (length lisp) `("@lisp" ,@lisp "@end lisp"))))
+  (flet ((maybe-line (index)
+           (and (< index (length lines)) (svref lines index))))
+    (let ((lisp (loop for index = line-number then (1+ index)
+                      for line = (maybe-line index)
+                      while (or (indentation line)
+                                ;; Allow empty lines in middle of lisp sections.
+                                (let ((next (1+ index)))
+                                  (lisp-section-p (maybe-line next) next lines)))
+                      collect line)))
+     (values (length lisp) `("@lisp" ,@lisp "@end lisp")))))
 
 ;;; itemized sections
 

diff --git a/src/compiler/main.lisp b/src/compiler/main.lisp
index 102a843..c0c6a81 100644 (file)
--- a/src/compiler/main.lisp
+++ b/src/compiler/main.lisp
@@ -161,38 +161,43 @@ Following options are defined:
       Supplying POLICY NIL is equivalent to the option not being supplied at
       all, ie. dynamic scoping of policy does not take place.
 
-      This option is an SBCL specific EXPERIMENTAL extension: Interface
+      This option is an SBCL-specific experimental extension: Interface
       subject to change.
 
-      Examples:
-
-        ;; Prevent OPTIMIZE proclamations from file leaking, and
-        ;; restrict SAFETY to 3 for the LOAD -- otherwise uses the
-        ;; current global policy.
-        (with-compilation-unit (:policy '(optimize))
-          (restrict-compiler-policy 'safety 3)
-          (load \"foo.lisp\"))
-
-        ;; Load using default policy instead of the current global one, except
-        ;; for DEBUG 3.
-        (with-compilation-unit (:policy '(optimize debug) :override t)
-          (load \"foo.lisp\"))
-
-        ;; Same as if :POLICY had not been specified at all: SAFETY 3
-        ;; leaks outside WITH-COMPILATION-UNIT.
-        (with-compilation-unit (:policy nil)
-          (declaim (optimize safety)))
-
   :SOURCE-PLIST Plist-Form
       Attaches the value returned by the Plist-Form to internal debug-source
-      information of functions compiled in within the dynamic contour.
-      Primarily for use by development environments, in order to eg. associate
-      function definitions with editor-buffers. Can be accessed as
-      SB-INTROSPECT:DEFINITION-SOURCE-PLIST. If multiple, nested
-      WITH-COMPILATION-UNITs provide :SOURCE-PLISTs, they are appended
-      togather, innermost left. Unaffected by :OVERRIDE.
+      information of functions compiled in within the dynamic extent of BODY.
 
-      This SBCL is and specific extension."
+      Primarily for use by development environments, in order to eg. associate
+      function definitions with editor-buffers. Can be accessed using
+      SB-INTROSPECT:DEFINITION-SOURCE-PLIST.
+
+      If an outer WITH-COMPILATION-UNIT form also provide a SOURCE-PLIST, it
+      is appended to the end of the provided SOURCE-PLIST. Unaffected
+      by :OVERRIDE.
+
+      This is an SBCL-specific extension.
+
+Examples:
+
+  ;; Prevent proclamations from the file leaking, and restrict
+  ;; SAFETY to 3 -- otherwise uses the current global policy.
+  (with-compilation-unit (:policy '(optimize))
+    (restrict-compiler-policy 'safety 3)
+    (load \"foo.lisp\"))
+
+  ;; Using default policy instead of the current global one,
+  ;; except for DEBUG 3.
+  (with-compilation-unit (:policy '(optimize debug)
+                          :override t)
+    (load \"foo.lisp\"))
+
+  ;; Same as if :POLICY had not been specified at all: SAFETY 3
+  ;; proclamation leaks out from WITH-COMPILATION-UNIT.
+  (with-compilation-unit (:policy nil)
+    (declaim (optimize safety))
+    (load \"foo.lisp\"))
+"
   `(%with-compilation-unit (lambda () ,@body) ,@options))
 
 (defvar *source-plist* nil)

diff --git a/version.lisp-expr b/version.lisp-expr
index 97e21db..dcf3f76 100644 (file)
--- a/version.lisp-expr
+++ b/version.lisp-expr
@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.36.19"
+"1.0.36.20"