* 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 ]
--- /dev/null
+@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}).
$(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
--- /dev/null
+@node Contributed Modules
+@comment node-name, next, previous, up
+@chapter Contributed Modules
+
+@include contrib-doc-list.texi-temp
--- /dev/null
+;;;; -*- 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)
\ No newline at end of file
+++ /dev/null
-#!/bin/sh
-
-# Create Texinfo snippets from the documentation of exported symbols.
-
-# This software is part of the SBCL system. See the README file for
-# more information.
-#
-# This software is in the public domain and is provided with
-# absolutely no warranty. See the COPYING and CREDITS files for
-# more information.
-
-# how we invoke SBCL
-
-# We create the documentation from the in-tree sbcl if it is found,
-# else an installed sbcl is used.
-sbclsystem=`pwd`/../../src/runtime/sbcl
-if [ -e $sbclsystem ]
-then
-SBCL="${1:-$sbclsystem --core `pwd`/../../output/sbcl.core}"
-export SBCL_HOME=`pwd`/../../contrib
-else
-SBCL="${1:-`which sbcl`}"
-fi
-
-# Output directory. This has to end with a slash (it's interpreted by
-# Lisp's `pathname' function) or you lose. This is normally set from
-# Makefile.
-DOCSTRINGDIR="${DOCSTRINGDIR:-docstrings/}"
-
-# List of package names that documentation will be created for. This
-# is normally set from Makefile.
-PACKAGES="${PACKAGES:-:COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD}"
-
-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
--- /dev/null
+#!/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.
+#
+# This software is in the public domain and is provided with
+# absolutely no warranty. See the COPYING and CREDITS files for
+# more information.
+
+# how we invoke SBCL
+
+# We create the documentation from the in-tree sbcl if it is found,
+# else an installed sbcl is used.
+sbclsystem=`pwd`/../../src/runtime/sbcl
+if [ -e $sbclsystem ]
+then
+SBCL="${1:-$sbclsystem --core `pwd`/../../output/sbcl.core}"
+export SBCL_HOME=`pwd`/../../contrib
+else
+SBCL="${1:-`which sbcl`}"
+fi
+
+# Output directory. This has to end with a slash (it's interpreted by
+# Lisp's `pathname' function) or you lose. This is normally set from
+# Makefile.
+DOCSTRINGDIR="${DOCSTRINGDIR:-docstrings/}"
+
+# List of package names that documentation will be created for. This
+# is normally set from Makefile.
+PACKAGES="${PACKAGES:-:COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD}"
+
+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
* The Debugger::
* Efficiency::
* Beyond The ANSI Standard::
-* The Foreign Function Interface::
+* The Foreign Function Interface::
+* Contributed Modules::
* Concept Index::
* Function Index::
* Variable Index::
@include efficiency.texinfo
@include beyond-ansi.texinfo
@include ffi.texinfo
+@include contrib-modules.texinfo
@include backmatter.texinfo
@bye
;;; 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"
projects / sbcl.git / commitdiff