From f5a3b5bfc0dadc42b92a73e16891f5093836d424 Mon Sep 17 00:00:00 2001 From: Rudi Schlatte Date: Fri, 9 Apr 2004 20:54:24 +0000 Subject: [PATCH] 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 | 22 +++++++++++---- contrib/sb-aclrepl/sb-aclrepl.texinfo | 46 +++++++++++++++++++++++++++++++ doc/manual/Makefile | 19 +++++++------ doc/manual/contrib-modules.texinfo | 5 ++++ doc/manual/create-contrib-doc-list.lisp | 42 ++++++++++++++++++++++++++++ doc/manual/docstrings.sh | 35 ----------------------- doc/manual/make-tempfiles.sh | 39 ++++++++++++++++++++++++++ doc/manual/sbcl.texinfo | 4 ++- version.lisp-expr | 2 +- 9 files changed, 164 insertions(+), 50 deletions(-) create mode 100644 contrib/sb-aclrepl/sb-aclrepl.texinfo create mode 100644 doc/manual/contrib-modules.texinfo create mode 100644 doc/manual/create-contrib-doc-list.lisp delete mode 100644 doc/manual/docstrings.sh create mode 100644 doc/manual/make-tempfiles.sh diff --git a/contrib/STANDARDS b/contrib/STANDARDS index 80b0b58..c66f77b 100644 --- a/contrib/STANDARDS +++ b/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 ] diff --git a/contrib/sb-aclrepl/sb-aclrepl.texinfo b/contrib/sb-aclrepl/sb-aclrepl.texinfo new file mode 100644 index 0000000..4a71c0f --- /dev/null +++ b/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}). diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 93f0be5..cf0b565 100644 --- a/doc/manual/Makefile +++ b/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 diff --git a/doc/manual/contrib-modules.texinfo b/doc/manual/contrib-modules.texinfo new file mode 100644 index 0000000..322eeab --- /dev/null +++ b/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 diff --git a/doc/manual/create-contrib-doc-list.lisp b/doc/manual/create-contrib-doc-list.lisp new file mode 100644 index 0000000..e83f147 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/doc/manual/docstrings.sh b/doc/manual/docstrings.sh deleted file mode 100644 index e85747c..0000000 --- a/doc/manual/docstrings.sh +++ /dev/null @@ -1,35 +0,0 @@ -#!/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 diff --git a/doc/manual/make-tempfiles.sh b/doc/manual/make-tempfiles.sh new file mode 100644 index 0000000..d0ce05c --- /dev/null +++ b/doc/manual/make-tempfiles.sh @@ -0,0 +1,39 @@ +#!/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 diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo index 9937ce4..7a00d47 100644 --- a/doc/manual/sbcl.texinfo +++ b/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 diff --git a/version.lisp-expr b/version.lisp-expr index 0a5d23f..c6efd9c 100644 --- a/version.lisp-expr +++ b/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" -- 1.7.10.4