Update of /cvsroot/sbcl/sbcl/doc/manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22956/doc/manual
Modified Files:
Makefile beyond-ansi.texinfo compiler.texinfo debugger.texinfo
docstrings.lisp ffi.texinfo make-tempfiles.sh
start-stop.texinfo
Removed Files:
extract-values.sh
Log Message:
0.8.14.20: Documentation madness, yet again
* Merge a partial rewrite of the docstring extractor,
capable of handling a few more cases and providing
nicer xref-names: @xref{Macro common-lisp:trace}
instead of @xref{macro-common-lisp-trace}.
* Reformat a few docstrings for nicer display.
* Add documentation for LOAD-SHARED-OBJECT to the manual.
* Move SAVE-LISP-AND-DIE to "Starting and Stopping"
chapter. Say bye-bye to "Interface to Low-level
Implementation."
* Extract the version number for the manual from
the SBCL the docstrings are pulled from, not
version.lisp-expr.
Index: Makefile
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/Makefile,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- Makefile 18 Aug 2004 12:42:45 -0000 1.12
+++ Makefile 14 Sep 2004 06:51:13 -0000 1.13
@@ -6,7 +6,6 @@
PSFILES=sbcl.ps asdf.ps
PDFFILES=sbcl.pdf asdf.pdf
INFOFILES=sbcl.info asdf.info
-VARSFILE=variables.template
HTMLDIRS=$(basename $(SBCLTEXI)) $(basename $(ASDFTEXI))
# Place where generated documentation ends up. The value of
# DOCSTRINGDIR has to end with a slash or you lose (it's passed to
@@ -41,14 +40,11 @@
rm -f asdf.texinfo
ln -s ../../contrib/asdf/asdf.texinfo
-variables: ${VARSFILE}
- ./extract-values.sh < ${VARSFILE} >variables.texinfo
-
# html documentation; output in $(HTMLDIRS)
.PHONY: html
html: html-stamp
-html-stamp: variables $(DOCFILES) docstrings
+html-stamp: $(DOCFILES) docstrings
@rm -rf $(HTMLDIRS)
$(MAKEINFO) $(I_FLAGS) --html $(SBCLTEXI)
$(MAKEINFO) --html $(ASDFTEXI)
@@ -62,21 +58,21 @@
dvips -o $@ $<
# DVI generation
-%.dvi: %.texinfo variables $(DOCFILES) docstrings
+%.dvi: %.texinfo $(DOCFILES) docstrings
texi2dvi $(I_FLAGS) $<
# PDF documentation
.PHONY: pdf
pdf: $(PDFFILES)
-%.pdf: %.texinfo variables $(DOCFILES) docstrings
+%.pdf: %.texinfo $(DOCFILES) docstrings
texi2pdf $(I_FLAGS) $<
# info docfiles
.PHONY: info
info: $(INFOFILES)
-%.info: %.texinfo variables $(DOCFILES) docstrings
+%.info: %.texinfo $(DOCFILES) docstrings
$(MAKEINFO) $(I_FLAGS) $<
# Texinfo docstring snippets
Index: beyond-ansi.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/beyond-ansi.texinfo,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- beyond-ansi.texinfo 9 Sep 2004 12:10:12 -0000 1.15
+++ beyond-ansi.texinfo 14 Sep 2004 06:51:13 -0000 1.16
@@ -11,7 +11,6 @@
* Support For Unix::
* Customization Hooks for Users::
* Tools To Help Developers::
-* Interface To Low-Level SBCL Implementation::
* Stale Extensions::
* Efficiency Hacks::
@end menu
@@ -98,7 +97,7 @@
@section Tools To Help Developers
SBCL provides a profiler and other extensions to the ANSI @code{trace}
-facility. For more information, see @ref{macro-common-lisp-trace}.
+facility. For more information, see @ref{Macro common-lisp:trace}.
The debugger supports a number of options. Its documentation is
accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
@@ -106,27 +105,6 @@
Documentation for @code{inspect} is accessed by typing @kbd{help} at
the @code{inspect} prompt.
-@... Interface To Low-Level SBCL Implementation
-@... node-name, next, previous, up
-@... Interface To Low-Level SBCL Implementation
-
-SBCL has the ability to save its state as a file for later
-execution. This functionality is important for its bootstrapping
-process, and is also provided as an extension to the user.
-
-Note that foreign libraries loaded via @code{load-shared-object} don't
-survive this process on all platforms; a core should not be saved in
-this case. Platforms where this is supported as of SBCL 0.8.14.5 are
-x86/Linux, x86/FreeBSD and sparc/SunOS.
-
-@...: what should be done for foreign libraries?}
-
-@...: document load-shared-object somewhere - it's in
-ffi.texinfo?}
-
-@... fun-sb-ext-save-lisp-and-die.texinfo
-
-
@node Stale Extensions
@comment node-name, next, previous, up
@section Stale Extensions
Index: compiler.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/compiler.texinfo,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- compiler.texinfo 26 Aug 2004 16:17:07 -0000 1.8
+++ compiler.texinfo 14 Sep 2004 06:51:13 -0000 1.9
@@ -769,7 +769,7 @@
Ordinarily, when the @code{speed} quality is high, the compiler emits
notes to notify the programmer about its inability to apply various
optimizations. For selective muffling of these notes @xref{Controlling
-Verbosity}
+Verbosity}.
The value of @code{space} mostly influences the compiler's decision
whether to inline operations, which tend to increase the size of
Index: debugger.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/debugger.texinfo,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- debugger.texinfo 13 Sep 2004 07:14:40 -0000 1.7
+++ debugger.texinfo 14 Sep 2004 06:51:13 -0000 1.8
@@ -921,7 +921,7 @@
If @code{debug} is also at least 2, then the code is @emph{partially
steppable}. If @code{debug} is 3, the code is @emph{fully steppable}.
-@... Stepping} for details.
+@xref{Single Stepping}, for details.
@end table
@@ -1186,7 +1186,7 @@
SBCL includes an instrumentation based single-stepper for compiled
code, that can be invoked via the @code{step} macro, or from within
-the debugger. @xref{Debugger Policy Control} for details on enabling
+the debugger. @xref{Debugger Policy Control}, for details on enabling
stepping for compiled code.
Compiled code can be unsteppable, partially steppable, or fully steppable.
Index: docstrings.lisp
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/docstrings.lisp,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- docstrings.lisp 1 Aug 2004 23:33:07 -0000 1.8
+++ docstrings.lisp 14 Sep 2004 06:51:13 -0000 1.9
@@ -4,13 +4,26 @@
;;;; @include-ready documentation from the docstrings of exported
;;;; symbols of specified packages.
-
;;;; This software is part of the SBCL software system. SBCL is in the
;;;; public domain and is provided with absolutely no warranty. See
;;;; the COPYING file for more information.
;;;;
-;;;; Written by Rudi Schlatte <rudi@...>
+;;;; Written by Rudi Schlatte <rudi@...>, mangled
+;;;; by Nikodemus Siivola.
[...1077 lines suppressed...]
- (def-end symbol kind)))
+(defun document-package (package &optional filename)
+ "Create a file containing all available documentation for the
+exported symbols of `package' in Texinfo format. If `filename' is not
+supplied, a file \"<packagename>.texinfo\" is generated.
+
+The definitions can be referenced using Texinfo statements like
+@ref{<doc-type>_<packagename>_<symbol-name>.texinfo}. Texinfo
+syntax-significant characters are escaped in symbol names, but if a
+docstring contains invalid Texinfo markup, you lose."
+ (handler-bind ((warning #'muffle-warning))
+ (let* ((package (find-package package))
+ (filename (or filename (make-pathname
+ :name (string-downcase (package-name package))
+ :type "texinfo")))
+ (docs (sort (collect-documentation package) #'documentation<)))
+ (with-texinfo-file filename
+ (dolist (doc docs)
+ (write-texinfo doc)))
+ filename)))
Index: ffi.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/ffi.texinfo,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- ffi.texinfo 17 Aug 2004 18:34:29 -0000 1.6
+++ ffi.texinfo 14 Sep 2004 06:51:13 -0000 1.7
@@ -24,7 +24,7 @@
* Operations On Foreign Values::
* Foreign Variables::
* Foreign Data Structure Examples::
-* Loading Unix Object Files::
+* Loading Shared Object Files::
* Foreign Function Calls::
* Step-By-Step Example of the Foreign Function Interface::
@end menu
@@ -711,33 +711,14 @@
(setq my-struct (slot my-struct 'n))
@end lisp
-@... Loading Unix Object Files
+@node Loading Shared Object Files
@comment node-name, next, previous, up
-@... Loading Unix Object Files
+@section Loading Shared Object Files
Foreign object files can be loaded into the running Lisp process by
calling @code{load-shared-object}.
-The @code{sb-alien:load-shared-object} loads a single object file into
-the currently running Lisp. The external symbols defining routines and
-variables are made available for future external references (e.g. by
-@...}). Forward references to foreign symbols aren't
-supported: @code{load-shared-object} must be run before any of the
-defined symbols are referenced.
-
-@...
-Note: As of SBCL 0.7.5, all foreign code (code loaded with
-@...}) is lost when a Lisp
-core is saved with @code{sb-ext:save-lisp-and-die}, and no attempt is
-made to restore it when the core is loaded. Historically this has been
-an annoyance both for SBCL users and for CMUCL users. It's hard to
-solve this problem completely cleanly, but some generally-reliable
-partial solution might be useful. Once someone in either camp gets
-sufficiently annoyed to create it, SBCL is likely to adopt some
-mechanism for automatically restoring foreign code when a saved core
-is loaded.
-@... quotation
-
+@include fun-sb-alien-load-shared-object.texinfo
@node Foreign Function Calls
@comment node-name, next, previous, up
Index: make-tempfiles.sh
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/make-tempfiles.sh,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- make-tempfiles.sh 17 Aug 2004 17:32:14 -0000 1.6
+++ make-tempfiles.sh 14 Sep 2004 06:51:13 -0000 1.7
@@ -15,6 +15,7 @@
# else an installed sbcl is used.
sbclsystem=`pwd`/../../src/runtime/sbcl
sbclcore=`pwd`/../../output/sbcl.core
+
if [ -e $sbclsystem ] && [ -e $sbclcore ]
then
SBCLRUNTIME="${1:-$sbclsystem --core $sbclcore}"
@@ -25,6 +26,13 @@
SBCL="$SBCLRUNTIME --noinform --sysinit /dev/null --userinit /dev/null --noprint --disable-debugger"
+# extract version and date
+VERSION=`$SBCL --eval '(write-line (lisp-implementation-version))' --eval '(sb-ext:quit)'`
+MONTH=`date "+%Y-%m"`
+
+sed -e "s/@VERSION@.../" \
+ -e "s/@MONTH@.../" < variables.template > variables.texinfo || exit 1
+
# 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.
@@ -39,7 +47,13 @@
#PACKAGES="${PACKAGES:-:COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD}"
echo /creating docstring snippets from SBCL=\'$SBCLRUNTIME\' for packages \'$PACKAGES\'
-echo "(progn (load \"docstrings.lisp\") (dolist (module (quote ($MODULES))) (require module)) (docstrings-to-texinfo \"$DOCSTRINGDIR\" $PACKAGES) (sb-ext:quit))" | $SBCL
+$SBCL <<EOF
+(load "docstrings.lisp")
+(dolist (module (quote ($MODULES)))
+ (require module))
+(sb-texinfo:generate-includes "$DOCSTRINGDIR" $PACKAGES)
+(sb-ext:quit))
+EOF
echo /creating package-locks.texi-temp
if $SBCL --eval "(let ((plp (find-symbol \"PACKAGE-LOCKED-P\" :sb-ext))) (quit :unix-status (if (and plp (fboundp plp)) 0 1)))";
Index: start-stop.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/start-stop.texinfo,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- start-stop.texinfo 26 Aug 2004 16:17:07 -0000 1.4
+++ start-stop.texinfo 14 Sep 2004 06:51:13 -0000 1.5
@@ -78,8 +78,9 @@
@menu
* Quit::
-* End of File::
-* Exit on Errors::
+* End of File::
+* Saving a Core Image::
+* Exit on Errors::
@end menu
@node Quit
@@ -101,6 +102,15 @@
pressing @kbd{Control-D} on an attached terminal, or end of input when
using SBCL as part of a shell pipeline.
+@node Saving a Core Image
+@comment node-name, next, previous, up
+@subsection Saving a Core Image
+
+SBCL has the ability to save its state as a file for later
+execution. This functionality is important for its bootstrapping
+process, and is also provided as an extension to the user.
+
+@include fun-sb-ext-save-lisp-and-die.texinfo
@node Exit on Errors
@comment node-name, next, previous, up
@@ -299,7 +309,8 @@
@lisp
;;; If the first user-processable command-line argument is a filename,
;;; disable the debugger, load the file handling shebang-line and quit.
-(let ((script (and (second *posix-argv*) (probe-file (second *posix-argv*)))))
+(let ((script (and (second *posix-argv*)
+ (probe-file (second *posix-argv*)))))
(when script
;; Handle shebang-line
(set-dispatch-macro-character #\# #\!
@@ -307,12 +318,13 @@
(declare (ignore char arg))
(read-line stream)))
;; Disable debugger
- (setf *invoke-debugger-hook* (lambda (condition hook)
- (declare (ignore hook))
- ;; Uncomment to get backtraces on errors
- ;; (sb-debug:backtrace 20)
- (format *error-output* "Error: ~A~%" condition)
- (quit)))
+ (setf *invoke-debugger-hook*
+ (lambda (condition hook)
+ (declare (ignore hook))
+ ;; Uncomment to get backtraces on errors
+ ;; (sb-debug:backtrace 20)
+ (format *error-output* "Error: ~A~%" condition)
+ (quit)))
(load script)
(quit)))
@end lisp
@@ -356,7 +368,8 @@
(require :asdf)
;;; If a fasl was stale, try to recompile and load (once).
-(defmethod asdf:perform :around ((o asdf:load-op) (c asdf:cl-source-file))
+(defmethod asdf:perform :around ((o asdf:load-op)
+ (c asdf:cl-source-file))
(handler-case (call-next-method o c)
;; If a fasl was stale, try to recompile and load (once).
(sb-ext:invalid-fasl ()
--- extract-values.sh DELETED ---
|