From b194e5262c0ca11756bc01ea4427aad465dbcaa0 Mon Sep 17 00:00:00 2001 From: Rudi Schlatte Date: Fri, 9 Apr 2004 16:04:48 +0000 Subject: [PATCH] 0.8.9.32: * Documentation changes: - Document trace and require - Add variable index - Remove explicit links from @node lines, since makeinfo figures this out anyway and they would make automagic contrib/ documentation inclusion harder. - add file TEXINFO-HINTS * Documentation infractructure changes: - document functions etc. with package prefix; index without package prefix too (makeinfo seems to index the name with prefix without being asked, so we just lay back and enjoy it) - Move list-of-packages-to-extract-docstrings-from to Makefile - Escape Texinfo special characters in documentation bodies as well. --- doc/manual/Makefile | 9 ++- doc/manual/TEXINFO-HINTS | 14 ++++ doc/manual/backmatter.texinfo | 18 ++++-- doc/manual/beyond-ansi.texinfo | 51 +++++++-------- doc/manual/compiler.texinfo | 30 ++++----- doc/manual/debugger.texinfo | 61 +++++++++--------- doc/manual/docstrings.lisp | 71 ++++++++++++--------- doc/manual/docstrings.sh | 9 +-- doc/manual/efficiency.texinfo | 6 +- doc/manual/ffi.texinfo | 70 ++++++++++++-------- doc/manual/intro.texinfo | 8 +-- doc/manual/sbcl.texinfo | 138 ++++------------------------------------ version.lisp-expr | 2 +- 13 files changed, 211 insertions(+), 276 deletions(-) create mode 100644 doc/manual/TEXINFO-HINTS diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 48c5ec5..93f0be5 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -8,9 +8,12 @@ PDFFILE=sbcl.pdf DVIFILE=sbcl.dvi INFOFILE=sbcl.info HTMLDIR=$(basename $(ROOTFILE)) -# The value of DOCSTRINGDIR has to end with a slash or you lose (it's -# passed to Lisp's `pathname' function). +# Place where generated documentation ends up. The value of +# DOCSTRINGDIR has to end with a slash or you lose (it's passed to +# Lisp's `pathname' function). DOCSTRINGDIR="docstrings/" +# List of package names that documentation will be created for. +PACKAGES=":COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD" ifeq ($(MAKEINFO),) @@ -78,7 +81,7 @@ docstrings-stamp: .PHONY: clean clean: - rm -f *~ *.bak *.orig \#*\# .\#* texput.log + rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl rm -rf $(HTMLDIR) $(DOCSTRINGDIR) rm -f $(PSFILE) $(PDFFILE) $(DVIFILE) html-stamp docstrings-stamp rm -f $(TMPFILES) diff --git a/doc/manual/TEXINFO-HINTS b/doc/manual/TEXINFO-HINTS new file mode 100644 index 0000000..4bfcdcb --- /dev/null +++ b/doc/manual/TEXINFO-HINTS @@ -0,0 +1,14 @@ +-*- text -*- + +Some hints for editing the manual files. Feel free to add anything +that will save the next person some time. Thanks! + + +- There's no need for Next, Prev, etc. pointers in @node lines: + makeinfo will deduce these automatically when the line after @node + contains a sectioning command like @section, @subsection. Hence, + texinfo-multiple-files-update should not be used either. + +- Don't create or update Menus by hand; use C-c C-u C-a + (texinfo-all-menus-update) instead. (Doesn't work in sbcl.texinfo, + but this file is only changed when an entire chapter is added.) diff --git a/doc/manual/backmatter.texinfo b/doc/manual/backmatter.texinfo index 061b214..c0cda39 100644 --- a/doc/manual/backmatter.texinfo +++ b/doc/manual/backmatter.texinfo @@ -1,16 +1,22 @@ -@node Function Index, Concept Index, The Foreign Function Interface, Top +@node Concept Index +@comment node-name, next, previous, up +@appendix Concept Index + +@printindex cp + +@node Function Index @comment node-name, next, previous, up @appendix Function Index @printindex fn -@node Concept Index, Colophon, Function Index, Top +@node Variable Index @comment node-name, next, previous, up -@appendix Concept Index - -@printindex cp +@appendix Variable Index + +@printindex vr -@node Colophon, , Concept Index, Top +@node Colophon @comment node-name, next, previous, up @unnumbered Colophon diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index c8f3abb..424217b 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -1,4 +1,4 @@ -@node Beyond The ANSI Standard, The Foreign Function Interface, Efficiency, Top +@node Beyond The ANSI Standard @comment node-name, next, previous, up @chapter Beyond The ANSI Standard @@ -14,7 +14,7 @@ violates the standard. * Extensions:: @end menu -@node Non-Conformance With The ANSI Standard, Idiosyncrasies, Beyond The ANSI Standard, Beyond The ANSI Standard +@node Non-Conformance With The ANSI Standard @comment node-name, next, previous, up @section Non-Conformance With The ANSI Standard @@ -27,7 +27,7 @@ through the sbcl-help or sbcl-devel mailings lists. For mailing list addresses, @ref{More SBCL Information}. -@node Idiosyncrasies, Extensions, Non-Conformance With The ANSI Standard, Beyond The ANSI Standard +@node Idiosyncrasies @comment node-name, next, previous, up @section Idiosyncrasies @@ -107,7 +107,7 @@ wrapped in @code{eval-when}, and ideally should be suppressed in that case, but still isn't as of SBCL 0.7.6.) -@node Extensions, , Idiosyncrasies, Beyond The ANSI Standard +@node Extensions @comment node-name, next, previous, up @section Extensions @@ -126,7 +126,7 @@ it still has quite a few. * Efficiency Hacks:: @end menu -@node Things Which Might Be In The Next ANSI Standard, Threading, Extensions, Extensions +@node Things Which Might Be In The Next ANSI Standard @comment node-name, next, previous, up @subsection Things Which Might Be In The Next ANSI Standard @@ -171,7 +171,7 @@ requested order from a user-supplied primary method. @end itemize -@node Threading, Support For Unix, Things Which Might Be In The Next ANSI Standard, Extensions +@node Threading @comment node-name, next, previous, up @subsection Threading (a.k.a Multiprocessing) @@ -286,7 +286,7 @@ Lisp session makes a new POSIX session, so that pressing this has been found to be embarrassing. -@node Support For Unix, Customization Hooks for Users, Threading, Extensions +@node Support For Unix @comment node-name, next, previous, up @subsection Support For Unix @@ -304,44 +304,39 @@ file on input is also supported. @include fun-sb-ext-quit.texinfo -@node Customization Hooks for Users, Tools To Help Developers, Support For Unix, Extensions +@node Customization Hooks for Users @comment node-name, next, previous, up @subsection Customization Hooks for Users -The behaviour of @code{require} when called with only one argument is -implementation-defined. In SBCL it calls functions on the -user-settable list @code{sb-ext:*module-provider-functions*} - see the -@code{require} documentation string for details. - The toplevel repl prompt may be customized, and the function that reads user input may be replaced completely. @c +The behaviour of @code{require} when called with only one argument is +implementation-defined. In SBCL, @code{require} behaves in the +following way: + +@include fun-common-lisp-require.texinfo + +@include var-sb-ext-star-module-provider-functions-star.texinfo + -@node Tools To Help Developers, Interface To Low-Level SBCL Implementation, Customization Hooks for Users, Extensions +@node Tools To Help Developers @comment node-name, next, previous, up @subsection Tools To Help Developers -SBCL provides a profiler and other extensions to the ANSI -@code{trace} facility. See the online function documentation for -@code{trace} for more information. +SBCL provides a profiler and other extensions to the ANSI @code{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. -@c +accessed by typing @kbd{help} at the debugger prompt. @xref{The +Debugger}. Documentation for @code{inspect} is accessed by typing @kbd{help} at the @code{inspect} prompt. -@node Interface To Low-Level SBCL Implementation, Efficiency Hacks, Tools To Help Developers, Extensions +@node Interface To Low-Level SBCL Implementation @comment node-name, next, previous, up @subsection Interface To Low-Level SBCL Implementation @@ -373,7 +368,7 @@ list. @end quotation -@node Efficiency Hacks, , Interface To Low-Level SBCL Implementation, Extensions +@node Efficiency Hacks @comment node-name, next, previous, up @subsection Efficiency Hacks diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo index 367f6f6..835a4d5 100644 --- a/doc/manual/compiler.texinfo +++ b/doc/manual/compiler.texinfo @@ -1,4 +1,4 @@ -@node The Compiler, The Debugger, Introduction, Top +@node The Compiler @comment node-name, next, previous, up @chapter The Compiler @@ -17,7 +17,7 @@ separate that they have their own chapter, @ref{Efficiency}. * Open Coding and Inline Expansion:: @end menu -@node Error Messages, Handling of Types, The Compiler, The Compiler +@node Error Messages @comment node-name, next, previous, up @section Error Messages @cindex Error messages, Compiler @@ -50,7 +50,7 @@ The main problem with this program is that it is trying to add * Read Errors:: @end menu -@node The Parts of the Error Message, The Original and Actual Source, Error Messages, Error Messages +@node The Parts of the Error Message @comment node-name, next, previous, up @subsection The Parts of the Error Message @@ -189,7 +189,7 @@ intervene between the original source and the actual source, then the processing path will also be omitted. -@node The Original and Actual Source, Error Severity, The Parts of the Error Message, Error Messages +@node The Original and Actual Source @comment node-name, next, previous, up @subsection The Original and Actual Source @@ -289,7 +289,7 @@ was applied. The innermost actual source form was the symbol explanation, so the compiler backed out one level. -@node Error Severity, Errors During Macroexpansion, The Original and Actual Source, Error Messages +@node Error Severity @comment node-name, next, previous, up @subsection Error Severity @cindex Severity of compiler errors @@ -307,7 +307,7 @@ condition classes, typically hints about how efficiency might be improved. -@node Errors During Macroexpansion, Read Errors, Error Severity, Error Messages +@node Errors During Macroexpansion @comment node-name, next, previous, up @subsection Errors During Macroexpansion @cindex Macroexpansion, errors during @@ -336,7 +336,7 @@ DO step variable is not a symbol: (ATOM CURRENT) @end example -@node Read Errors, , Errors During Macroexpansion, Error Messages +@node Read Errors @comment node-name, next, previous, up @subsection Read Errors @cindex Read errors, compiler @@ -394,7 +394,7 @@ offending character position and gives up on the entire source file. @c _ --> -@node Handling of Types, Compiler Policy, Error Messages, The Compiler +@node Handling of Types @comment node-name, next, previous, up @section The Compiler's Handling of Types @@ -434,7 +434,7 @@ types. @end menu -@node Type Errors at Compile Time, Precise Type Checking, Handling of Types, Handling of Types +@node Type Errors at Compile Time @comment node-name, next, previous, up @subsection Type Errors at Compile Time @cindex Compile time type errors @@ -491,7 +491,7 @@ can be used in a local declaration to inhibit type warnings in a code fragment that has spurious warnings. -@node Precise Type Checking, Weakened Type Checking, Type Errors at Compile Time, Handling of Types +@node Precise Type Checking @comment node-name, next, previous, up @subsection Precise Type Checking @cindex Precise type checking @@ -539,7 +539,7 @@ precisely as possible. This often involves the use of @code{or}, @code{member}, and other list-style type specifiers. -@node Weakened Type Checking, Getting Existing Programs to Run, Precise Type Checking, Handling of Types +@node Weakened Type Checking @comment node-name, next, previous, up @subsection Weakened Type Checking @cindex Weakened type checking @@ -558,7 +558,7 @@ option believe any or all type declarations with either partial or nonexistent runtime checking. -@node Getting Existing Programs to Run, Implementation Limitations, Weakened Type Checking, Handling of Types +@node Getting Existing Programs to Run @comment node-name, next, previous, up @subsection Getting Existing Programs to Run @cindex Existing programs, to run @@ -704,7 +704,7 @@ variable in the loop body. @c -@node Implementation Limitations, , Getting Existing Programs to Run, Handling of Types +@node Implementation Limitations @comment node-name, next, previous, up @subsection Implementation Limitations @@ -740,7 +740,7 @@ These are important bugs, but are not necessarily easy to fix, so they may, alas, remain in the system for a while. -@node Compiler Policy, Open Coding and Inline Expansion, Handling of Types, The Compiler +@node Compiler Policy @comment node-name, next, previous, up @section Compiler Policy @@ -942,7 +942,7 @@ is to slow the program by causing cache misses or swapping. @c _--> -@node Open Coding and Inline Expansion, , Compiler Policy, The Compiler +@node Open Coding and Inline Expansion @comment node-name, next, previous, up @section Open Coding and Inline Expansion @cindex Open-coding diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 3713a9a..040c49c 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -1,4 +1,4 @@ -@node The Debugger, Efficiency, The Compiler, Top +@node The Debugger @comment node-name, next, previous, up @chapter The Debugger @cindex Debugger @@ -37,7 +37,7 @@ indistinguishable from interpreted code debugging. * Function Tracing:: @end menu -@node Starting the Debugger, The Debugger Command Loop, The Debugger, The Debugger +@node Starting the Debugger @comment node-name, next, previous, up @section Starting the Debugger @@ -79,7 +79,7 @@ top-level. After printing its banner, the debugger prints the current frame and the debugger prompt. -@node The Debugger Command Loop, Controlling Printing in the Debugger, Starting the Debugger, The Debugger +@node The Debugger Command Loop @comment node-name, next, previous, up @section The Debugger Command Loop @cindex Evaluation, in the debugger @@ -117,7 +117,7 @@ current frame. For more information on debugger variable access, see @ref{Variable Access}. -@node Controlling Printing in the Debugger, Stack Frames, The Debugger Command Loop, The Debugger +@node Controlling Printing in the Debugger @comment node-name, next, previous, up @section Controlling Printing in the Debugger @@ -140,7 +140,7 @@ initially. @end defvr -@node Stack Frames, Variable Access, Controlling Printing in the Debugger, The Debugger +@node Stack Frames @comment node-name, next, previous, up @section Stack Frames @cindex Stack frames @@ -176,7 +176,7 @@ another function, or because of an interrupt or error. * Unknown Locations and Interrupts:: @end menu -@node Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames +@node Stack Motion @comment node-name, next, previous, up @subsection Stack Motion @@ -209,7 +209,7 @@ was entered. @end deffn -@node How Arguments are Printed, Function Names, Stack Motion, Stack Frames +@node How Arguments are Printed @comment node-name, next, previous, up @subsection How Arguments are Printed @@ -293,7 +293,7 @@ Printing of argument values is controlled by the Debugger}. -@node Function Names, Funny Frames, How Arguments are Printed, Stack Frames +@node Function Names @comment node-name, next, previous, up @subsection Function Names @@ -320,7 +320,7 @@ that encloses or expanded into the lambda, or the outermost enclosing form if there is no @code{def@var{mumble}}. -@node Funny Frames, Debug Tail Recursion, Function Names, Stack Frames +@node Funny Frames @comment node-name, next, previous, up @subsection Funny Frames @cindex External entry points @@ -385,7 +385,7 @@ are present in the debugger, see @ref{Debugger Policy Control}. @c @ref{open-coding} -@node Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames +@node Debug Tail Recursion @comment node-name, next, previous, up @subsection Debug Tail Recursion @cindex Tail recursion @@ -435,7 +435,7 @@ optimization quality is greater than @code{2}. @c For a more thorough discussion of tail recursion, @ref{tail-recursion}. -@node Unknown Locations and Interrupts, , Debug Tail Recursion, Stack Frames +@node Unknown Locations and Interrupts @comment node-name, next, previous, up @subsection Unknown Locations and Interrupts @cindex Unknown code locations @@ -483,7 +483,7 @@ when the real problem is that the current stack frame can't be located. If this happens, return from the interrupt and try again. -@node Variable Access, Source Location Printing, Stack Frames, The Debugger +@node Variable Access @comment node-name, next, previous, up @section Variable Access @cindex Debug variables @@ -545,7 +545,7 @@ that must unambiguously complete to the name of a valid variable. * Note On Lexical Variable Access:: @end menu -@node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access +@node Variable Value Availability @comment node-name, next, previous, up @subsection Variable Value Availability @cindex Availability of debug variables @@ -628,7 +628,7 @@ values to be available, and even then, values are only available at known locations. -@node Note On Lexical Variable Access, , Variable Value Availability, Variable Access +@node Note On Lexical Variable Access @comment node-name, next, previous, up @subsection Note On Lexical Variable Access @@ -647,7 +647,7 @@ proved the variable could never take on. This may result in bad things happening. -@node Source Location Printing, Debugger Policy Control, Variable Access, The Debugger +@node Source Location Printing @comment node-name, next, previous, up @section Source Location Printing @cindex Source location printing, debugger @@ -726,7 +726,7 @@ print: * Source Location Availability:: @end menu -@node How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing +@node How the Source is Found @comment node-name, next, previous, up @subsection How the Source is Found @@ -783,7 +783,7 @@ into something different, or if a read-macro ever returns the same @code{##} in perverted ways, you don't need to worry about this. -@node Source Location Availability, , How the Source is Found, Source Location Printing +@node Source Location Availability @comment node-name, next, previous, up @subsection Source Location Availability @cindex Debug optimization quality @@ -835,7 +835,7 @@ next conditional (but watch out because the compiler may have changed the program on you.) -@node Debugger Policy Control, Exiting Commands, Source Location Printing, The Debugger +@node Debugger Policy Control @comment node-name, next, previous, up @section Debugger Policy Control @cindex Policy, debugger @@ -923,7 +923,7 @@ but the call is to an optimized local version of the function, not to the original function. -@node Exiting Commands, Information Commands, Debugger Policy Control, The Debugger +@node Exiting Commands @comment node-name, next, previous, up @section Exiting Commands @@ -958,7 +958,7 @@ is of the same type as SBCL expects the stack frame to return. @end deffn -@node Information Commands, Function Tracing, Exiting Commands, The Debugger +@node Information Commands @comment node-name, next, previous, up @section Information Commands @@ -1137,7 +1137,7 @@ Displays all the frames from the current to the bottom. Only shows @c @end example -@node Function Tracing, , Information Commands, The Debugger +@node Function Tracing @comment node-name, next, previous, up @section Function Tracing @cindex Tracing @@ -1148,16 +1148,17 @@ their results whenever they are called. Options allow conditional printing of the trace information and conditional breakpoints on function entry or exit. -@comment rudi 2004-03-26: The docstring for `trace' is quite comprehensive, -@comment so refer to it (see also ``OAOO'') -The docstrings for @code{trace} and @code{untrace} explain SBCL's -tracing facility. +@include macro-common-lisp-trace.texinfo -@comment FIXME rudi 2004-03-26: revive the documentation of variables -@comment describing trace behaviour: *trace-encapsulate-default*, -@comment *max-trace-indentation* and friends. Some of these are -@comment mentioned (perhaps under different names) in the cmucl -@comment manual. +@include macro-common-lisp-untrace.texinfo + +@include var-sb-debug-star-trace-indentation-step-star.texinfo + +@include var-sb-debug-star-max-trace-indentation-star.texinfo + +@include var-sb-debug-star-trace-encapsulate-default-star.texinfo + +@include var-sb-debug-star-trace-values-star.texinfo @comment FIXME rudi 2004-03-26: encapsulate is (per TODO file as of @comment 0.8.9) in a state of flux. When it's sorted out, revive the diff --git a/doc/manual/docstrings.lisp b/doc/manual/docstrings.lisp index 5e6f39d..717c9eb 100644 --- a/doc/manual/docstrings.lisp +++ b/doc/manual/docstrings.lisp @@ -1,9 +1,16 @@ ;;;; -*- lisp -*- -;;;; (c) 2004 Rudi Schlatte -;;;; Use it as you wish, send changes back to me if you like. +;;;; A docstring extractor for the sbcl manual. Creates +;;;; @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 + -#+sbcl (eval-when (:compile-toplevel :load-toplevel :execute) (require 'sb-introspect)) @@ -109,7 +116,7 @@ (package "package") (setf "setf-expander") (structure "struct") - (type (let ((class (find-class symbol))) + (type (let ((class (ignore-errors (find-class symbol)))) (etypecase class (structure-class "struct") (standard-class "class") @@ -125,14 +132,14 @@ (ecase kind (compiler-macro "@deffn {Compiler Macro}") (function (cond - ((macro-function symbol) "@defmac") - ((special-operator-p symbol) "@defspec") - (t "@defun"))) + ((macro-function symbol) "@deffn Macro") + ((special-operator-p symbol) "@deffn {Special Operator}") + (t "@deffn Function"))) (method-combination "@deffn {Method Combination}") - (package "@deffn Package") + (package "@defvr Package") (setf "@deffn {Setf Expander}") (structure "@deftp Structure") - (type (let ((class (find-class symbol))) + (type (let ((class (ignore-errors (find-class symbol)))) (etypecase class (structure-class "@deftp Structure") (standard-class "@deftp Class") @@ -140,7 +147,16 @@ ((or built-in-class null) "@deftp Type")))) (variable (if (constantp symbol) "@defvr Constant" - "@defvar")))) + "@defvr Variable")))) + +(defun def-index (symbol kind) + (case kind + ((compiler-macro function method-combination) + (format nil "@findex ~A" (texinfoify symbol))) + ((structure type) + (format nil "@tindex ~A" (texinfoify symbol))) + (variable + (format nil "@vindex ~A" (texinfoify symbol))))) (defparameter *arglist-keywords* '(&allow-other-keys &aux &body &environment &key &optional &rest &whole)) @@ -157,26 +173,19 @@ (list (format s "(~{~A~^ ~})" (mapcar #'texinfoify-arglist-part part)))))) -(defun def-rest (symbol kind) +(defun def-arglist (symbol kind) (case kind (function (format nil "~{~A~^ ~}" (mapcar #'texinfoify-arglist-part (argument-list symbol)))))) (defun def-end (symbol kind) + (declare (ignore symbol)) (ecase kind - (compiler-macro "@end deffn") - (function (cond - ((macro-function symbol) "@end defmac") - ((special-operator-p symbol) "@end defspec") - (t "@end defun"))) - (method-combination "@end deffn") - (package "@end deffn") - (setf "@end deffn") - (type "@end deftp") - (variable (if (constantp symbol) - "@end defvr" - "@defvar")))) + ((compiler-macro function method-combination setf) "@end deffn") + ((package variable) "@end defvr") + ((structure type) "@end deftp")) + ) (defun make-info-file (package &optional filename) "Create a file containing all available documentation for the @@ -195,12 +204,14 @@ (with-open-file (out filename :direction :output :if-does-not-exist :create :if-exists :supersede) (loop for (symbol kind docstring) in docs - do (format out "~&@anchor{~A}~%~A ~A~@[ ~A~]~%~A~%~A~%~%" + do (format out "~&@anchor{~A}~%~A ~A:~A~@[ ~A~]~%~A~&~A~%~A~%~%" (unique-name symbol package kind) (def-begin symbol kind) + (texinfoify (package-name package)) (texinfoify symbol) - (def-rest symbol kind) - docstring + (def-arglist symbol kind) + (def-index symbol kind) + (texinfoify docstring) (def-end symbol kind)))) filename)) @@ -226,11 +237,13 @@ directory) :direction :output :if-does-not-exist :create :if-exists :supersede) - (format out "~&@anchor{~A}~%~A ~A~@[ ~A~]~%~A~%~A~%~%" + (format out "~&@anchor{~A}~%~A ~A:~A~@[ ~A~]~%~A~&~A~%~A~%~%" (unique-name symbol package kind) (def-begin symbol kind) + (texinfoify (package-name package)) (texinfoify symbol) - (def-rest symbol kind) - docstring + (def-arglist symbol kind) + (def-index symbol kind) + (texinfoify docstring) (def-end symbol kind))))) directory)) diff --git a/doc/manual/docstrings.sh b/doc/manual/docstrings.sh index 4b499a9..e85747c 100644 --- a/doc/manual/docstrings.sh +++ b/doc/manual/docstrings.sh @@ -22,13 +22,14 @@ else SBCL="${1:-`which sbcl`}" fi -# List of package names that documentation will be created for. -PACKAGES=":SB-ALIEN :SB-EXT :SB-GRAY :SB-MOP :SB-PROFILE :SB-THREAD" - # Output directory. This has to end with a slash (it's interpreted by -# Lisp's `pathname' function) or you lose. +# 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/efficiency.texinfo b/doc/manual/efficiency.texinfo index 7559abf..775ac4f 100644 --- a/doc/manual/efficiency.texinfo +++ b/doc/manual/efficiency.texinfo @@ -1,4 +1,4 @@ -@node Efficiency, Beyond The ANSI Standard, The Debugger, Top +@node Efficiency @comment node-name, next, previous, up @chapter Efficiency @@ -122,7 +122,7 @@ examples (some straightforward, some less so). * Modular arithmetic:: @end menu -@node Dynamic-extent allocation, Modular arithmetic, Efficiency, Efficiency +@node Dynamic-extent allocation @comment node-name, next, previous, up @section Dynamic-extent allocation @cindex Dynamic-extent declaration @@ -197,7 +197,7 @@ closure, even when the closure is not declared @code{dynamic-extent}. @end itemize -@node Modular arithmetic, , Dynamic-extent allocation, Efficiency +@node Modular arithmetic @comment node-name, next, previous, up @section Modular arithmetic @cindex Modular arithmetic diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo index 68d5cce..feed6a8 100644 --- a/doc/manual/ffi.texinfo +++ b/doc/manual/ffi.texinfo @@ -1,4 +1,4 @@ -@node The Foreign Function Interface, Function Index, Beyond The ANSI Standard, Top +@node The Foreign Function Interface @comment node-name, next, previous, up @chapter The Foreign Function Interface @@ -29,7 +29,7 @@ notably in the name of the @code{SB-ALIEN} package. * Step-By-Step Example of the Foreign Function Interface:: @end menu -@node Introduction to the Foreign Function Interface, Foreign Types, The Foreign Function Interface, The Foreign Function Interface +@node Introduction to the Foreign Function Interface @comment node-name, next, previous, up @section Introduction to the Foreign Function Interface @c AKA "Introduction to Aliens" in the CMU CL manual @@ -79,7 +79,7 @@ raw pointer to the foreign data within an @code{alien-value} object. The type language and operations on foreign types are intentionally similar to those of the C language. -@node Foreign Types, Operations On Foreign Values, Introduction to the Foreign Function Interface, The Foreign Function Interface +@node Foreign Types @comment node-name, next, previous, up @section Foreign Types @c AKA "Alien Types" in the CMU CL manual @@ -109,7 +109,7 @@ has the corresponding SBCL @acronym{FFI} type * Foreign Type Specifiers:: @end menu -@node Defining Foreign Types, Foreign Types and Lisp Types, Foreign Types, Foreign Types +@node Defining Foreign Types @comment node-name, next, previous, up @subsection Defining Foreign Types @@ -127,7 +127,7 @@ An anonymous structure or union type is specified by using the name inherently named, but can be given named abbreviations using the @code{define-alien-type} macro. -@node Foreign Types and Lisp Types, Foreign Type Specifiers, Defining Foreign Types, Foreign Types +@node Foreign Types and Lisp Types @comment node-name, next, previous, up @subsection Foreign Types and Lisp Types @@ -153,7 +153,7 @@ to Lisp floats. When @code{type-of} is called on an alien value that is not automatically converted to a Lisp value, then it will return an @code{alien} type specifier. -@node Foreign Type Specifiers, , Foreign Types and Lisp Types, Foreign Types +@node Foreign Type Specifiers @comment node-name, next, previous, up @subsection Foreign Type Specifiers @@ -323,7 +323,7 @@ specifiers as foreign type specifiers: @code{sb-alien:char}, @end itemize -@node Operations On Foreign Values, Foreign Variables, Foreign Types, The Foreign Function Interface +@node Operations On Foreign Values @comment node-name, next, previous, up @section Operations On Foreign Values @c AKA "Alien Operations" in the CMU CL manual @@ -338,11 +338,12 @@ to dynamically allocate and free foreign variables. * Foreign Dynamic Allocation:: @end menu -@node Accessing Foreign Values, Coercing Foreign Values, Operations On Foreign Values, Operations On Foreign Values +@node Accessing Foreign Values @comment node-name, next, previous, up @subsection Accessing Foreign Values @defun sb-alien:deref @var{pointer-or-array} &rest @var{indices} +@findex deref The @code{sb-alien:deref} function returns the value pointed to by a foreign pointer, or the value of a foreign array element. When @@ -352,11 +353,11 @@ the size of the type pointed to. When dereferencing an array, the number of indices must be the same as the number of dimensions in the array type. @code{deref} can be set with @code{setf} to assign a new value. - @end defun @defun sb-alien:slot @var{struct-or-union} &rest @var{slot-names} - +@findex slot + The @code{sb-alien:slot} function extracts the value of the slot named @var{slot-name} from a foreign @code{struct} or @code{union}. If @var{struct-or-union} is a pointer to a structure or union, then it is @@ -378,12 +379,14 @@ used with caution; corrupting the Lisp heap or other memory with @acronym{SAP}s is trivial. @defun sb-sys:int-sap @var{machine-address} +@findex int-sap Creates a @acronym{SAP} pointing at the virtual address @var{machine-address}. @end defun @defun sb-sys:sap-ref-32 @var{sap} @var{offset} +@findex sap-ref-32 Access the value of the memory location at @var{offset} bytes from @var{sap}. This form may also be used with @code{setf} to alter the @@ -391,6 +394,7 @@ memory at that location. @end defun @defun sb-sys:sap= @var{sap1} @var{sap2} +@findex sap= Compare @var{sap1} and @var{sap2} for equality. @end defun @@ -404,12 +408,13 @@ use @code{apropos} and @code{describe} for more details @end lisp -@node Coercing Foreign Values, Foreign Dynamic Allocation, Accessing Foreign Values, Operations On Foreign Values +@node Coercing Foreign Values @comment node-name, next, previous, up @subsection Coercing Foreign Values @defun sb-alien:addr @var{alien-expr} - +@findex addr + The @code{sb-alien:addr} macro returns a pointer to the location specified by @var{alien-expr}, which must be either a foreign variable, a use of @code{sb-alien:deref}, a use of @@ -417,7 +422,8 @@ variable, a use of @code{sb-alien:deref}, a use of @end defun @defun sb-alien:cast @var{foreign-value} @var{new-type} - +@findex cast + The @code{sb-alien:cast} macro converts @var{foreign-value} to a new foreign value with the specified @var{new-type}. Both types, old and new, must be foreign pointer, array or function types. Note that the @@ -426,7 +432,8 @@ argument, but it does refer to the same foreign data bits. @end defun @defun sb-alien:sap-alien @var{sap} @var{type} - +@findex sap-alien + The @code{sb-alien:sap-alien} function converts @var{sap} (a system area pointer) to a foreign value with the specified @var{type}. @var{type} is not evaluated. @@ -435,6 +442,7 @@ The @var{type} must be some foreign pointer, array, or record type. @end defun @defun sb-alien:alien-sap @var{foreign-value} @var{type} +@findex alien-sap The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which points to @var{alien-value}'s data. @@ -444,7 +452,7 @@ record type. @end defun -@node Foreign Dynamic Allocation, , Coercing Foreign Values, Operations On Foreign Values +@node Foreign Dynamic Allocation @comment node-name, next, previous, up @subsection Foreign Dynamic Allocation @@ -457,7 +465,8 @@ Lisp @code{sb-alien:make-alien}, or for Lisp code to call code. @defmac sb-alien:make-alien @var{type} @var{size} - +@findex make-alien + The @code{sb-alien:make-alien} macro returns a dynamically allocated foreign value of the specified @var{type} (which is not evaluated.) The allocated memory is not @@ -494,6 +503,7 @@ result pointing to the first one. @end defmac @defun sb-alien:free-alien @var{foreign-value} +@findex free-alien The @code{sb-alien:free-alien} function frees the storage for @var{foreign-value}, @@ -504,7 +514,7 @@ See also the @code{sb-alien:with-alien} macro, which allocates foreign values on the stack. @end defun -@node Foreign Variables, Foreign Data Structure Examples, Operations On Foreign Values, The Foreign Function Interface +@node Foreign Variables @comment node-name, next, previous, up @section Foreign Variables @c AKA "Alien Variables" in the CMU CL manual @@ -517,11 +527,12 @@ are supported. * External Foreign Variables:: @end menu -@node Local Foreign Variables, External Foreign Variables, Foreign Variables, Foreign Variables +@node Local Foreign Variables @comment node-name, next, previous, up @subsection Local Foreign Variables @defmac sb-alien:with-alien @var{var-definitions} &body @var{body} +@findex with-alien The @code{with-alien} macro establishes local foreign variables with the specified alien types and names. This form is analogous to @@ -549,7 +560,7 @@ defined foreign structure type @var{foo} can be referenced by its name using @code{(struct @var{foo})}. @end defmac -@node External Foreign Variables, , Local Foreign Variables, Foreign Variables +@node External Foreign Variables @comment node-name, next, previous, up @subsection External Foreign Variables @@ -580,6 +591,7 @@ specified by using a list of the form @end itemize @defmac sb-alien:define-alien-variable @var{name} @var{type} +@findex define-alien-variable The @code{define-alien-variable} macro defines @var{name} as an external foreign variable of the specified foreign @code{type}. @@ -606,6 +618,7 @@ For example, to access a C-level counter @var{foo}, one could write @end defmac @defun sb-alien:get-errno +@findex get-errno Since in modern C libraries, the @code{errno} ``variable'' is typically no longer a variable, but some bizarre artificial construct @@ -616,6 +629,7 @@ the operator @code{sb-alien:get-errno} to allow Lisp code to read it. @end defun @defmac sb-alien:extern-alien @var{name} @var{type} +@findex extern-alien The @code{extern-alien} macro returns an alien with the specified @var{type} which points to an externally defined value. @var{name} is @@ -623,7 +637,7 @@ not evaluated, and may be either a string or a symbol. @var{type} is an unevaluated alien type specifier. @end defmac -@node Foreign Data Structure Examples, Loading Unix Object Files, Foreign Variables, The Foreign Function Interface +@node Foreign Data Structure Examples @comment node-name, next, previous, up @section Foreign Data Structure Examples @c AKA "Alien Data Structure Example" in the CMU CL manual @@ -697,7 +711,7 @@ which can be manipulated in Lisp like this: (setq my-struct (slot my-struct 'n)) @end lisp -@node Loading Unix Object Files, Foreign Function Calls, Foreign Data Structure Examples, The Foreign Function Interface +@node Loading Unix Object Files @comment node-name, next, previous, up @section Loading Unix Object Files @@ -732,7 +746,7 @@ is loaded. @end quotation -@node Foreign Function Calls, Step-By-Step Example of the Foreign Function Interface, Loading Unix Object Files, The Foreign Function Interface +@node Foreign Function Calls @comment node-name, next, previous, up @section Foreign Function Calls @@ -759,11 +773,12 @@ the only documentation. Users of a Lisp built with the * Calling Lisp From C:: @end menu -@node The alien-funcall Primitive, The define-alien-routine Macro, Foreign Function Calls, Foreign Function Calls +@node The alien-funcall Primitive @comment node-name, next, previous, up @subsection The @code{alien-funcall} Primitive @defun sb-alien:alien-funcall @var{alien-function} &rest @var{arguments} +@findex alien-funcall The @code{alien-funcall} function is the foreign function call primitive: @var{alien-function} is called with the supplied @@ -812,11 +827,12 @@ the @code{(* (struct foo))} objects filled in by the foreign call: result))) @end lisp -@node The define-alien-routine Macro, define-alien-routine Example, The alien-funcall Primitive, Foreign Function Calls +@node The define-alien-routine Macro @comment node-name, next, previous, up @subsection The @code{define-alien-routine} Macro @defmac sb-alien:define-alien-routine @var{name} @var{result-type} &rest @var{arg-specifiers} +@findex define-alien-routine The @code{define-alien-routine} macro is a convenience for automatically generating Lisp interfaces to simple foreign functions. @@ -890,7 +906,7 @@ representations, avoiding consing.) @end defmac -@node define-alien-routine Example, Calling Lisp From C, The define-alien-routine Macro, Foreign Function Calls +@node define-alien-routine Example @comment node-name, next, previous, up @subsection @code{define-alien-routine} Example @@ -921,7 +937,7 @@ This can be described by the following call to The Lisp function @code{cfoo} will have two arguments (@var{str} and @var{a}) and two return values (@var{a} and @var{i}). -@node Calling Lisp From C, , define-alien-routine Example, Foreign Function Calls +@node Calling Lisp From C @comment node-name, next, previous, up @subsection Calling Lisp From C @@ -1099,7 +1115,7 @@ call. @c --> -@node Step-By-Step Example of the Foreign Function Interface, , Foreign Function Calls, The Foreign Function Interface +@node Step-By-Step Example of the Foreign Function Interface @comment node-name, next, previous, up @section Step-By-Step Example of the Foreign Function Interface diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 8a98d73..0dc84bd 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -1,4 +1,4 @@ -@node Introduction, The Compiler, Top, Top +@node Introduction @comment node-name, next, previous, up @chapter Introduction @@ -13,7 +13,7 @@ Lisp. * Overview:: @end menu -@node More Common Lisp Information, More SBCL Information, Introduction, Introduction +@node More Common Lisp Information @comment node-name, next, previous, up @section Where To Go For More Information about Common Lisp in General @@ -56,7 +56,7 @@ culture shock. @end itemize -@node More SBCL Information, Overview, More Common Lisp Information, Introduction +@node More SBCL Information @comment node-name, next, previous, up @section Where To Go For More Information About SBCL @@ -111,7 +111,7 @@ distribution. @end itemize -@node Overview, , More SBCL Information, Introduction +@node Overview @comment node-name, next, previous, up @section Overview Of SBCL, How It Works And Where It Came From diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo index 10e9736..9937ce4 100644 --- a/doc/manual/sbcl.texinfo +++ b/doc/manual/sbcl.texinfo @@ -9,7 +9,14 @@ @set VERSION 0.8.9 @set UPDATED 2 April 2004 @set UPDATE-MONTH April 2004 - + +@c for install-info +@dircategory Software development +@direntry +* sbcl: (sbcl). The Steel Bank Common Lisp compiler +@end direntry + + @copying @@ -45,9 +52,9 @@ provided with absolutely no warranty. See the @file{COPYING} and @ifnottex -@node Top, Introduction, (dir), (dir) +@node Top @comment node-name, next, previous, up -@top SBCL +@top sbcl @insertcopying @@ -58,131 +65,10 @@ provided with absolutely no warranty. See the @file{COPYING} and * Efficiency:: * Beyond The ANSI Standard:: * The Foreign Function Interface:: -* Function Index:: * Concept Index:: +* Function Index:: +* Variable Index:: * Colophon:: - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* More Common Lisp Information:: -* More SBCL Information:: -* Overview:: - -The Compiler - -* Error Messages:: -* Handling of Types:: -* Compiler Policy:: -* Open Coding and Inline Expansion:: - -Error Messages - -* The Parts of the Error Message:: -* The Original and Actual Source:: -* Error Severity:: -* Errors During Macroexpansion:: -* Read Errors:: - -The Compiler's Handling of Types - -* Implementation Limitations:: -* Type Errors at Compile Time:: -* Precise Type Checking:: -* Weakened Type Checking:: -* Getting Existing Programs to Run:: - -The Debugger - -* Starting the Debugger:: -* The Debugger Command Loop:: -* Controlling Printing in the Debugger:: -* Stack Frames:: -* Variable Access:: -* Source Location Printing:: -* Debugger Policy Control:: -* Exiting Commands:: -* Information Commands:: -* Function Tracing:: - -Stack Frames - -* Stack Motion:: -* How Arguments are Printed:: -* Function Names:: -* Funny Frames:: -* Debug Tail Recursion:: -* Unknown Locations and Interrupts:: - -Variable Access - -* Variable Value Availability:: -* Note On Lexical Variable Access:: - -Source Location Printing - -* How the Source is Found:: -* Source Location Availability:: - -Efficiency - -* Dynamic-extent allocation:: -* Modular arithmetic:: - -Beyond The ANSI Standard - -* Non-Conformance With The ANSI Standard:: -* Idiosyncrasies:: -* Extensions:: - -Extensions - -* Things Which Might Be In The Next ANSI Standard:: -* Threading:: -* Support For Unix:: -* Customization Hooks for Users:: -* Tools To Help Developers:: -* Interface To Low-Level SBCL Implementation:: -* Efficiency Hacks:: - -The Foreign Function Interface - -* Introduction to the Foreign Function Interface:: -* Foreign Types:: -* Operations On Foreign Values:: -* Foreign Variables:: -* Foreign Data Structure Examples:: -* Loading Unix Object Files:: -* Foreign Function Calls:: -* Step-By-Step Example of the Foreign Function Interface:: - -Foreign Types - -* Defining Foreign Types:: -* Foreign Types and Lisp Types:: -* Foreign Type Specifiers:: - -Operations On Foreign Values - -* Accessing Foreign Values:: -* Coercing Foreign Values:: -* Foreign Dynamic Allocation:: - -Foreign Variables - -* Local Foreign Variables:: -* External Foreign Variables:: - -Foreign Function Calls - -* The alien-funcall Primitive:: -* The define-alien-routine Macro:: -* define-alien-routine Example:: -* Calling Lisp From C:: - -@end detailmenu @end menu @end ifnottex diff --git a/version.lisp-expr b/version.lisp-expr index dcd8ec4..0a5d23f 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.31" +"0.8.9.32" -- 1.7.10.4