master: doc: define and clean up docstring syntax
melisgl via Sbcl-commits <[email protected]> Sat, 30 May 2026 10:18:16 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via 2868d4dd0e946ab8e0bbea5e1aee778e8873184d (commit)
from cec8b3965734dea6c08976ee9a9b0fa66f513577 (commit)
- Log -----------------------------------------------------------------
commit 2868d4dd0e946ab8e0bbea5e1aee778e8873184d
Author: Gabor Melis <[email protected]>
Date: Fri May 29 12:47:08 2026 +0200
doc: define and clean up docstring syntax
Previously, the format was ad-hoc and implicitly defined by
doc/manual/docstrings.lisp. Now, it is a bit less ad-hoc and still
implicitly defined docstrings.lisp.
The syntax is now a simple, strict subset of Markdown with escaping
extensions. The long comment near the top of docstrings.lisp has the
documentation.
Some notable changes:
- Markdown backticks are supported (e.g. `exit`(3),
`/usr/local/bin/`).
- When the heuristic codification is overly eager, use backslashes to
prevent codification (e.g. \\HTTP, where the backslash is doubled
assuming that this is in a docstring).
- It is now possible to have code that's not downcased
(`\\\\AC_LOCAL`, backslashes doubled again).
- Fenced code blocks are supported (but use them sparingly).
- Texinfo @itemize is used instead of @table.
- Texinfo @var was inconsistently used at best. What used to be @var
is now simply @code.
For the user, the most visible effect of this change is that the
manual has much fewer errors in codification, and a few docstrings
have backticks and escapes in them, which should be acceptably
readable in the sources or via CL:DOCUMENTATION.
---
NEWS | 2 +
contrib/sb-bsd-sockets/inet4.lisp | 4 +-
contrib/sb-bsd-sockets/inet6.lisp | 4 +-
contrib/sb-bsd-sockets/local.lisp | 6 +-
contrib/sb-concurrency/mailbox.lisp | 6 +-
contrib/sb-introspect/introspect.lisp | 2 +-
contrib/sb-md5/md5.lisp | 58 ++--
contrib/sb-posix/interface.lisp | 6 +-
doc/manual/docstrings.lisp | 595 ++++++++++++++++++++++------------
doc/manual/threading.texinfo | 1 +
src/code/alien-callback.lisp | 24 +-
src/code/cold-init.lisp | 10 +-
src/code/deadline.lisp | 13 +-
src/code/defpackage.lisp | 20 +-
src/code/error.lisp | 2 +-
src/code/filesys.lisp | 4 +-
src/code/final.lisp | 62 ++--
src/code/foreign-load.lisp | 8 +-
src/code/loop.lisp | 4 +-
src/code/macros.lisp | 39 ++-
src/code/misc-aliens.lisp | 2 +-
src/code/ntrace.lisp | 141 ++++----
src/code/pprint.lisp | 20 +-
src/code/run-program.lisp | 222 +++++++------
src/code/save.lisp | 148 +++++----
src/code/target-alieneval.lisp | 46 +--
src/code/target-extensions.lisp | 2 +-
src/code/target-hash-table.lisp | 183 ++++++-----
src/code/target-package.lisp | 9 +-
src/code/target-pathname.lisp | 8 +-
src/code/target-random.lisp | 3 +-
src/code/target-thread.lisp | 6 +-
src/code/timer.lisp | 13 +-
src/code/traceroot.lisp | 52 +--
src/code/typep.lisp | 3 +-
src/code/unix.lisp | 2 +-
src/cold/exports.lisp | 21 +-
src/compiler/ir1-translators.lisp | 25 +-
src/compiler/macros.lisp | 4 +-
src/compiler/main.lisp | 143 ++++----
src/pcl/generic-functions.lisp | 8 +-
src/pcl/gray-streams.lisp | 10 +-
42 files changed, 1117 insertions(+), 824 deletions(-)
diff --git a/NEWS b/NEWS
index bdfc34262..217bc2278 100644
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,8 @@ changes relative to sbcl-2.6.5:
* bug fix: TRACE no longer fails when trying to print a return value that
cannot be printed readble and *PRINT-READABLY* is true.
* documentation: SB-INTROSPECT is documented.
+ * documentation: fixed many typesetting problems and typos in the user
+ manual.
changes in sbcl-2.6.5 relative to sbcl-2.6.4:
* minor incompatible change: the condition signalled when an accessed slot
diff --git a/contrib/sb-bsd-sockets/inet4.lisp b/contrib/sb-bsd-sockets/inet4.lisp
index 69b405ab2..bee8ec7cd 100644
--- a/contrib/sb-bsd-sockets/inet4.lisp
+++ b/contrib/sb-bsd-sockets/inet4.lisp
@@ -9,9 +9,9 @@
Examples:
- (make-instance 'sb-bsd-sockets:inet-socket :type :stream :protocol :tcp)
+ (make-instance 'sb-bsd-sockets:inet-socket :type :stream :protocol :tcp)
- (make-instance 'sb-bsd-sockets:inet-socket :type :datagram :protocol :udp)
+ (make-instance 'sb-bsd-sockets:inet-socket :type :datagram :protocol :udp)
")))
(defun address-numbers/v4 (address)
diff --git a/contrib/sb-bsd-sockets/inet6.lisp b/contrib/sb-bsd-sockets/inet6.lisp
index f0007498f..319d47ce7 100644
--- a/contrib/sb-bsd-sockets/inet6.lisp
+++ b/contrib/sb-bsd-sockets/inet6.lisp
@@ -9,9 +9,9 @@
Examples:
- (make-instance 'sb-bsd-sockets:inet6-socket :type :stream :protocol :tcp)
+ (make-instance 'sb-bsd-sockets:inet6-socket :type :stream :protocol :tcp)
- (make-instance 'sb-bsd-sockets:inet6-socket :type :datagram :protocol :udp)
+ (make-instance 'sb-bsd-sockets:inet6-socket :type :datagram :protocol :udp)
")))
(defun address-numbers/v6 (address)
diff --git a/contrib/sb-bsd-sockets/local.lisp b/contrib/sb-bsd-sockets/local.lisp
index aedaf2b54..bb5580927 100644
--- a/contrib/sb-bsd-sockets/local.lisp
+++ b/contrib/sb-bsd-sockets/local.lisp
@@ -6,7 +6,7 @@
(defclass local-socket (socket)
((family :initform sockint::af-local))
(:documentation
- "Class representing local domain (AF_LOCAL) sockets,
+ "Class representing local domain (`\\\\AF_LOCAL`) sockets,
also known as unix-domain sockets."))
(defmethod socket-namestring ((socket local-socket))
@@ -41,8 +41,8 @@ also known as unix-domain sockets."))
(defclass local-abstract-socket (local-socket) ()
(:documentation
- "Class representing local domain (AF_LOCAL) sockets with addresses
-in the abstract namespace."))
+ "Class representing local domain (`\\\\AF_LOCAL`) sockets with
+addresses in the abstract namespace."))
(defmethod make-sockaddr-for ((socket local-abstract-socket)
&optional sockaddr &rest address)
diff --git a/contrib/sb-concurrency/mailbox.lisp b/contrib/sb-concurrency/mailbox.lisp
index c46ba68cb..3225b6218 100644
--- a/contrib/sb-concurrency/mailbox.lisp
+++ b/contrib/sb-concurrency/mailbox.lisp
@@ -127,9 +127,9 @@ message could be received."
from MAILBOX, or returns NIL if no messages are pending.
Note: Concurrent threads may be snarfing messages during the run of
-this function, so even though X,Y appear right next to each other in
-the result, does not necessarily mean that Y was the message sent
-right after X."
+this function, so even `X` and `Y` appearing right next to each other
+in the result does not necessarily mean that `Y` was the message sent
+right after `X`."
(prog* ((msgs '())
(sem (mailbox-semaphore mailbox))
(queue (mailbox-queue mailbox))
diff --git a/contrib/sb-introspect/introspect.lisp b/contrib/sb-introspect/introspect.lisp
index 56c3e7fc7..b3a7fffdc 100644
--- a/contrib/sb-introspect/introspect.lisp
+++ b/contrib/sb-introspect/introspect.lisp
@@ -246,7 +246,7 @@ the sexp.")
the time of compilation. NIL if not compiled from a file.")
(plist
nil
- :documentation "The SOURCE-PLIST from WITH-COMPILATION-UNIT in effect
+ :documentation "The `SOURCE-PLIST` from WITH-COMPILATION-UNIT in effect
when the file was compiled.")
;; Any extra metadata that the caller might be interested in. For
;; example, DEFINITION-SOURCE of a method contains the specializers
diff --git a/contrib/sb-md5/md5.lisp b/contrib/sb-md5/md5.lisp
index cc2cfe185..501c521af 100644
--- a/contrib/sb-md5/md5.lisp
+++ b/contrib/sb-md5/md5.lisp
@@ -270,7 +270,7 @@ where a is the intended low-order byte and d the high-order byte."
(deftype md5-regs ()
"The working state of the MD5 algorithm, which contains the 4 32-bit
-registers A, B, C and D."
+registers `\\\\A`, `\\\\B`, `\\\\C` and `\\\\D`."
`(ub32-vector 4))
(defmacro md5-regs-a (regs)
@@ -286,13 +286,13 @@ registers A, B, C and D."
`(ub32-aref ,regs 3))
(defconstant +md5-magic-a+ (assemble-ub32 #x01 #x23 #x45 #x67)
- "Initial value of Register A of the MD5 working state.")
+ "Initial value of Register `\\\\A` of the MD5 working state.")
(defconstant +md5-magic-b+ (assemble-ub32 #x89 #xab #xcd #xef)
- "Initial value of Register B of the MD5 working state.")
+ "Initial value of Register `\\\\B` of the MD5 working state.")
(defconstant +md5-magic-c+ (assemble-ub32 #xfe #xdc #xba #x98)
- "Initial value of Register C of the MD5 working state.")
+ "Initial value of Register `\\\\C` of the MD5 working state.")
(defconstant +md5-magic-d+ (assemble-ub32 #x76 #x54 #x32 #x10)
- "Initial value of Register D of the MD5 working state.")
+ "Initial value of Register `\\\\D` of the MD5 working state.")
(declaim (inline initial-md5-regs))
(defun initial-md5-regs ()
@@ -314,8 +314,8 @@ registers A, B, C and D."
(defun update-md5-block (regs block)
"This is the core part of the MD5 algorithm. It takes a complete 16
-word block of input, and updates the working state in A, B, C, and D
-accordingly."
+word block of input, and updates the working state in `\\\\A`,
+`\\\\B`, `\\\\C`, and `\\\\D` accordingly."
(declare (type md5-regs regs)
(type md5-block block)
(optimize (speed 3) (safety 0) (space 0) (debug 0) #+lw-int32 (float 0)))
@@ -358,7 +358,7 @@ accordingly."
(declaim (inline fill-block fill-block-ub8 fill-block-char))
(defun fill-block-ub8 (block buffer offset)
"Convert a complete 64 (unsigned-byte 8) input vector segment
-starting from `offset' into the given 16 word MD5 block."
+starting from OFFSET into the given 16 word MD5 block."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block)
(type (simple-array (unsigned-byte 8) (*)) buffer)
@@ -384,7 +384,7 @@ starting from `offset' into the given 16 word MD5 block."
(defun fill-block-char (block buffer offset)
"DEPRECATED: Convert a complete 64 character input string segment
-starting from `offset' into the given 16 word MD5 block."
+starting from OFFSET into the given 16 word MD5 block."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block)
(type simple-string buffer)
@@ -412,9 +412,9 @@ starting from `offset' into the given 16 word MD5 block."
(defun fill-block (block buffer offset)
"Convert a complete 64 byte input vector segment into the given 16
word MD5 block. This currently works on (unsigned-byte 8) and
-character simple-arrays, via the functions `fill-block-ub8' and
-`fill-block-char' respectively. Note that it will not work correctly
-on character simple-arrays if `char-code-limit' is greater than 256."
+character simple-arrays, via the functions FILL-BLOCK-UB8 and
+FILL-BLOCK-CHAR respectively. Note that it will not work correctly
+on character simple-arrays if CHAR-CODE-LIMIT is greater than 256."
(declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
(type md5-block block)
(type (simple-array * (*)) buffer)
@@ -431,7 +431,7 @@ on character simple-arrays if `char-code-limit' is greater than 256."
(declaim (inline md5regs-digest))
(defun md5regs-digest (regs)
"Create the final 16 byte message-digest from the MD5 working state
-in `regs'. Returns a (simple-array (unsigned-byte 8) (16))."
+in REGS. Returns a (simple-array (unsigned-byte 8) (16))."
(declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
#+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
(type md5-regs regs))
@@ -474,9 +474,9 @@ in `regs'. Returns a (simple-array (unsigned-byte 8) (16))."
(declaim (inline copy-to-buffer))
(defun copy-to-buffer (from from-offset count buffer buffer-offset)
- "Copy a partial segment from input vector `from' starting at
-`from-offset' and copying `count' elements into the 64 byte buffer
-starting at `buffer-offset'."
+ "Copy a partial segment from input vector FROM starting at
+FROM-OFFSET and copying COUNT elements into the 64 byte buffer
+starting at BUFFER-OFFSET."
(declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
#+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
(type sb-int:index from-offset)
@@ -510,12 +510,12 @@ starting at `buffer-offset'."
from-index))))))
(defun update-md5-state (state sequence &key (start 0) (end (length sequence)))
- "Update the given md5-state from `sequence', which is either a
+ "Update the given md5-state from SEQUENCE, which is either a
simple-string or a simple-array with element-type (unsigned-byte 8),
-bounded by `start' and `end', which must be numeric bounding-indices.
+bounded by START and END, which must be numeric bounding-indices.
Note that usage on simple-strings is DEPRECATED, since this will not
-work correctly if `char-code-limit' is more than 256. String input
-should be converted to (unsigned-byte 8) simple-arrays with
+work correctly if CHAR-CODE-LIMIT is more than 256. String input
+should be converted to (UNSIGNED-BYTE 8) simple-arrays with
external-format conversion routines beforehand."
(declare (type md5-state state)
(type (simple-array * (*)) sequence)
@@ -591,8 +591,8 @@ by processing any remaining input in its buffer, with suitable padding
and appended bit-length, as specified by the MD5 standard.
The resulting MD5 message-digest is returned as an array of sixteen
-(unsigned-byte 8) values. Calling `update-md5-state' after a call to
-`finalize-md5-state' results in unspecified behaviour."
+(unsigned-byte 8) values. Calling UPDATE-MD5-STATE after a call to
+FINALIZE-MD5-STATE results in unspecified behaviour."
(declare (type md5-state state)
(optimize (speed 3) (safety 1) (space 0) (debug 1) #+lw-int32 (float 0)))
(locally
@@ -633,7 +633,7 @@ The resulting MD5 message-digest is returned as an array of sixteen
;;; High-Level Drivers
(defun md5sum-sequence (sequence &key (start 0) end)
- "Calculate the MD5 message-digest of data in `sequence', which should
+ "Calculate the MD5 message-digest of data in SEQUENCE, which should
be a 1d simple-array with element type (unsigned-byte 8). On CMU CL
and SBCL non-simple and non-1d arrays with this element-type are also
supported."
@@ -666,8 +666,8 @@ supported."
(defun md5sum-string (string &key (external-format :default) (start 0) end)
"Calculate the MD5 message-digest of the binary representation of
-`string' (as octets) in the external format specified by
-`external-format'. The boundaries `start' and `end' refer to character
+STRING (as octets) in the external format specified by
+EXTERNAL-FORMAT. The boundaries START and END refer to character
positions in the string, not to octets in the resulting binary
representation. The permissible external format specifiers are
determined by the underlying implementation."
@@ -716,16 +716,16 @@ determined by the underlying implementation."
(eval-when (:compile-toplevel :load-toplevel :execute)
(defconstant +buffer-size+ (* 128 1024)
- "Size of internal buffer to use for `md5sum-stream' and `md5sum-file'
+ "Size of internal buffer to use for MD5SUM-STREAM and MD5SUM-FILE
operations. This should be a multiple of 64, the MD5 block size."))
(deftype buffer-index () `(integer 0 ,+buffer-size+))
(defun md5sum-stream (stream)
- "Calculate an MD5 message-digest of the contents of `stream'. Its
+ "Calculate an MD5 message-digest of the contents of STREAM. Its
element-type has to be (unsigned-byte 8). Use on character streams is
DEPRECATED, as this will not work correctly on implementations with
-`char-code-limit' > 256 and ignores character coding issues."
+CHAR-CODE-LIMIT > 256 and ignores character coding issues."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
(locally
(declare (optimize (safety 1) (debug 0)))
@@ -755,7 +755,7 @@ DEPRECATED, as this will not work correctly on implementations with
(stream-element-type stream) stream))))))
(defun md5sum-file (pathname)
- "Calculate the MD5 message-digest of the file specified by `pathname'."
+ "Calculate the MD5 message-digest of the file specified by PATHNAME."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
(with-open-file (stream pathname :element-type '(unsigned-byte 8))
(md5sum-stream stream)))
diff --git a/contrib/sb-posix/interface.lisp b/contrib/sb-posix/interface.lisp
index 0e1570164..06918ee1e 100644
--- a/contrib/sb-posix/interface.lisp
+++ b/contrib/sb-posix/interface.lisp
@@ -322,7 +322,8 @@
(arg alien-pointer-to-anything-or-nil))
(define-protocol-class flock alien-flock ()
((type :initarg :type :accessor flock-type
- :documentation "Type of lock; F_RDLCK, F_WRLCK, F_UNLCK.")
+ :documentation "Type of lock; `\\\\F_RDLCK`, `\\\\F_WRLCK`,
+`\\\\F_UNLCK`.")
(whence :initarg :whence :accessor flock-whence
:documentation "Flag for starting offset.")
(start :initarg :start :accessor flock-start
@@ -334,7 +335,8 @@
;; so we initialize it to 0.
(pid :initform 0 :reader flock-pid
:documentation
- "Process ID of the process holding the lock; returned with F_GETLK."))
+ "Process ID of the process holding the lock;
+ returned with `\\\\F_GETLK`."))
(:documentation "Class representing locks used in fcntl(2)."))
(define-entry-point "fcntl" (fd cmd &optional (arg nil argp))
(if argp
diff --git a/doc/manual/docstrings.lisp b/doc/manual/docstrings.lisp
index 0bcd20eeb..df899e9bd 100644
--- a/doc/manual/docstrings.lisp
+++ b/doc/manual/docstrings.lisp
@@ -6,12 +6,84 @@
;;;; public domain and is provided with absolutely no warranty. See
;;;; the COPYING file for more information.
;;;;
-;;;; Written by Rudi Schlatte <[email protected]>, mangled
-;;;; by Nikodemus Siivola.
+;;;; Written by Rudi Schlatte <[email protected]>, mangled by
+;;;; Nikodemus Siivola. Brought closer to Markdown by Gabor Melis.
+
+;;;; This code can convert a strict subset of Markdown to Texinfo.
+;;;; Supported:
+;;;;
+;;;; - Inline code: `set this with monospace`
+;;;;
+;;;; - Indented code blocks are indented with 4 extra spaces after a
+;;;; blank line:
+;;;;
+;;;; Like this:
+;;;;
+;;;; void main();
+;;;;
+;;;; - Fenced code blocks are indented at the normal level after a
+;;;; blank line:
+;;;;
+;;;; ```
+;;;; void main();
+;;;; ```
+;;;;
+;;;; Use fenced code blocks only when you have consecutive code
+;;;; blocks, which would be collapsed into a single code block
+;;;; when indented.
+;;;;
+;;;; - Itemized lists (like this one). List items can span multiple
+;;;; lines.
+;;;;
+;;;; - Nested lists are indented 4 spaces. A blank line required
+;;;; before the first one.
+;;;;
+;;;; Codification and Downcasing
+;;;; ---------------------------
+;;;
+;;;; Summary: Some text in docstrings is automatically codified (e.g.
+;;;; FOO -> `FOO`) and most code is downcased.
+;;;;
+;;;; We approximate the semantics of PAX::@CODIFICATION with the
+;;;; settings PAX:*DOCUMENT-UPPERCASE-IS-CODE* and
+;;;; PAX:*DOCUMENT-DOWNCASE-UPPERCASE-CODE* both true.
+;;;;
+;;;; - Fully-qualified all-uppercase string representatation of
+;;;; symbols are codified (SB-EXT:CAS, :XYZ).
+;;;;
+;;;; - All-uppercase SYMBOL-NAMEs accessible in the package that was
+;;;; in effect when the definition with the docstring was compiled
+;;;; are codified.
+;;;;
+;;;; - When at least 3 uppercase characters are followed by a
+;;;; lowercase character (e.g. SETFable), then the uppercase prefix
+;;;; is codified with the previous rules.
+;;;;
+;;;; Detecting the package is a heuristic endeavour. See
+;;;; GUESS-PACKAGE-FROM-ARGLIST and PACKAGE-OVERRIDE.
+;;;;
+;;;; When there is no corresponding symbol, the Markdown backtick
+;;;; syntax (`PRINT`) can be used to codify.
+;;;;
+;;;; When there are no lowercase nor #\" characters in inline code (as
+;;;; opposed to code blocks), be it auto-codified or explicitly
+;;;; backticked, it's downcased.
+;;;;
+;;;; When there is a corresponding symbol, but codification or
+;;;; downcasing should not happen, use backslash escapes.
+;;;;
+;;;; Escaping (following PAX::@OVERVIEW-OF-ESCAPING):
+;;;;
+;;;; PRINT -> @code{print} (Should be autolinked, unimplemented)
+;;;; \PRINT -> @code{print} (Prevent autolinking)
+;;;; \\PRINT -> PRINT (Prevent autolinking and codification)
+;;;; `PRINT` -> @code{print} (Should be autolinked, unimplemented)
+;;;; `\PRINT` -> @code{print} (Prevent autolinking)
+;;;; `\\PRINT` -> @code{PRINT} (Prevent autolinking and downcasing)
+;;;;
+;;;; Note that in docstrings, the backslashes need to be doubled.
;;;; TODO
-;;;; * Verbatim text
-;;;; * Quotations
;;;; * Method documentation untested
;;;; * Method sorting, somehow
;;;; * Index for macros & constants?
@@ -20,20 +92,6 @@
;;;; * doc -> internal form -> texinfo (so that non-texinfo format are also
;;;; easily generated)
-;;;; FIXME: The description below is no longer complete. This
-;;;; should possibly be turned into a contrib with proper documentation.
-
-;;;; Formatting heuristics (tweaked to format SAVE-LISP-AND-DIE sanely):
-;;;;
-;;;; Formats SYMBOL as @code{symbol}, or @var{symbol} if symbol is in
-;;;; the argument list of the defun / defmacro.
-;;;;
-;;;; Lines starting with * or - that are followed by intented lines
-;;;; are marked up with @itemize.
-;;;;
-;;;; Lines containing only a SYMBOL that are followed by indented
-;;;; lines are marked up as @table @code, with the SYMBOL as the item.
-
(eval-when (:compile-toplevel :load-toplevel :execute)
(require 'sb-introspect))
@@ -450,24 +508,43 @@ with #\@. Optionally downcase the result."
(defun empty-p (line-number lines)
(and (< -1 line-number (length lines))
(not (indentation (svref lines line-number)))))
+
-;;; line markups
+;;;; Codification
-(defvar *not-code* '("ANSI" "CLHS" "UNIX" "SBCL" "BSD" "C" "A" "I"))
-(defvar *code*
- '(":WINDOW" ":HIDE" ":SHOW-NORMAL" ":SHOW-MAXIMIZED" ":SHOW-MINIMIZED"
- ":SHOW-NO-ACTIVATE" ":SHOW-MIN-NO-ACTIVE" ":SHOW-NA"
- ":SB-CORE-COMPRESSION" ":CONSOLE" ":GUI" ":APPLICATION-TYPE"
- "NODE*" "GUESSED-PC" "SYS" "SPECIALIZER-KIND" "SPECIFIC-SYNTAX"
- "QUALIFIERS*" "SPECIALIZERS*" "OUTER-NAME" "EXTERNAL-NAME"
- "GET-FOO" "RELEASE-FOO" "C-CALL" "BODY-FORM" "ALLOCATION"
- "INITIAL-VALUE" "ARG-NAME" "ARG-TYPE" "FORM" "WHILE"
- "TO-SEC" "TO-USEC" "STOP-SEC" "STOP-USEC" "DEADLINEP"
- "FUNDAMENTAL-CHARACTER-STREAM" "SOURCE-PLIST" "PEEK-TYPE"
- "THREAD-NAME" "THREAD-OBJECT" "NEW-VALUE" "PROCESS"
- "COLON" "ATSIGN" "GATE" "MAILBOX" "QUEUE" "X" "Y"
- "INDEX" "SEQUENCE" "ITERATOR" "STATEMENT"
- "MACROEXPAND-ALL"))
+;;; These wouldn't be necessary if we implemented PAX::@CODIFIABLE and
+;;; PAX::@INTERESTING properly.
+(defvar *not-code* '("A" "I"))
+
+;;; GUESS-PACKAGE-FROM-ARGLIST doesn't always guess right.
+(defvar *docstring-packages*
+ '(("SB-CONCURRENCY:GATEP" "SB-CONCURRENCY")
+ ("SB-CONCURRENCY:MAILBOXP" "SB-CONCURRENCY")
+ ("SB-CONCURRENCY:QUEUEP" "SB-CONCURRENCY")
+ ("SB-EXT:INTERACTIVE-EVAL" "SB-IMPL")
+ ("SB-EXT:PROCESS-P" "SB-IMPL")
+ ("SB-EXT:PROCESS-STATUS-HOOK" "SB-IMPL")
+ ("(SETF SB-EXT:READTABLE-NORMALIZATION)" "SB-IMPL")))
+
+(defun package-override (name)
+ (let ((fully-qualified-name (let ((*package* (find-package :cl)))
+ (prin1-to-string name))))
+ (second (find fully-qualified-name *docstring-packages*
+ :key #'first :test #'equal))))
+
+#+nil
+(let ((*texinfo-output* *standard-output*)
+ (*documentation-package* *package*))
+ (write-texinfo-string "`XXXXX`")
+ (write-texinfo-string "`\\XXXXX`")
+ (write-texinfo-string "`\\\\XXXXX`")
+ (write-texinfo-string "`Not allcaps`")
+ (write-texinfo-string "- a
+ c
+
+x
+")
+ (write-texinfo-string "`(X Y*)"))
(defun interesting-name-p (name)
(let ((name (if (and (plusp (length name))
@@ -500,8 +577,7 @@ with #\@. Optionally downcase the result."
(flet ((grab (start end)
(let ((name (subseq line start end)))
(when (and (not (member name *not-code* :test #'equal))
- (or (member name *code* :test #'equal)
- (interesting-name-p name)))
+ (interesting-name-p name))
(push (list start end) result))))
(got-symbol-p (start)
(let ((end (when (< start (length line))
@@ -528,15 +604,15 @@ with #\@. Optionally downcase the result."
(and (char= (char line i) #\:)
(or (= (1+ i) (length line))
(whitespacep (char line (1+ i)))))))
- ;; 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))
+ ;; symbol end
+ (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*))
+ ((and maybe-begin (not begin)
+ (find (char line i) *symbol-characters*))
;; potential symbol begin at this position
(setf begin i
maybe-begin nil))
@@ -568,192 +644,247 @@ variables if the symbol in question is contained in symbols
(let ((symbol-name (apply #'subseq line symbol/index)))
(format result (if (member symbol-name *texinfo-variables*
:test #'string=)
+ ;; FIXME: We don't use @var{} elsewhere.
+ ;; Should we here?
"@var{~A}"
"@code{~A}")
(string-downcase symbol-name)))
(setf last (second symbol/index)))
(write-string (subseq line last) result))))
+
-;;; lisp sections
+;;;; SBCL-flavoured Markdown to Texinfo Parser
+;;;; Replaces heuristic codification with strict Markdown rules.
-(defun lisp-section-p (line line-number lines)
- "Returns T if the given LINE looks like start of lisp code --
-i.e. if it starts with whitespace followed by a paren or
-semicolon, and the previous line is empty"
- (let ((offset (indentation line)))
- (and offset
- (plusp offset)
- (find (find-if-not #'whitespacep line) "(;")
- (empty-p (1- line-number) lines))))
+(defun blankp (line)
+ "Returns T if the line is empty or contains only whitespace."
+ (null (indentation line)))
-(defun collect-lisp-section (lines line-number)
- (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")))))
+(defun process-inline-markdown (string)
+ "Translates escapes (\*) and backticks (`FOO` -> @code{FOO}), while
+delegating normal text to the existing TEXINFO-LINE heuristic
+codifier."
+ (let ((len (length string))
+ (i 0)
+ (raw-buffer (make-string-output-stream))
+ (out (make-string-output-stream)))
+ (flet ((flush-raw ()
+ (let ((raw (get-output-stream-string raw-buffer)))
+ (when (plusp (length raw))
+ (write-string (texinfo-line raw) out)))))
+ (loop while (< i len)
+ for char = (char string i)
+ do (cond
+ ;; Escapes: \FOO
+ ((char= char #\\)
+ (flush-raw)
+ (incf i) ; Skip the backslash
+ (when (< i len)
+ (write-char (char string i) out)
+ (incf i)
+ ;; Protect the rest of the contiguous word from TEXINFO-LINE
+ (loop
+ while (and (< i len)
+ (not (member (char string i)
+ '(#\Space #\Tab #\Newline
+ #\( #\) #\[ #\] #\{ #\}
+ #\' #\" #\, #\. #\; #\? #\!))))
+ do (write-char (char string i) out)
+ (incf i))
+ (decf i)))
+ ;; Backticks: `CODE` with PAX downcasing and escape rules
+ ((char= char #\`)
+ (flush-raw)
+ (incf i)
+ (let ((code-buffer (make-string-output-stream)))
+ (loop while (and (< i len) (char/= (char string i) #\`))
+ do (write-char (char string i) code-buffer)
+ (incf i))
+ (let* ((code-str (get-output-stream-string code-buffer))
+ (slash-count (loop for c across code-str
+ while (char= c #\\)
+ count t))
+ ;; Consume up to 2 leading backslashes as PAX escapes
+ (actual-code (subseq code-str (min slash-count 2))))
+ (write-string "@code{" out)
+ (if (< slash-count 2)
+ ;; 0 or 1 backslash: Downcase if there are
+ ;; no lowercase letters (1 backslash turns
+ ;; off autolinking, which is naturally
+ ;; handled by bypassing TEXINFO-LINE).
+ (if (and (not (find-if #'lower-case-p actual-code))
+ (not (find #\" actual-code)))
+ (write-string (string-downcase actual-code) out)
+ (write-string actual-code out))
+ ;; 2 backslashes turn off autolinking AND downcasing.
+ (write-string actual-code out))
+ (write-string "}" out))))
+ (t
+ (write-char char raw-buffer)))
+ (incf i))
+ (flush-raw)
+ (get-output-stream-string out))))
-;;; itemized sections
+(defun collect-fenced-code (lines starting-line base-indent)
+ "Collects lines enclosed in ``` fences.
+Returns (VALUES CONSUMED-COUNT TEXINFO-LINES)."
+ (let* ((first-line (svref lines starting-line))
+ (trimmed (string-left-trim " " first-line)))
+ (when (and (>= (length trimmed) 3)
+ (string= (subseq trimmed 0 3) "```"))
+ (let ((lang (string-trim " " (subseq trimmed 3)))
+ (consumed 1)
+ (result nil))
+ (loop for index from (1+ starting-line) below (length lines)
+ for line = (svref lines index)
+ for line-trimmed = (string-left-trim " " line)
+ do (incf consumed)
+ if (and (>= (length line-trimmed) 3)
+ (string= (subseq line-trimmed 0 3) "```"))
+ do (loop-finish) ; Closing fence found
+ else
+ ;; Strip up to the base indentation of the environment
+ do (push (if (and (indentation line) (>= (indentation line) base-indent))
+ (subseq line base-indent)
+ line)
+ result))
+ (let ((env (if (string-equal lang "lisp") "lisp" "example")))
+ (values consumed
+ `(,(format nil "@~A" env)
+ ,@(nreverse result)
+ ,(format nil "@end ~A" env))))))))
+
+(defun collect-indented-code (lines starting-line base-indent)
+ "Collects lines using the classic 4-space indentation rule."
+ ;; An indented code block must be by a blank line (or be the first line).
+ (unless (and (> starting-line 0)
+ (not (blankp (svref lines (1- starting-line)))))
+ (let ((indent (indentation (svref lines starting-line))))
+ (when (and indent (>= indent (+ base-indent 4)))
+ (let ((consumed 0)
+ (result nil))
+ (loop for index from starting-line below (length lines)
+ for line = (svref lines index)
+ for line-indent = (indentation line)
+ do (cond
+ ((blankp line)
+ ;; Blank lines are allowed inside indented code blocks
+ (push "" result)
+ (incf consumed))
+ ((>= line-indent (+ base-indent 4))
+ (push (subseq line (+ base-indent 4)) result)
+ (incf consumed))
+ (t
+ (loop-finish)))) ; Indentation dropped, code block ends
+ ;; Trim trailing empty lines
+ (loop while (and result (string= (car result) ""))
+ do (pop result) (decf consumed))
+ (if result
+ (values consumed `("@example" ,@(nreverse result) "@end example"))
+ nil))))))
(defun maybe-itemize-offset (line)
- "Return NIL or the indentation offset if LINE looks like it starts
-an item in an itemization."
- (let* ((offset (indentation line))
- (char (when offset (char line offset))))
- (and offset
- (member char *itemize-start-characters* :test #'char=)
- (char= #\Space (find-if-not (lambda (c) (char= c char))
- line :start offset))
- offset)))
+ "Returns the indent if the line starts with a Markdown list marker (- or *)."
+ (let ((indent (indentation line)))
+ (when indent
+ (let ((trimmed (string-left-trim " " line)))
+ (when (and (>= (length trimmed) 2)
+ (member (char trimmed 0) '(#\- #\*))
+ (char= (char trimmed 1) #\Space))
+ indent)))))
-(defun collect-maybe-itemized-section (lines starting-line)
- ;; Return index of next line to be processed outside
- (let ((this-offset (maybe-itemize-offset (svref lines starting-line)))
- (result nil)
- (lines-consumed 0))
- (loop for line-number from starting-line below (length lines)
- for line = (svref lines line-number)
- for indentation = (indentation line)
- for offset = (maybe-itemize-offset line)
- do (cond
- ((not indentation)
- ;; empty line -- inserts paragraph.
- (push "" result)
- (incf lines-consumed))
- ((and offset (> indentation this-offset))
- ;; nested itemization -- handle recursively
- ;; FIXME: tables in itemizations go wrong
- (multiple-value-bind (sub-lines-consumed sub-itemization)
- (collect-maybe-itemized-section lines line-number)
- (when sub-lines-consumed
- (incf line-number (1- sub-lines-consumed)) ; +1 on next loop
- (incf lines-consumed sub-lines-consumed)
- (setf result (append (reverse sub-itemization) result)))))
- ((and offset (= indentation this-offset))
- ;; start of new item
- (push (format nil "@item ~A"
- (texinfo-line (subseq line (1+ offset))))
- result)
- (incf lines-consumed))
- ((and (not offset) (> indentation this-offset))
- ;; continued item from previous line
- (push (texinfo-line line) result)
- (incf lines-consumed))
- (t
- ;; end of itemization
- (loop-finish))))
- ;; a single-line itemization isn't.
- (if (> (count-if (lambda (line) (> (length line) 0)) result) 1)
- (values lines-consumed `("@itemize" ,@(reverse result) "@end itemize"))
- nil)))
-
-;;; table sections
-
-(defun tabulation-body-p (offset line-number lines)
- (when (< line-number (length lines))
- (let ((offset2 (indentation (svref lines line-number))))
- (and offset2 (< offset offset2)))))
-
-(defun tabulation-p (offset line-number lines direction)
- (let ((step (ecase direction
- (:backwards (1- line-number))
- (:forwards (1+ line-number)))))
- (when (and (plusp line-number) (< line-number (length lines)))
- (and (eql offset (indentation (svref lines line-number)))
- (or (when (eq direction :backwards)
- (empty-p step lines))
- (tabulation-p offset step lines direction)
- (tabulation-body-p offset step lines))))))
-
-(defun maybe-table-offset (line-number lines)
- "Return NIL or the indentation offset if LINE looks like it starts
-an item in a tabulation. Ie, if it is (1) indented, (2) preceded by an
-empty line, another tabulation label, or a tabulation body, (3) and
-followed another tabulation label or a tabulation body."
- (let* ((line (svref lines line-number))
- (offset (indentation line))
- (prev (1- line-number))
- (next (1+ line-number)))
- (when (and offset (plusp offset))
- (and (or (empty-p prev lines)
- (tabulation-body-p offset prev lines)
- (tabulation-p offset prev lines :backwards))
- (or (tabulation-body-p offset next lines)
- (tabulation-p offset next lines :forwards))
- offset))))
-
-;;; FIXME: This and itemization are very similar: could they share
-;;; some code, mayhap?
-
-(defun collect-maybe-table-section (lines starting-line)
- ;; Return index of next line to be processed outside
- (let ((this-offset (maybe-table-offset starting-line lines))
- (result nil)
- (lines-consumed 0))
- (loop for line-number from starting-line below (length lines)
- for line = (svref lines line-number)
- for indentation = (indentation line)
- for offset = (maybe-table-offset line-number lines)
- do (cond
- ((not indentation)
- ;; empty line -- inserts paragraph.
- (push "" result)
- (incf lines-consumed))
- ((and offset (= indentation this-offset))
- ;; start of new item, or continuation of previous item
- (if (and result (search "@item" (car result) :test #'char=))
- (push (format nil "@itemx ~A" (texinfo-line line))
+(defun collect-markdown-itemize (lines starting-line base-indent)
+ "Collects a list, strictly enforcing the 4-space rule for list bodies."
+ (let ((this-offset (maybe-itemize-offset (svref lines starting-line))))
+ (when (and this-offset (= this-offset base-indent))
+ (let ((result nil)
+ (lines-consumed 0)
+ (child-base (+ base-indent 4)))
+ (loop for line-number = starting-line then (+ starting-line
+ lines-consumed)
+ while (< line-number (length lines))
+ for line = (svref lines line-number)
+ for indent = (indentation line)
+ for offset = (maybe-itemize-offset line)
+ do (cond
+ ((blankp line)
+ ;; Blank lines inside lists are buffered
+ (push "" result)
+ (incf lines-consumed))
+ ;; New Item in the same list
+ ((and offset (= offset base-indent))
+ (push (format nil "@item ~A"
+ (process-inline-markdown
+ (subseq line (+ offset 2))))
result)
- (progn
- (push "" result)
- (push (format nil "@item ~A" (texinfo-line line))
- result)))
- (incf lines-consumed))
- ((> indentation this-offset)
- ;; continued item from previous line
- (push (texinfo-line line) result)
- (incf lines-consumed))
- (t
- ;; end of itemization
- (loop-finish))))
- ;; a single-line table isn't.
- (if (> (count-if (lambda (line) (> (length line) 0)) result) 1)
- (values lines-consumed
- `("" "@table @emph" ,@(reverse result) "@end table" ""))
- nil)))
+ (incf lines-consumed))
+ ;; Indented block/text inside the list item (>= 4 spaces)
+ ((and indent (>= indent child-base))
+ (multiple-value-bind (sub-consumed sub-result)
+ (parse-markdown-blocks lines line-number child-base)
+ (if sub-consumed
+ (progn
+ (setf result (append (reverse sub-result) result))
+ (incf lines-consumed sub-consumed))
+ ;; Fallback: normal text continuing the item body
+ (progn
+ (push (process-inline-markdown
+ (subseq line child-base)) result)
+ (incf lines-consumed)))))
+ ;; Normal text continuing the item body (indent >
+ ;; base-indent, but < child-base)
+ ((and indent (> indent base-indent))
+ (push (process-inline-markdown line) result)
+ (incf lines-consumed))
+ ;; If we get here, the line is NOT a new bullet,
+ ;; and it less than 4 spaces of relative
+ ;; indentation, so the list is over.
+ (t
+ (loop-finish))))
+ ;; Trim trailing empty lines so they return to the outer scope.
+ (loop while (and result (string= (car result) ""))
+ do (pop result) (decf lines-consumed))
-;;; section markup
+ (values lines-consumed `("@itemize" ,@(reverse result)
+ "@end itemize"))))))
-(defmacro with-maybe-section (index &rest forms)
+(defun parse-markdown-blocks (lines index base-indent)
+ "Parse the line at INDEX as a Markdown block.
+Return (VALUES CONSUMED RESULT)."
+ (let ((line (svref lines index)))
+ (multiple-value-bind (n-lines-consumed result)
+ (collect-fenced-code lines index base-indent)
+ (cond
+ (n-lines-consumed
+ (values n-lines-consumed result))
+ ((maybe-itemize-offset line)
+ (collect-markdown-itemize lines index (maybe-itemize-offset line)))
+ ((and (indentation line) (>= (indentation line) (+ base-indent 4)))
+ (collect-indented-code lines index base-indent))
+ (t nil)))))
+
+(defmacro with-markdown-section (index &rest forms)
`(multiple-value-bind (count collected) (progn ,@forms)
- (when count
- (dolist (line collected)
- (write-line line *texinfo-output*))
- (incf ,index (1- count)))))
+ (when count
+ (dolist (line collected)
+ (write-line line *texinfo-output*))
+ (incf ,index count)
+ t)))
(defun write-texinfo-string (string &optional lambda-list)
- "Try to guess as much formatting for a raw docstring as possible."
(let ((*texinfo-variables* (flatten lambda-list))
- (lines (string-lines (escape-for-texinfo string nil))))
- (loop for line-number from 0 below (length lines)
- for line = (svref lines line-number)
- do (cond
- ((with-maybe-section line-number
- (and (lisp-section-p line line-number lines)
- (collect-lisp-section lines line-number))))
- ((with-maybe-section line-number
- (and (maybe-itemize-offset line)
- (collect-maybe-itemized-section lines line-number))))
- ((with-maybe-section line-number
- (and (maybe-table-offset line-number lines)
- (collect-maybe-table-section lines line-number))))
- (t
- (write-line (texinfo-line line) *texinfo-output*))))))
+ ;; Note: The heuristic upcaser (e.g., FOO to @code{foo}) can either run on 'string'
+ ;; before escape-for-texinfo, or be integrated into process-inline-markdown.
+ (lines (string-lines (escape-for-texinfo string nil)))
+ (line-number 0))
+ (loop while (< line-number (length lines))
+ for line = (svref lines line-number)
+ do (unless (with-markdown-section line-number
+ (parse-markdown-blocks lines line-number 0))
+ ;; If it wasn't a block, process it as a normal inline string
+ (write-line (process-inline-markdown line) *texinfo-output*)
+ (incf line-number)))))
+
;;;; texinfo formatting tools
@@ -850,7 +981,7 @@ followed another tabulation label or a tabulation body."
(format *texinfo-output* "@end itemize~%~%"))))))
(defun texinfo-body (doc)
- (write-texinfo-string (get-string doc)))
+ (write-texinfo-string (sanitize-docstring (get-string doc))))
(defun texinfo-end (doc)
(write-line (case (get-kind doc)
@@ -862,7 +993,8 @@ followed another tabulation label or a tabulation body."
(defun write-texinfo (doc)
"Writes TexInfo for a DOCUMENTATION instance to *TEXINFO-OUTPUT*."
(let ((*documentation-package*
- (or (guess-package-from-arglist (lambda-list doc))
+ (or (package-override (get-name doc))
+ (guess-package-from-arglist (lambda-list doc))
(let ((p (get-package doc)))
(cond ((eq p (find-package :cl))
;; Most of the implementation of CL is done under
@@ -883,6 +1015,51 @@ followed another tabulation label or a tabulation body."
;;;; Utilities lifted from MGL-PAX
+(defun sanitize-docstring (docstring)
+ (let ((indentation (docstring-indentation docstring)))
+ (strip-docstring-indent docstring indentation t)))
+
+;;; Return the minimum number of leading spaces in non-blank lines
+;;; after the first.
+(defun docstring-indentation (docstring &key (first-line-special-p t))
+ (let ((n-min-indentation nil))
+ (with-input-from-string (s docstring)
+ (loop for i upfrom 0
+ for line = (read-line s nil nil)
+ while line
+ do (when (and (or (not first-line-special-p) (plusp i))
+ (not (blankp line)))
+ (when (or (null n-min-indentation)
+ (< (n-leading-spaces line) n-min-indentation))
+ (setq n-min-indentation (n-leading-spaces line))))))
+ (or n-min-indentation 0)))
+
+(defun n-leading-spaces (line)
+ (let ((n 0))
+ (loop for i below (length line)
+ while (char= (aref line i) #\Space)
+ do (incf n))
+ n))
+
+(defun subseq* (seq start)
+ (subseq seq (min (length seq) start)))
+
+(defun strip-docstring-indent (docstring indentation first-line-special-p)
+ (with-output-to-string (out)
+ (with-input-from-string (s docstring)
+ (loop for i upfrom 0
+ do (multiple-value-bind (line missing-newline-p)
+ (read-line s nil nil)
+ (unless line
+ (return))
+ (write-string (if (and first-line-special-p
+ (zerop i))
+ line
+ (subseq* line indentation))
+ out)
+ (unless missing-newline-p
+ (terpri out)))))))
+
;;; Unexported argument names are highly informative about *PACKAGE*
;;; at read time. No one ever uses fully-qualified internal symbols
;;; from another package for arguments, right?
diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo
index 2ba749559..621c4fa39 100644
--- a/doc/manual/threading.texinfo
+++ b/doc/manual/threading.texinfo
@@ -126,6 +126,7 @@ named (CAS place), allowing users to add CAS support to new
places.
@include macro-sb-ext-cas.texinfo
+@include fun-sb-ext-get-cas-expansion.texinfo
@node Mutex Support
@comment node-name, next, previous, up
diff --git a/src/code/alien-callback.lisp b/src/code/alien-callback.lisp
index a91eecac8..1c04c7110 100644
--- a/src/code/alien-callback.lisp
+++ b/src/code/alien-callback.lisp
@@ -274,15 +274,15 @@ Create new alien callable (old alien callable gets freed)."))
(defmacro define-alien-callable (name result-type typed-lambda-list
&body body
&environment env)
- "(define-alien-callable NAME RESULT-TYPE {(ARG-NAME ARG-TYPE)}*
- {doc-string} {decls}* {FORM}*)
-
-Define an alien function which can be called by alien code. The alien
+ "Define an alien function which can be called by alien code. The alien
function returned by (alien-callable-function NAME) expects alien
-arguments of the specified ARG-TYPEs and returns an alien of type
-RESULT-TYPE.
+arguments of the specified `ARG-TYPE`s and returns an alien of type
+`RESULT-TYPE`.
-If (alien-callable-function NAME) already exists, its value is not
+TYPED-LAMBDA-LIST is a list of `(ARG-NAME ARG-TYPE)` elements, and
+BODY is `{DOC-STRING} {DECL}* {FORM}*`.
+
+If (ALIEN-CALLABLE-FUNCTION NAME) already exists, its value is not
changed (though it is arranged that an updated version of the Lisp
callable function will be called, provided that the new type and the
existing type are compatible). This feature allows for incremental
@@ -301,12 +301,12 @@ redefinition of callable functions."
(defmacro with-alien-callable (definitions
&body body
&environment env)
- "Establish some local alien functions.
- Each element of DEFINITIONS is of the form:
- NAME RESULT-TYPE {(ARG-NAME ARG-TYPE)}*
- {doc-string} {decls}* {FORM}*
+ "Establish some local alien functions.
+ Each element of DEFINITIONS is of the form:
- The resulting alien callable value has dynamic extent."
+ NAME RESULT-TYPE {(ARG-NAME ARG-TYPE)}* {DOC-STRING} {DECL}* {FORM}*
+
+ The resulting alien callable value has dynamic extent."
(collect ((bindings)
(declarations)
(cleanup))
diff --git a/src/code/cold-init.lisp b/src/code/cold-init.lisp
index 729364ec5..6ed8b445a 100644
--- a/src/code/cold-init.lisp
+++ b/src/code/cold-init.lisp
@@ -397,13 +397,13 @@ defaults to 0 when ABORT is false, and 1 when it is true.
When ABORT is false (the default), current thread is first unwound,
*EXIT-HOOKS* are run, other threads are terminated, and standard
-output streams are flushed before SBCL calls exit(3) -- at which point
-atexit(3) functions will run. If multiple threads call EXIT with ABORT
+output streams are flushed before SBCL calls `exit`(3) -- at which point
+`atexit`(3) functions will run. If multiple threads call EXIT with ABORT
being false, the first one to call it will complete the protocol.
-When ABORT is true, SBCL exits immediately by calling _exit(2) without
-unwinding stack, or calling exit hooks. Note that _exit(2) does not
-call atexit(3) functions unlike exit(3).
+When ABORT is true, SBCL exits immediately by calling `_exit`(2)
+without unwinding stack, or calling exit hooks. Note that `_exit`(2)
+does not call `atexit`(3) functions unlike `exit`(3).
Recursive calls to EXIT cause EXIT to behave as if ABORT was true.
diff --git a/src/code/deadline.lisp b/src/code/deadline.lisp
index 87655278c..3abac3d32 100644
--- a/src/code/deadline.lisp
+++ b/src/code/deadline.lisp
@@ -205,13 +205,14 @@ If ABS-SEC and ABS-USEC are in the past, 0 0 is returned."
decode-timeout))
(defun decode-timeout (seconds)
"Decodes a relative timeout in SECONDS into five values, taking any
-global deadlines into account: TO-SEC, TO-USEC, STOP-SEC, STOP-USEC,
-DEADLINEP.
+global deadlines into account: `TO-SEC`, `TO-USEC`, `STOP-SEC`,
+`STOP-USEC`, `DEADLINEP`.
-TO-SEC and TO-USEC indicate the relative timeout in seconds and microseconds.
-STOP-SEC and STOP-USEC indicate the absolute timeout in seconds and
-microseconds. DEADLINEP is true if the returned values reflect a global
-deadline instead of the local timeout indicated by SECONDS.
+`TO-SEC` and `TO-USEC` indicate the relative timeout in seconds and
+microseconds. `STOP-SEC` and `STOP-USEC` indicate the absolute timeout
+in seconds and microseconds. `DEADLINEP` is true if the returned
+values reflect a global deadline instead of the local timeout
+indicated by SECONDS.
If SECONDS is null and there is no global timeout all returned values will be
null. If a global deadline has already passed when DECODE-TIMEOUT is called,
diff --git a/src/code/defpackage.lisp b/src/code/defpackage.lisp
index ee67f1f14..dde0627c0 100644
--- a/src/code/defpackage.lisp
+++ b/src/code/defpackage.lisp
@@ -447,21 +447,25 @@ definition is in variance with the current state of the package.
The value should be of the form:
- (:WARN [T | packages-names] :ERROR [T | package-names])
+ (:warn [t | packages-names] :error [t | package-names])
-specifying which packages get which behaviour -- with T signifying the default unless
-otherwise specified. If default is not specified, :WARN is used.
+specifying which packages get which behaviour -- with T signifying the
+default unless otherwise specified. If default is not specified, :WARN
+is used.
-:WARN keeps as much state as possible and causes SBCL to signal a full warning.
+- :WARN keeps as much state as possible and causes SBCL to signal a
+ full warning.
-:ERROR causes SBCL to signal an error when the variant DEFPACKAGE form is executed,
-with restarts provided for user to specify what action should be taken.
+- :ERROR causes SBCL to signal an error when the variant DEFPACKAGE
+ form is executed, with restarts provided for user to specify what
+ action should be taken.
Example:
- (setf *on-package-variance* '(:warn (:swank :swank-backend) :error t))
+ (setf *on-package-variance* '(:warn (:swank :swank-backend) :error t))
-specifies to signal a warning if SWANK package is in variance, and an error otherwise.")
+specifies to signal a warning if SWANK package is in variance, and an
+error otherwise.")
(defun note-package-variance (&rest args &key package &allow-other-keys)
(let ((pname (package-name package)))
diff --git a/src/code/error.lisp b/src/code/error.lisp
index 17e7b0131..78fcdaab8 100644
--- a/src/code/error.lisp
+++ b/src/code/error.lisp
@@ -194,7 +194,7 @@ condition."
;;;; HANDLER-CASE and IGNORE-ERRORS.
(sb-xc:defmacro handler-case (form &rest cases)
- "(HANDLER-CASE form { (type ([var]) body) }* )
+ "(HANDLER-CASE form { (type ([var]) body) }*)
Execute FORM in a context with handlers established for the condition types. A
peculiar property allows type to be :NO-ERROR. If such a clause occurs, and
diff --git a/src/code/filesys.lisp b/src/code/filesys.lisp
index 616fab4d8..2ded542d5 100644
--- a/src/code/filesys.lisp
+++ b/src/code/filesys.lisp
@@ -618,8 +618,8 @@ directory, or if the directory could not be deleted for any reason.
Both
- \(DELETE-DIRECTORY \"/tmp/foo\")
- \(DELETE-DIRECTORY \"/tmp/foo/\")
+ (DELETE-DIRECTORY \"/tmp/foo\")
+ (DELETE-DIRECTORY \"/tmp/foo/\")
delete the \"foo\" subdirectory of \"/tmp\", or signal an error if it does not
exist or if is a file or a symbolic link."
diff --git a/src/code/final.lisp b/src/code/final.lisp
index dbff310d1..c43836e5f 100644
--- a/src/code/final.lisp
+++ b/src/code/final.lisp
@@ -187,13 +187,13 @@
(defun finalize (object function &key dont-save
&aux (function (%coerce-callable-to-fun function)))
"Arrange for the designated FUNCTION to be called when there
-are no more references to OBJECT, including references in
-FUNCTION itself.
+are no more references to OBJECT, including references in FUNCTION
+itself.
If DONT-SAVE is true, the finalizer will be cancelled when
SAVE-LISP-AND-DIE is called: this is useful for finalizers
-deallocating system memory, which might otherwise be called
-with addresses from the old image.
+deallocating system memory, which might otherwise be called with
+addresses from the old image.
In a multithreaded environment FUNCTION may be called in any
thread. In both single and multithreaded environments FUNCTION
@@ -205,33 +205,41 @@ signalled in whichever thread the FUNCTION was called in.
Examples:
- ;;; GOOD, assuming RELEASE-HANDLE is re-entrant.
- (let* ((handle (get-handle))
- (object (make-object handle)))
- (finalize object (lambda () (release-handle handle)))
- object)
+```
+;;; GOOD, assuming RELEASE-HANDLE is re-entrant.
+(let* ((handle (get-handle))
+ (object (make-object handle)))
+ (finalize object (lambda () (release-handle handle)))
+ object)
+```
- ;;; BAD, finalizer refers to object being finalized, causing
- ;;; it to be retained indefinitely!
- (let* ((handle (get-handle))
- (object (make-object handle)))
- (finalize object
- (lambda ()
- (release-handle (object-handle object)))))
+```
+;;; BAD, finalizer refers to object being finalized, causing
+;;; it to be retained indefinitely!
+(let* ((handle (get-handle))
+ (object (make-object handle)))
+ (finalize object
+ (lambda ()
+ (release-handle (object-handle object)))))
+```
- ;;; BAD, not re-entrant!
- (defvar *rec* nil)
+```
+;;; BAD, not re-entrant!
+(defvar *rec* nil)
- (defun oops ()
- (when *rec*
- (error \"recursive OOPS\"))
- (let ((*rec* t))
- (gc))) ; or just cons enough to cause one
+(defun oops ()
+ (when *rec*
+ (error \"recursive OOPS\"))
+ (let ((*rec* t))
+ (gc))) ; or just cons enough to cause one
+```
- (progn
- (finalize \"oops\" #'oops)
- (oops)) ; GC causes re-entry to #'oops due to the finalizer
- ; -> ERROR, caught, WARNING signalled"
+```
+(progn
+ (finalize \"oops\" #'oops)
+ (oops)) ; GC causes re-entry to #'oops due to the finalizer
+ ; -> ERROR, caught, WARNING signalled
+```"
(declare (sb-c::tlab :system))
(let ((space (heap-allocated-p object)))
;; Rule out immediate, stack, arena, readonly, and static objects.
diff --git a/src/code/foreign-load.lisp b/src/code/foreign-load.lisp
index c09c08b5d..a6f3b642b 100644
--- a/src/code/foreign-load.lisp
+++ b/src/code/foreign-load.lisp
@@ -33,17 +33,17 @@
container specified by designated PATHNAME, such as a .so on an ELF platform.
Locating the shared object follows standard rules of the platform, consult the
-manual page for dlopen(3) for details. Typically paths specified by
+manual page for `dlopen`(3) for details. Typically paths specified by
environment variables such as LD_LIBRARY_PATH are searched if the PATHNAME has
no directory, but on some systems (eg. Mac OS X) search may happen even if
-PATHNAME is absolute. (On Windows LoadLibrary is used instead of dlopen(3).)
+PATHNAME is absolute. (On Windows LoadLibrary is used instead of `dlopen`(3).)
On non-Windows platforms calling LOAD-SHARED-OBJECT again with a PATHNAME
EQUAL to the designated pathname of a previous call will replace the old
definitions; if a symbol was previously referenced through the object and
is not present in the reloaded version an error will be signalled. Reloading
-may not work as expected if user or library-code has called dlopen(3) on the
-same shared object or running on a system where dlclose(3) is a noop.
+may not work as expected if user or library-code has called `dlopen`(3) on the
+same shared object or running on a system where `dlclose`(3) is a noop.
LOAD-SHARED-OBJECT interacts with SB-EXT:SAVE-LISP-AND-DIE:
diff --git a/src/code/loop.lisp b/src/code/loop.lisp
index 0439072c1..e6bf7d4d9 100644
--- a/src/code/loop.lisp
+++ b/src/code/loop.lisp
@@ -1981,8 +1981,8 @@ code to be loaded.
(sb-xc:defmacro loop-finish ()
"Cause the iteration to terminate \"normally\", the same as implicit
-termination by an iteration driving clause, or by use of WHILE or
-UNTIL -- the epilogue code (if any) will be run, and any implicitly
+termination by an iteration driving clause, or by use of `WHILE` or
+`UNTIL` -- the epilogue code (if any) will be run, and any implicitly
collected result will be returned as the value of the LOOP."
'(go end-loop))
diff --git a/src/code/macros.lisp b/src/code/macros.lisp
index ddc269b96..177ce8bdf 100644
--- a/src/code/macros.lisp
+++ b/src/code/macros.lisp
@@ -1895,10 +1895,10 @@ EXPERIMENTAL: Interface subject to change."
Additionally DEFUN, DEFGENERIC, DEFMETHOD, FLET, and LABELS can be also used to
define CAS-functions analogously to SETF-functions:
- (defvar *foo* nil)
+ (defvar *foo* nil)
- (defun (cas foo) (old new)
- (cas (symbol-value '*foo*) old new))
+ (defun (cas foo) (old new)
+ (cas (symbol-value '*foo*) old new))
First argument of a CAS function is the expected old value, and the second
argument of is the new value. Note that the system provides no automatic
@@ -2114,24 +2114,23 @@ PLACE can be any place supported by SB-EXT:COMPARE-AND-SWAP.
Examples:
- ;;; Conses T to the head of FOO-LIST.
- (defstruct foo list)
- (defvar *foo* (make-foo))
- (atomic-update (foo-list *foo*) #'cons t)
+ ;;; Conses T to the head of FOO-LIST.
+ (defstruct foo list)
+ (defvar *foo* (make-foo))
+ (atomic-update (foo-list *foo*) #'cons t)
- (let ((x (cons :count 0)))
- (mapc #'sb-thread:join-thread
- (loop repeat 1000
- collect (sb-thread:make-thread
- (lambda ()
- (loop repeat 1000
- do (atomic-update (cdr x) #'1+)
- (sleep 0.00001))))))
- ;; Guaranteed to be (:COUNT . 1000000) -- if you replace
- ;; atomic update with (INCF (CDR X)) above, the result becomes
- ;; unpredictable.
- x)
-"
+ (let ((x (cons :count 0)))
+ (mapc #'sb-thread:join-thread
+ (loop repeat 1000
+ collect (sb-thread:make-thread
+ (lambda ()
+ (loop repeat 1000
+ do (atomic-update (cdr x) #'1+)
+ (sleep 0.00001))))))
+ ;; Guaranteed to be (:COUNT . 1000000) -- if you replace
+ ;; atomic update with (INCF (CDR X)) above, the result becomes
+ ;; unpredictable.
+ x)"
(multiple-value-bind (vars vals old new cas-form read-form)
(get-cas-expansion place env)
`(let* (,@(mapcar 'list vars vals)
diff --git a/src/code/misc-aliens.lisp b/src/code/misc-aliens.lisp
index a1684d2b1..49620026e 100644
--- a/src/code/misc-aliens.lisp
+++ b/src/code/misc-aliens.lisp
@@ -99,7 +99,7 @@
(define-alien-routine ("os_set_errno" set-errno) void (new-errno int))
(setf (documentation 'set-errno 'function)
- "Set the C library pseudo-variable named \"errno\", for obscure syscalls.")
+ "Set the \\C library pseudo-variable named `\\errno` for obscure syscalls.")
;;; Decode errno into a string.
#-win32
diff --git a/src/code/ntrace.lisp b/src/code/ntrace.lisp
index fad1e26c2..d17ca1b57 100644
--- a/src/code/ntrace.lisp
+++ b/src/code/ntrace.lisp
@@ -16,17 +16,17 @@
;;; prefixes..
(defvar *trace-indentation-step* 2
- "the increase in trace indentation at each call level")
+ "The increase in trace indentation at each call level.")
(defvar *max-trace-indentation* 40
- "If the trace indentation exceeds this value, then indentation restarts at
- 0.")
+ "If the trace indentation exceeds this value, then indentation restarts
+at 0.")
(defvar *trace-encapsulate-default* t
- "the default value for the :ENCAPSULATE option to TRACE")
+ "The default value for the :ENCAPSULATE option to TRACE.")
(defvar *trace-report-default* 'trace
- "the default value for the :REPORT option to TRACE")
+ "The default value for the :REPORT option to TRACE.")
;;;; internal state
@@ -678,20 +678,20 @@
collect (trace-info-what x)))
(defmacro trace (&rest specs)
- "TRACE {Option Global-Value}* {Name {Option Value}*}*
+ "TRACE `{Option Global-Value}* {Name {Option Value}*}*`
TRACE is a debugging tool that provides information when specified
functions are called. In its simplest form:
- (TRACE NAME-1 NAME-2 ...)
+ (TRACE NAME-1 NAME-2 ...)
The NAMEs are not evaluated. Each may be one of the following:
* SYMBOL, denoting a function or macro.
* FNAME, a valid function name, denoting a function.
- * (METHOD FNAME QUALIFIERS* (SPECIALIZERS*)) denoting a method.
- * (COMPILER-MACRO SYMBOL) denoting a compiler macro.
- * (LABELS FNAME :IN OUTER-NAME) or (FLET FNAME :IN OUTER-NAME)
- denoting a local function where OUTER-NAME may be any of the
+ * `(METHOD FNAME QUALIFIERS* (SPECIALIZERS*))` denoting a method.
+ * `(COMPILER-MACRO SYMBOL)` denoting a compiler macro.
+ * `(LABELS FNAME :IN OUTER-NAME)` or `(FLET FNAME :IN OUTER-NAME)`
+ denoting a local function where `OUTER-NAME` may be any of the
previous names for functions, macros, methods or compiler macros.
Tracing local functions may require DEBUG policy 3 to inhibit
inlining.
@@ -712,62 +712,69 @@ ANSI Common Lisp behavior of TRACE.)
The following options are defined:
- :REPORT Report-Type
- If Report-Type is TRACE (the default) then information is
- reported by printing immediately. If Report-Type is NIL, then
- the only effect of the trace is to execute other
- options (e.g. PRINT or BREAK). Otherwise, Report-Type is
- treated as a function designator and, for each trace event,
- funcalled with 5 arguments: trace depth (a non-negative
- integer), a function name or a function object, a
- keyword (:ENTER, :EXIT or :NON-LOCAL-EXIT), a stack frame, and
- a list of values (arguments or return values).
-
- :CONDITION Form
- :CONDITION-AFTER Form
- :CONDITION-ALL Form
- If :CONDITION is specified, then TRACE does nothing unless Form
- evaluates to true at the time of the call. :CONDITION-AFTER is
- similar, but suppresses the initial printout, and is tested when the
- function returns. :CONDITION-ALL tries both before and after.
-
- :BREAK Form
- :BREAK-AFTER Form
- :BREAK-ALL Form
- If specified, and Form evaluates to true, then the debugger is invoked
- at the start of the function, at the end of the function, or both,
- according to the respective option.
-
- :PRINT Form
- :PRINT-AFTER Form
- :PRINT-ALL Form
- In addition to the usual printout, the result of evaluating Form is
- printed at the start of the function, at the end of the function, or
- both, according to the respective option. Multiple print options cause
- multiple values to be printed.
-
- :WHEREIN Names
- If specified, Names is a function name or list of names. TRACE does
- nothing unless a call to one of those functions encloses the call to
- this function (i.e. it would appear in a backtrace.) Anonymous
- functions have string names like \"DEFUN FOO\".
-
- :ENCAPSULATE {:DEFAULT | T | NIL}
- If T, the default, tracing is done via encapsulation (redefining the
- function name) rather than by modifying the function. :DEFAULT is
- not the default, but means to use encapsulation for interpreted
- functions and funcallable instances, breakpoints otherwise. When
- encapsulation is used, forms are *not* evaluated in the function's
- lexical environment, but SB-DEBUG:ARG can still be used.
-
- :METHODS {T | NIL}
- If T, any function argument naming a generic function will have its
- methods traced in addition to the generic function itself.
-
- :FUNCTION Function-Form
- This is a not really an option, but rather another way of specifying
- what function to trace. The Function-Form is evaluated immediately,
- and the resulting function is traced.
+- :REPORT `<report-type>`
+
+ If `REPORT-TYPE` is TRACE (the default) then information is
+ reported by printing immediately. If `REPORT-TYPE` is NIL, then
+ the only effect of the trace is to execute other options (e.g.
+ PRINT or BREAK). Otherwise, `REPORT-TYPE` is treated as a function
+ designator and, for each trace event, funcalled with 5 arguments:
+ trace depth (a non-negative integer), a function name or a
+ function object, a keyword (:ENTER, :EXIT or :NON-LOCAL-EXIT), a
+ stack frame, and a list of values (arguments or return values).
+
+- :CONDITION `<form>`
+- :CONDITION-AFTER `<form>`
+- :CONDITION-ALL `<form>`
+
+ If :CONDITION is specified, then TRACE does nothing unless `FORM`
+ evaluates to true at the time of the call. :CONDITION-AFTER is
+ similar, but suppresses the initial printout, and is tested when
+ the function returns. :CONDITION-ALL tries both before and after.
+
+- :BREAK `<form>`
+- :BREAK-AFTER `<form>`
+- :BREAK-ALL `<form>`
+
+ If specified, and `FORM` evaluates to true, then the debugger is
+ invoked at the start of the function, at the end of the function,
+ or both, according to the respective option.
+
+- :PRINT `<form>`
+- :PRINT-AFTER `<form>`
+- :PRINT-ALL `<form>`
+
+ In addition to the usual printout, the result of evaluating `FORM`
+ is printed at the start of the function, at the end of the
+ function, or both, according to the respective option. Multiple
+ print options cause multiple values to be printed.
+
+- :WHEREIN `<names>`
+
+ If specified, `NAMES` is a function name or list of names. TRACE
+ does nothing unless a call to one of those functions encloses the
+ call to this function (i.e. it would appear in a backtrace.)
+ Anonymous functions have string names like \"DEFUN FOO\".
+
+- :ENCAPSULATE {:DEFAULT | T | NIL}
+
+ If T, the default, tracing is done via encapsulation (redefining
+ the function name) rather than by modifying the function. :DEFAULT
+ is not the default but means to use encapsulation for interpreted
+ functions and funcallable instances, breakpoints otherwise. When
+ encapsulation is used, forms are *not* evaluated in the function's
+ lexical environment, but SB-DEBUG:ARG can still be used.
+
+- :METHODS {T | NIL}
+
+ If T, any function argument naming a generic function will have
+ its methods traced in addition to the generic function itself.
+
+- :FUNCTION `<function-form>`
+
+ This is a not really an option but rather another way of
+ specifying what function to trace. The `FUNCTION-FORM` is
+ evaluated immediately, and the resulting function is traced.
:CONDITION, :BREAK and :PRINT forms are evaluated in a context which
mocks up the lexical environment of the called function, so that
diff --git a/src/code/pprint.lisp b/src/code/pprint.lisp
index 7b309e0fa..36a36a8d8 100644
--- a/src/code/pprint.lisp
+++ b/src/code/pprint.lisp
@@ -685,9 +685,9 @@ line break."
(defun pprint-fill (stream list &optional (colon? t) atsign?)
"Output LIST to STREAM putting :FILL conditional newlines between each
- element. If COLON? is NIL (defaults to T), then no parens are printed
- around the output. ATSIGN? is ignored (but allowed so that PPRINT-FILL
- can be used with the ~/.../ format directive."
+ element. If `COLON?` is NIL (defaults to T), then no parens are
+ printed around the output. `ATSIGN?` is ignored (but allowed so
+ that PPRINT-FILL can be used with the `~/.../` format directive."
(declare (ignore atsign?))
(pprint-logical-block (stream list
:prefix (if colon? "(" "")
@@ -701,9 +701,9 @@ line break."
(defun pprint-linear (stream list &optional (colon? t) atsign?)
"Output LIST to STREAM putting :LINEAR conditional newlines between each
- element. If COLON? is NIL (defaults to T), then no parens are printed
- around the output. ATSIGN? is ignored (but allowed so that PPRINT-LINEAR
- can be used with the ~/.../ format directive."
+ element. If `COLON?` is NIL (defaults to T), then no parens are
+ printed around the output. `ATSIGN?` is ignored (but allowed so
+ that PPRINT-LINEAR can be used with the `~/.../` format directive."
(declare (ignore atsign?))
(pprint-logical-block (stream list
:prefix (if colon? "(" "")
@@ -718,10 +718,10 @@ line break."
(defun pprint-tabular (stream list &optional (colon? t) atsign? tabsize)
"Output LIST to STREAM tabbing to the next column that is an even multiple
of TABSIZE (which defaults to 16) between each element. :FILL style
- conditional newlines are also output between each element. If COLON? is
- NIL (defaults to T), then no parens are printed around the output.
- ATSIGN? is ignored (but allowed so that PPRINT-TABULAR can be used with
- the ~/.../ format directive."
+ conditional newlines are also output between each element. If
+ `COLON?` is NIL (defaults to T), then no parens are printed around
+ the output. `ATSIGN?` is ignored (but allowed so that
+ PPRINT-TABULAR can be used with the `~/.../` format directive."
(declare (ignore atsign?))
(pprint-logical-block (stream list
:prefix (if colon? "(" "")
diff --git a/src/code/run-program.lisp b/src/code/run-program.lisp
index 9719fce0c..84259d90d 100644
--- a/src/code/run-program.lisp
+++ b/src/code/run-program.lisp
@@ -752,100 +752,136 @@ default external format for streams.
RUN-PROGRAM will return a PROCESS structure. See the CMU Common Lisp
Users Manual for details about the PROCESS structure.
- Notes about Unix environments (as in the :ENVIRONMENT and :ENV args):
-
- - The SBCL implementation of RUN-PROGRAM, like Perl and many other
- programs, but unlike the original CMU CL implementation, copies
- the Unix environment by default.
- - Running Unix programs from a setuid process, or in any other
- situation where the Unix environment is under the control of someone
- else, is a mother lode of security problems. If you are contemplating
- doing this, read about it first. (The Perl community has a lot of good
- documentation about this and other security issues in script-like
- programs.)
-
- The &KEY arguments have the following meanings:
- :ENVIRONMENT
- a list of STRINGs describing the new Unix environment
- (as in \"man environ\"). The default is to copy the environment of
- the current process.
- :ENV
- an alternative lossy representation of the new Unix environment,
- for compatibility with CMU CL
- :SEARCH
- Look for PROGRAM in each of the directories in the child's $PATH
- environment variable. Otherwise an absolute pathname is required.
- :WAIT
- If non-NIL (default), wait until the created process finishes. If
- NIL, continue running Lisp until the program finishes.
- :PTY (not supported on win32)
- Either T, NIL, or a stream. Unless NIL, the subprocess is established
- under a PTY. If :pty is a stream, all output to this pty is sent to
- this stream, otherwise the PROCESS-PTY slot is filled in with a stream
- connected to pty that can read output and write input.
- :INPUT
- Either T, NIL, a pathname, a stream, or :STREAM.
- T: the standard input for the current process is inherited.
- NIL: /dev/null (nul on win32) is used.
- pathname: the specified file is used.
- stream: all the input is read from that stream and sent to the
+Notes about Unix environments (as in the :ENVIRONMENT and :ENV args):
+
+- The SBCL implementation of RUN-PROGRAM, like Perl and many other
+ programs, but unlike the original CMU CL implementation, copies the
+ Unix environment by default.
+
+- Running Unix programs from a setuid process, or in any other
+ situation where the Unix environment is under the control of someone
+ else, is a mother lode of security problems. If you are
+ contemplating doing this, read about it first. (The Perl community
+ has a lot of good documentation about this and other security issues
+ in script-like programs.)
+
+The &KEY arguments have the following meanings:
+
+- :ENVIRONMENT
+
+ A list of STRINGs describing the new Unix environment
+ (as in \"man environ\"). The default is to copy the environment of
+ the current process.
+
+- :ENV
+ An alternative lossy representation of the new Unix environment,
+ for compatibility with CMU CL.
+
+- :SEARCH
+
+ Look for PROGRAM in each of the directories in the child's $PATH
+ environment variable. Otherwise an absolute pathname is required.
+
+- :WAIT
+
+ If non-NIL (default), wait until the created process finishes. If
+ NIL, continue running Lisp until the program finishes.
+
+- :PTY (not supported on win32)
+
+ Either T, NIL, or a stream. Unless NIL, the subprocess is
+ established under a PTY. If :PTY is a stream, all output to this
+ pty is sent to this stream, otherwise the PROCESS-PTY slot is
+ filled in with a stream connected to pty that can read output and
+ write input.
+
+- :INPUT
+
+ Either T, NIL (the default), a pathname, a stream, or :STREAM.
+
+ - T: the standard input for the current process is inherited.
+ - NIL: `/dev/null` (nul on win32) is used.
+ - Pathname: the specified file is used.
+ - Stream: all the input is read from that stream and sent to the
subprocess.
- :STREAM: the PROCESS-INPUT slot is filled in with a stream that sends
- its output to the process.
- Defaults to NIL.
- :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
- can be one of:
- :ERROR to generate an error
- :CREATE to create an empty file
- NIL (the default) to return NIL from RUN-PROGRAM
- :OUTPUT
- Either T, NIL, a pathname, a stream, or :STREAM.
- T: the standard output for the current process is inherited.
- NIL: /dev/null (nul on win32) is used.
- pathname: the specified file is used.
- stream: all the output from the process is written to this stream.
- :STREAM: the PROCESS-OUTPUT slot is filled in with a stream that can be
- read to get the output.
- Defaults to NIL.
- :ERROR
- Same as :OUTPUT, additionally accepts :OUTPUT, making all error
- output routed to the same place as normal output.
- Defaults to :OUTPUT.
- :IF-OUTPUT-EXISTS (when :OUTPUT is the name of a file)
- can be one of:
- :ERROR (the default) to generate an error
- :SUPERSEDE to supersede the file with output from the program
- :APPEND to append output from the program to the file
- NIL to return NIL from RUN-PROGRAM, without doing anything
- :IF-ERROR-EXISTS
- Same as :IF-OUTPUT-EXISTS, controlling :ERROR output to files.
- Ignored when :ERROR :OUTPUT.
- Defaults to :ERROR.
- :STATUS-HOOK
- This is a function the system calls whenever the status of the
- process changes. The function takes the process as an argument.
- :EXTERNAL-FORMAT
- The external-format to use for :INPUT, :OUTPUT, and :ERROR :STREAMs.
- :DIRECTORY
- Specifies the directory in which the program should be run.
- NIL (the default) means the directory is unchanged.
-
- :PRESERVE-FDS
- A sequence of file descriptors which should remain open in the child
- process.
-
- Windows specific options:
- :ESCAPE-ARGUMENTS (default T)
- Controls escaping of the arguments passed to CreateProcess.
- :WINDOW (default NIL)
- When NIL, the subprocess decides how it will display its window. The
- following options control how the subprocess window should be displayed:
- :HIDE, :SHOW-NORMAL, :SHOW-MAXIMIZED, :SHOW-MINIMIZED, :SHOW-NO-ACTIVATE,
- :SHOW-MIN-NO-ACTIVE, :SHOW-NA.
- Note: console application subprocesses may or may not display a console
- window depending on whether the SBCL runtime is itself a console or GUI
- application. Invoke CMD /C START to consistently display a console window
- or use the :WINDOW :HIDE option to consistently hide the console window."
+ - :STREAM: the PROCESS-INPUT slot is filled in with a stream that
+ sends its output to the process.
+
+- :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
+
+ It is one of:
+
+ - :ERROR to generate an error
+ - :CREATE to create an empty file
+ - NIL (the default) to return NIL from RUN-PROGRAM
+
+- :OUTPUT
+
+ Either T, NIL (the default), a pathname, a stream, or :STREAM.
+
+ - T: the standard output for the current process is inherited.
+ - NIL: `/dev/null` (nul on win32) is used.
+ - Pathname: the specified file is used.
+ - Stream: all the output from the process is written to this stream.
+ - :STREAM: the PROCESS-OUTPUT slot is filled in with a stream that
+ can be read to get the output.
+
+- :ERROR
+
+ Same as :OUTPUT, additionally accepts :OUTPUT, making all error
+ output routed to the same place as normal output. Defaults to
+ :OUTPUT.
+
+- :IF-OUTPUT-EXISTS (when :OUTPUT is the name of a file)
+
+ It is one of:
+
+ - :ERROR (the default) to generate an error
+ - :SUPERSEDE to supersede the file with output from the program
+ - :APPEND to append output from the program to the file
+ - NIL to return NIL from RUN-PROGRAM, without doing anything
+
+- :IF-ERROR-EXISTS
+
+ Same as :IF-OUTPUT-EXISTS, controlling :ERROR output to files.
+ Ignored when :ERROR :OUTPUT. Defaults to :ERROR.
+
+- :STATUS-HOOK
+
+ This is a function the system calls whenever the status of the
+ process changes. The function takes the process as an argument.
+
+- :EXTERNAL-FORMAT
+
+ The external-format to use for :INPUT, :OUTPUT, and :ERROR :STREAMs.
+
+- :DIRECTORY
+
+ Specifies the directory in which the program should be run.
+ NIL (the default) means the directory is unchanged.
+
+- :PRESERVE-FDS
+
+ A sequence of file descriptors which should remain open in the child
+ process.
+
+Windows specific options:
+
+- `:ESCAPE-ARGUMENTS` (default T)
+
+ Controls escaping of the arguments passed to CreateProcess.
+
+- `:WINDOW` (default NIL)
+
+ When NIL, the subprocess decides how it will display its window.
+ The following options control how the subprocess window should be
+ displayed: `:HIDE`, `:SHOW-NORMAL`, `:SHOW-MAXIMIZED`,
+ `:SHOW-MINIMIZED`, `:SHOW-NO-ACTIVATE`, `:SHOW-MIN-NO-ACTIVE`,
+ `:SHOW-NA`. Note: console application subprocesses may or may not
+ display a console window depending on whether the SBCL runtime is
+ itself a console or GUI application. Invoke `cmd /c start` to
+ consistently display a console window or use the `:WINDOW` `:HIDE`
+ option to consistently hide the console window."
(when (and env-p environment-p)
(error "can't specify :ENV and :ENVIRONMENT simultaneously"))
(let* (;; Clear various specials used by GET-DESCRIPTOR-FOR to
diff --git a/src/code/save.lisp b/src/code/save.lisp
index 1e3a3e8cb..4655e1f77 100644
--- a/src/code/save.lisp
+++ b/src/code/save.lisp
@@ -111,79 +111,93 @@ Only global state is preserved: the stack is unwound in the process.
The following &KEY arguments are defined:
- :TOPLEVEL
- The function to run when the created core file is resumed. The
- default function handles command line toplevel option processing
- and runs the top level read-eval-print loop. This function returning
- is equivalent to (SB-EXT:EXIT :CODE 0) being called.
-
- TOPLEVEL functions should always provide an ABORT restart: otherwise
- code they call will run without one.
-
- :EXECUTABLE
- If true, arrange to combine the SBCL runtime and the core image
- to create a standalone executable. If false (the default), the
- core image will not be executable on its own. Executable images
- always behave as if they were passed the --noinform runtime option.~A
-
- :SAVE-RUNTIME-OPTIONS
- If true, values of runtime options --dynamic-space-size and
- --control-stack-size that were used to start SBCL are stored in
- the standalone executable, and restored when the executable is
- run. This also inhibits normal runtime option processing, causing
- all command line arguments to be passed to the toplevel.
- If :ACCEPT-RUNTIME-OPTIONS then --dynamic-space-size and
- --control-stack-size are still processed by the runtime.
- Meaningless if :EXECUTABLE is NIL.
-
- :CALLABLE-EXPORTS
- This should be a list of symbols to be initialized to the
- appropriate alien callables on startup. All exported symbols should
- be present as global symbols in the symbol table of the runtime
- before the saved core is loaded. When this list is non-empty, the
- :TOPLEVEL argument cannot be supplied.
-
- :PURIFY
- If true (the default), then some objects in the restarted core will
- be memory-mapped as read-only. Among those objects are numeric vectors
- that were determined to be compile-time constants, and any immutable
- values according to the language specification such as symbol names.
-
- :ROOT-STRUCTURES
- This should be a list of the main entry points in any newly loaded
- systems. This need not be supplied, but locality and/or GC performance
- may be better if they are. This has two different but related meanings:
- If :PURIFY is true - and only for cheneygc - the root structures
- are those which anchor the set of objects moved into static space.
- On gencgc - and only on platforms supporting immobile code - these are
- the functions and/or function-names which commence a depth-first scan
- of code when reordering based on the statically observable call chain.
- The complete set of reachable objects is not affected per se.
- This argument is meaningless if neither enabling precondition holds.
-
- :ENVIRONMENT-NAME
- This has no purpose; it is accepted only for legacy compatibility.
-
- :COMPRESSION
- This is only meaningful if the runtime was built with the :SB-CORE-COMPRESSION
- feature enabled. If NIL (the default), saves to uncompressed core files. If
- :SB-CORE-COMPRESSION was enabled at build-time, the argument may also be
- an integer from -7 to 22, corresponding to zstd compression levels, or T
- (which is equivalent to the default compression level, 9).
-
- :APPLICATION-TYPE
- Present only on Windows and is meaningful only with :EXECUTABLE T.
- Specifies the subsystem of the executable, :CONSOLE or :GUI.
- The notable difference is that :GUI doesn't automatically create a console
- window. The default is :CONSOLE.
+- :TOPLEVEL
+
+ The function to run when the created core file is resumed. The
+ default function handles command line toplevel option processing
+ and runs the top level read-eval-print loop. This function
+ returning is equivalent to (SB-EXT:EXIT :CODE 0) being called.
+
+ TOPLEVEL functions should always provide an ABORT restart:
+ otherwise code they call will run without one.
+
+- :EXECUTABLE
+
+ If true, arrange to combine the SBCL runtime and the core image to
+ create a standalone executable. If false (the default), the core
+ image will not be executable on its own. Executable images always
+ behave as if they were passed the `--noinform` runtime option.~A
+
+- :SAVE-RUNTIME-OPTIONS
+
+ If true, values of runtime options --dynamic-space-size and
+ --control-stack-size that were used to start SBCL are stored in
+ the standalone executable, and restored when the executable is
+ run. This also inhibits normal runtime option processing, causing
+ all command line arguments to be passed to the toplevel. If
+ :ACCEPT-RUNTIME-OPTIONS then --dynamic-space-size and
+ --control-stack-size are still processed by the runtime.
+ Meaningless if :EXECUTABLE is NIL.
+
+- :CALLABLE-EXPORTS
+
+ This should be a list of symbols to be initialized to the
+ appropriate alien callables on startup. All exported symbols
+ should be present as global symbols in the symbol table of the
+ runtime before the saved core is loaded. When this list is
+ non-empty, the :TOPLEVEL argument cannot be supplied.
+
+- :PURIFY
+
+ If true (the default), then some objects in the restarted core
+ will be memory-mapped as read-only. Among those objects are
+ numeric vectors that were determined to be compile-time constants,
+ and any immutable values according to the language specification
+ such as symbol names.
+
+- :ROOT-STRUCTURES
+
+ This should be a list of the main entry points in any newly loaded
+ systems. This need not be supplied, but locality and/or GC
+ performance may be better if they are. This has two different but
+ related meanings: If :PURIFY is true - and only for cheneygc - the
+ root structures are those which anchor the set of objects moved
+ into static space. On gencgc - and only on platforms supporting
+ immobile code - these are the functions and/or function-names
+ which commence a depth-first scan of code when reordering based on
+ the statically observable call chain. The complete set of
+ reachable objects is not affected per se. This argument is
+ meaningless if neither enabling precondition holds.
+
+- :ENVIRONMENT-NAME
+
+ This has no purpose; it is accepted only for legacy compatibility.
+
+- :COMPRESSION
+
+ This is only meaningful if the runtime was built with the
+ `:SB-CORE-COMPRESSION` feature enabled. If NIL (the default),
+ saves to uncompressed core files. If `:SB-CORE-COMPRESSION` was
+ enabled at build-time, the argument may also be an integer from -7
+ to 22, corresponding to zstd compression levels, or T (which is
+ equivalent to the default compression level, 9).
+
+- `:APPLICATION-TYPE`
+
+ Present only on Windows and is meaningful only with :EXECUTABLE T.
+ Specifies the subsystem of the executable, `:CONSOLE` or `:GUI`.
+ The notable difference is that `:GUI` doesn't automatically create
+ a console window. The default is `:CONSOLE`.
The save/load process changes the values of some global variables:
- *STANDARD-OUTPUT*, *DEBUG-IO*, etc.
+- *STANDARD-OUTPUT*, *DEBUG-IO*, etc
+
Everything related to open streams is necessarily changed, since
the OS won't let us preserve a stream across save and load.
- *DEFAULT-PATHNAME-DEFAULTS*
+- *DEFAULT-PATHNAME-DEFAULTS*
+
This is reinitialized to reflect the working directory where the
saved core is loaded.
diff --git a/src/code/target-alieneval.lisp b/src/code/target-alieneval.lisp
index 4aebdbfe4..dce96d26b 100644
--- a/src/code/target-alieneval.lisp
+++ b/src/code/target-alieneval.lisp
@@ -136,13 +136,15 @@ This is SETFable."
(defmacro with-alien (bindings &body body &environment env)
"Establish some local alien variables. Each of BINDINGS is of the form:
- VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
- ALLOCATION should be one of:
+
+ VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
+
+ `ALLOCATION` should be one of:
:LOCAL (the default)
The alien is allocated on the stack, and has dynamic extent.
:EXTERN
No alien is allocated, but VAR is established as a local name for
- the external alien given by EXTERNAL-NAME."
+ the external alien given by `EXTERNAL-NAME`."
;; FIXME:
;; :STATIC
;; The alien is allocated on the heap, and has infinite extent. The alien
@@ -274,8 +276,8 @@ This is SETFable."
(defmacro make-alien (type &optional size &environment env)
"Allocate an alien of type TYPE in foreign heap, and return an alien
pointer to it. The allocated memory is not initialized, and may
-contain garbage. The memory is allocated using malloc(3), so it can be
-passed to foreign functions which use free(3), or released using
+contain garbage. The memory is allocated using `malloc`(3), so it can
+be passed to foreign functions which use `free`(3), or released using
FREE-ALIEN.
For alien stack allocation, see macro WITH-ALIEN.
@@ -283,26 +285,26 @@ For alien stack allocation, see macro WITH-ALIEN.
The TYPE argument is not evaluated. If SIZE is supplied, how it is
interpreted depends on TYPE:
- * When TYPE is a foreign array type, an array of that type is
- allocated, and a pointer to it is returned. Note that you
- must use DEREF to first access the array through the pointer.
+* When TYPE is a foreign array type, an array of that type is
+ allocated, and a pointer to it is returned. Note that you must use
+ DEREF to first access the array through the pointer.
If supplied, SIZE is used as the first dimension for the array.
- * When TYPE is any other foreign type, then an object for that
- type is allocated, and a pointer to it is returned. So
- (make-alien int) returns a (* int).
+* When TYPE is any other foreign type, then an object for that type is
+ allocated, and a pointer to it is returned. So
+ (make-alien int) returns a (* int).
If SIZE is specified, then a block of that many objects is
allocated, with the result pointing to the first one.
Examples:
- (defvar *foo* (make-alien (array char 10)))
- (type-of *foo*) ; => (alien (* (array (signed 8) 10)))
- (setf (deref (deref *foo*) 0) 10) ; => 10
+ (defvar *foo* (make-alien (array char 10)))
+ (type-of *foo*) ; => (alien (* (array (signed 8) 10)))
+ (setf (deref (deref *foo*) 0) 10) ; => 10
- (make-alien char 12) ; => (alien (* (signed 8)))"
+ (make-alien char 12) ; => (alien (* (signed 8)))"
(let ((alien-type (if (alien-type-p type)
type
(parse-alien-type type env))))
@@ -379,7 +381,7 @@ Examples:
(declaim (inline free-alien))
(defun free-alien (alien)
"Dispose of the storage pointed to by ALIEN. The ALIEN must have been
-allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or malloc(3)."
+allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or `malloc`(3)."
(alien-funcall (extern-alien "free" (function (values) system-area-pointer))
(alien-sap alien))
nil)
@@ -406,7 +408,7 @@ allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or malloc(3)."
(external-format :default)
(null-terminate t))
"Copy part of STRING delimited by START and END into freshly
-allocated foreign memory, freeable using free(3) or FREE-ALIEN.
+allocated foreign memory, freeable using `free`(3) or FREE-ALIEN.
Returns the allocated string as a (* CHAR) alien, and the number of
bytes allocated as secondary value.
@@ -817,7 +819,7 @@ Only supported on x86-64 and ARM64."
(defmacro define-alien-routine (name result-type
&rest args
&environment lexenv)
- "DEFINE-ALIEN-ROUTINE Name Result-Type {(Arg-Name Arg-Type [Style])}*
+ "DEFINE-ALIEN-ROUTINE name result-type {(arg-name arg-type [style])}*
Define a foreign interface function for the routine with the specified NAME.
Also automatically DECLAIM the FTYPE of the defined function.
@@ -827,10 +829,10 @@ NAME may be either a string, a symbol, or a list of the form (string symbol).
RESULT-TYPE is the alien type for the function return value. VOID may be
used to specify a function with no result.
-The remaining forms specify individual arguments that are passed to the
-routine. ARG-NAME is a symbol that names the argument, primarily for
-documentation. ARG-TYPE is the C type of the argument. STYLE specifies the
-way that the argument is passed.
+The remaining forms specify individual arguments that are passed to
+the routine. `ARG-NAME` is a symbol that names the argument, primarily
+for documentation. `ARG-TYPE` is the C type of the argument. `STYLE`
+specifies the way that the argument is passed.
:IN
An :IN argument is simply passed by value. The value to be passed is
diff --git a/src/code/target-extensions.lisp b/src/code/target-extensions.lisp
index 165d20469..8644646f7 100644
--- a/src/code/target-extensions.lisp
+++ b/src/code/target-extensions.lisp
@@ -66,7 +66,7 @@ order when SBCL process exits.
Unused by SBCL itself: reserved for user and applications.
-Using (SB-EXT:EXIT :ABORT T), or calling exit(3) directly circumvents
+Using (SB-EXT:EXIT :ABORT T), or calling `exit`(3) directly circumvents
these hooks.")
(defun call-hooks (kind hooks &key (on-error :error))
diff --git a/src/code/target-hash-table.lisp b/src/code/target-hash-table.lisp
index be2a99bfc..ba15d3ccc 100644
--- a/src/code/target-hash-table.lisp
+++ b/src/code/target-hash-table.lisp
@@ -737,39 +737,38 @@ package lock violation.
Examples:
- ;;; 1.
-
- ;; We want to use objects of type FOO as keys (by their
- ;; names.) EQUALP would work, but would make the names
- ;; case-insensitive -- which we don't want.
- (defstruct foo (name nil :type (or null string)))
-
- ;; Define an equivalence test function and a hash function.
- (defun foo-name= (f1 f2) (equal (foo-name f1) (foo-name f2)))
- (defun sxhash-foo-name (f) (sxhash (foo-name f)))
-
- (define-hash-table-test foo-name= sxhash-foo-name)
-
- ;; #'foo-name would work too.
- (defun make-foo-table () (make-hash-table :test 'foo-name=))
-
- ;;; 2.
-
- (defun == (x y) (= x y))
-
- (define-hash-table-test ==
- (lambda (x)
- ;; Hash codes must be consistent with test, so
- ;; not (SXHASH X), since
- ;; (= 1 1.0) => T
- ;; (= (SXHASH 1) (SXHASH 1.0)) => NIL
- ;; Note: this doesn't deal with complex numbers or
- ;; bignums too large to represent as double floats.
- (sxhash (coerce x 'double-float))))
-
- ;; #'== would work too
- (defun make-number-table () (make-hash-table :test '==))
-"
+```
+;; We want to use objects of type FOO as keys (by their
+;; names.) EQUALP would work, but would make the names
+;; case-insensitive -- which we don't want.
+(defstruct foo (name nil :type (or null string)))
+
+;; Define an equivalence test function and a hash function.
+(defun foo-name= (f1 f2) (equal (foo-name f1) (foo-name f2)))
+(defun sxhash-foo-name (f) (sxhash (foo-name f)))
+
+(define-hash-table-test foo-name= sxhash-foo-name)
+
+;; #'foo-name would work too.
+(defun make-foo-table () (make-hash-table :test 'foo-name=))
+```
+
+```
+(defun == (x y) (= x y))
+
+(define-hash-table-test ==
+ (lambda (x)
+ ;; Hash codes must be consistent with test, so
+ ;; not (SXHASH X), since
+ ;; (= 1 1.0) => T
+ ;; (= (SXHASH 1) (SXHASH 1.0)) => NIL
+ ;; Note: this doesn't deal with complex numbers or
+ ;; bignums too large to represent as double floats.
+ (sxhash (coerce x 'double-float))))
+
+;; #'== would work too
+(defun make-number-table () (make-hash-table :test '==))
+```"
(check-type name symbol)
(if (member name '(eq eql equal equalp))
(error "Cannot redefine standard hash table test ~S." name)
@@ -893,63 +892,75 @@ Examples:
(synchronized))
"Create and return a new hash table. The keywords are as follows:
- :TEST
- Determines how keys are compared. Must a designator for one of the
- standard hash table tests, or a hash table test defined using
- SB-EXT:DEFINE-HASH-TABLE-TEST. Additionally, when an explicit
- HASH-FUNCTION is provided (see below), any two argument equivalence
- predicate can be used as the TEST.
-
- :SIZE
- A hint as to how many elements will be put in this hash table.
-
- :REHASH-SIZE
- Indicates how to expand the table when it fills up. If an integer, add
- space for that many elements. If a floating point number (which must be
- greater than 1.0), multiply the size by that amount.
-
- :REHASH-THRESHOLD
- Indicates how dense the table can become before forcing a rehash. Can be
- any positive number <=1, with density approaching zero as the threshold
- approaches 0. Density 1 means an average of one entry per bucket.
-
- :HASH-FUNCTION
- If unsupplied, a hash function based on the TEST argument is used,
- which then must be one of the standardized hash table test functions, or
- one for which a default hash function has been defined using
- SB-EXT:DEFINE-HASH-TABLE-TEST. If HASH-FUNCTION is specified, the TEST
- argument can be any two argument predicate consistent with it. The
- HASH-FUNCTION is expected to return a non-negative fixnum hash code.
- If TEST is neither standard nor defined by DEFINE-HASH-TABLE-TEST,
- then the HASH-FUNCTION must be specified.
-
- :WEAKNESS
- When :WEAKNESS is not NIL, garbage collection may remove entries from the
- hash table. The value of :WEAKNESS specifies how the presence of a key or
- value in the hash table preserves their entries from garbage collection.
-
- Valid values are:
-
- :KEY means that the key of an entry must be live to guarantee that the
- entry is preserved.
-
- :VALUE means that the value of an entry must be live to guarantee that
- the entry is preserved.
-
- :KEY-AND-VALUE means that both the key and the value must be live to
- guarantee that the entry is preserved.
+ - :TEST
+
+ Determines how keys are compared. Must a designator for one of
+ the standard hash table tests, or a hash table test defined
+ using SB-EXT:DEFINE-HASH-TABLE-TEST. Additionally, when an
+ explicit HASH-FUNCTION is provided (see below), any two argument
+ equivalence predicate can be used as the TEST.
+
+ - :SIZE
+
+ A hint as to how many elements will be put in this hash table.
+
+ - :REHASH-SIZE
+
+ Indicates how to expand the table when it fills up. If an
+ integer, add space for that many elements. If a floating point
+ number (which must be greater than 1.0), multiply the size by
+ that amount.
+
+ - :REHASH-THRESHOLD
+
+ Indicates how dense the table can become before forcing a
+ rehash. Can be any positive number <=1, with density approaching
+ zero as the threshold approaches 0. Density 1 means an average
+ of one entry per bucket.
+
+ - :HASH-FUNCTION
- :KEY-OR-VALUE means that either the key or the value must be live to
+ If unsupplied, a hash function based on the TEST argument is
+ used, which then must be one of the standardized hash table test
+ functions, or one for which a default hash function has been
+ defined using SB-EXT:DEFINE-HASH-TABLE-TEST. If HASH-FUNCTION is
+ specified, the TEST argument can be any two argument predicate
+ consistent with it. The HASH-FUNCTION is expected to return a
+ non-negative fixnum hash code. If TEST is neither standard nor
+ defined by DEFINE-HASH-TABLE-TEST, then the HASH-FUNCTION must
+ be specified.
+
+ - :WEAKNESS
+
+ When :WEAKNESS is not NIL, garbage collection may remove entries
+ from the hash table. The value of :WEAKNESS specifies how the
+ presence of a key or value in the hash table preserves their
+ entries from garbage collection.
+
+ Valid values are:
+
+ - :KEY means that the key of an entry must be live to guarantee
+ that the entry is preserved.
+
+ - :VALUE means that the value of an entry must be live to
guarantee that the entry is preserved.
- NIL (the default) means that entries are always preserved.
+ - :KEY-AND-VALUE means that both the key and the value must be
+ live to guarantee that the entry is preserved.
+
+ - :KEY-OR-VALUE means that either the key or the value must be
+ live to guarantee that the entry is preserved.
+
+ - NIL (the default) means that entries are always preserved.
+
+ - :SYNCHRONIZED
- :SYNCHRONIZED
- If NIL (the default), the hash-table may have multiple concurrent readers,
- but results are undefined if a thread writes to the hash-table
- concurrently with another reader or writer. If T, all concurrent accesses
- are safe, but note that CLHS 3.6 (Traversal Rules and Side Effects)
- remains in force. See also: SB-EXT:WITH-LOCKED-HASH-TABLE."
+ If NIL (the default), the hash-table may have multiple
+ concurrent readers, but results are undefined if a thread writes
+ to the hash-table concurrently with another reader or writer. If
+ T, all concurrent accesses are safe, but note that CLHS
+ 3.6 (Traversal Rules and Side Effects) remains in force. See
+ also: SB-EXT:WITH-LOCKED-HASH-TABLE."
(declare (type (or function symbol) test))
(declare (type unsigned-byte size))
(let* ((size (max +min-hash-table-size+
diff --git a/src/code/target-package.lisp b/src/code/target-package.lisp
index 14450bb08..b6ce75127 100644
--- a/src/code/target-package.lisp
+++ b/src/code/target-package.lisp
@@ -979,10 +979,11 @@ ACTUAL-PACKAGE must be a package designator.
Returns the designated package.
-Signals a continuable error if LOCAL-NICKNAME is already a package local
-nickname for a different package, or if LOCAL-NICKNAME is one of \"CL\",
-\"COMMON-LISP\", or, \"KEYWORD\", or if LOCAL-NICKNAME is a global name or
-nickname for the package to which the nickname would be added.
+Signals a continuable error if LOCAL-NICKNAME is already a package
+local nickname for a different package, or if LOCAL-NICKNAME is one of
+`\"CL\"`, `\"COMMON-LISP\"`, `\"KEYWORD\"`, or if LOCAL-NICKNAME is a
+global name or nickname for the package to which the nickname would be
+added.
When in the designated package, calls to FIND-PACKAGE with the LOCAL-NICKNAME
will return the package the designated ACTUAL-PACKAGE instead. This also
diff --git a/src/code/target-pathname.lisp b/src/code/target-pathname.lisp
index f246636b0..4b52b66c7 100644
--- a/src/code/target-pathname.lisp
+++ b/src/code/target-pathname.lisp
@@ -2047,10 +2047,10 @@ experimental and subject to change."
("SYS:OUTPUT;**;*.*.*" ,output)))))
(defun set-sbcl-source-location (pathname)
- "Initialize the SYS logical host based on PATHNAME, which should be
-the top-level directory of the SBCL sources. This will replace any
-existing translations for \"SYS:SRC;\", \"SYS:CONTRIB;\", and
-\"SYS:OUTPUT;\". Other \"SYS:\" translations are preserved."
+ "Initialize the `\\\\SYS` logical host based on PATHNAME, which should
+be the top-level directory of the SBCL sources. This will replace any
+existing translations for `\"SYS:SRC;\"`, `\"SYS:CONTRIB;\"`, and
+`\"SYS:OUTPUT;\"`. Other `\"SYS:\"` translations are preserved."
(let ((truename (truename pathname))
(current-translations
(remove-if (lambda (translation)
diff --git a/src/code/target-random.lisp b/src/code/target-random.lisp
index ae8242308..2204ac9b0 100644
--- a/src/code/target-random.lisp
+++ b/src/code/target-random.lisp
@@ -156,8 +156,7 @@ This particular SBCL version also accepts an argument of the following type:
This particular SBCL version uses the popular MT19937 PRNG algorithm, and its
internal state only effectively contains about 19937 bits of information.
-http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
-"
+<http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>"
(declare (explicit-check))
(named-let seed-random-state ((state state))
(etypecase state
diff --git a/src/code/target-thread.lisp b/src/code/target-thread.lisp
index 1fa5f2b99..4a60e675e 100644
--- a/src/code/target-thread.lisp
+++ b/src/code/target-thread.lisp
@@ -2492,9 +2492,9 @@ eg. thread executing
;; to be dropped.
(release-foo foo))))
-might miss calling RELEASE-FOO despite GET-FOO having returned true if
-the interrupt occurs inside the cleanup clause, eg. during execution
-of RELEASE-FOO.
+might miss calling `RELEASE-FOO` despite GET-FOO having returned true
+if the interrupt occurs inside the cleanup clause, eg. during
+execution of `RELEASE-FOO`.
Thus, in order to write an asynch unwind safe UNWIND-PROTECT you need
to use WITHOUT-INTERRUPTS:
diff --git a/src/code/timer.lisp b/src/code/timer.lisp
index 93eed2e32..a69fe1e88 100644
--- a/src/code/timer.lisp
+++ b/src/code/timer.lisp
@@ -503,12 +503,13 @@ Note that it is never safe to unwind from an asynchronous condition. Consider:
(when foo
(release-foo foo)))))
-If TIMEOUT occurs after GET-FOO has executed, but before the assignment, then
-RELEASE-FOO will be missed. While individual sites like this can be made proof
-against asynchronous unwinds, this doesn't solve the fundamental issue, as all
-the frames potentially unwound through need to be proofed, which includes both
-system and application code -- and in essence proofing everything will make
-the system uninterruptible."
+If TIMEOUT occurs after `GET-FOO` has executed, but before the
+assignment, then `RELEASE-FOO` will be missed. While individual sites
+like this can be made proof against asynchronous unwinds, this doesn't
+solve the fundamental issue, as all the frames potentially unwound
+through need to be proofed, which includes both system and application
+code -- and in essence proofing everything will make the system
+uninterruptible."
`(dx-flet ((timeout-body () ,@body))
(let ((expires ,expires))
;; FIXME: a temporary compatibility workaround for CLX, if unsafe
diff --git a/src/code/traceroot.lisp b/src/code/traceroot.lisp
index eb5bbe0c2..a5ca39a49 100644
--- a/src/code/traceroot.lisp
+++ b/src/code/traceroot.lisp
@@ -166,17 +166,20 @@ pointing to objects for which roots should be searched.
CRITERION determines just how rooty (how deep) a root must be in order
to be considered. Possible values are:
- :OLDEST
- This says we can stop upon seeing an object in the oldest gen to
- GC, or older. This is the easiest test to satisfy.
+- :OLDEST
- :PSEUDO-STATIC
- This is usually the same as :OLDEST, unless the oldest gen to GC
- has been decreased.
+ This says we can stop upon seeing an object in the oldest gen to
+ GC, or older. This is the easiest test to satisfy.
- :STATIC
- To find a root of an image-backed object, you want to stop only at
- a truly :STATIC object.
+- :PSEUDO-STATIC
+
+ This is usually the same as :OLDEST, unless the oldest gen to GC
+ has been decreased.
+
+- :STATIC
+
+ To find a root of an image-backed object, you want to stop only at a
+ truly :STATIC object.
IGNORE is a list of objects to treat as if nonexistent in the heap.
It can often be useful for finding a path to an interned symbol other than
@@ -185,39 +188,46 @@ through its package by specifying the package as an ignored object.
PRINT controls whether discovered paths should be returned or
printed. Possible values are
- :VERBOSE
+- :VERBOSE
+
Return no values. Print discovered paths using a verbose format
with each node of each path on a separate line.
- true (other than :VERBOSE)
+- true (other than :VERBOSE)
+
Return no values. Print discovered paths using a compact format
with all nodes of each path on a single line.
- NIL
+- NIL
+
Do not print any output. Instead return the discovered paths as a
list of lists. Each list has the form
- (TARGET . (ROOT NODE*))
+ (TARGET . (ROOT NODE*))
where TARGET is one of the target of one of the WEAK-POINTERS.
ROOT is a description of the root at which the path starts and has
one of the following forms:
- :STATIC
+ - :STATIC
+
If the root of the path is a non-collectible heap object.
- :PINNED
+ - :PINNED
+
If an unknown thread stack pins the root of the path.
- ((THREAD-NAME | THREAD-OBJECT) SYMBOL CURRENTP)
- If the path begins at a special binding of SYMBOL in a
- thread. CURRENTP is a BOOLEAN indicating whether the value is
- current or shadowed by another binding.
+ - `((THREAD-NAME | THREAD-OBJECT) SYMBOL CURRENTP)`
+
+ If the path begins at a special binding of SYMBOL in a thread.
+ CURRENTP is a BOOLEAN indicating whether the value is current
+ or shadowed by another binding.
+
+ - `((THREAD-NAME | THREAD-OBJECT) GUESSED-PC)`
- ((THREAD-NAME | THREAD-OBJECT) GUESSED-PC)
If the path begins at a lexical variable in the function whose
- code contains GUESSED-PC.
+ code contains `GUESSED-PC`.
Each NODE in the remainder of the path is a cons (OBJECT . SLOT)
indicating that the slot at index SLOT in OBJECT references the
diff --git a/src/code/typep.lisp b/src/code/typep.lisp
index d00f3213c..30747df60 100644
--- a/src/code/typep.lisp
+++ b/src/code/typep.lisp
@@ -340,7 +340,8 @@
;;;; which are not needed during self-build.
(defun typexpand-all (type-specifier &optional env)
- "Takes and expands a type specifier recursively like MACROEXPAND-ALL."
+ "Takes and expands a type specifier recursively like
+`SB-CLTL2:MACROEXPAND-ALL`."
;; TYPE-SPECIFIER is of type TYPE-SPECIFIER, but it is preferable to
;; defer to VALUES-SPECIFIER-TYPE for the check.
(declare (type lexenv-designator env) (ignore env))
diff --git a/src/code/unix.lisp b/src/code/unix.lisp
index 10f9946ef..87e37c148 100644
--- a/src/code/unix.lisp
+++ b/src/code/unix.lisp
@@ -458,7 +458,7 @@ corresponds to NAME, or NIL if there is none."
`(signed-byte 32))
(defun os-exit (code &key abort)
"Exit the process with CODE. If ABORT is true, exit is performed using _exit(2),
-avoiding atexit(3) hooks, etc. Otherwise exit(2) is called."
+avoiding `atexit`(3) hooks, etc. Otherwise `exit`(2) is called."
(unless (typep code 'exit-code)
(setf code (if abort 1 0)))
(if abort
diff --git a/src/cold/exports.lisp b/src/cold/exports.lisp
index 07412165a..cf0f8b564 100644
--- a/src/cold/exports.lisp
+++ b/src/cold/exports.lisp
@@ -1066,10 +1066,10 @@ Lisp extension proposal by David N. Gray")
"private: In theory, this \"contains functions and information
necessary for system interfacing\" (said cmu-user.tex at the time of
the SBCL code fork). That probably was and is a good idea, but in
-practice, the distinctions between this package and SB-KERNEL and even
-SB-VM seem to have become somewhat blurred over the years. Some
-anomalies (e.g. SB-IMPL::FIND-IF-IN-CLOSURE being in SB-IMPL instead
-of SB-KERNEL) have been undone, but probably more remain.")
+practice, the distinctions between this package and `SB-KERNEL` and even
+`SB-VM` seem to have become somewhat blurred over the years. Some
+anomalies (e.g. SB-IMPL::FIND-IF-IN-CLOSURE being in `SB-IMPL` instead
+of `SB-KERNEL`) have been undone, but probably more remain.")
(:use "CL" "SB-EXT" "SB-INT")
(:export
;; FIXME: %PRIMITIVE shouldn't be here. (I now know that %SYS
@@ -1215,9 +1215,9 @@ of SB-KERNEL) have been undone, but probably more remain.")
;; SB-ALIEN/SB-C-CALL split. That split went away and was deprecated
;; in 0.7.0, so we should get rid of this nickname after a while.
(:nicknames "SB-C-CALL")
- (:documentation "public: the ALIEN foreign function interface (If you're
+ (:documentation "public: the `ALIEN` foreign function interface (If you're
porting CMU CL code, note that this package corresponds roughly to a union
-of the packages ALIEN and C-CALL at the time of the SBCL fork. SB-C-CALL
+of the packages `ALIEN` and `C-CALL` at the time of the SBCL fork. `SB-C-CALL`
is a deprecated nickname to help ease the transition from older versions
of SBCL which maintained the CMU-CL-style split into two packages.)")
(:use "CL" "SB-EXT" "SB-INT" "SB-SYS" "SB-ALIEN-INTERNALS")
@@ -2411,7 +2411,7 @@ is a good idea, but see SB-SYS re. blurring of boundaries.")
(defpackage "SB-SEQUENCE"
(:documentation "semi-public: implements something which might eventually
-be submitted as a CDR")
+be submitted as a \\CDR")
(:use)
(:export "PROTOCOL-UNIMPLEMENTED"
"PROTOCOL-UNIMPLEMENTED-OPERATION"
@@ -3273,9 +3273,10 @@ structure representations")
(defpackage "SB-DEBUG"
(:documentation
"sorta public: Eventually this should become the debugger interface, with
-basic stuff like BACKTRACE and ARG. For now, the actual supported interface
-is still mixed indiscriminately with low-level internal implementation stuff
-like *STACK-TOP-HINT* and unsupported stuff like *TRACED-FUNS*.")
+basic stuff like BACKTRACE and ARG. For now, the actual supported
+interface is still mixed indiscriminately with low-level internal
+implementation stuff like SB-DEBUG:*STACK-TOP-HINT* and unsupported
+stuff like SB-DEBUG::*TRACED-FUNS*.")
(:use "CL" "SB-EXT" "SB-INT" "SB-SYS" "SB-KERNEL")
(:export "*BACKTRACE-FRAME-COUNT*"
"*DEBUG-BEGINNER-HELP-P*"
diff --git a/src/compiler/ir1-translators.lisp b/src/compiler/ir1-translators.lisp
index fc7f93d63..c6c5ba9cf 100644
--- a/src/compiler/ir1-translators.lisp
+++ b/src/compiler/ir1-translators.lisp
@@ -233,11 +233,11 @@ extent of the block."
(def-ir1-translator tagbody ((&rest statements) start next result)
"TAGBODY {tag | statement}*
-Define tags for use with GO. The STATEMENTs are evaluated in order,
+Define tags for use with GO. The `STATEMENT`s are evaluated in order,
skipping TAGs, and NIL is returned. If a statement contains a GO to a
defined TAG within the lexical scope of the form, then control is
transferred to the next statement following that tag. A TAG must be an
-integer or a symbol. A STATEMENT must be a list. Other objects are
+integer or a symbol. A `STATEMENT` must be a list. Other objects are
illegal within the body."
(let ((segments (and statements
(parse-tagbody statements))))
@@ -411,9 +411,10 @@ Evaluate the FORMS in the specified SITUATIONS (any of :COMPILE-TOPLEVEL,
(def-ir1-translator macrolet ((definitions &rest body) start next result)
"MACROLET ({(name lambda-list form*)}*) body-form*
-Evaluate BODY-FORMs in an environment with the specified local macros
-defined. NAME is the local macro name, LAMBDA-LIST is a DEFMACRO style
-destructuring lambda list, and the FORMS evaluate to the expansion."
+Evaluate `BODY-FORM`s in an environment with the specified local
+macros defined. NAME is the local macro name, LAMBDA-LIST is a
+DEFMACRO style destructuring lambda list, and the `FORM`s evaluate to
+the expansion."
(funcall-in-macrolet-lexenv
definitions
(lambda (&optional funs)
@@ -981,10 +982,10 @@ FORMs are also processed as top level forms."
start next result)
"FLET ({(name lambda-list declaration* form*)}*) declaration* body-form*
-Evaluate the BODY-FORMs with local function definitions. The bindings
-do not enclose the definitions; any use of NAME in the FORMS will
-refer to the lexically apparent function definition in the enclosing
-environment."
+Evaluate the `BODY-FORM`s with local function definitions. The
+bindings do not enclose the definitions; any use of NAME in the
+`FORM`s will refer to the lexically apparent function definition in
+the enclosing environment."
(multiple-value-bind (names defs forms decls)
(parse-fletish definitions body 'flet)
(let* ((fvars (mapcar (lambda (name def original)
@@ -1013,9 +1014,9 @@ environment."
(def-ir1-translator labels ((definitions &body body) start next result)
"LABELS ({(name lambda-list declaration* form*)}*) declaration* body-form*
-Evaluate the BODY-FORMs with local function definitions. The bindings
-enclose the new definitions, so the defined functions can call
-themselves or each other."
+Evaluate the `BODY-FORM`s with local function definitions. The
+bindings enclose the new definitions, so the defined functions can
+call themselves or each other."
(multiple-value-bind (names defs forms decls)
(parse-fletish definitions body 'labels)
(let* ((new-fenv
diff --git a/src/compiler/macros.lisp b/src/compiler/macros.lisp
index 9098cdee2..0462bd2f3 100644
--- a/src/compiler/macros.lisp
+++ b/src/compiler/macros.lisp
@@ -1002,7 +1002,7 @@
;;; We use WITH-SANE-IO-SYNTAX to provide safe defaults, and provide
;;; *COMPILER-PRINT-VARIABLE-ALIST* for user customization.
(defvar *compiler-print-variable-alist* nil
- "an association list describing new bindings for special variables
+ "An association list describing new bindings for special variables
to be used by the compiler for error-reporting, etc. Eg.
((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
@@ -1012,7 +1012,7 @@ during the execution of some debug commands. When evaluating arbitrary
expressions in the debugger, the normal values of the printer control
variables are in effect.
-Initially empty, *COMPILER-PRINT-VARIABLE-ALIST* is Typically used to
+Initially empty, *COMPILER-PRINT-VARIABLE-ALIST* is typically used to
specify bindings for printer control variables.")
(defmacro with-compiler-io-syntax (&body forms)
diff --git a/src/compiler/main.lisp b/src/compiler/main.lisp
index 58332abe1..8c53c62b0 100644
--- a/src/compiler/main.lisp
+++ b/src/compiler/main.lisp
@@ -71,76 +71,89 @@ intended to be eg. wrapped around the compilation of all files in the same syste
Following options are defined:
- :OVERRIDE Boolean-Form
- One of the effects of this form is to delay undefined warnings until the
- end of the form, instead of giving them at the end of each compilation.
- If OVERRIDE is NIL (the default), then the outermost
- WITH-COMPILATION-UNIT form grabs the undefined warnings. Specifying
- OVERRIDE true causes that form to grab any enclosed warnings, even if it
- is enclosed by another WITH-COMPILATION-UNIT.
-
- :POLICY Optimize-Declaration-Form
- Provides dynamic scoping for global compiler optimization qualities and
- restrictions, limiting effects of subsequent OPTIMIZE proclamations and
- calls to SB-EXT:RESTRICT-COMPILER-POLICY to the dynamic scope of BODY.
-
- If OVERRIDE is false, specified POLICY is merged with current global
- policy. If OVERRIDE is true, current global policy, including any
- restrictions, is discarded in favor of the specified POLICY.
-
- 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
- subject to change.
-
- :SOURCE-NAMESTRING Namestring-Form
- Attaches the value returned by the Namestring-Form to the internal
- debug-source information as the namestring of the source file. Normally
- the namestring of the input-file for COMPILE-FILE is used: this option
- can be used to provide source-file information for functions compiled
- using COMPILE, or to override the input-file of COMPILE-FILE.
-
- If both an outer and an inner WITH-COMPILATION-UNIT provide a
- SOURCE-NAMESTRING, the inner one takes precedence. Unaffected
- by :OVERRIDE.
-
- This is an SBCL-specific extension.
-
- :SOURCE-PLIST Plist-Form
- Attaches the value returned by the Plist-Form to internal debug-source
- information of functions compiled in within the dynamic extent of BODY.
-
- 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.
+- :OVERRIDE `<boolean-form>`
+
+ One of the effects of this form is to delay undefined warnings
+ until the end of the form, instead of giving them at the end of
+ each compilation. If OVERRIDE is NIL (the default), then the
+ outermost WITH-COMPILATION-UNIT form grabs the undefined warnings.
+ Specifying OVERRIDE true causes that form to grab any enclosed
+ warnings, even if it is enclosed by another WITH-COMPILATION-UNIT.
+
+- :POLICY `<optimize-declaration-form>`
+
+ Provides dynamic scoping for global compiler optimization
+ qualities and restrictions, limiting effects of subsequent
+ OPTIMIZE proclamations and calls to
+ SB-EXT:RESTRICT-COMPILER-POLICY to the dynamic scope of BODY.
+
+ If OVERRIDE is false, specified POLICY is merged with current
+ global policy. If OVERRIDE is true, current global policy,
+ including any restrictions, is discarded in favor of the specified
+ POLICY.
+
+ 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
+ subject to change.
+
+:SOURCE-NAMESTRING `<namestring-form>`
+
+ Attaches the value returned by the Namestring-Form to the internal
+ debug-source information as the namestring of the source file.
+ Normally the namestring of the input-file for COMPILE-FILE is
+ used: this option can be used to provide source-file information
+ for functions compiled using COMPILE, or to override the
+ input-file of COMPILE-FILE.
+
+ If both an outer and an inner WITH-COMPILATION-UNIT provide a
+ SOURCE-NAMESTRING, the inner one takes precedence. Unaffected
+ by :OVERRIDE.
+
+ This is an SBCL-specific extension.
+
+- :SOURCE-PLIST `<plist-form>`
+
+ Attaches the value returned by the Plist-Form to internal
+ debug-source information of functions compiled in within the
+ dynamic extent of BODY.
+
+ 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\"))
+```
+;; 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\"))
+```
+;; 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\"))
-"
+```
+;; 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/src/pcl/generic-functions.lisp b/src/pcl/generic-functions.lisp
index 74c4ff3d6..fb26543db 100644
--- a/src/pcl/generic-functions.lisp
+++ b/src/pcl/generic-functions.lisp
@@ -372,9 +372,11 @@ form or a SPECIALIZER instance.
More specifically, SPECIALIZER can be
* a non-parsed specializer form such as
- * a symbol naming a class
- * a list of the form (eql OBJECT)
- * a list of the form (SPECIALIZER-KIND &rest SPECIFIC-SYNTAX)
+
+ * a symbol naming a class
+ * a list of the form (eql OBJECT)
+ * a list of the form `(SPECIALIZER-KIND &REST SPECIFIC-SYNTAX)`
+
* an instance of a subclass of SPECIALIZER
When SPECIALIZER cannot be parsed/used as a specializer for
diff --git a/src/pcl/gray-streams.lisp b/src/pcl/gray-streams.lisp
index f3352968a..5317807e4 100644
--- a/src/pcl/gray-streams.lisp
+++ b/src/pcl/gray-streams.lisp
@@ -28,8 +28,8 @@
(!def-stream-generic stream-element-type (stream)
(:documentation
"Return a type specifier for the kind of object returned by the
- STREAM. The class FUNDAMENTAL-CHARACTER-STREAM provides a default method
- which returns CHARACTER."))
+ STREAM. The class SB-GRAY:FUNDAMENTAL-CHARACTER-STREAM provides a
+ default method which returns CHARACTER."))
(defmethod stream-element-type ((stream fundamental-character-stream))
'character)
@@ -125,9 +125,9 @@
(defgeneric stream-peek-char (stream)
(:documentation
- "This is used to implement PEEK-CHAR; this corresponds to PEEK-TYPE of NIL.
- It returns either a character or :EOF. The default method calls
- STREAM-READ-CHAR and STREAM-UNREAD-CHAR."))
+ "This is used to implement PEEK-CHAR; this corresponds to `PEEK-TYPE`
+ of NIL. It returns either a character or :EOF. The default method
+ calls STREAM-READ-CHAR and STREAM-UNREAD-CHAR."))
(defmethod stream-peek-char ((stream fundamental-character-input-stream))
(let ((char (stream-read-char stream)))
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL