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

@@ -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.

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.

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.

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

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

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 \

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 ]

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.
+    `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?
+
+- Improve section names
+
+    They are a soft interface: exported from `sb-manual` and visible
+    to the user via HTML anchors.

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")

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
+  [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

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
+  [`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))
 

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

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")

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

doc/manual/.gitignore

@@ -30,6 +30,5 @@ sbcl.info*
 sbcl.pdf
 sbcl.ps
 sbcl/
-sbcl-contento.texinfo
 variables.texinfo
 generated-texinfo-stamp

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

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}

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

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

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

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)

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

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)