master: various documentation changes
melisgl via Sbcl-commits <[email protected]> Thu, 02 Jul 2026 13:09:31 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via 2be4173812091f6c17def98a3f0b48a56b67ad46 (commit)
from ff7a653710315dd1d3a4a2ecdc70a9ca02a8ad7f (commit)
- Log -----------------------------------------------------------------
commit 2be4173812091f6c17def98a3f0b48a56b67ad46
Author: Gabor Melis <[email protected]>
Date: Thu Jul 2 11:15:27 2026 +0200
various documentation changes
- make bug reporting instructions more consistent
- add DOCUMENTATION file
- deduplicate Texinfo @cindex lines
- fix typos and URLs
- update obsolete references to Texinfo
- standardize the spelling of HyperSpec
---
BUGS | 6 +++-
DOCUMENTATION | 26 +++++++++++++++++
HACKING | 3 +-
INSTALL | 18 ++++++------
README | 12 ++++----
binary-distribution.sh | 1 +
contrib/STANDARDS | 22 ++++++---------
contrib/sb-manual/TODO.md | 44 ++++++++++++++++-------------
contrib/sb-manual/doc/deprecation.lisp | 2 +-
contrib/sb-manual/doc/intro.lisp | 8 ++++--
contrib/sb-manual/doc/support-and-bugs.lisp | 10 ++++---
contrib/sb-manual/markdown.lisp | 2 +-
contrib/sb-manual/texinfo.lisp | 3 ++
doc/README | 6 ++--
doc/manual/.gitignore | 1 -
doc/manual/README | 5 ++--
doc/manual/deprecation.texinfo | 2 +-
doc/manual/intro.texinfo | 8 ++++--
doc/manual/start-stop.texinfo | 1 -
doc/manual/support-and-bugs.texinfo | 10 ++++---
src/code/coerce.lisp | 2 +-
src/code/early-extensions.lisp | 2 +-
src/code/target-format.lisp | 4 +--
23 files changed, 119 insertions(+), 79 deletions(-)
diff --git a/BUGS b/BUGS
index 1e2fde677..bbc3881b3 100644
--- a/BUGS
+++ b/BUGS
@@ -14,4 +14,8 @@ Historical note: before Launchpad was adopted this file contained a
list of currently open bugs. If you run into an SBCL bug number in the
range 1-431 inclusive, it refers to that list.
-Refer to User Manual for more details.
+Refer to the User Manual for more details at
+
+ https://www.sbcl.org/manual/#Reporting-Bugs
+
+or SB-MANUAL:@REPORTING-BUGS.
diff --git a/DOCUMENTATION b/DOCUMENTATION
new file mode 100644
index 000000000..899b7596a
--- /dev/null
+++ b/DOCUMENTATION
@@ -0,0 +1,26 @@
+Files:
+
+- doc/sbcl.1: man page
+
+- doc/manual/sbcl.{info*,pdf,html}: The user manual. See the "INSTALL"
+ file on how to build them.
+
+A prebuilt manual for the latest release is available for download in
+HTML and PDF formats at <https://www.sbcl.org>.
+
+Sections of the manual are defined and exported from the SB-MANUAL
+package (available after (REQUIRE :SB-MANUAL)). The top-level section
+is SB-MANUAL:@SBCL-MANUAL. You can browse these directly (e.g. with
+Slime's M-.) if the SBCL sources are available. Note that all other
+formats (including the intermediate Texinfo) are generated from these
+sections and the docstrings of individual Lisp definitions (of e.g.
+functions, variables).
+
+> An alternative, unofficial (and unsupported by the SBCL project)
+> rendering of the manual is available at <https://fixnum.com> in
+> HTML, PDF, Markdown and plain text for the latest development
+> version. This version is heavily linked both internally and to the
+> HyperSpec, and documents e.g. the default values of arguments and
+> the initial values of variables. It is generated with MGL-PAX v0.5+
+> (<https://fixnum.com/pax-manual.html>), which also supports browsing
+> the documentation live.
diff --git a/HACKING b/HACKING
index 4d927fa33..6a1a19a57 100644
--- a/HACKING
+++ b/HACKING
@@ -49,7 +49,8 @@ We aren't always as well-educated as we'd like to be...
Ready-to-apply patches should be submitted via Launchpad: please add
the tag "review" to the associated bug (create new bug with name if
-there isn't one about the issue yet.)
+there isn't one about the issue yet). Alternatively, they may be sent
+to the sbcl-bugs mailing list.
Patches requiring more widespread discussion and feedback should be
sent to the sbcl-devel mailing list.
diff --git a/INSTALL b/INSTALL
index 572dd9641..d2d176fbb 100644
--- a/INSTALL
+++ b/INSTALL
@@ -145,10 +145,10 @@ INSTALLING SBCL
$ cd ./doc/manual && make
- This builds the Info, HTML and PDF documentation from the Texinfo
- sources. The manual includes documentation strings from the built
- SBCL. If SBCL itself has not been built yet, but an installed one
- is found, documentation strings from the installed version are used.
+ This builds the Info, HTML and PDF documentation from the SB-MANUAL
+ contrib. The manual includes documentation strings from the built
+ SBCL. If SBCL itself has not been built yet, but an installed one is
+ found, documentation strings from the installed version are used.
Now you should have the same src/runtime/sbcl and output/sbcl.core
files that come with the binary distribution, and you can install
@@ -230,7 +230,7 @@ INSTALLING SBCL
files under "src/runtime", down- or upgrading GCC may help.
* Ask for help on the mailing lists referenced from
- <http://www.sbcl.org/>.
+ <https://www.sbcl.org/>.
2.4. Tracking SBCL sources
@@ -288,9 +288,7 @@ INSTALLING SBCL
by e.g. testing during the monthly freeze periods, and most
importantly by reporting any problems.
- For further support, see Getting Support and Reporting Bugs
- in the manual, or
+ For further support, see "Getting Support and Reporting Bugs"
+ (SB-MANUAL:@SUPPORT-AND-BUGS) in the manual locally or at
- http://www.sbcl.org/manual/Getting-Support-and-Reporting-Bugs.html
-
- if you do not have the manual for some reason.
+ https://www.sbcl.org/manual/#Getting-Support-and-Reporting-Bugs
diff --git a/README b/README
index e4f14c2df..58aa49c40 100644
--- a/README
+++ b/README
@@ -9,19 +9,17 @@ To find out more about who created the system, see the "CREDITS" file.
If you'd like information about the legalities of copying the system,
see the "COPYING" file.
-If you'd like more information about using the system, see the man
-page, "sbcl.1", or the user manual in the "doc/manual" subdirectory of
-the distribution. (The user manual is maintained as Texinfo in the
-source distribution; HTML version is available for download, and
-"INSTALL" describes how to build the Texinfo version in HTML and PDF.)
+The "DOCUMENTATION" file describes the various formats and ways to
+access the documentation.
The system is a work in progress. See the "TODO" file in the source
distribution for some highlights.
See the "BUGS" file for how to view or report bugs.
-If you'd like to make suggestions, report a bug, or help to improve the
-system, please send mail to one of the mailing lists:
+If you'd like to make suggestions or help to improve the system,
+please send mail to one of the mailing lists:
+
[email protected]
[email protected]
Note that as a spam reduction measure you must subscribe to the lists
diff --git a/binary-distribution.sh b/binary-distribution.sh
index 011ca0080..0a4f10d45 100755
--- a/binary-distribution.sh
+++ b/binary-distribution.sh
@@ -19,6 +19,7 @@ tar -cf $b-binary.tar \
$b/src/runtime/sbcl.mk \
`grep '^LIBSBCL=' $b/src/runtime/sbcl.mk | cut -d= -f2- | while read lib; do echo $b/src/runtime/$lib; done` \
$b/BUGS $b/COPYING $b/CREDITS $b/INSTALL $b/NEWS $b/README \
+ $b/DOCUMENTATION \
$b/install.sh $b/find-gnumake.sh $b/sbcl-pwd.sh $b/run-sbcl.sh \
$b/doc/sbcl.1 \
$b/pubring.pgp \
diff --git a/contrib/STANDARDS b/contrib/STANDARDS
index 9fb19a793..05fc88f92 100644
--- a/contrib/STANDARDS
+++ b/contrib/STANDARDS
@@ -71,23 +71,19 @@ good place to test that they still exist, etc.
* Documentation
-Each package should provide documentation in Texinfo format. For the
-documentation to be included in the sbcl manual, the following must
-hold:
+Each package should provide documentation in SB-MANUAL format. For the
+documentation to be included in the SBCL manual, you must
-- Each Texinfo file must have the extension `.texinfo' so the
- automatic manual builder will find it.
+- symlink contrib/sb-manual/doc/<some-contrib>/manual.lisp to
+ contrib/<some-contrib>/manual.lisp,
-- It must contain one @node - @section pair at the top and only
- @subsection (or lower) sectioning commands within, e.g.
+- add the symlink to contrib/sb-manual/sb-manual.asd,
-@node Sample Contrib
-@section Sample Contrib
-...
+- modify SB-MANUAL::*PAGES*.
- so that the contrib menu can be created automatically.
-
-Take care to choose unique node names.
+Take care to choose globally unique and meaningful section names, as
+the names are exported from SB-MANUAL and also visible to the user as
+HTML anchors.
[ make install should copy the documentation somewhere that the user
can find it ]
diff --git a/contrib/sb-manual/TODO.md b/contrib/sb-manual/TODO.md
index e15a93b4b..72d2432ae 100644
--- a/contrib/sb-manual/TODO.md
+++ b/contrib/sb-manual/TODO.md
@@ -1,26 +1,32 @@
-# How/when to load/include docs of contribs?
+- How/when to load/include docs of contribs?
-Currently, `SB-MANUAL` loads *all* contribs to be able to query the
-definition docstrings. Each contrib directory has a `manual.lisp`
-file, which is part of the `SB-MANUAL` contrib (the files are
-symlinked).
+ Currently, `sb-manual` loads *all* contribs to be able to query
+ the definition docstrings. Each contrib directory has a
+ `manual.lisp` file, which is part of the `sb-manual` contrib (the
+ files are symlinked).
-On the positive side, this does not load extra stuff until the user
-`REQUIRE`s `SB-MANUAL`. However, then it loads all contribs.
+ On the positive side, this does not load extra stuff until the
+ user `require`s `sb-manual`. However, then it loads all contribs.
-A finer grained approach may be preferable. For example, we could make
-the `manual.lisp` file part of the contrib itself. Then people might
-complain about the overhead of loading/having the docstrings in the
-image.
+ A finer grained approach may be preferable. For example, we could
+ make the `manual.lisp` file part of the contrib itself. Then
+ people might complain about the overhead of loading/having the
+ docstrings in the image.
-Alternatively, we could have `sb-bsd-sockets/manual.lisp` as a new
-`SB-BSD-SOCKETS-MANUAL` module. Eh.
+ Alternatively, we could have `sb-bsd-sockets/manual.lisp` as a new
+ `sb-bsd-sockets-manual` module. Eh.
-# How to deal with repetitive package names?
+- How to deal with repetitive package names?
-For example, `SB-ALIEN` is `:USE`d by `SB-MANUAL` so that the section
-docstrings need not fully qualify with `SB-ALIEN:` a thousand times.
-In the generated Texinfo, this can be a tad confusing. In output
-formats with links (e.g. HTML from PAX), this is clearly preferable.
+ For example, `sb-alien` is `:use`d by `sb-manual` so that the
+ section docstrings need not fully qualify with `sb-alien:` a
+ thousand times. In the generated Texinfo, this can be a tad
+ confusing. In output formats with links (e.g. HTML from PAX), this
+ is clearly preferable.
-Nicknames, maybe?
+ Nicknames, maybe?
+
+- Improve section names
+
+ They are a soft interface: exported from `sb-manual` and visible
+ to the user via HTML anchors.
diff --git a/contrib/sb-manual/doc/deprecation.lisp b/contrib/sb-manual/doc/deprecation.lisp
index 0b78b4a0f..8937f167c 100644
--- a/contrib/sb-manual/doc/deprecation.lisp
+++ b/contrib/sb-manual/doc/deprecation.lisp
@@ -163,7 +163,7 @@
in various namespaces as deprecated.
> _Note_: See the `namespace` CLHS glossary entry in the glossary of
- > the Common Lisp Hyperspec.)"
+ > the Common Lisp HyperSpec.)"
(sb-ext:deprecated declaration))
(defsection @deprecation-examples (:title "Deprecation Examples")
diff --git a/contrib/sb-manual/doc/intro.lisp b/contrib/sb-manual/doc/intro.lisp
index deab55fce..5b577d87f 100644
--- a/contrib/sb-manual/doc/intro.lisp
+++ b/contrib/sb-manual/doc/intro.lisp
@@ -259,7 +259,7 @@
SLIME can be downloaded from <https://slime.common-lisp.dev/>.")
(defsection @language-reference (:title "Language Reference")
- "_\\CLHS_ (Common Lisp Hyperspec) is a hypertext version of the ANSI
+ "_\\CLHS_ (Common Lisp HyperSpec) is a hypertext version of the ANSI
standard, made freely available by LispWorks -- an invaluable
reference.
@@ -315,7 +315,9 @@
(defsection @internals-documentation (:title "Internals Documentation")
"If you're interested in the development of the SBCL system itself,
- then subscribing to `sbcl-devel` is a good idea.
+ then subscribing to
+ [[email protected]](mailto:[email protected])
+ is a good idea.
SBCL internals documentation -- besides comments in the source -- is
available in the Web Archive:
@@ -462,7 +464,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
diff --git a/contrib/sb-manual/doc/support-and-bugs.lisp b/contrib/sb-manual/doc/support-and-bugs.lisp
index 844be0fd1..fcead62ca 100644
--- a/contrib/sb-manual/doc/support-and-bugs.lisp
+++ b/contrib/sb-manual/doc/support-and-bugs.lisp
@@ -56,11 +56,13 @@
<https://bugs.launchpad.net/sbcl>
Reporting bugs there requires registering at Launchpad. However,
- bugs can also be reported on the mailing list `sbcl-bugs`,
- which is moderated but does _not_ require subscribing.
+ bugs can also be reported on the mailing list `sbcl-bugs`, which is
+ moderated but does _not_ require subscribing. Simply send email to
+ [`[email protected]`](mailto:[email protected])
+ and the bug will be checked and added to Launchpad by SBCL
+ maintainers.
- Simply send email to `[email protected]` and the bug
- will be checked and added to Launchpad by SBCL maintainers."
+ See the `\\\\HACKING` file on how to send patches."
(@how-to-report-bugs-effectively section)
(@how-to-report-signal-related-bugs section))
diff --git a/contrib/sb-manual/markdown.lisp b/contrib/sb-manual/markdown.lisp
index 045eeebf6..547c36407 100644
--- a/contrib/sb-manual/markdown.lisp
+++ b/contrib/sb-manual/markdown.lisp
@@ -457,7 +457,7 @@
(write-string (escape-texinfo (subseq line last)) result))))
(defun write-concept-keys (keys stream)
- (dolist (key keys)
+ (dolist (key (remove-duplicates keys :test #'equal))
(typecase key
(list
;; We don't use @subentry because with it Texinfo always
diff --git a/contrib/sb-manual/texinfo.lisp b/contrib/sb-manual/texinfo.lisp
index 1458dde80..30c9a3f4c 100644
--- a/contrib/sb-manual/texinfo.lisp
+++ b/contrib/sb-manual/texinfo.lisp
@@ -223,6 +223,9 @@
(markdown-to-texinfo (reindent-docstring docstring) arglist))
+;;; Currently, we have the Texinfo file under version control to keep
+;;; a closer eye on the Markdown-to-Texinfo converter, which is young.
+;;; When that's no longer the case, this is no longer needed.
(defparameter *pages*
'((@support-and-bugs "support-and-bugs.texinfo")
(@introduction "intro.texinfo")
diff --git a/doc/README b/doc/README
index bf901a4af..34bbec09a 100644
--- a/doc/README
+++ b/doc/README
@@ -3,9 +3,9 @@ documentation might not be refused.:-)
There is a Unix man page, sbcl.1.
-There is a user manual in texinfo format, in doc/manual/. (In
-binary distributions, the compiled-into-HTML translations are also
-included.)
+There is a user manual in Texinfo format, in doc/manual/, generated
+from the SB-MANUAL contrib. (In binary distributions, the
+compiled-into-HTML translations are also included.)
Much of the documentation for supported extensions is in their Lisp
doc strings. For example, to find out how to use the SAVE-LISP-AND-DIE
diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore
index fdff4f7dd..a9908b686 100644
--- a/doc/manual/.gitignore
+++ b/doc/manual/.gitignore
@@ -30,6 +30,5 @@ sbcl.info*
sbcl.pdf
sbcl.ps
sbcl/
-sbcl-contento.texinfo
variables.texinfo
generated-texinfo-stamp
diff --git a/doc/manual/README b/doc/manual/README
index 1b9939862..6f77dcb33 100644
--- a/doc/manual/README
+++ b/doc/manual/README
@@ -1,5 +1,6 @@
-With the exception of sbcl.texinfo, backmatter.texinfo, all other
-Texinfo files are from SB-MANUAL::GENERATE-TEXINFO.
+With the exception of sbcl.texinfo, backmatter.texinfo, and
+asdf.texinfo, all other Texinfo files are from
+SB-MANUAL::GENERATE-TEXINFO.
With the exception of variables.texinfo, the generated files are under
version control, to keep a closer eye on the Markdown-to-Texinfo
diff --git a/doc/manual/deprecation.texinfo b/doc/manual/deprecation.texinfo
index 7d9640797..fc8d3bc6f 100644
--- a/doc/manual/deprecation.texinfo
+++ b/doc/manual/deprecation.texinfo
@@ -215,7 +215,7 @@ in various namespaces as deprecated.
@quotation
@emph{Note}: See the @code{namespace} @code{clhs} glossary entry in the glossary of
-the Common Lisp Hyperspec.)
+the Common Lisp HyperSpec.)
@end quotation
@anchor{Declaration sb-ext deprecated}
diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo
index 790f60eb2..bf2bca6e5 100644
--- a/doc/manual/intro.texinfo
+++ b/doc/manual/intro.texinfo
@@ -301,7 +301,7 @@ SLIME can be downloaded from @url{https://slime.common-lisp.dev/}.
@node language reference
@subsection Language Reference
-@emph{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
+@emph{CLHS} (Common Lisp HyperSpec) is a hypertext version of the ANSI
standard, made freely available by LispWorks -- an invaluable
reference.
@@ -372,7 +372,9 @@ be installed along with this manual on your system, e.g. in
@subsection Internals Documentation
If you're interested in the development of the SBCL system itself,
-then subscribing to @code{sbcl-devel} is a good idea.
+then subscribing to
+@uref{mailto:sbcl-devel@@lists.sourceforge.net, sbcl-devel@@lists.sourceforge.net}
+is a good idea.
SBCL internals documentation -- besides comments in the source -- is
available in the Web Archive:
@@ -539,7 +541,7 @@ particularly well there. SBCL should be able to improve in these areas
@cindex garbage collector, conservative
@cindex conservative garbage collector
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
-_@@CONSERVATIVE-GC. This means that it doesn't maintain a strict
+@emph{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
diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index 629d4af1c..4f0b83950 100644
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -382,7 +382,6 @@ system.
@node runtime options
@subsection Runtime Options
-@cindex LDB
@cindex disabling LDB
@cindex LDB, disabling
@cindex LDB
diff --git a/doc/manual/support-and-bugs.texinfo b/doc/manual/support-and-bugs.texinfo
index 70eaebeac..e22786450 100644
--- a/doc/manual/support-and-bugs.texinfo
+++ b/doc/manual/support-and-bugs.texinfo
@@ -71,11 +71,13 @@ SBCL uses Launchpad to track bugs. The bug database is available at
@url{https://bugs.launchpad.net/sbcl}
Reporting bugs there requires registering at Launchpad. However,
-bugs can also be reported on the mailing list @code{sbcl-bugs},
-which is moderated but does @emph{not} require subscribing.
+bugs can also be reported on the mailing list @code{sbcl-bugs}, which is
+moderated but does @emph{not} require subscribing. Simply send email to
+@uref{mailto:sbcl-bugs@@lists.sourceforge.net, @code{sbcl-bugs@@lists.sourceforge.net}}
+and the bug will be checked and added to Launchpad by SBCL
+maintainers.
-Simply send email to @code{sbcl-bugs@@lists.sourceforge.net} and the bug
-will be checked and added to Launchpad by SBCL maintainers.
+See the @code{HACKING} file on how to send patches.
@node how to report bugs effectively
@subsection How to Report Bugs Effectively
diff --git a/src/code/coerce.lisp b/src/code/coerce.lisp
index d915c4b24..61ab41a49 100644
--- a/src/code/coerce.lisp
+++ b/src/code/coerce.lisp
@@ -216,7 +216,7 @@
(coerce-error)))))
;; If RES has the wrong type, that means that rule of
;; canonical representation for complex rationals was
- ;; invoked. According to the Hyperspec, (coerce 7/2
+ ;; invoked. According to the HyperSpec, (coerce 7/2
;; 'complex) returns 7/2. Thus, if the object was a
;; rational, there is no error here.
(unless (or (typep res output-type-spec)
diff --git a/src/code/early-extensions.lisp b/src/code/early-extensions.lisp
index c52abd7b7..a0e97c5f6 100644
--- a/src/code/early-extensions.lisp
+++ b/src/code/early-extensions.lisp
@@ -1267,7 +1267,7 @@ NOTE: This interface is experimental and subject to change."
;;; When you deprecate something, note it here till it is fully gone: makes it
;;; easier to keep things progressing orderly. Also add the relevant section
;;; (or update it when deprecation proceeds) in the manual, in
-;;; deprecated.texinfo.
+;;; SB-MANUAL:@DEPRECATION.
;;;
;;; EARLY:
;;; - SOCKINT::WIN32-BIND since 1.2.10 (03/2015) -> Late: 08/2015
diff --git a/src/code/target-format.lisp b/src/code/target-format.lisp
index c173392f8..2e2f20310 100644
--- a/src/code/target-format.lisp
+++ b/src/code/target-format.lisp
@@ -673,9 +673,9 @@
;;; errors. As for now, we let the user get away with it, and merely guarantee
;;; that at least one significant digit will appear.
-;;; Raymond Toy writes: The Hyperspec seems to say that the exponent
+;;; Raymond Toy writes: The HyperSpec seems to say that the exponent
;;; marker is always printed. Make it so. Also, the original version
-;;; causes errors when printing infinities or NaN's. The Hyperspec is
+;;; causes errors when printing infinities or NaN's. The HyperSpec is
;;; silent here, so let's just print out infinities and NaN's instead
;;; of causing an error.
(defun format-exp-aux (stream number w d e k ovf pad marker atsign)
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL