master: sb-manual: readd concepts
melisgl via Sbcl-commits <[email protected]> Mon, 29 Jun 2026 12:20:19 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via 34812e52a1d77953d118733eb3c51da37ba08ae1 (commit)
from 40658bfd6a61376775439289abeb6489ab42802f (commit)
- Log -----------------------------------------------------------------
commit 34812e52a1d77953d118733eb3c51da37ba08ae1
Author: Gabor Melis <[email protected]>
Date: Fri Jun 26 15:03:59 2026 +0200
sb-manual: readd concepts
---
contrib/sb-manual/doc/beyond-ansi.lisp | 69 ++++++++++++-------
contrib/sb-manual/doc/compiler.lisp | 72 +++++++++++++------
contrib/sb-manual/doc/concepts.lisp | 103 ++++++++++++++++++++++++++++
contrib/sb-manual/doc/debugger.lisp | 85 +++++++++++++++--------
contrib/sb-manual/doc/deprecation.lisp | 3 +-
contrib/sb-manual/doc/efficiency.lisp | 26 ++++---
contrib/sb-manual/doc/external-formats.lisp | 3 +-
contrib/sb-manual/doc/ffi.lisp | 21 +++---
contrib/sb-manual/doc/intro.lisp | 17 +++--
contrib/sb-manual/doc/package-locks.lisp | 6 +-
contrib/sb-manual/doc/pathnames.lisp | 5 +-
contrib/sb-manual/doc/profiling.lisp | 14 ++--
contrib/sb-manual/doc/start-stop.lisp | 4 +-
contrib/sb-manual/doc/streams.lisp | 2 +-
contrib/sb-manual/doc/support-and-bugs.lisp | 2 +-
contrib/sb-sprof/sb-sprof.texinfo | 7 +-
doc/manual/beyond-ansi.texinfo | 51 +++++++++++---
doc/manual/compiler.texinfo | 56 ++++++++++++---
doc/manual/debugger.texinfo | 70 +++++++++++++++----
doc/manual/deprecation.texinfo | 1 +
doc/manual/efficiency.texinfo | 22 ++++--
doc/manual/external-formats.texinfo | 2 +
doc/manual/ffi.texinfo | 17 +++--
doc/manual/intro.texinfo | 21 +++---
doc/manual/package-locks.texinfo | 3 +
doc/manual/pathnames.texinfo | 3 +
doc/manual/profiling.texinfo | 2 +
doc/manual/start-stop.texinfo | 10 ++-
doc/manual/streams.texinfo | 4 +-
doc/manual/support-and-bugs.texinfo | 3 +-
src/code/reader.lisp | 4 +-
31 files changed, 534 insertions(+), 174 deletions(-)
diff --git a/contrib/sb-manual/doc/beyond-ansi.lisp b/contrib/sb-manual/doc/beyond-ansi.lisp
index 6ddb59adf..6c8c3c710 100644
--- a/contrib/sb-manual/doc/beyond-ansi.lisp
+++ b/contrib/sb-manual/doc/beyond-ansi.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @beyond-the-ansi-standard (:title "Beyond the ANSI Standard")
+(defsection @beyond-the-ansi-standard (:title "Beyond the ANSI Standard"
+ :concepts (("reader" "extensions")))
"SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
it still has quite a few. See @CONTRIBUTED-MODULES."
@@ -30,10 +31,12 @@
(@decimal-syntax-for-rationals section))
(defsection @extended-package-prefix-syntax
- (:title "Extended Package Prefix Syntax")
+ (:title "Extended Package Prefix Syntax"
+ :concepts (("extended" "package prefix syntax")
+ ("package prefix syntax," "extended")))
"SBCL supports extended package prefix syntax, which allows specifying
an alternate package instead of *PACKAGE* for the reader to use as
- the default package for interning symbols:
+ the default package for @INTERNING-SYMBOLS:
<package-name>::<form-with-interning-into-package>
@@ -43,11 +46,14 @@
*PACKAGE* is not rebound during the course of reading a form with
extended package prefix syntax; if `FOO::BAR` would cause a
- read-time package lock violation, so does `FOO::(BAR)`.")
+ read-time @PACKAGE-LOCK violation, so does `FOO::(BAR)`.")
-(defsection @symbol-name-normalization (:title "Symbol Name Normalization")
+(defsection @symbol-name-normalization
+ (:title "Symbol Name Normalization"
+ :concepts (("symbol name" "normalization")
+ ("normalization" "of symbol name")))
"SBCL also extends the reader to normalize all symbols to _Normalization
- Form KC_ in builds with Unicode enabled. Whether symbols are
+ Form KC_ in builds with @UNICODE enabled. Whether symbols are
normalized is controlled by"
(sb-ext:readtable-normalization function)
"Symbols created by INTERN and similar functions are not affected by
@@ -55,7 +61,9 @@
are not normalized are escaped during printing.")
(defsection @decimal-syntax-for-rationals
- (:title "Decimal Syntax for Rationals")
+ (:title "Decimal Syntax for Rationals"
+ :concepts ("decimal syntax for rationals"
+ ("rational," "decimal syntax")))
"SBCL supports a decimal syntax for rationals, modelled after the
standard syntax for floating-point numbers. If a number with
floating-point syntax has an exponent marker of `r` or `R`
@@ -74,7 +82,10 @@
however, rational numbers are printed in their standard syntax,
irrespective of the value of *READ-DEFAULT-FLOAT-FORMAT*.")
-(defsection @package-local-nicknames (:title "Package-Local Nicknames")
+(defsection @package-local-nicknames
+ (:title "Package-Local Nicknames"
+ :concepts (("package-local" "nicknames")
+ ("nicknames," "package-local")))
"SBCL allows giving packages local nicknames: they allow short and
easy-to-use names to be used without fear of name conflict associated
with normal nicknames.
@@ -118,7 +129,8 @@
the following variable."
(sb-ext:*on-package-variance* variable))
-(defsection @garbage-collection (:title "Garbage Collection")
+(defsection @garbage-collection (:title "Garbage Collection"
+ :concepts ("garbage collection"))
"SBCL provides additional garbage collection functionality not
specified by ANSI."
(sb-ext:gc function)
@@ -128,14 +140,16 @@
(@introspection-and-tuning section)
(@tracing-live-objects-back-to-roots section))
-(defsection @finalization (:title "Finalization")
+(defsection @finalization (:title "Finalization"
+ :concepts ("finalization"))
"Finalization allows code to be executed after an object has been
garbage collected. This is useful for example for releasing foreign
memory associated with a Lisp object."
(sb-ext:finalize function)
(sb-ext:cancel-finalization function))
-(defsection @weak-pointers (:title "Weak Pointers")
+(defsection @weak-pointers (:title "Weak Pointers"
+ :concepts ("weak pointers"))
"Weak pointers allow references to objects to be maintained without
keeping them from being garbage collected: useful for building caches
among other things.
@@ -234,7 +248,7 @@
- SLOT-VALUE and SLOT-BOUNDP function as expected, including (for
SLOT-VALUE) calling and respecting the return value of
- SLOT-UNBOUND if the slot is unbound;
+ SLOT-UNBOUND if the slot is unbound; ~UNBOUND-SLOT
- `(SETF SLOT-VALUE)` functions as expected, including performing
type checks to verify that the new value is of an appropriate type
@@ -440,8 +454,8 @@
methods convert between classes and proper names and between lists
of the form `(EQL <x>)` and interned eql specializer objects.
- - Distinguishing unbound instance allocated slots from bound ones
- when using SB-MOP:STANDARD-INSTANCE-ACCESS and
+ - Distinguishing unbound instance allocated slots ~UNBOUND-SLOT from
+ bound ones when using SB-MOP:STANDARD-INSTANCE-ACCESS and
SB-MOP:FUNCALLABLE-STANDARD-INSTANCE-ACCESS is possible by
comparison to the symbol-macro SB-PCL:+SLOT-UNBOUND+.")
@@ -633,7 +647,8 @@
(sb-ext:process-close function)
(sb-ext:process-kill function))
-(defsection @unicode-support (:title "Unicode Support")
+(defsection @unicode-support (:title "Unicode Support"
+ :concepts (@unicode))
"SBCL provides support for working with Unicode text and querying the
standard Unicode database for information about individual codepoints.
Unicode-related functions are located in the `SB-UNICODE` package.
@@ -702,7 +717,8 @@
(sb-unicode:sentence-break-class function)
(sb-unicode:line-break-class function))
-(defsection @string-operations (:title "String operations")
+(defsection @string-operations (:title "String operations"
+ :concepts (("normalization" "of strings")))
"SBCL can normalize strings using:"
(sb-unicode:normalize-string function)
(sb-unicode:normalized-p function)
@@ -781,7 +797,7 @@
the condition accessor SB-EXT:NAME-CONFLICT-SYMBOLS.")
(defsection @hash-table-extensions (:title "Hash Table Extensions")
- "Hash table extensions supported by SBCL are all controlled by keyword
+ "@HASH-TABLE extensions supported by SBCL are all controlled by keyword
arguments to MAKE-HASH-TABLE."
(make-hash-table function)
(sb-ext:define-hash-table-test macro)
@@ -789,7 +805,8 @@
(sb-ext:hash-table-synchronized-p function)
(sb-ext:hash-table-weakness function))
-(defsection @random-number-generation (:title "Random Number Generation")
+(defsection @random-number-generation (:title "Random Number Generation"
+ :concepts ("random number generation"))
"The initial value of *RANDOM-STATE* is the same each time SBCL
is started. This makes it possible for user code to obtain
repeatable pseudo random numbers using only standard-provided
@@ -883,7 +900,8 @@
(@asynchronous-timeouts section)
(@operations-supporting-timeouts-and-deadlines section))
-(defsection @timeout-parameters (:title "Timeout Parameters")
+(defsection @timeout-parameters (:title "Timeout Parameters"
+ :concepts (("timeout" "parameters")))
"Certain operations accept :TIMEOUT keyword arguments. These only
affect the specific operation and must be specified at each call
site by passing a :TIMEOUT keyword argument and a corresponding
@@ -916,7 +934,10 @@
;; here.
)
-(defsection @synchronous-timeouts (:title "Synchronous Timeouts")
+(defsection @synchronous-timeouts (:title "Synchronous Timeouts"
+ :concepts (("synchronous" "timeout")
+ ("timeout," "synchronous")
+ "deadline"))
"Deadlines, in contrast to timeout parameters, are established for a
dynamic scope using the SB-SYS:WITH-DEADLINE macro and indirectly
affect operations within that scope. In case of nested uses, the
@@ -957,7 +978,9 @@
three seconds, a SB-SYS:DEADLINE-TIMEOUT condition will be signaled
after the SLEEP call has been executing for one second.")
-(defsection @asynchronous-timeouts (:title "Asynchronous Timeouts")
+(defsection @asynchronous-timeouts (:title "Asynchronous Timeouts"
+ :concepts (("asynchronous" "timeout")
+ ("timeout," "asynchronous")))
"Asynchronous timeouts are established for a dynamic scope using the
SB-EXT:WITH-TIMEOUT macro:"
(sb-ext:with-timeout macro)
@@ -1038,8 +1061,8 @@
is well suited to the program's memory usage pattern. It also allows
permanent code to be frozen at fixed addresses, a precondition for
using copy-on-write to share code between multiple Lisp processes.
- This is less important with modern generational garbage collectors,
- but not all SBCL platforms use such a garbage collector.
+ This is less important with modern @GENERATIONAL-GC, but not all
+ SBCL platforms use such a garbage collector.
The SB-EXT:TRULY-THE special form declares the type of the result of
the operations, producing its argument; the declaration is not
diff --git a/contrib/sb-manual/doc/compiler.lisp b/contrib/sb-manual/doc/compiler.lisp
index 48519b5b5..fa636308b 100644
--- a/contrib/sb-manual/doc/compiler.lisp
+++ b/contrib/sb-manual/doc/compiler.lisp
@@ -16,12 +16,17 @@
(@interpreter section)
(@advanced-compiler-use-and-efficiency-hints section))
-(defsection @diagnostic-messages (:title "Diagnostic Messages")
+(defsection @diagnostic-messages (:title "Diagnostic Messages"
+ :concepts (("compiler" "messsage")
+ ("messsage," "compiler")))
(@controlling-verbosity section)
(@diagnostic-severity section)
(@understanding-compiler-diagnostics section))
-(defsection @controlling-verbosity (:title "Controlling Verbosity")
+(defsection @controlling-verbosity
+ (:title "Controlling Verbosity"
+ :concepts (("compiler" "messsage" "verbosity")
+ ("verbosity" "of compiler messsages")))
"The compiler can be quite verbose in its diagnostic reporting, rather
more then some users would prefer -- the amount of noise emitted can
be controlled, however.
@@ -91,7 +96,10 @@
;; associated with anonymous functions.
;; \end{defmac}
-(defsection @diagnostic-severity (:title "Diagnostic Severity")
+(defsection @diagnostic-severity
+ (:title "Diagnostic Severity"
+ :concepts (("compiler" "message" "severity")
+ ("severity" "of compiler message")))
"There are four levels of compiler diagnostic severity:
- error
@@ -137,7 +145,7 @@
defined anywhere."
(@parts-of-a-compiler-diagnostic section)
(@original-and-actual-source section)
- (@processing-path section))
+ (@processing-paths section))
(defsection @parts-of-a-compiler-diagnostic
(:title "Parts of a Compiler Diagnostic")
@@ -170,17 +178,17 @@
they are all printed from the outside in, separated by `=>`s. In
this example, the problem was in the DEFUN for `FOO`.
- - `(ZOQ Y)` is the _original source_ form responsible for the
+ - `(ZOQ Y)` is the _@ORIGINAL-SOURCE_ form responsible for the
diagnostic. Original source means that the form directly appeared
in the original input to the compiler, i.e. in the lambda passed
to COMPILE or in the top level form read from the source file. In
this example, the expansion of the `ZOQ` macro was responsible for
the message.
- - `--> ROQ PLOQ` This is the _processing path_ that the compiler
+ - `--> ROQ PLOQ` This is the _@PROCESSING-PATH_ that the compiler
used to produce the code that caused the message to be emitted.
The processing path is a representation of the evaluated forms
- enclosing the actual source that the compiler encountered when
+ enclosing the @ACTUAL-SOURCE that the compiler encountered when
processing the original source. The path is the first element of
each form, or the form itself if the form is not a list. These
forms result from the expansion of macros or source-to-source
@@ -254,7 +262,9 @@
intervene between the original source and the actual source, then
the processing path will also be omitted.")
-(defsection @original-and-actual-source (:title "Original and Actual Source")
+(defsection @original-and-actual-source (:title "Original and Actual Source"
+ :concepts (@original-source
+ @actual-source))
"The _original source_ displayed will almost always be a list. If
the actual source for an message is a symbol, the original source will
be the immediately enclosing evaluated list form. So even if the
@@ -295,7 +305,8 @@
this example, the problem is that `A`'s NIL initial value is not a
FIXNUM.")
-(defsection @processing-path (:title "Processing Path")
+(defsection @processing-paths (:title "Processing Paths"
+ :concepts (@processing-path))
"The processing path is mainly useful for debugging macros, so if you
don't write macros, you can probably ignore it. Consider this example:
@@ -320,7 +331,8 @@
((>= i #:g1) *undefined*)
(declare (type unsigned-byte i)))
- The rest of the processing path results from the expansion of DO:
+ The rest of the processing path results from the @MACROEXPANSION of
+ DO: ~SOURCE-TRANSFORM
(block nil
(let ((i 0) (#:g1 n))
@@ -377,10 +389,11 @@
CLOS slot types form a notable exception. Types declared using the
:TYPE slot option in DEFCLASS are asserted if and only if the class
- was defined in _safe code_ and the slot access location is in _safe
- code_ as well. This laxness does not pose any internal consistency
- issues, as the CLOS slot types are not available for the type
- inferencer, nor do CLOS slot types provide any efficiency benefits.
+ was defined in _safe code_ ~SAFETY and the slot access location is
+ in _safe code_ as well. This laxness does not pose any internal
+ consistency issues, as the CLOS slot types are not available for the
+ type inferencer, nor do CLOS slot types provide any efficiency
+ benefits.
There are three type checking policies available in SBCL, selectable
via OPTIMIZE declarations."
@@ -415,7 +428,9 @@
Used when `(= SAFETY 0)`.")
-(defsection @precise-type-checking (:title "Precise Type Checking")
+(defsection @precise-type-checking (:title "Precise Type Checking"
+ :concepts (("type checking," "precise")
+ ("precise" "type checking")))
"Precise checking means that the check is done as though TYPEP
had been called with the exact type specifier that appeared in the
declaration.
@@ -432,7 +447,10 @@
MEMBER, and other list-style type specifiers.")
(defsection @getting-existing-programs-to-run
- (:title "Getting Existing Programs to Run")
+ (:title "Getting Existing Programs to Run"
+ :concepts (("existing programs," "getting them to run")
+ ("types," "portability")
+ ("compatibility" "with other Lisps")))
"Since SBCL's compiler does much more comprehensive type checking than
most Lisp compilers, SBCL may detect type errors in programs that have
been debugged using other compilers. These errors are mostly incorrect
@@ -441,7 +459,7 @@
Some incorrect declarations can only be detected by run-time type
checking. It is very important to initially compile a program with
- full type checks (high SAFETY optimization) and then test this safe
+ full type checks (high @SAFETY optimization) and then test this safe
version. After the checking version has been tested, then you can
consider weakening or eliminating type checks. _This applies even to
previously debugged programs_ because the SBCL compiler does much
@@ -721,7 +739,10 @@
(@errors-during-macroexpansion section)
(@read-errors section))
-(defsection @type-errors-at-compile-time (:title "Type Errors at Compile Time")
+(defsection @type-errors-at-compile-time
+ (:title "Type Errors at Compile Time"
+ :concepts (("compile-time" "type error")
+ ("type error," "compile-time")))
"If the compiler can prove at compile time that some portion of the
program cannot be executed without a type error, then it will give a
warning at compile time.
@@ -766,7 +787,8 @@
an error if it is executed) and gives a warning.")
(defsection @errors-during-macroexpansion
- (:title "Errors During Macroexpansion")
+ (:title "Errors During Macroexpansion"
+ :concepts (("macroexpansion," "errors during")))
"The compiler handles errors that happen during macroexpansion, turning
them into compiler errors. If you want to debug the error (to debug
a macro), you can set *BREAK-ON-SIGNALS* to ERROR. For example, this
@@ -789,13 +811,18 @@
; (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
; DO step variable is not a symbol: (ATOM CURRENT)")
-(defsection @read-errors (:title "Read Errors")
+(defsection @read-errors (:title "Read Errors"
+ :concepts (("compiler" "read error")
+ ("read error," "compiler")))
"SBCL's compiler does not attempt to recover from read errors when
reading a source file, but instead just reports the offending
character position and gives up on the entire source file.")
(defsection @open-coding-and-inline-expansion
- (:title "Open Coding and Inline Expansion")
+ (:title "Open Coding and Inline Expansion"
+ :concepts ("open-coding"
+ ("inline" "expansion")
+ ("static" "functions")))
"Since Common Lisp forbids the redefinition of standard functions, the
compiler can have special knowledge of these standard functions
embedded in it. This special knowledge is used in various ways (open
@@ -849,7 +876,8 @@
or compiled as _static call_. Static function call uses a more
efficient calling convention that forbids redefinition.")
-(defsection @interpreter (:title "Interpreter")
+(defsection @interpreter (:title "Interpreter"
+ :concepts ("interpreter"))
"By default SBCL implements EVAL by calling the native code
compiler.
diff --git a/contrib/sb-manual/doc/concepts.lisp b/contrib/sb-manual/doc/concepts.lisp
index 0d6ee4cc9..c1d1f8d04 100644
--- a/contrib/sb-manual/doc/concepts.lisp
+++ b/contrib/sb-manual/doc/concepts.lisp
@@ -1,5 +1,108 @@
(in-package :sb-manual)
+(define-concept @interning-symbols (:title "interning symbols"
+ :keys (("interning" "symbols")
+ ("symbols," "interning"))))
+
+(define-concept @package-lock (:title "package lock"
+ :keys (("package" "lock")
+ ("lock," "package"))))
+
+(define-concept @unicode (:title "Unicode" :keys ("Unicode")))
+
+(define-concept @nfkc (:title "NFKC"
+ :keys ("NFKC"
+ "normalization form compatibility composition")))
+
+(define-concept ~unbound-slot (:keys (("unbound" "slot")
+ ("slot," "unbound"))))
+
+(define-concept ~character-name (:keys (("character" "name")
+ ("name" "of character"))))
+
+(define-concept @hash-table (:title "hash table"
+ :keys (("hash" "table"))))
+
+(define-concept @actual-source (:title "actual source"
+ :keys (("actual" "source")
+ ("source," "actual"))))
+
+(define-concept @original-source (:title "original source"
+ :keys (("original" "source")
+ ("source," "original"))))
+
+(define-concept @processing-path (:title "processing path"
+ :keys (("processing" "path"))))
+
+(define-concept @macroexpansion (:title "macroexpansion"
+ :keys ("macroexpansion")))
+
+(define-concept ~source-transform (:keys (("source" "transform"))))
+
+(define-concept ~safety (:keys (("safety," "optimization quality")
+ ("optimization quality" "safety"))))
+
+(define-concept @safety (:title "safety" :keys (~safety)))
+
+(define-concept ~debug (:keys (("debug," "optimization quality")
+ ("optimization quality" "debug"))))
+
+(define-concept @debug (:title "debug" :keys (~debug)))
+
+(define-concept @tail-recursion (:title "tail recursion"
+ :keys (("tail" "recursion")
+ ("recursion," "tail"))))
+
+(define-concept @tail-recursive (:title "tail recursive"
+ :keys (@tail-recursion)))
+
+(define-concept @interrupt (:title "interrupt"
+ :keys ("interrupt")))
+
+(define-concept ~run-time-error (:keys (("run-time" "error")
+ ("error," "run-time"))))
+
+(define-concept @basic-block (:title "basic block"
+ :keys ("basic block"
+ ("block," "basic"))))
+
+(define-concept @block-start (:title "block start"
+ :keys (("block," "start location"))))
+
+(define-concept @semi-inline (:title "semi inline"
+ :keys (("inline," "semi")
+ ("semi-inline"))))
+
+(define-concept @external-format (:title "external format"
+ :keys (("external" "format")
+ ("format," "external"))))
+
+(define-concept @generational-gc
+ (:title "generational GC"
+ :keys (("garbage collector," "generational")
+ ("generational" "garbage collector"))))
+
+(define-concept @conservative-gc
+ (:title "conservative GC"
+ :keys (("garbage collector," "conservative")
+ ("conservative" "garbage collector"))))
+
+(define-concept @declaration (:title "declaration"
+ :keys ("declaration")))
+
+(define-concept @logical-pathname (:title "logical pathname"
+ :keys (("logical" "pathname")
+ ("pathname," "logical"))))
+
+(define-concept @ldb (:title "LDB" :keys ("LDB")))
+
+(define-concept ~disabling-ldb (:title "disabling LDB"
+ :keys (("disabling" "LDB")
+ ("LDB," "disabling"))))
+
+(define-concept ~enabling-ldb (:title "enabling LDB"
+ :keys (("enabling" "LDB")
+ ("LDB," "enabling"))))
(define-concept ~repl (:keys ("Read-Eval-Print Loop" "REPL")))
(define-concept @repl (:title "REPL" :keys (~repl)))
diff --git a/contrib/sb-manual/doc/debugger.lisp b/contrib/sb-manual/doc/debugger.lisp
index 6c7fd85d1..b07c00e35 100644
--- a/contrib/sb-manual/doc/debugger.lisp
+++ b/contrib/sb-manual/doc/debugger.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @debugger (:title "Debugger")
+(defsection @debugger (:title "Debugger"
+ :concepts ("debugger"))
"This chapter documents the debugging facilities of SBCL, including
the debugger, single-stepper and TRACE, and the effect of `(OPTIMIZE
DEBUG)` declarations."
@@ -98,7 +99,8 @@
debugger by using the SB-EXT:*DEBUG-PRINT-VARIABLE-ALIST*."
(sb-ext:*debug-print-variable-alist* variable))
-(defsection @stack-frames (:title "Stack Frames")
+(defsection @stack-frames (:title "Stack Frames"
+ :concepts ("stack frame"))
"A _stack frame_ is the run-time representation of a call to a
function; the frame stores the state that a function needs to
remember what it is doing. Frames have:
@@ -209,7 +211,14 @@
lambdas will appear as `(LAMBDA <LAMBDA-LIST>)`."
(@entry-point-details section))
-(defsection @entry-point-details (:title "Entry Point Details")
+(defsection @entry-point-details
+ (:title "Entry Point Details"
+ :concepts (("external" "entry point")
+ ("entry point," "external")
+ ("block compilation," "debugger implications")
+ ("external," "stack frame kind")
+ ("optional," "stack frame kind")
+ ("cleanup," "stack frame kind")))
"Sometimes the compiler introduces new functions that are used to
implement a user function, but are not directly specified in the
source. This is mostly done for argument type and count checking.
@@ -224,7 +233,7 @@
(defsection @debug-tail-recursion (:title "Debug Tail Recursion")
"The compiler is _properly tail recursive_. If a function call is
- in a tail-recursive position, the stack frame will be deallocated
+ in a @TAIL-RECURSIVE position, the stack frame will be deallocated
_at the time of the call_, rather than after the call returns.
Consider this backtrace:
@@ -263,7 +272,9 @@
)
(defsection @unknown-locations-and-interrupts
- (:title "Unknown Locations and Interrupts")
+ (:title "Unknown Locations and Interrupts"
+ :concepts (("unknown code location")
+ ("code location" "unknown")))
"The debugger operates using special debugging information attached to
the compiled code. This debug information tells the debugger what it
needs to know about the locations in the code where the debugger can
@@ -278,10 +289,10 @@
- There is inadequate debug information due to the value of the
DEBUG optimization quality. See @DEBUGGER-POLICY-CONTROL.
- - The debugger was entered because of an interrupt such as `C-c`.
+ - The debugger was entered because of an @INTERRUPT such as `C-c`.
- - A hardware error such as a bus error occurred in code that was
- compiled unsafely due to the value of the SAFETY
+ - A hardware error ~RUN-TIME-ERROR such as a bus error occurred in
+ code that was compiled unsafely due to the value of the SAFETY
optimization quality."
;; FIXME: reinstate link when section on optimize qualities exists.
;; @OPTIMIZE-DECLARATION.
@@ -296,7 +307,9 @@
be located. If this happens, return from the interrupt and try
again.")
-(defsection @variable-access (:title "Variable Access")
+(defsection @variable-access (:title "Variable Access"
+ :concepts (("debug" "variables")
+ ("variable," "debugger access")))
"There are two ways to access the current frame's local variables in
the debugger: `list-locals` and SB-DEBUG:VAR.
@@ -331,7 +344,10 @@
(@variable-value-availability section)
(@note-on-lexical-variable-access section))
-(defsection @variable-value-availability (:title "Variable Value Availability")
+(defsection @variable-value-availability
+ (:title "Variable Value Availability"
+ :concepts (("variable," "value availabilty in debugger")
+ ("debug variable," "value availabilty")))
"The value of a variable may be unavailable to the debugger in portions
of the program where Lisp says that the variable is defined. If a
variable value is not available, the debugger will not let you read
@@ -353,10 +369,10 @@
The value of a variable may be unavailable for these reasons:
- - The value of the DEBUG optimization quality may have omitted debug
- information needed to determine whether the variable is available.
- Unless a variable is an argument, its value will only be available
- when DEBUG is at least 2.
+ - The value of the @DEBUG optimization quality may have omitted
+ debug information needed to determine whether the variable is
+ available. Unless a variable is an argument, its value will only
+ be available when DEBUG is at least 2.
- The compiler did lifetime analysis and determined that the value
was no longer needed, even though its scope had not been exited.
@@ -418,7 +434,9 @@
proved the variable could never take on. This may result in bad
things happening.")
-(defsection @source-location-printing (:title "Source Location Printing")
+(defsection @source-location-printing
+ (:title "Source Location Printing"
+ :concepts (("source location" "in debugger")))
"One of the debugger's capabilities is source level debugging of
compiled code. These commands display the source location for the
current frame:
@@ -525,7 +543,7 @@
(defsection @source-location-availability
(:title "Source Location Availability")
- "Source location information is only available when the DEBUG
+ "Source location information is only available when the @DEBUG
optimization quality is at least 2. If source location information
is unavailable, the source commands will give an error message.
@@ -537,11 +555,11 @@
Unknown location: using block start.
and then proceed to print the source location for the start of the
- _basic block_ enclosing the code location. It's a bit complicated to
+ _@BASIC-BLOCK_ enclosing the code location. It's a bit complicated to
explain exactly what a basic block is, but here are some properties
of the block start location:
- - The block start location may be the same as the true location.
+ - The @BLOCK-START location may be the same as the true location.
- The block start location will never be later in the program's flow
of control than the true location.
@@ -561,9 +579,11 @@
and the next conditional (but watch out because the compiler may
have changed the program on you.)")
-(defsection @debugger-policy-control (:title "Debugger Policy Control")
+(defsection @debugger-policy-control (:title "Debugger Policy Control"
+ :concepts (("debugger" "policy")
+ ("policy," "debugger")))
"The compilation policy specified by OPTIMIZE declarations
- affects the behavior seen in the debugger. The DEBUG quality
+ affects the behavior seen in the debugger. The @DEBUG quality
directly affects the debugger by controlling the amount of debugger
information dumped. Other optimization qualities have indirect but
observable effects due to changes in the way compilation is done.
@@ -629,9 +649,9 @@
functions are inline expanded. If a function is inline expanded,
then there will be no frame to represent the call, and the arguments
will be treated like any other local variable. Functions may also be
- _semi-inline_, in which case there is a frame to represent the call,
- but the call is to an optimized local version of the function, not
- to the original function."
+ _@SEMI-INLINE_, in which case there is a frame to represent the
+ call, but the call is to an optimized local version of the function,
+ not to the original function."
;; FIXME: link to section about inline expansion when it exists
;; (@INLINE-EXPANSION).
)
@@ -684,7 +704,8 @@
bottom. Only shows `<n>` frames if specified. The printing is
controlled by SB-DEBUG:*DEBUG-PRINT-VARIABLE-ALIST*.")
-(defsection @breakpoint-commands (:title "Breakpoint Commands")
+(defsection @breakpoint-commands (:title "Breakpoint Commands"
+ :concepts ("breakpoint"))
"SBCL supports setting of breakpoints inside compiled functions and
stepping of compiled code. Breakpoints can only be set at known
locations (see @UNKNOWN-LOCATIONS-AND-INTERRUPTS), so these commands
@@ -801,7 +822,9 @@
> stepping may be improved enough to subsume the instrumentation
> based stepping commands, which have much higher overhead.")
-(defsection @function-tracing (:title "Function Tracing")
+(defsection @function-tracing (:title "Function Tracing"
+ :concepts ("tracing"
+ ("function," "tracing")))
"The tracer causes selected functions to print their arguments and
their results whenever they are called. Options allow conditional
printing of the trace information and conditional breakpoints on
@@ -830,7 +853,9 @@
(sb-debug:*trace-encapsulate-default* variable)
(sb-debug:*trace-report-default* variable))
-(defsection @single-stepping (:title "Single Stepping")
+(defsection @single-stepping (:title "Single Stepping"
+ :concepts ("stepper"
+ "single-stepping"))
"SBCL includes an instrumentation based single-stepper for compiled
code, that can be invoked via the STEP macro, or from within the
debugger. See @DEBUGGER-POLICY-CONTROL, for details on enabling
@@ -857,7 +882,13 @@
(step macro))
(defsection @enabling-and-disabling-the-debugger
- (:title "Enabling and Disabling the Debugger")
+ (:title "Enabling and Disabling the Debugger"
+ :concepts (("debugger," "enabling")
+ ("debugger," "disabling")
+ ("enabling" "debugger")
+ ("disabling" "debugger")
+ ~enabling-ldb
+ ~disabling-ldb))
"In certain contexts (e.g. non-interactive applications), it may be
desirable to turn off the SBCL debugger (and possibly re-enable it).
The functions here control the debugger."
diff --git a/contrib/sb-manual/doc/deprecation.lisp b/contrib/sb-manual/doc/deprecation.lisp
index ac0cbb72c..0b78b4a0f 100644
--- a/contrib/sb-manual/doc/deprecation.lisp
+++ b/contrib/sb-manual/doc/deprecation.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @deprecation (:title "Deprecation")
+(defsection @deprecation (:title "Deprecation"
+ :concepts ("deprecation"))
"In order to support evolution of interfaces in SBCL as well as in user
code, SBCL allows declaring functions, variables and types as
deprecated. Users of deprecated things are notified by means of
diff --git a/contrib/sb-manual/doc/efficiency.lisp b/contrib/sb-manual/doc/efficiency.lisp
index e0724bd2b..03aba5739 100644
--- a/contrib/sb-manual/doc/efficiency.lisp
+++ b/contrib/sb-manual/doc/efficiency.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @efficiency (:title "Efficiency")
+(defsection @efficiency (:title "Efficiency"
+ :concepts ("efficicency"))
(@slot-access section)
(@stack-allocation section)
(@modular-arithmetic section)
@@ -8,7 +9,8 @@
(@global-and-always-bound-variables section)
(@miscellaneous-efficiency-issues section))
-(defsection @slot-access (:title "Slot Access")
+(defsection @slot-access (:title "Slot Access"
+ :concepts (("slot" "access")))
(@structure-object-slot-access section)
(@standard-object-slot-access section))
@@ -88,7 +90,7 @@
> __Warning__: Stack space is limited, so allocation of a large
> vector may cause stack overflow. Stack overflow checks are
- > done except in zero SAFETY policies.
+ > done except in 0 @SAFETY policies.
- closures defined with FLET or LABELS with a bound DYNAMIC-EXTENT
declaration;
@@ -231,7 +233,10 @@
(declare (optimize speed (safety 0) (debug 0)))
(trivial-hof (lambda (a b) (+ a b x)) 92))")
-(defsection @modular-arithmetic (:title "Modular Arithmetic")
+(defsection @modular-arithmetic (:title "Modular Arithmetic"
+ :concepts ("modular arithmetic"
+ ("arithmetic," "modular")
+ ("arithmetic," "hardware")))
"Some numeric functions have a property: n lower bits of the
result depend only on n lower bits of (all or some) arguments. If
the compiler sees an expression of form `(LOGAND <EXPR> <MASK>)`,
@@ -272,7 +277,10 @@
(let ((u (ldb (byte 64 0) (+ a b))))
(logior u (- (mask-field (byte 1 63) u)))))")
-(defsection @recognized-idioms (:title "Recognized Idioms")
+(defsection @recognized-idioms (:title "Recognized Idioms"
+ :concepts ("modular arithmetic"
+ ("arithmetic," "modular")
+ ("arithmetic," "hardware")))
"Common Lisp doesn't directly expose all features present in
modern hardware. Some code patterns are recognized and turned into
more efficient hardware instructions without requiring the use of
@@ -335,10 +343,10 @@
;; real problems are loop induction, closed over variables and
;; aliases.
"- Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
- has gotten a generational garbage collector. This means that there
- are some efficiency implications of various patterns of memory
- usage which aren't discussed in the CMUCL manual. (Some new
- material should be written about this.)
+ has gotten a @GENERATIONAL-GC. This means that there are some
+ efficiency implications of various patterns of memory usage which
+ aren't discussed in the CMUCL manual. (Some new material should be
+ written about this.)
- SBCL has some important known efficiency problems. Perhaps the
most important are
diff --git a/contrib/sb-manual/doc/external-formats.lisp b/contrib/sb-manual/doc/external-formats.lisp
index ac09e3b63..3354b065f 100644
--- a/contrib/sb-manual/doc/external-formats.lisp
+++ b/contrib/sb-manual/doc/external-formats.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @external-formats (:title "External Formats")
+(defsection @external-formats (:title "External Formats"
+ :concepts (@external-format))
"External formats determine the coding of characters from/to sequences
of octets when exchanging data with the outside world. Examples of
such exchanges are:
diff --git a/contrib/sb-manual/doc/ffi.lisp b/contrib/sb-manual/doc/ffi.lisp
index 7ef2f85fd..c8da7f6b6 100644
--- a/contrib/sb-manual/doc/ffi.lisp
+++ b/contrib/sb-manual/doc/ffi.lisp
@@ -225,17 +225,17 @@
declare that no useful value is returned. Using ALIEN-FUNCALL to
call a VOID foreign function will return zero values.
- - The foreign type specifier `(C-STRING &KEY <external-format>
- <element-type> <not-null>)` is similar to `(* CHAR)` but is
+ - The foreign type specifier `(C-STRING &KEY <EXTERNAL-FORMAT>
+ <ELEMENT-TYPE> <NOT-NULL>)` is similar to `(* CHAR)` but is
interpreted as a null-terminated string, and is automatically
converted into a Lisp string when accessed; or if the pointer is C
`\\NULL` or 0, then accessing it gives Lisp NIL unless
- `<not-null>` is true, in which case a TYPE-ERROR is signalled.
+ `<NOT-NULL>` is true, in which case a TYPE-ERROR is signalled.
- External format conversion is automatically done when Lisp
+ @EXTERNAL-FORMAT conversion is automatically done when Lisp
strings are passed to foreign code, or when foreign strings are
passed to Lisp code. If the type specifier has an explicit
- `<external-format>`, that external format will be used.
+ `<EXTERNAL-FORMAT>`, that external format will be used.
Otherwise SB-EXT:*DEFAULT-C-STRING-EXTERNAL-FORMAT* will be
used. For example, when the following alien routine is called,
the Lisp string given as argument is converted to an \\EBCDIC
@@ -249,7 +249,7 @@
assuming that the `<EXTERNAL-FORMAT>` and `<ELEMENT-TYPE>` of
the C-STRING type are compatible with the internal
representation of the string. For an SBCL built with Unicode
- support that means an `<external-format>` of :ASCII and an
+ support that means an `<EXTERNAL-FORMAT>` of :ASCII and an
`<ELEMENT-TYPE>` of BASE-CHAR. Without Unicode support the
`<EXTERNAL-FORMAT>` can also be :ISO-8859-1, and the
`<ELEMENT-TYPE>` can also be [CHARACTER][type]. If
@@ -615,11 +615,10 @@
- SB-SYS:WITH-PINNED-OBJECTS is a macro which arranges for some set
of objects to be pinned in memory for the dynamic extent of its
- body forms. On ports which use the generational garbage
- collector (most, as of this writing) this affects exactly the
- specified objects. On other ports it is implemented by turning off
- GC for the duration (so could be said to have a whole-world
- granularity).
+ body forms. On ports which use the @GENERATIONAL-GC
+ (most, as of this writing) this affects exactly the specified
+ objects. On other ports it is implemented by turning off GC for
+ the duration (so could be said to have a whole-world granularity).
- Disable GC, using the SB-EXT:WITHOUT-GCING macro."
(@lisp-as-a-shared-library section))
diff --git a/contrib/sb-manual/doc/intro.lisp b/contrib/sb-manual/doc/intro.lisp
index cbebc2c00..deab55fce 100644
--- a/contrib/sb-manual/doc/intro.lisp
+++ b/contrib/sb-manual/doc/intro.lisp
@@ -128,8 +128,8 @@
regression and unit-test framework.
- __MD5 Sums:__ The @SB-MD5 module provides an implementation of the
- MD5 message digest algorithm for Common Lisp, using the modular
- arithmetic optimizations provided by SBCL.")
+ MD5 message digest algorithm for Common Lisp, using the
+ @MODULAR-ARITHMETIC optimizations provided by SBCL.")
(defsection @idiosyncrasies (:title "Idiosyncrasies")
"The information in this section describes some of the ways that SBCL
@@ -435,9 +435,8 @@
SBCL also inherited some newer architectural features from CMUCL.
The most important is that on some architectures it has a
- generational garbage collector (GC), which has various
- implications (mostly good) for performance. These are discussed in
- another chapter, @EFFICIENCY.
+ @GENERATIONAL-GC, which has various implications (mostly good) for
+ performance. These are discussed in another chapter, @EFFICIENCY.
SBCL has diverged from CMUCL in that SBCL is now essentially a
compiler-only implementation of Common Lisp. This is a change in
@@ -463,7 +462,7 @@
(and has already improved in some other areas), but it takes a while.
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
- _conservative_ GC. This means that it doesn't maintain a strict
+ _@CONSERVATIVE-GC. This means that it doesn't maintain a strict
separation between tagged and untagged data, instead treating some
untagged data (e.g. raw floating point numbers) as possibly-tagged
data and so not collecting any Lisp objects that they point to. This
@@ -471,9 +470,9 @@
possibly no worse than the negative consequences of trying to
implement an exact GC on a processor architecture as register-poor
as the X86) and also has potentially unlimited consequences for
- worst-case memory efficiency. In practice, conservative garbage
- collectors work reasonably well, not getting anywhere near the worst
- case. But they can occasionally cause odd patterns of memory usage.
+ worst-case memory efficiency. In practice, @CONSERVATIVE-GCs work
+ reasonably well, not getting anywhere near the worst case. But they
+ can occasionally cause odd patterns of memory usage.
The fork from CMUCL was based on a major rewrite of the system
bootstrap process. CMUCL has for many years tolerated a very unusual
diff --git a/contrib/sb-manual/doc/package-locks.lisp b/contrib/sb-manual/doc/package-locks.lisp
index d51fd21c8..44127d66a 100644
--- a/contrib/sb-manual/doc/package-locks.lisp
+++ b/contrib/sb-manual/doc/package-locks.lisp
@@ -1,6 +1,8 @@
(in-package :sb-manual)
-(defsection @package-locks (:title "Package Locks")
+(defsection @package-locks (:title "Package Locks"
+ :concepts (("package" "lock")
+ ("lock," "package")))
"None of the following sections apply to SBCL built without package
locking support.
@@ -49,7 +51,7 @@
(defsection @lexical-bindings-and-declarations
(:title "Lexical Bindings and Declarations")
- "Lexical bindings or declarations that violate package locks cause a
+ "Lexical bindings or @DECLARATIONs that violate package locks cause a
compile-time warning, and a runtime PROGRAM-ERROR when the form that
violates package locks would be executed.
diff --git a/contrib/sb-manual/doc/pathnames.lisp b/contrib/sb-manual/doc/pathnames.lisp
index c0e4ff3ba..1cde48741 100644
--- a/contrib/sb-manual/doc/pathnames.lisp
+++ b/contrib/sb-manual/doc/pathnames.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @pathnames (:title "Pathnames")
+(defsection @pathnames (:title "Pathnames"
+ :concepts ("pathname"))
(@lisp-pathnames section)
(@native-filenames section))
@@ -84,7 +85,7 @@
(:title "The SYS Logical Pathname Host")
;; The existence and meaning of SYS: logical pathnames is
;; implementation-defined (CLHS 19.3.1.1.1).
- "The logical pathname host named by `\"SYS\"` exists in SBCL.
+ "The @LOGICAL-PATHNAME host named by `\"SYS\"` exists in SBCL.
Its LOGICAL-PATHNAME-TRANSLATIONS may be set by the site or the user
applicable to point to the locations of the system's sources; in
particular, the core system's source files match the logical
diff --git a/contrib/sb-manual/doc/profiling.lisp b/contrib/sb-manual/doc/profiling.lisp
index a8acd84f3..689541647 100644
--- a/contrib/sb-manual/doc/profiling.lisp
+++ b/contrib/sb-manual/doc/profiling.lisp
@@ -1,6 +1,7 @@
(in-package :sb-manual)
-(defsection @profiling (:title "Profiling")
+(defsection @profiling (:title "Profiling"
+ :concepts ("profiling"))
"SBCL includes both a deterministic profiler, that can collect
statistics on individual functions, and a more \"modern\",
statistical profiler.
@@ -9,7 +10,9 @@
(@deterministic-profiler section)
(@statistical-profiler section))
-(defsection @deterministic-profiler (:title "Deterministic Profiler")
+(defsection @deterministic-profiler
+ (:title "Deterministic Profiler"
+ :concepts (("profiling," "deterministic")))
"The package `SB-PROFILE` provides a classic, per-function-call
profiler.
@@ -20,7 +23,8 @@
(sb-profile:report function)
(sb-profile:reset function))
-(defsection @statistical-profiler (:title "Statistical Profiler")
+(defsection @statistical-profiler (:title "Statistical Profiler"
+ :concepts (("profiling," "statistical")))
"The `SB-SPROF` module, loadable by
(require :sb-sprof)
@@ -134,8 +138,8 @@
__Platform support__
Allocation profiling is only supported on SBCL builds that use the
- generational garbage collector. Tracking of call stacks at a depth
- of more than two levels is only supported on x86 and x86-64.
+ @GENERATIONAL-GC. Tracking of call stacks at a depth of more than
+ two levels is only supported on x86 and x86-64.
__Macros__"
(sb-sprof:with-profiling macro)
diff --git a/contrib/sb-manual/doc/start-stop.lisp b/contrib/sb-manual/doc/start-stop.lisp
index d884f6393..0754d626a 100644
--- a/contrib/sb-manual/doc/start-stop.lisp
+++ b/contrib/sb-manual/doc/start-stop.lisp
@@ -174,7 +174,7 @@
- `--disable-ldb`
Disable the low-level debugger. Only effective if SBCL is
- compiled with LDB.
+ compiled with @LDB. ~DISABLING-LDB
- `--lose-on-corruption`
@@ -184,7 +184,7 @@
to continue and handle the error in Lisp, but this will not
always work, and SBCL may malfunction or even hang. With this
option, upon encountering such an error, SBCL will exit instead
- of invoking LDB (if present and enabled).
+ of invoking @LDB (if present and enabled ~ENABLING-LDB).
- `--script <filename>`
diff --git a/contrib/sb-manual/doc/streams.lisp b/contrib/sb-manual/doc/streams.lisp
index 35d6aa11f..c15ae5f8f 100644
--- a/contrib/sb-manual/doc/streams.lisp
+++ b/contrib/sb-manual/doc/streams.lisp
@@ -30,7 +30,7 @@
(defsection @stream-external-formats (:title "Stream External Formats")
"The function STREAM-EXTERNAL-FORMAT returns the canonical name of
- the external format (See @EXTERNAL-FORMATS) used by the stream for
+ the @EXTERNAL-FORMAT (see @EXTERNAL-FORMATS) used by the stream for
character-based input and/or output.
When constructing file streams, for example using OPEN or
diff --git a/contrib/sb-manual/doc/support-and-bugs.lisp b/contrib/sb-manual/doc/support-and-bugs.lisp
index 1e33365d5..844be0fd1 100644
--- a/contrib/sb-manual/doc/support-and-bugs.lisp
+++ b/contrib/sb-manual/doc/support-and-bugs.lisp
@@ -96,7 +96,7 @@
such as `signal N is [un]blocked` or just hangs, and you want to
send a useful bug report then:
- - Compile SBCL with ldb enabled (feature `:sb-ldb`, see
+ - Compile SBCL with @LDB enabled (feature `:SB-LDB`, see
`base-target-features.lisp-expr`).
- Isolate a smallish test case, run it.
diff --git a/contrib/sb-sprof/sb-sprof.texinfo b/contrib/sb-sprof/sb-sprof.texinfo
index 7a6685fee..ea2025a6d 100644
--- a/contrib/sb-sprof/sb-sprof.texinfo
+++ b/contrib/sb-sprof/sb-sprof.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node statistical profiler
+@cindex profiling, statistical
@section Statistical Profiler
The @code{sb-sprof} module, loadable by
@@ -123,9 +124,11 @@ sampling runs.
@strong{Platform support}
+@cindex garbage collector, generational
+@cindex generational garbage collector
Allocation profiling is only supported on SBCL builds that use the
-generational garbage collector. Tracking of call stacks at a depth
-of more than two levels is only supported on x86 and x86-64.
+generational GC. Tracking of call stacks at a depth of more than
+two levels is only supported on x86 and x86-64.
@strong{Macros}
diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 9204ae772..8f2d8466f 100644
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node beyond the ansi standard
+@cindex reader extensions
@chapter Beyond the ANSI Standard
@menu
@@ -39,8 +40,12 @@ it still has quite a few. See @ref{contributed modules}.
@end menu
@node extended package prefix syntax
+@cindex extended package prefix syntax
+@cindex package prefix syntax, extended
@subsection Extended Package Prefix Syntax
+@cindex interning symbols
+@cindex symbols, interning
SBCL supports extended package prefix syntax, which allows specifying
an alternate package instead of @code{*package*} for the reader to use as
the default package for interning symbols:
@@ -55,13 +60,18 @@ Example:
'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
@end example
+@cindex package lock
+@cindex lock, package
@code{*package*} is not rebound during the course of reading a form with
extended package prefix syntax; if @code{foo::bar} would cause a
read-time package lock violation, so does @code{foo::(bar)}.
@node symbol name normalization
+@cindex symbol name normalization
+@cindex normalization of symbol name
@subsection Symbol Name Normalization
+@cindex Unicode
SBCL also extends the reader to normalize all symbols to @emph{Normalization
Form KC} in builds with Unicode enabled. Whether symbols are
normalized is controlled by
@@ -69,14 +79,18 @@ normalized is controlled by
@anchor{Function sb-ext readtable-normalization}
@ffindex @sortas{readtable-normalization sb-ext} readtable-normalization [sb-ext]
@deffn{Function} sb-ext:readtable-normalization readtable
-Returns @code{t} if @code{readtable} normalizes symbols to NFKC, and @code{nil} otherwise.
-The @code{readtable-normalization} of the standard readtable is @code{t}.
+@cindex NFKC
+@cindex normalization form compatibility composition
+Returns @code{t} if @code{readtable} normalizes symbols to NFKC, and @code{nil}
+otherwise. The @code{readtable-normalization} of the standard readtable is @code{t}.
@end deffn
Symbols created by @code{intern} and similar functions are not affected by
this setting. If @code{sb-ext:readtable-normalization} is @code{t}, symbols that
are not normalized are escaped during printing.
@node decimal syntax for rationals
+@cindex decimal syntax for rationals
+@cindex rational, decimal syntax
@subsection Decimal Syntax for Rationals
SBCL supports a decimal syntax for rationals, modelled after the
@@ -98,6 +112,8 @@ however, rational numbers are printed in their standard syntax,
irrespective of the value of @code{*read-default-float-format*}.
@node package local nicknames
+@cindex package-local nicknames
+@cindex nicknames, package-local
@section Package-Local Nicknames
SBCL allows giving packages local nicknames: they allow short and
@@ -239,6 +255,7 @@ specifies to signal a warning if SWANK package is in variance, and an
error otherwise.
@end deffn
@node garbage collection
+@cindex garbage collection
@section Garbage Collection
@menu
@@ -269,6 +286,7 @@ triggered during thread exits. In a multithreaded environment these hooks may
run in any thread.
@end deffn
@node finalization
+@cindex finalization
@subsection Finalization
Finalization allows code to be executed after an object has been
@@ -339,6 +357,7 @@ Examples:
Cancel all finalizations for @code{object}, returning @code{t} if it had a finalizer.
@end deffn
@node weak pointers
+@cindex weak pointers
@subsection Weak Pointers
Weak pointers allow references to objects to be maintained without
@@ -636,6 +655,8 @@ limitations, on structures (of metaclass @code{structure-class}).
For structures:
+@cindex unbound slot
+@cindex slot, unbound
@itemize
@item The name of a slot for the purposes of the slot access functions
is the symbol used as the slot-name in the slot-description in the
@@ -643,7 +664,7 @@ For structures:
@item @code{slot-value} and @code{slot-boundp} function as expected, including (for
@code{slot-value}) calling and respecting the return value of
- @code{slot-unbound} if the slot is unbound;
+ @code{slot-unbound} if the slot is unbound;
@item @code{(setf slot-value)} functions as expected, including performing
type checks to verify that the new value is of an appropriate type
@@ -839,6 +860,8 @@ part of the contract of the @code{:instance} or @code{:class} allocations.
In addition, SBCL supports extensions to the Metaobject protocol from
AMOP; at present, they are:
+@cindex unbound slot
+@cindex slot, unbound
@itemize
@item Compile-time support for generating specializer metaobjects from
specializer names in @code{defmethod} forms is provided by the
@@ -863,8 +886,8 @@ AMOP; at present, they are:
methods convert between classes and proper names and between lists
of the form @code{(EQL <x>)} and interned eql specializer objects.
-@item Distinguishing unbound instance allocated slots from bound ones
- when using @code{sb-mop:standard-instance-access} and
+@item Distinguishing unbound instance allocated slots from
+ bound ones when using @code{sb-mop:standard-instance-access} and
@code{sb-mop:funcallable-standard-instance-access} is possible by
comparison to the symbol-macro @code{sb-pcl:+slot-unbound+}.
@end itemize
@@ -1618,6 +1641,7 @@ Returns @code{t} if successful, otherwise returns @code{nil} and error
number (two values).
@end deffn
@node unicode support
+@cindex Unicode
@section Unicode Support
@menu
@@ -1859,6 +1883,7 @@ is @code{:east-asian}, Ambigious (class @code{:ai}) characters will be mapped to
Ideographic (@code{:id}) class instead of Alphabetic (@code{:al}).
@end deffn
@node string operations
+@cindex normalization of strings
@subsection String operations
SBCL can normalize strings using:
@@ -2083,7 +2108,8 @@ the condition accessor @code{sb-ext:name-conflict-symbols}.
@node hash table extensions
@section Hash Table Extensions
-Hash table extensions supported by SBCL are all controlled by keyword
+@cindex hash table
+hash table extensions supported by SBCL are all controlled by keyword
arguments to @code{make-hash-table}.
@anchor{Function common-lisp make-hash-table}
@@ -2246,6 +2272,7 @@ Return the @code{weakness} of @code{hash-table} which is one of @code{nil}, @cod
@code{:value}, @code{:key-and-value}, @code{:key-or-value}.
@end deffn
@node random number generation
+@cindex random number generation
@section Random Number Generation
The initial value of @code{*random-state*} is the same each time SBCL
@@ -2387,6 +2414,7 @@ available to individual operations or parts of computations:
@end itemize
@node timeout parameters
+@cindex timeout parameters
@subsection Timeout Parameters
Certain operations accept @code{:timeout} keyword arguments. These only
@@ -2432,6 +2460,9 @@ deadline.
Experimental: subject to change without prior notice.
@end deffn
@node synchronous timeouts
+@cindex synchronous timeout
+@cindex timeout, synchronous
+@cindex deadline
@subsection Synchronous Timeouts
Deadlines, in contrast to timeout parameters, are established for a
@@ -2511,6 +2542,8 @@ three seconds, a @code{sb-sys:deadline-timeout} condition will be signaled
after the @code{sleep} call has been executing for one second.
@node asynchronous timeouts
+@cindex asynchronous timeout
+@cindex timeout, asynchronous
@subsection Asynchronous Timeouts
Asynchronous timeouts are established for a dynamic scope using the
@@ -2716,6 +2749,8 @@ code and bring it up on the developers' mailing list.
@node efficiency hacks
@section Efficiency Hacks
+@cindex garbage collector, generational
+@cindex generational garbage collector
The @code{sb-ext:purify} function (available when @code{#+cheneygc}) causes
SBCL first to collect all garbage, then to mark all uncollected
objects as permanent, never again attempting to collect them as
@@ -2725,8 +2760,8 @@ efficiency when using a more sophisticated garbage collector which
is well suited to the program's memory usage pattern. It also allows
permanent code to be frozen at fixed addresses, a precondition for
using copy-on-write to share code between multiple Lisp processes.
-This is less important with modern generational garbage collectors,
-but not all SBCL platforms use such a garbage collector.
+This is less important with modern generational GC, but not all
+SBCL platforms use such a garbage collector.
The @code{sb-ext:truly-the} special form declares the type of the result of
the operations, producing its argument; the declaration is not
diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo
index d74bf6cd9..e3afe66ef 100644
--- a/doc/manual/compiler.texinfo
+++ b/doc/manual/compiler.texinfo
@@ -22,6 +22,8 @@ naive translation. Efficiency issues are sufficiently varied and
separate that they have their own chapter, @ref{efficiency}.
@node diagnostic messages
+@cindex compiler messsage
+@cindex messsage, compiler
@section Diagnostic Messages
@menu
@@ -31,6 +33,8 @@ separate that they have their own chapter, @ref{efficiency}.
@end menu
@node controlling verbosity
+@cindex compiler messsage verbosity
+@cindex verbosity of compiler messsages
@subsection Controlling Verbosity
The compiler can be quite verbose in its diagnostic reporting, rather
@@ -102,6 +106,8 @@ For information about muffling warnings signaled outside of the
compiler, see @ref{customization hooks for users}.
@node diagnostic severity
+@cindex compiler message severity
+@cindex severity of compiler message
@subsection Diagnostic Severity
There are four levels of compiler diagnostic severity:
@@ -150,7 +156,7 @@ has written, having proved that it is unreachable.
@menu
* Parts of a Compiler Diagnostic: parts of a compiler diagnostic.
* Original and Actual Source: original and actual source.
-* Processing Path: processing path.
+* Processing Paths: processing paths.
@end menu
The messages emitted by the compiler contain a lot of detail in a
@@ -190,6 +196,11 @@ When processing this program, the compiler will produce this warning:
In this example we see each of the six possible parts of a compiler
diagnostic:
+@cindex original source
+@cindex source, original
+@cindex processing path
+@cindex actual source
+@cindex source, actual
@itemize
@item @code{file: /tmp/foo.lisp} is the name of the file that the compiler
read the relevant code from. The file name is displayed because it
@@ -295,6 +306,10 @@ intervene between the original source and the actual source, then
the processing path will also be omitted.
@node original and actual source
+@cindex original source
+@cindex source, original
+@cindex actual source
+@cindex source, actual
@subsubsection Original and Actual Source
The @emph{original source} displayed will almost always be a list. If
@@ -341,8 +356,9 @@ This message is not saying that there is a problem somewhere in this
this example, the problem is that @code{a}'s @code{nil} initial value is not a
@code{fixnum}.
-@node processing path
-@subsubsection Processing Path
+@node processing paths
+@cindex processing path
+@subsubsection Processing Paths
The processing path is mainly useful for debugging macros, so if you
don't write macros, you can probably ignore it. Consider this example:
@@ -374,7 +390,10 @@ Note that @code{do} appears in the processing path. This is because
(declare (type unsigned-byte i)))
@end example
-The rest of the processing path results from the expansion of @code{do}:
+@cindex macroexpansion
+@cindex source transform
+The rest of the processing path results from the macroexpansion of
+@code{do}:
@example
(block nil
@@ -431,12 +450,15 @@ not been proven to always hold are asserted at runtime.
provide some exceptions to this rule, see
@ref{implementation limitations}.}
+@cindex safety, optimization quality
+@cindex optimization quality safety
CLOS slot types form a notable exception. Types declared using the
@code{:type} slot option in @code{defclass} are asserted if and only if the class
-was defined in @emph{safe code} and the slot access location is in @emph{safe
-code} as well. This laxness does not pose any internal consistency
-issues, as the CLOS slot types are not available for the type
-inferencer, nor do CLOS slot types provide any efficiency benefits.
+was defined in @emph{safe code} and the slot access location is
+in @emph{safe code} as well. This laxness does not pose any internal
+consistency issues, as the CLOS slot types are not available for the
+type inferencer, nor do CLOS slot types provide any efficiency
+benefits.
There are three type checking policies available in SBCL, selectable
via @code{optimize} declarations.
@@ -477,6 +499,8 @@ Used when @code{(= safety 0)}.
@end itemize
@node precise type checking
+@cindex type checking, precise
+@cindex precise type checking
@subsection Precise Type Checking
Precise checking means that the check is done as though @code{typep}
@@ -495,6 +519,9 @@ slots as precisely as possible. This often involves the use of @code{or},
@code{member}, and other list-style type specifiers.
@node getting existing programs to run
+@cindex existing programs, getting them to run
+@cindex types, portability
+@cindex compatibility with other Lisps
@subsection Getting Existing Programs to Run
Since SBCL's compiler does much more comprehensive type checking than
@@ -503,9 +530,11 @@ been debugged using other compilers. These errors are mostly incorrect
declarations, although compile-time type errors can find actual bugs
if parts of the program have never been tested.
+@cindex safety, optimization quality
+@cindex optimization quality safety
Some incorrect declarations can only be detected by run-time type
checking. It is very important to initially compile a program with
-full type checks (high @code{safety} optimization) and then test this safe
+full type checks (high safety optimization) and then test this safe
version. After the checking version has been tested, then you can
consider weakening or eliminating type checks. @emph{This applies even to
previously debugged programs} because the SBCL compiler does much
@@ -787,6 +816,8 @@ Examples:
@end menu
@node type errors at compile time
+@cindex compile-time type error
+@cindex type error, compile-time
@subsection Type Errors at Compile Time
If the compiler can prove at compile time that some portion of the
@@ -837,6 +868,7 @@ executed), so it compiles the erroneous code (which will always signal
an error if it is executed) and gives a warning.
@node errors during macroexpansion
+@cindex macroexpansion, errors during
@subsection Errors During Macroexpansion
The compiler handles errors that happen during macroexpansion, turning
@@ -866,6 +898,8 @@ gives this error:
@end example
@node read errors
+@cindex compiler read error
+@cindex read error, compiler
@subsection Read Errors
SBCL's compiler does not attempt to recover from read errors when
@@ -873,6 +907,9 @@ reading a source file, but instead just reports the offending
character position and gives up on the entire source file.
@node open coding and inline expansion
+@cindex open-coding
+@cindex inline expansion
+@cindex static functions
@section Open Coding and Inline Expansion
Since Common Lisp forbids the redefinition of standard functions, the
@@ -941,6 +978,7 @@ or compiled as @emph{static call}. Static function call uses a more
efficient calling convention that forbids redefinition.
@node interpreter
+@cindex interpreter
@section Interpreter
By default SBCL implements @code{eval} by calling the native code
diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index 12503e683..98b381bfb 100644
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node debugger
+@cindex debugger
@chapter Debugger
@menu
@@ -145,6 +146,7 @@ Initially empty, @code{*debug-print-variable-alist*} is typically used to
provide bindings for printer control variables.
@end deffn
@node stack frames
+@cindex stack frame
@section Stack Frames
@menu
@@ -288,6 +290,12 @@ by that name. Functions defined by @code{labels} and @code{flet} will appear as
lambdas will appear as @code{(lambda <lambda-list>)}.
@node entry point details
+@cindex external entry point
+@cindex entry point, external
+@cindex block compilation, debugger implications
+@cindex external, stack frame kind
+@cindex optional, stack frame kind
+@cindex cleanup, stack frame kind
@subsubsection Entry Point Details
Sometimes the compiler introduces new functions that are used to
@@ -305,8 +313,10 @@ entry points.
@node debug tail recursion
@subsection Debug Tail Recursion
+@cindex tail recursion
+@cindex recursion, tail
The compiler is @emph{properly tail recursive}. If a function call is
-in a tail-recursive position, the stack frame will be deallocated
+in a tail recursive position, the stack frame will be deallocated
@emph{at the time of the call}, rather than after the call returns.
Consider this backtrace:
@@ -346,6 +356,8 @@ optimization quality is greater than 2. See
@ref{debugger policy control}.
@node unknown locations and interrupts
+@cindex unknown code location
+@cindex code location unknown
@subsection Unknown Locations and Interrupts
The debugger operates using special debugging information attached to
@@ -359,14 +371,17 @@ displayed.
There are three reasons why a code location could be unknown:
+@cindex interrupt
+@cindex run-time error
+@cindex error, run-time
@itemize
@item There is inadequate debug information due to the value of the
@code{debug} optimization quality. See @ref{debugger policy control}.
@item The debugger was entered because of an interrupt such as @code{C-c}.
-@item A hardware error such as a bus error occurred in code that was
- compiled unsafely due to the value of the @code{safety}
+@item A hardware error such as a bus error occurred in
+ code that was compiled unsafely due to the value of the @code{safety}
optimization quality.
@end itemize
@@ -382,6 +397,8 @@ be located. If this happens, return from the interrupt and try
again.
@node variable access
+@cindex debug variables
+@cindex variable, debugger access
@section Variable Access
@menu
@@ -445,6 +462,8 @@ The result of this function is limited to the availability of
variable information. This is @code{setf}able.
@end deffn
@node variable value availability
+@cindex variable, value availabilty in debugger
+@cindex debug variable, value availabilty
@subsection Variable Value Availability
The value of a variable may be unavailable to the debugger in portions
@@ -470,11 +489,13 @@ never be available in the interrupted frame. See
The value of a variable may be unavailable for these reasons:
+@cindex debug, optimization quality
+@cindex optimization quality debug
@itemize
-@item The value of the @code{debug} optimization quality may have omitted debug
- information needed to determine whether the variable is available.
- Unless a variable is an argument, its value will only be available
- when @code{debug} is at least 2.
+@item The value of the debug optimization quality may have omitted
+ debug information needed to determine whether the variable is
+ available. Unless a variable is an argument, its value will only
+ be available when @code{debug} is at least 2.
@item The compiler did lifetime analysis and determined that the value
was no longer needed, even though its scope had not been exited.
@@ -543,6 +564,7 @@ proved the variable could never take on. This may result in bad
things happening.
@node source location printing
+@cindex source location in debugger
@section Source Location Printing
@menu
@@ -671,7 +693,9 @@ same @code{eq} list twice. If you don't define read macros and don't use
@node source location availability
@subsection Source Location Availability
-Source location information is only available when the @code{debug}
+@cindex debug, optimization quality
+@cindex optimization quality debug
+Source location information is only available when the debug
optimization quality is at least 2. If source location information
is unavailable, the source commands will give an error message.
@@ -684,11 +708,14 @@ print
Unknown location: using block start.
@end example
+@cindex basic block
+@cindex block, basic
and then proceed to print the source location for the start of the
@emph{basic block} enclosing the code location. It's a bit complicated to
explain exactly what a basic block is, but here are some properties
of the block start location:
+@cindex block, start location
@itemize
@item The block start location may be the same as the true location.
@@ -712,10 +739,14 @@ and the next conditional (but watch out because the compiler may
have changed the program on you.)
@node debugger policy control
+@cindex debugger policy
+@cindex policy, debugger
@section Debugger Policy Control
+@cindex debug, optimization quality
+@cindex optimization quality debug
The compilation policy specified by @code{optimize} declarations
-affects the behavior seen in the debugger. The @code{debug} quality
+affects the behavior seen in the debugger. The debug quality
directly affects the debugger by controlling the amount of debugger
information dumped. Other optimization qualities have indirect but
observable effects due to changes in the way compilation is done.
@@ -780,14 +811,16 @@ variable special-casing (see @ref{variable value availability}). Some
degree of speed/debuggability tradeoff is unavoidable, but the
effect is not too drastic when @code{debug} is at least 2.
+@cindex inline, semi
+@cindex semi-inline
In addition to @code{inline} and @code{notinline} declarations, the relative
values of the @code{speed} and @code{space} qualities also change whether
functions are inline expanded. If a function is inline expanded,
then there will be no frame to represent the call, and the arguments
will be treated like any other local variable. Functions may also be
-@emph{semi-inline}, in which case there is a frame to represent the call,
-but the call is to an optimized local version of the function, not
-to the original function.
+@emph{semi inline}, in which case there is a frame to represent the
+call, but the call is to an optimized local version of the function,
+not to the original function.
@node exiting commands
@section Exiting Commands
@@ -846,6 +879,7 @@ function, but a few show general information.
@end itemize
@node breakpoint commands
+@cindex breakpoint
@section Breakpoint Commands
@menu
@@ -982,6 +1016,8 @@ based stepping commands, which have much higher overhead.
@end quotation
@node function tracing
+@cindex tracing
+@cindex function, tracing
@section Function Tracing
The tracer causes selected functions to print their arguments and
@@ -1152,6 +1188,8 @@ The default value for the @code{:encapsulate} option to @code{trace}.
The default value for the @code{:report} option to @code{trace}.
@end deffn
@node single stepping
+@cindex stepper
+@cindex single-stepping
@section Single Stepping
SBCL includes an instrumentation based single-stepper for compiled
@@ -1189,6 +1227,14 @@ functions in question have been compiled with sufficient @code{debug} policy
to be at least partially steppable.
@end deffn
@node enabling and disabling the debugger
+@cindex debugger, enabling
+@cindex debugger, disabling
+@cindex enabling debugger
+@cindex disabling debugger
+@cindex enabling LDB
+@cindex LDB, enabling
+@cindex disabling LDB
+@cindex LDB, disabling
@section Enabling and Disabling the Debugger
In certain contexts (e.g. non-interactive applications), it may be
diff --git a/doc/manual/deprecation.texinfo b/doc/manual/deprecation.texinfo
index 56f36a609..7d9640797 100644
--- a/doc/manual/deprecation.texinfo
+++ b/doc/manual/deprecation.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node deprecation
+@cindex deprecation
@chapter Deprecation
@menu
diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo
index 8e8615a81..dd6543167 100644
--- a/doc/manual/efficiency.texinfo
+++ b/doc/manual/efficiency.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node efficiency
+@cindex efficicency
@chapter Efficiency
@menu
@@ -13,6 +14,7 @@
@end menu
@node slot access
+@cindex slot access
@section Slot Access
@menu
@@ -109,9 +111,11 @@ of values when they are recognized as having dynamic extent:
and one-dimensional, and has a constant @code{:element-type};
@quotation
+@cindex safety, optimization quality
+@cindex optimization quality safety
@strong{Warning}: Stack space is limited, so allocation of a large
vector may cause stack overflow. Stack overflow checks are
-done except in zero @code{safety} policies.
+done except in 0 safety policies.
@end quotation
@item closures defined with @code{flet} or @code{labels} with a bound @code{dynamic-extent}
@@ -271,6 +275,9 @@ detect incorrect usage of dynamic extent declarations.
@end example
@node modular arithmetic
+@cindex modular arithmetic
+@cindex arithmetic, modular
+@cindex arithmetic, hardware
@section Modular Arithmetic
@menu
@@ -323,6 +330,9 @@ translated into signed modular arithmetic:
@end example
@node recognized idioms
+@cindex modular arithmetic
+@cindex arithmetic, modular
+@cindex arithmetic, hardware
@section Recognized Idioms
@menu
@@ -431,12 +441,14 @@ points to keep in mind.
explicit type declarations.)
@end itemize
+@cindex garbage collector, generational
+@cindex generational garbage collector
@itemize
@item Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
- has gotten a generational garbage collector. This means that there
- are some efficiency implications of various patterns of memory
- usage which aren't discussed in the CMUCL manual. (Some new
- material should be written about this.)
+ has gotten a generational GC. This means that there are some
+ efficiency implications of various patterns of memory usage which
+ aren't discussed in the CMUCL manual. (Some new material should be
+ written about this.)
@item SBCL has some important known efficiency problems. Perhaps the
most important are
diff --git a/doc/manual/external-formats.texinfo b/doc/manual/external-formats.texinfo
index 3112bbf74..bf188e4f9 100644
--- a/doc/manual/external-formats.texinfo
+++ b/doc/manual/external-formats.texinfo
@@ -1,6 +1,8 @@
@c Generated by the sb-manual contrib. Do not edit.
@node external formats
+@cindex external format
+@cindex format, external
@chapter External Formats
@menu
diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index 8481d260a..800ffa37e 100644
--- a/doc/manual/ffi.texinfo
+++ b/doc/manual/ffi.texinfo
@@ -181,6 +181,8 @@ the first dimension. Fixed-size arrays can be allocated as array
elements, structure slots or @code{with-alien} variables. Dynamic arrays
can only be allocated using @code{make-alien}.
+@cindex external format
+@cindex format, external
@itemize
@item The foreign type specifier @code{(struct <name> &rest <fields>)}
describes a structure type with the specified @code{<name>} and
@@ -256,14 +258,14 @@ current (local or global) alien structure type definition of
declare that no useful value is returned. Using @code{alien-funcall} to
call a @code{void} foreign function will return zero values.
-@item The foreign type specifier @code{(C-STRING &KEY <external-format>
+@item The foreign type specifier @code{(c-string &key <external-format>
<element-type> <not-null>)} is similar to @code{(* char)} but is
interpreted as a null-terminated string, and is automatically
converted into a Lisp string when accessed; or if the pointer is C
@code{null} or 0, then accessing it gives Lisp @code{nil} unless
@code{<not-null>} is true, in which case a @code{type-error} is signalled.
-External format conversion is automatically done when Lisp
+external format conversion is automatically done when Lisp
strings are passed to foreign code, or when foreign strings are
passed to Lisp code. If the type specifier has an explicit
@code{<external-format>}, that external format will be used.
@@ -974,6 +976,8 @@ Note that the garbage collector moves objects, and won't be able to fix
up any references in C variables. There are three mechanisms for
coping with this:
+@cindex garbage collector, generational
+@cindex generational garbage collector
@itemize
@item @code{sb-ext:purify} moves all live Lisp data into static or read-only
areas such that it will never be moved (or freed) again in the
@@ -981,11 +985,10 @@ coping with this:
@item @code{sb-sys:with-pinned-objects} is a macro which arranges for some set
of objects to be pinned in memory for the dynamic extent of its
- body forms. On ports which use the generational garbage
- collector (most, as of this writing) this affects exactly the
- specified objects. On other ports it is implemented by turning off
- GC for the duration (so could be said to have a whole-world
- granularity).
+ body forms. On ports which use the generational GC
+ (most, as of this writing) this affects exactly the specified
+ objects. On other ports it is implemented by turning off GC for
+ the duration (so could be said to have a whole-world granularity).
@item Disable GC, using the SB-EXT:WITHOUT-GCING macro.
@end itemize
diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo
index 0cb76cf86..790f60eb2 100644
--- a/doc/manual/intro.texinfo
+++ b/doc/manual/intro.texinfo
@@ -139,8 +139,8 @@ also supports allocation profiling.
regression and unit-test framework.
@item @strong{MD5 Sums:} The @ref{sb md5} module provides an implementation of the
- MD5 message digest algorithm for Common Lisp, using the modular
- arithmetic optimizations provided by SBCL.
+ MD5 message digest algorithm for Common Lisp, using the
+ @ref{modular arithmetic} optimizations provided by SBCL.
@end itemize
@node idiosyncrasies
@@ -506,11 +506,12 @@ still reflected in the current implementation:
supplying low-level services and loading a Lisp @code{.core} file.
@end itemize
+@cindex garbage collector, generational
+@cindex generational garbage collector
SBCL also inherited some newer architectural features from CMUCL.
The most important is that on some architectures it has a
-generational garbage collector (GC), which has various
-implications (mostly good) for performance. These are discussed in
-another chapter, @ref{efficiency}.
+generational GC, which has various implications (mostly good) for
+performance. These are discussed in another chapter, @ref{efficiency}.
SBCL has diverged from CMUCL in that SBCL is now essentially a
compiler-only implementation of Common Lisp. This is a change in
@@ -535,8 +536,10 @@ x86 architecture. Some things (like tracing and debugging) do not work
particularly well there. SBCL should be able to improve in these areas
(and has already improved in some other areas), but it takes a while.
+@cindex garbage collector, conservative
+@cindex conservative garbage collector
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
-@emph{conservative} GC. This means that it doesn't maintain a strict
+_@@CONSERVATIVE-GC. This means that it doesn't maintain a strict
separation between tagged and untagged data, instead treating some
untagged data (e.g. raw floating point numbers) as possibly-tagged
data and so not collecting any Lisp objects that they point to. This
@@ -544,9 +547,9 @@ has some negative consequences for average time efficiency (though
possibly no worse than the negative consequences of trying to
implement an exact GC on a processor architecture as register-poor
as the X86) and also has potentially unlimited consequences for
-worst-case memory efficiency. In practice, conservative garbage
-collectors work reasonably well, not getting anywhere near the worst
-case. But they can occasionally cause odd patterns of memory usage.
+worst-case memory efficiency. In practice, conservative GCs work
+reasonably well, not getting anywhere near the worst case. But they
+can occasionally cause odd patterns of memory usage.
The fork from CMUCL was based on a major rewrite of the system
bootstrap process. CMUCL has for many years tolerated a very unusual
diff --git a/doc/manual/package-locks.texinfo b/doc/manual/package-locks.texinfo
index 93235e009..248e0275f 100644
--- a/doc/manual/package-locks.texinfo
+++ b/doc/manual/package-locks.texinfo
@@ -1,6 +1,8 @@
@c Generated by the sb-manual contrib. Do not edit.
@node package locks
+@cindex package lock
+@cindex lock, package
@chapter Package Locks
@menu
@@ -66,6 +68,7 @@ Unless explicitly altered by @code{defpackage},
@node lexical bindings and declarations
@subsubsection Lexical Bindings and Declarations
+@cindex declaration
Lexical bindings or declarations that violate package locks cause a
compile-time warning, and a runtime @code{program-error} when the form that
violates package locks would be executed.
diff --git a/doc/manual/pathnames.texinfo b/doc/manual/pathnames.texinfo
index 3821d7b27..ae28c3ff7 100644
--- a/doc/manual/pathnames.texinfo
+++ b/doc/manual/pathnames.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node pathnames
+@cindex pathname
@chapter Pathnames
@menu
@@ -40,6 +41,8 @@ Using @code{(:home} @code{"user")} form on Windows signals an error.
@node the sys logical pathname host
@subsection The SYS Logical Pathname Host
+@cindex logical pathname
+@cindex pathname, logical
The logical pathname host named by @code{"SYS"} exists in SBCL.
Its @code{logical-pathname-translations} may be set by the site or the user
applicable to point to the locations of the system's sources; in
diff --git a/doc/manual/profiling.texinfo b/doc/manual/profiling.texinfo
index 1d9a9d568..00aa14c25 100644
--- a/doc/manual/profiling.texinfo
+++ b/doc/manual/profiling.texinfo
@@ -1,6 +1,7 @@
@c Generated by the sb-manual contrib. Do not edit.
@node profiling
+@cindex profiling
@chapter Profiling
@menu
@@ -15,6 +16,7 @@ statistical profiler.
Inlined functions do not appear in the results reported by either.
@node deterministic profiler
+@cindex profiling, deterministic
@section Deterministic Profiler
The package @code{sb-profile} provides a classic, per-function-call
diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 8a2578bd2..629d4af1c 100644
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -382,6 +382,12 @@ system.
@node runtime options
@subsection Runtime Options
+@cindex LDB
+@cindex disabling LDB
+@cindex LDB, disabling
+@cindex LDB
+@cindex enabling LDB
+@cindex LDB, enabling
@itemize
@item @code{--core <corefilename>}
@@ -415,7 +421,7 @@ and @code{--disable-debugger} options.
@item @code{--disable-ldb}
Disable the low-level debugger. Only effective if SBCL is
-compiled with @code{ldb}.
+compiled with LDB. disabling LDB
@item @code{--lose-on-corruption}
@@ -425,7 +431,7 @@ corrupt the image. By default, SBCL prints a warning, then tries
to continue and handle the error in Lisp, but this will not
always work, and SBCL may malfunction or even hang. With this
option, upon encountering such an error, SBCL will exit instead
-of invoking @code{ldb} (if present and enabled).
+of invoking LDB (if present and enabled enabling LDB).
@item @code{--script <filename>}
diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo
index 12b05b8be..d723ca060 100644
--- a/doc/manual/streams.texinfo
+++ b/doc/manual/streams.texinfo
@@ -38,8 +38,10 @@ streams:
@node stream external formats
@section Stream External Formats
+@cindex external format
+@cindex format, external
The function @code{stream-external-format} returns the canonical name of
-the external format (See @ref{external formats}) used by the stream for
+the external format (see @ref{external formats}) used by the stream for
character-based input and/or output.
When constructing file streams, for example using @code{open} or
diff --git a/doc/manual/support-and-bugs.texinfo b/doc/manual/support-and-bugs.texinfo
index 528b39330..70eaebeac 100644
--- a/doc/manual/support-and-bugs.texinfo
+++ b/doc/manual/support-and-bugs.texinfo
@@ -115,8 +115,9 @@ If you run into a signal related bug, you are getting fatal errors
such as @code{signal N is [un]blocked} or just hangs, and you want to
send a useful bug report then:
+@cindex LDB
@itemize
-@item Compile SBCL with ldb enabled (feature @code{:sb-ldb}, see
+@item Compile SBCL with LDB enabled (feature @code{:sb-ldb}, see
@code{base-target-features.lisp-expr}).
@item Isolate a smallish test case, run it.
diff --git a/src/code/reader.lisp b/src/code/reader.lisp
index a4d5483de..8ad0027dc 100644
--- a/src/code/reader.lisp
+++ b/src/code/reader.lisp
@@ -249,8 +249,8 @@
(declaim (inline readtable-normalization))
(defun readtable-normalization (readtable)
- "Returns T if READTABLE normalizes symbols to NFKC, and NIL otherwise.
-The READTABLE-NORMALIZATION of the standard readtable is T."
+ "Returns T if READTABLE normalizes symbols to SB-MANUAL::@NFKC, and NIL
+otherwise. The READTABLE-NORMALIZATION of the standard readtable is T."
(%readtable-normalization readtable))
(defun (setf readtable-normalization) (new-value readtable)
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL