0.8.9.33:

* infrastructure for contrib/ documentation in the main manual:
  contrib;**;*.texinfo get automagically included in the chapter
  "Contributed Modules"

  ... rename docstrings.sh to make-tempfiles.sh, since it makes more
      than docstrings now

  ... test it all by converting sb-aclrepl/README to texinfo format.

contrib/STANDARDS

@@ -71,11 +71,23 @@ good place to test that they still exist, etc.
 
 * Documentation
 
-[ Would be at least nice.  My tendency is to say plain text or HTML,
-and optionally your choice of source format which can generate either
-of the preceding.  Document formats not available on typical
-well-endowed-with-free-stuff Unix systems are discouraged.  DocBook
-is fine, as the SBCL manual is DocBook anyway ]
+Each package should provide documentation in Texinfo format.  For the
+documentation to be included in the sbcl manual, the following must
+hold:
+
+- Each Texinfo file must have the extension `.texinfo' so the
+  automatic manual builder will find it.
+
+- It must contain one @node - @section pair at the top and only
+  @subsection (or lower) sectioning commands within, e.g.
+
+@node Sample Contrib
+@section Sample Contrib
+...
+
+  so that the contrib menu can be created automatically.
+
+Take care to choose unique node names.
 
 [ make install should copy the documentation somewhere that the user
 can find it ]

contrib/sb-aclrepl/sb-aclrepl.texinfo

@@ -0,0 +1,46 @@
+@node sb-aclrepl
+@section sb-aclrepl
+
+The @code{sb-aclrepl} module offers an AllegroCL style Read-Eval-Print
+Loop for SBCL. An AllegroCL style inspector is integrated. Adding an
+AllegroCL style debugger is planned.
+
+@menu
+* Usage::                       
+@end menu
+
+@node Usage
+@subsection Usage
+
+To start @code{sb-aclrepl} as your read-eval-print loop, put the form
+@lisp
+(require 'sb-aclrepl)
+@end lisp
+
+in your @file{~/.sbclrc} initialization file.
+
+Here's a longer example of a @file{~/.sbclrc} file that shows off
+some of the features of @code{sb-aclrepl}:
+
+@lisp
+(ignore-errors (require 'sb-aclrepl))
+
+(when (find-package 'sb-aclrepl)
+  (push :aclrepl cl:*features*))
+#+aclrepl
+(progn
+  (setq sb-aclrepl:*max-history* 100)
+  (setf (sb-aclrepl:alias "asdc") 
+       #'(lambda (sys) (asdf:operate 'asdf:compile-op sys)))
+  (sb-aclrepl:alias "l" (sys) (asdf:operate 'asdf:load-op sys))
+  (sb-aclrepl:alias "t" (sys) (asdf:operate 'asdf:test-op sys))
+  ;; The 1 below means that two characaters ("up") are required
+  (sb-aclrepl:alias ("up" 1 "Use package") (package) (use-package package))
+  ;; The 0 below means only the first letter ("r") is required,
+  ;; such as ":r base64"
+  (sb-aclrepl:alias ("require" 0 "Require module") (sys) (require sys))
+  (setq cl:*features* (delete :aclrepl cl:*features*)))
+@end lisp
+
+Questions, comments, or bug reports should be sent to Kevin Rosenberg
+(@email{kevin@@rosenberg.net}).

doc/manual/Makefile

@@ -69,22 +69,25 @@ info: $(INFOFILE)
 $(INFOFILE): $(DOCFILES) docstrings
 	$(MAKEINFO) -I $(DOCSTRINGDIR) $(ROOTFILE)
 
-# Texinfo docstring snippets; output hardcoded in docstrings/ for now.
-.PHONY: docstrings
-docstrings: docstrings-stamp
+# contrib-modules.texinfo includes contrib-doc-list.texi-temp
+contrib-modules.texinfo: tempfiles-stamp
 
-docstrings-stamp:
-	DOCSTRINGDIR=$(DOCSTRINGDIR) sh docstrings.sh
-	touch docstrings-stamp
+# Texinfo docstring snippets
+.PHONY: docstrings
+docstrings: tempfiles-stamp
 
+tempfiles-stamp:
+	DOCSTRINGDIR=$(DOCSTRINGDIR) sh make-tempfiles.sh
+	touch tempfiles-stamp
 
 
 .PHONY: clean
 clean: 
 	rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
 	rm -rf $(HTMLDIR) $(DOCSTRINGDIR)
-	rm -f $(PSFILE) $(PDFFILE) $(DVIFILE) html-stamp docstrings-stamp
-	rm -f $(TMPFILES)
+	rm -f contrib-docs.texi-temp
+	rm -f $(PSFILE) $(PDFFILE) $(DVIFILE) html-stamp tempfiles-stamp
+	rm -f $(TMPFILES) contrib-doc-list.texi-temp
 	rm -f sbcl.info sbcl.info-*
 
 .PHONY: distclean

doc/manual/contrib-modules.texinfo

@@ -0,0 +1,5 @@
+@node Contributed Modules
+@comment  node-name,  next,  previous,  up
+@chapter Contributed Modules
+
+@include contrib-doc-list.texi-temp

doc/manual/create-contrib-doc-list.lisp

@@ -0,0 +1,42 @@
+;;;; -*- lisp -*-
+
+;;;; "Lisp as scripting language -- discuss"
+
+;;;; Generate contrib-docs.texi-temp from any texinfo files found in
+;;;; the contrib/ sub-tree.
+
+(defun nodename (texi-file)
+  (with-open-file (f texi-file)
+    (loop for line = (read-line f)
+         while line
+         do (let ((index (search "@node" line)))
+              (when index
+                (return-from nodename
+                  (subseq line (+ index 1 (length "@node"))))))))
+  (error "No `@node' line found in file ~A" texi-file))
+
+(let ((texi-files (directory "../../contrib/**/*.texinfo")))
+  (with-open-file (out "contrib-doc-list.texi-temp" :direction :output
+                       :if-does-not-exist :create :if-exists :supersede)
+    (write-string "@c -*- texinfo -*-
+
+@c Include documentation for contrib modules.
+@c This is a generated file - do not edit!
+
+" out)
+    (write-line "@menu" out)
+    (dolist (texi-file texi-files)
+      (let ((nodename (nodename texi-file)))
+        (format out "* ~A::~%" nodename)))
+    (write-line "@end menu" out)
+    (terpri out)
+    (dolist (texi-file texi-files)
+      (format out "@include ~A~%"
+              (namestring (make-pathname
+                           :directory (list* :relative :up :up
+                                             (last
+                                              (pathname-directory texi-file) 2))
+                           :name (pathname-name texi-file)
+                           :type (pathname-type texi-file)))))))
+
+(sb-ext:quit)

doc/manual/docstrings.sh → doc/manual/make-tempfiles.sh

@@ -1,6 +1,7 @@
 #!/bin/sh
 
 # Create Texinfo snippets from the documentation of exported symbols.
+# Also create contrib-docs.texi-temp to include documentation in contrib/.
 
 # This software is part of the SBCL system. See the README file for
 # more information.
@@ -33,3 +34,6 @@ PACKAGES="${PACKAGES:-:COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP
 
 echo /creating docstring snippets from SBCL=\'$SBCL\' for packages \'$PACKAGES\'
 echo "(progn (load \"docstrings.lisp\") (docstrings-to-texinfo \"$DOCSTRINGDIR\" $PACKAGES) (sb-ext:quit))" | $SBCL --noinform --sysinit /dev/null --userinit /dev/null --noprint --disable-debugger
+
+echo /creating contrib-docs.texi-temp
+echo "(load \"create-contrib-doc-list.lisp\")" | $SBCL --noinform --sysinit /dev/null --userinit /dev/null --noprint --disable-debugger

doc/manual/sbcl.texinfo

@@ -64,7 +64,8 @@ provided with absolutely no warranty. See the @file{COPYING} and
 * The Debugger::                
 * Efficiency::                  
 * Beyond The ANSI Standard::    
-* The Foreign Function Interface::  
+* The Foreign Function Interface::
+* Contributed Modules::    
 * Concept Index::
 * Function Index::              
 * Variable Index::              
@@ -79,6 +80,7 @@ provided with absolutely no warranty. See the @file{COPYING} and
 @include efficiency.texinfo
 @include beyond-ansi.texinfo
 @include ffi.texinfo
+@include contrib-modules.texinfo
 @include backmatter.texinfo
 
 @bye

version.lisp-expr

@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"0.8.9.32"
+"0.8.9.33"