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 . + +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 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+ +> (), 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 - . + . 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: + sbcl-help@lists.sourceforge.net sbcl-devel@lists.sourceforge.net 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//manual.lisp to + 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 .") (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 + [sbcl-devel@lists.sourceforge.net](mailto:sbcl-devel@lists.sourceforge.net) + 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 @@ 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 + [`sbcl-bugs@lists.sourceforge.net`](mailto:sbcl-bugs@lists.sourceforge.net) + and the bug will be checked and added to Launchpad by SBCL + maintainers. - Simply send email to `sbcl-bugs@lists.sourceforge.net` 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)