From: Christophe R. <cr...@us...> - 2010-06-06 20:44:07
|
Update of /cvsroot/sbcl/sbcl/doc/manual In directory sfp-cvsdas-3.v30.ch3.sourceforge.com:/tmp/cvs-serv29631/doc/manual Modified Files: Makefile beyond-ansi.texinfo compiler.texinfo debugger.texinfo docstrings.lisp efficiency.texinfo ffi.texinfo intro.texinfo package-locks-extended.texinfo pathnames.texinfo sbcl.texinfo start-stop.texinfo streams.texinfo support-and-bugs.texinfo texinfo-macros.texinfo Log Message: 1.0.39.9: improvements to the manual These improvements mainly centre around better indexing, including some nifty trickery to get suitably collated and aligned index entries (to cope with issues like *earmuffs* and sb-foo package prefixes). This patch also incorporates work by Robert Goldman to document the commands for enabling and disabling the debuggers. The remainder of this log message is a squashed version of my git branch's log messages: improve text relating to my support availability Remove a stray comma in instructions for signal-related bug reporting Patch from Robert Goldman for enable/disable-debugger documentation trick texinfo's collation engine into producing a better index The issue is that the sort order and what is printed (both in the index and as the title of a definition entry) are deeply tied together in texinfo, and there's no obvious way short of rewriting lots of TeX code to undo that. There is one get-out clause, though: texinfo macros are replaced by their arguments. So define a number of macros which hide from the collation engine things that we would rather not play a part in the sorting (package names, "(setf", *earmuffs*) In the process, note that @deffoo in texinfo automatically produces an index entry, so get rid of the apparently redundant extra index entries produced by docstrings.lisp Mostly move to using the new indexing helper macros Only mostly: there are a few remaining issues. The first is declarations, which are treated as types; I think they might warrant their own index; similarly, various commands (debugger, inspector) aren't really functions. Hardest of all is the ffi chapter, which has handwritten function documentation which is highly similar to but not exactly the same as the docstrings for those operators; it would be good to merge the documentation into the docstrings, include the autogenerated texinfo snippets into the manual, and thereby gain complete consistency. add some index entries from the efficiency chapter ... because why not? manually (!) change the entries for FFI-related functions and macros Making the docstrings match the text match reality is an exercise for the future. make index in info form mostly work info readers apparently parse the formatted index to work out where to go. This is hilariously bad if the index entries contain colons, so define macros conditional on output format to make sure that they don't in info. better, more useful indexes Now that collation is sorted (!), getting the display of index entries to be useful is important. This not-quite-general trick is to make the package name as small as possible, have the colon always in the same horizontal position, and arrange that the package name extends at most three characters ("sb-") into the left margin. This is the most tolerable I can find. Continue not having package information at all in info format; in other formats, place the package information after the symbol name. This probably goes wrong in corner cases like (setf sb-mop:symbol-value-using-class) deal with remaining manually-documented functions make documentation for declarations consistent Arbitrarily decide that declarations belong in the function index rather than the type index; use the package prefix texinfo macros to get them properly indented. One more manually-documented thing which needed a package macro decoration Fix the nopkg{} macro to align index entries in TeX mode Use it for debugger commands. Index: Makefile =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/Makefile,v retrieving revision 1.24 retrieving revision 1.25 diff -u -d -r1.24 -r1.25 --- Makefile 30 Mar 2010 10:46:44 -0000 1.24 +++ Makefile 6 Jun 2010 20:43:58 -0000 1.25 @@ -19,6 +19,7 @@ :sb-sprof :sb-bsd-sockets :sb-cover :sb-posix' # List of package names that docstring docs will be created for. PACKAGES=":COMMON-LISP :SB-ALIEN :SB-DEBUG :SB-EXT :SB-GRAY :SB-MOP \ + :SB-PCL :SB-SYS \ :SB-PROFILE :SB-THREAD :SB-MD5 :SB-QUEUE :SB-ROTATE-BYTE \ :SB-SPROF :SB-BSD-SOCKETS :SB-COVER :SB-POSIX :SB-CONCURRENCY" Index: beyond-ansi.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/beyond-ansi.texinfo,v retrieving revision 1.39 retrieving revision 1.40 diff -u -d -r1.39 -r1.40 --- beyond-ansi.texinfo 19 Nov 2009 16:08:37 -0000 1.39 +++ beyond-ansi.texinfo 6 Jun 2010 20:43:58 -0000 1.40 @@ -76,20 +76,18 @@ @itemize @item -@findex compute-effective-method -@findex sb-mop:compute-effective-method +@findex @sbmop{compute-effective-method} @code{compute-effective-method} only returns one value, not two. There is no record of what the second return value was meant to indicate, and apparently no clients for it. @item -@tindex generic-function -@tindex standard-generic-function -@tindex funcallable-standard-object -@tindex sb-mop:funcallable-standard-object -@tindex standard-object -@tindex function +@tindex @cl{generic-function} +@tindex @cl{standard-generic-function} +@tindex @sbmop{funcallable-standard-object} +@tindex @cl{standard-object} +@tindex @cl{function} The direct superclasses of @code{sb-mop:funcallable-standard-object} are @code{(function standard-object)}, not @code{(standard-object function)}. @@ -100,9 +98,8 @@ ANSI specification. @item -@findex ensure-generic-function -@findex generic-function-declarations -@findex sb-mop:generic-function-declarations +@findex @cl{ensure-generic-function} +@findex @sbmop{generic-function-declarations} the arguments @code{:declare} and @code{:declarations} to @code{ensure-generic-function} are both accepted, with the leftmost argument defining the declarations to be stored and returned by @@ -113,16 +110,12 @@ @code{:declare}. Portable code should use @code{:declare}. @item -@findex validate-superclass -@findex finalize-inheritance -@findex sb-mop:validate-superclass -@findex sb-mop:finalize-inheritance -@tindex standard-class -@tindex funcallable-standard-class -@tindex sb-mop:funcallable-standard-class -@tindex function -@findex sb-mop:class-prototype -@findex class-prototype +@findex @sbmop{validate-superclass} +@findex @sbmop{finalize-inheritance} +@tindex @cl{standard-class} +@tindex @sbmop{funcallable-standard-class} +@tindex @cl{function} +@findex @sbmop{class-prototype} although SBCL obeys the requirement in AMOP that @code{validate-superclass} should treat @code{standard-class} and @code{funcallable-standard-class} as compatible metaclasses, we @@ -131,9 +124,9 @@ @code{function} in its superclasses, and a class of metaclass @code{standard-class} must not. -@findex typep -@findex class-of -@findex subtypep +@findex @cl{typep} +@findex @cl{class-of} +@findex @cl{subtypep} After a class has been finalized, it is associated with a class prototype which is accessible by a standard mop function @code{sb-mop:class-prototype}. The user can then ask whether this @@ -165,8 +158,7 @@ @end lisp and leads to a class whose instances are funcallable and have one slot. -@tindex funcallable-standard-object -@tindex sb-mop:funcallable-standard-object +@tindex @sbmop{funcallable-standard-object} Note that this requirement also applies to the class @code{sb-mop:funcallable-standard-object}, which has metaclass @code{sb-mop:funcallable-standard-class} rather than @@ -187,12 +179,9 @@ of software from colliding with each other. @item -@findex slot-value-using-class -@findex sb-mop:slot-value-using-class -@findex (setf slot-value-using-class) -@findex (setf sb-mop:slot-value-using-class) -@findex slot-boundp-using-class -@findex sb-mop:slot-boundp-using-class +@findex @sbmop{slot-value-using-class} +@findex @setf{@sbmop{slot-value-using-class}} +@findex @sbmop{slot-boundp-using-class} specializations of the @code{new-value} argument to @code{(setf sb-mop:slot-value-using-class)} are not allowed: all user-defined methods must have a specializer of the class @code{t}. @@ -211,13 +200,11 @@ argument of slot accessors. @item -@findex defclass -@findex ensure-class -@findex ensure-class-using-class -@findex sb-mop:ensure-class -@findex sb-mop:ensure-class-using-class -@findex find-class -@findex class-name +@findex @cl{defclass} +@findex @sbmop{ensure-class} +@findex @sbmop{ensure-class-using-class} +@findex @cl{find-class} +@findex @cl{class-name} the class named by the @code{name} argument to @code{ensure-class}, if any, is only redefined if it is the proper name of that class; otherwise, a new class is created. @@ -236,14 +223,11 @@ @itemize @item -@findex defmethod -@findex find-class -@findex intern-eql-specializer -@findex sb-mop:intern-eql-specializer -@findex make-method-specializers-form -@findex sb-pcl:make-method-specializers-form -@findex make-method-lambda -@findex sb-mop:make-method-lambda +@findex @cl{defmethod} +@findex @cl{find-class} +@findex @sbmop{intern-eql-specializer} +@findex @sbpcl{make-method-specializers-form} +@findex @sbmop{make-method-lambda} compile-time support for generating specializer metaobjects from specializer names in @code{defmethod} forms is provided by the @code{make-method-specializers-form} function, which returns a form @@ -259,11 +243,9 @@ @var{x})} specializer name. @item -@findex find-method -@findex parse-specializer-using-class -@findex unparse-specializer-using-class -@findex sb-pcl:parse-specializer-using-class -@findex sb-pcl:unparse-specializer-using-class +@findex @cl{find-method} +@findex @sbpcl{parse-specializer-using-class} +@findex @sbpcl{unparse-specializer-using-class} run-time support for converting between specializer names and specializer metaobjects, mostly for the purposes of @code{find-method}, is provided by @@ -288,8 +270,7 @@ @node Command-line arguments @subsection Command-line arguments -@vindex sb-ext:*posix-argv* -@vindex *posix-argv* +@vindex @sbext{@earmuffs{posix-argv}} The UNIX command line can be read from the variable @code{sb-ext:*posix-argv*}. @@ -379,8 +360,8 @@ @node Tools To Help Developers @comment node-name, next, previous, up @section Tools To Help Developers -@findex trace -@findex inspect +@findex @cl{trace} +@findex @cl{inspect} SBCL provides a profiler and other extensions to the ANSI @code{trace} facility. For more information, see @ref{Macro common-lisp:trace}. @@ -393,10 +374,8 @@ @node Resolution of Name Conflicts @section Resolution of Name Conflicts -@tindex sb-ext:name-conflict -@tindex name-conflict -@findex sb-ext:name-conflict-symbols -@findex name-conflict-symbols +@tindex @sbext{name-conflict} +@findex @sbext{name-conflict-symbols} The ANSI standard (section 11.1.1.2.5) requires that name conflicts in packages be resolvable in favour of any of the conflicting symbols. In Index: compiler.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/compiler.texinfo,v retrieving revision 1.22 retrieving revision 1.23 diff -u -d -r1.22 -r1.23 --- compiler.texinfo 11 Mar 2010 13:53:49 -0000 1.22 +++ compiler.texinfo 6 Jun 2010 20:43:58 -0000 1.23 @@ -64,17 +64,17 @@ (* x -5)))) @end lisp -@deffn {Declaration} sb-ext:muffle-conditions +@deffn {Declaration} @sbext{muffle-conditions} Syntax: type* Muffles the diagnostic messages that would be caused by compile-time signals of given types. @end deffn -@deffn {Declaration} sb-ext:unmuffle-conditions +@deffn {Declaration} @sbext{unmuffle-conditions} Syntax: type* -Cancels the effect of a previous @code{sb-ext:muffle-condition} +Cancels the effect of a previous @code{sb-ext:muffle-conditions} declaration. @end deffn @@ -130,11 +130,11 @@ @subsection Diagnostic Severity @cindex Severity of compiler messages @cindex Compiler Diagnostic Severity -@tindex error -@tindex warning -@tindex style-warning -@tindex compiler-note -@tindex code-deletion-note +@tindex @cl{error} +@tindex @cl{warning} +@tindex @cl{style-warning} +@tindex @sbext{compiler-note} +@tindex @sbext{code-deletion-note} There are four levels of compiler diagnostic severity: @@ -217,7 +217,7 @@ @enumerate @item -@findex with-compilation-unit +@findex @cl{with-compilation-unit} @samp{file: /tmp/foo.lisp} This is the name of the file that the compiler read the relevant code from. The file name is displayed because it may not be immediately obvious when there is an error @@ -467,7 +467,7 @@ of appropriate type declarations can be very important for performance as well. -@findex satisfies +@findex @cl{satisfies} The SBCL compiler also has a greater knowledge of the Common Lisp type system than other compilers. Support is incomplete only for types involving the @code{satisfies} type specifier. @@ -490,7 +490,7 @@ @node Declarations as Assertions @comment node-name, next, previous, up @subsection Declarations as Assertions -@findex safety +@cindex Safety optimization quality The SBCL compiler treats type declarations differently from most other Lisp compilers. Under default compilation policy the compiler doesn't @@ -1114,7 +1114,7 @@ @comment node-name, next, previous, up @section Interpreter @cindex Interpreter -@vindex sb-ext:*evaluator-mode* +@vindex @sbext{@earmuffs{evaluator-mode}} By default SBCL implements @code{eval} by calling the native code compiler. SBCL also includes an interpreter for use in special cases Index: debugger.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/debugger.texinfo,v retrieving revision 1.16 retrieving revision 1.17 diff -u -d -r1.16 -r1.17 --- debugger.texinfo 5 Apr 2007 00:21:27 -0000 1.16 +++ debugger.texinfo 6 Jun 2010 20:43:58 -0000 1.17 @@ -18,6 +18,7 @@ * Information Commands:: * Function Tracing:: * Single Stepping:: +* Enabling and Disabling the Debugger:: @end menu @node Debugger Entry @@ -168,25 +169,25 @@ function and the values of its arguments in the style of a Lisp function call: -@deffn {Debugger Command} up +@deffn {Debugger Command} @nopkg{up} Move up to the next higher frame. More recent function calls are considered to be higher on the stack. @end deffn -@deffn {Debugger Command} down +@deffn {Debugger Command} @nopkg{down} Move down to the next lower frame. @end deffn -@deffn {Debugger Command} top +@deffn {Debugger Command} @nopkg{top} Move to the highest frame, that is, the frame where the debugger was entered. @end deffn -@deffn {Debugger Command} bottom +@deffn {Debugger Command} @nopkg{bottom} Move to the lowest frame. @end deffn -@deffn {Debugger Command} frame [@var{n}] +@deffn {Debugger Command} @nopkg{frame} [@var{n}] Move to the frame with the specified number. Prompts for the number if not supplied. The frame with number 0 is the frame where the debugger was entered. @@ -461,7 +462,7 @@ X#1 = 2 @end example -@deffn {Debugger Command} list-locals [@var{prefix}] +@deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}] This command prints the name and value of all variables in the current frame whose name has the specified @var{prefix}. @var{prefix} may be a string or a symbol. If no @var{prefix} is given, then all available @@ -471,7 +472,7 @@ name unique. @end deffn -@defun sb-debug:var @var{name} &optional @var{identifier} +@defun @sbdebug{var} @var{name} &optional @var{identifier} This function returns the value of the variable in the current frame with the specified @var{name}. If supplied, @var{identifier} determines which value to return when there are ambiguous variables. @@ -604,7 +605,7 @@ compiled code. These commands display the source location for the current frame: -@deffn {Debugger Command} source [@var{context}] +@deffn {Debugger Command} @nopkg{source} [@var{context}] This command displays the file that the current frame's function was defined from (if it was defined from a file), and then the source form responsible for generating the code that the current frame was @@ -881,35 +882,35 @@ These commands get you out of the debugger. -@deffn {Debugger Command} toplevel +@deffn {Debugger Command} @nopkg{toplevel} Throw to top level. @end deffn -@deffn {Debugger Command} restart [@var{n}] +@deffn {Debugger Command} @nopkg{restart} [@var{n}] Invokes the @var{n}th restart case as displayed by the @code{error} command. If @var{n} is not specified, the available restart cases are reported. @end deffn -@deffn {Debugger Command} continue +@deffn {Debugger Command} @nopkg{continue} Calls @code{continue} on the condition given to @code{debug}. If there is no restart case named @var{continue}, then an error is signaled. @end deffn -@deffn {Debugger Command} abort +@deffn {Debugger Command} @nopkg{abort} Calls @code{abort} on the condition given to @code{debug}. This is useful for popping debug command loop levels or aborting to top level, as the case may be. @end deffn -@deffn {Debugger Command} return @var{value} +@deffn {Debugger Command} @nopkg{return} @var{value} Returns @var{value} from the current stack frame. This command is available when the @code{debug} optimization quality is greater than both @code{speed} and @code{space}. Care must be taken that the value is of the same type as SBCL expects the stack frame to return. @end deffn -@deffn {Debugger Command} restart-frame +@deffn {Debugger Command} @nopkg{restart-frame} Restarts execution of the current stack frame. This command is available when the @code{debug} optimization quality is greater than both @code{speed} and @code{space} and when the frame is for is a global @@ -924,27 +925,27 @@ Most of these commands print information about the current frame or function, but a few show general information. -@deffn {Debugger Command} help -@deffnx {Debugger Command} ? +@deffn {Debugger Command} @nopkg{help} +@deffnx {Debugger Command} @nopkg{?} Displays a synopsis of debugger commands. @end deffn -@deffn {Debugger Command} describe +@deffn {Debugger Command} @nopkg{describe} Calls @code{describe} on the current function and displays the number of local variables. @end deffn -@deffn {Debugger Command} print +@deffn {Debugger Command} @nopkg{print} Displays the current function call as it would be displayed by moving to this frame. @end deffn -@deffn {Debugger Command} error +@deffn {Debugger Command} @nopkg{error} Prints the condition given to @code{invoke-debugger} and the active proceed cases. @end deffn -@deffn {Debugger Command} backtrace [@var{n}] +@deffn {Debugger Command} @nopkg{backtrace} [@var{n}] Displays all the frames from the current to the bottom. Only shows @var{n} frames if specified. The printing is controlled by @code{*debug-print-variable-alist*}. @@ -1125,30 +1126,49 @@ The following debugger commands are used for controlling single stepping. -@deffn {Debugger Command} start +@deffn {Debugger Command} @nopkg{start} Selects the @code{continue} restart if one exists and starts single stepping. None of the other single stepping commands can be used before stepping has been started either by using @code{start} or by using the standard @code{step} macro. @end deffn -@deffn {Debugger Command} step +@deffn {Debugger Command} @nopkg{step} Steps into the current form. Stepping will be resumed when the next form that has been compiled with stepper instrumentation is evaluated. @end deffn -@deffn {Debugger Command} next +@deffn {Debugger Command} @nopkg{next} Steps over the current form. Stepping will be disabled until evaluation of the form is complete. @end deffn -@deffn {Debugger Command} out +@deffn {Debugger Command} @nopkg{out} Steps out of the current frame. Stepping will be disabled until the topmost stack frame that had been stepped into returns. @end deffn -@deffn {Debugger Command} stop +@deffn {Debugger Command} @nopkg{stop} Stops the single stepper and resumes normal execution. @end deffn @include macro-common-lisp-step.texinfo + +@node Enabling and Disabling the Debugger +@comment node-name, next, previous, up +@section Enabling and Disabling the Debugger + +@cindex debugger, enabling +@cindex debugger, disabling +@cindex disabling debugger +@cindex ldb, enabling +@cindex ldb, disabling +@cindex disabling ldb + +In certain contexts (e.g., non-interactive applications), it may be +desirable to turn off the SBCL debugger (and possibly re-enable it). +The functions here control the debugger. + +@include fun-sb-ext-disable-debugger.texinfo + +@include fun-sb-ext-enable-debugger.texinfo Index: docstrings.lisp =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/docstrings.lisp,v retrieving revision 1.22 retrieving revision 1.23 diff -u -d -r1.22 -r1.23 --- docstrings.lisp 28 Mar 2010 16:36:30 -0000 1.22 +++ docstrings.lisp 6 Jun 2010 20:43:58 -0000 1.23 @@ -226,9 +226,14 @@ (let ((kind (get-kind doc))) (format nil "~:(~A~) ~(~A~)" kind (name-using-kind/name kind (get-name doc) doc)))) -(defun short-package-name (package) - (car (sort (copy-list (cons (package-name package) (package-nicknames package))) - #'< :key #'length))) +(defun package-shortest-name (package) + (let* ((names (cons (package-name package) (package-nicknames package))) + (sorted (sort (copy-list names) #'< :key #'length))) + (car sorted))) + +(defun package-macro-name (package) + (let ((short-name (package-shortest-name package))) + (remove-if-not #'alpha-char-p (string-downcase short-name)))) ;;; Definition titles for DOCUMENTATION instances @@ -240,12 +245,18 @@ (defmethod title-using-kind/name (kind (name symbol) doc) (declare (ignore kind)) - (format nil "~A:~A" (short-package-name (get-package doc)) name)) + (let* ((symbol-name (symbol-name name)) + (earmuffsp (and (char= (char symbol-name 0) #\*) + (char= (char symbol-name (1- (length symbol-name))) #\*) + (some #'alpha-char-p symbol-name)))) + (if earmuffsp + (format nil "@~A{@earmuffs{~A}}" (package-macro-name (get-package doc)) (subseq symbol-name 1 (1- (length symbol-name)))) + (format nil "@~A{~A}" (package-macro-name (get-package doc)) name)))) (defmethod title-using-kind/name (kind (name list) doc) (declare (ignore kind)) (assert (setf-name-p name)) - (format nil "(setf ~A:~A)" (short-package-name (get-package doc)) (second name))) + (format nil "@setf{@~A{~A}}" (package-macro-name (get-package doc)) (second name))) (defmethod title-using-kind/name ((kind (eql 'method)) name doc) (format nil "~{~A ~}~A" @@ -723,16 +734,6 @@ name)) (lambda-list doc))))) -(defun texinfo-index (doc) - (let ((title (title-name doc))) - (case (get-kind doc) - ((structure type class condition) - (format *texinfo-output* "@tindex ~A~%" title)) - ((variable constant) - (format *texinfo-output* "@vindex ~A~%" title)) - ((compiler-macro function method-combination macro generic-function) - (format *texinfo-output* "@findex ~A~%" title))))) - (defun texinfo-inferred-body (doc) (when (member (get-kind doc) '(class structure condition)) (let ((name (get-name doc))) @@ -779,7 +780,6 @@ "Writes TexInfo for a DOCUMENTATION instance to *TEXINFO-OUTPUT*." (texinfo-anchor doc) (texinfo-begin doc) - (texinfo-index doc) (texinfo-inferred-body doc) (texinfo-body doc) (texinfo-end doc) @@ -828,6 +828,44 @@ :if-exists :supersede) ,@forms)) +(defun write-package-macro (package) + (let* ((package-name (package-shortest-name package)) + (macro-name (package-macro-name package))) + (write-packageish-macro package-name macro-name))) + +(defun write-packageish-macro (package-name macro-name) + ;; a word of explanation about the iftex branch here is probably + ;; warranted. The package information should be present for + ;; clarity, because these produce body text as well as index + ;; entries (though in info output it's more important to use a + ;; very restricted character set because the info reader parses + ;; the link, and colon is a special character). In TeX output we + ;; make the package name unconditionally small, and arrange such + ;; that the start of the symbol name is at a constant horizontal + ;; offset, that offset being such that the longest package names + ;; have the "sb-" extending into the left margin. (At the moment, + ;; the length of the longest package name, sb-concurrency, is + ;; hard-coded). + (format *texinfo-output* "~ +@iftex +@macro ~A{name} +{@smallertt@phantom{concurrency:}~@[@llap{~(~A~):}~]}\\name\\ +@end macro +@end iftex +@ifinfo +@macro ~2:*~A{name} +\\name\\ +@end macro +@end ifinfo +@ifnottex +@ifnotinfo +@macro ~:*~A{name} +\\name\\ ~@[[~(~A~)]~] +@end macro +@end ifnotinfo +@end ifnottex~%" + macro-name package-name)) + (defun generate-includes (directory &rest packages) "Create files in `directory' containing Texinfo markup of all docstrings of each exported symbol in `packages'. `directory' is @@ -844,6 +882,10 @@ (dolist (doc (collect-documentation (find-package package))) (with-texinfo-file (merge-pathnames (include-pathname doc) directory) (write-texinfo doc)))) + (with-texinfo-file (merge-pathnames "package-macros.texinfo" directory) + (dolist (package packages) + (write-package-macro package)) + (write-packageish-macro nil "nopkg")) directory))) (defun document-package (package &optional filename) Index: efficiency.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/efficiency.texinfo,v retrieving revision 1.18 retrieving revision 1.19 diff -u -d -r1.18 -r1.19 --- efficiency.texinfo 19 Nov 2009 16:08:37 -0000 1.18 +++ efficiency.texinfo 6 Jun 2010 20:43:58 -0000 1.19 @@ -70,7 +70,8 @@ @node Dynamic-extent allocation @comment node-name, next, previous, up @section Dynamic-extent allocation -@cindex Dynamic-extent declaration +@cindex @code{dynamic-extent} declaration +@cindex declaration, @code{dynamic-extent} SBCL has limited support for performing allocation on the stack when a variable is declared @code{dynamic-extent}. The @code{dynamic-extent} @@ -93,21 +94,31 @@ @code{&rest} lists, when these are declared @code{dynamic-extent}. @item +@findex @cl{cons} +@findex @cl{list} +@findex @cl{list*} +@findex @cl{vector} @code{cons}, @code{list}, @code{list*}, and @code{vector} when the result is bound to a variable declared @code{dynamic-extent}. @item +@findex @cl{make-array} simple forms of @code{make-array}, whose result is bound to a variable declared @code{dynamic-extent}: stack allocation is possible only if the resulting array is known to be both simple and one-dimensional, and has a constant @code{:element-type}. +@cindex Safety optimization quality @strong{Note}: stack space is limited, so allocation of a large vector may cause stack overflow. For this reason potentially large vectors, which might circumvent stack overflow detection, are stack allocated only in zero @code{safety} policies. @item +@findex @cl{flet} +@findex @cl{labels} +@cindex @code{safety} optimization quality +@cindex optimization quality, @code{safety} closures defined with @code{flet} or @code{labels}, with a bound @code{dynamic-extent} declaration. Closed-over variables, which are assigned to (either inside or outside the closure) are still allocated @@ -189,7 +200,7 @@ @cindex Modular arithmetic @cindex Arithmetic, modular @cindex Arithmetic, hardware - +@findex @cl{logand} Some numeric functions have a property: @var{N} lower bits of the result depend only on @var{N} lower bits of (all or some) arguments. If the compiler sees an expression of form @code{(logand @@ -230,7 +241,7 @@ @include macro-sb-ext-defglobal.texinfo -@deftp {Declaration} sb-ext:global +@deffn {Declaration} @sbext{global} Syntax: @code{(sb-ext:global symbol*)} @@ -241,9 +252,9 @@ variable name as @code{global} signal an error. Allows more efficient value lookup in threaded environments in addition to expressing programmer intention. -@end deftp +@end deffn -@deftp {Declaration} sb-ext:always-bound +@deffn {Declaration} @sbext{always-bound} Syntax: @code{(sb-ext:always-bound symbol*)} @@ -252,7 +263,7 @@ Specifies that the named symbols is always bound. Inhibits @code{makunbound} of the named symbols. Proclaiming an unbound symbol as @code{always-bound} signals an error. Allows compiler to elide boundness checks from value lookups. -@end deftp +@end deffn @node Miscellaneous Efficiency Issues @comment node-name, next, previous, up @@ -287,6 +298,10 @@ @itemize @item +@findex @cl{let} +@findex @cl{let*} +@findex @cl{setq} +@findex @cl{setf} The CMUCL manual doesn't seem to state it explicitly, but Python has a mental block about type inference when assignment is involved. Python is very aggressive and clever about inferring the types of values Index: ffi.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/ffi.texinfo,v retrieving revision 1.19 retrieving revision 1.20 diff -u -d -r1.19 -r1.20 --- ffi.texinfo 28 Mar 2010 09:38:46 -0000 1.19 +++ ffi.texinfo 6 Jun 2010 20:43:58 -0000 1.20 @@ -369,8 +369,7 @@ @comment node-name, next, previous, up @subsection Accessing Foreign Values -@defun sb-alien:deref @var{pointer-or-array} &rest @var{indices} -@findex deref +@defun @sbalien{deref} @var{pointer-or-array} &rest @var{indices} The @code{sb-alien:deref} function returns the value pointed to by a foreign pointer, or the value of a foreign array element. When @@ -382,8 +381,7 @@ value. @end defun -@defun sb-alien:slot @var{struct-or-union} @var{slot-name} -@findex slot +@defun @sbalien{slot} @var{struct-or-union} @var{slot-name} 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 @@ -405,23 +403,20 @@ 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 +@defun @sbsys{int-sap} @var{machine-address} 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 +@defun @sbsys{sap-ref-32} @var{sap} @var{offset} 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 memory at that location. @end defun -@defun sb-sys:sap= @var{sap1} @var{sap2} -@findex sap= +@defun @sbsys{sap=} @var{sap1} @var{sap2} Compare @var{sap1} and @var{sap2} for equality. @end defun @@ -439,37 +434,33 @@ @comment node-name, next, previous, up @subsection Coercing Foreign Values -@defun sb-alien:addr @var{alien-expr} -@findex addr +@defmac @sbalien{addr} @var{alien-expr} 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 @code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}. -@end defun +@end defmac -@defun sb-alien:cast @var{foreign-value} @var{new-type} -@findex cast +@defmac @sbalien{cast} @var{foreign-value} @var{new-type} 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 resulting Lisp foreign variable object is not @code{eq} to the argument, but it does refer to the same foreign data bits. -@end defun +@end defmac -@defun sb-alien:sap-alien @var{sap} @var{type} -@findex sap-alien +@defmac @sbalien{sap-alien} @var{sap} @var{type} -The @code{sb-alien:sap-alien} function converts @var{sap} (a system +The @code{sb-alien:sap-alien} macro converts @var{sap} (a system area pointer) to a foreign value with the specified @var{type}. @var{type} is not evaluated. The @var{type} must be some foreign pointer, array, or record type. -@end defun +@end defmac -@defun sb-alien:alien-sap @var{foreign-value} -@findex alien-sap +@defun @sbalien{alien-sap} @var{foreign-value} The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which points to @var{alien-value}'s data. @@ -491,8 +482,7 @@ @code{sb-alien:free-alien} on foreign objects allocated by C code. -@defmac sb-alien:make-alien @var{type} @var{size} -@findex make-alien +@defmac @sbalien{make-alien} @var{type} @var{size} The @code{sb-alien:make-alien} macro returns a dynamically allocated foreign value of the specified @@ -529,10 +519,9 @@ @end defmac -@defun sb-alien:free-alien @var{foreign-value} -@findex free-alien +@defun @sbalien{free-alien} @var{foreign-value} -The @code{sb-alien:free-alien} function +The @code{sb-alien:free-alien} macro frees the storage for @var{foreign-value}, which must have been allocated with Lisp @code{make-alien} or C @code{malloc}. @@ -558,8 +547,7 @@ @comment node-name, next, previous, up @subsection Local Foreign Variables -@defmac sb-alien:with-alien @var{var-definitions} &body @var{body} -@findex with-alien +@defmac @sbalien{with-alien} @var{var-definitions} &body @var{body} The @code{with-alien} macro establishes local foreign variables with the specified alien types and names. This form is analogous to @@ -617,8 +605,7 @@ @end itemize -@defmac sb-alien:define-alien-variable @var{name} @var{type} -@findex define-alien-variable +@defmac @sbalien{define-alien-variable} @var{name} @var{type} The @code{define-alien-variable} macro defines @var{name} as an external foreign variable of the specified foreign @code{type}. @@ -644,8 +631,7 @@ @end lisp @end defmac -@defun sb-alien:get-errno -@findex get-errno +@defun @sbalien{get-errno} Since in modern C libraries, the @code{errno} ``variable'' is typically no longer a variable, but some bizarre artificial construct @@ -655,8 +641,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 +@defmac @sbalien{extern-alien} @var{name} @var{type} The @code{extern-alien} macro returns an alien with the specified @var{type} which points to an externally defined value. @var{name} is @@ -780,8 +765,7 @@ @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 +@defun @sbalien{alien-funcall} @var{alien-function} &rest @var{arguments} The @code{alien-funcall} function is the foreign function call primitive: @var{alien-function} is called with the supplied @@ -834,8 +818,7 @@ @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 +@defmac @sbalien{define-alien-routine} @var{name} @var{result-type} &rest @var{arg-specifiers} The @code{define-alien-routine} macro is a convenience for automatically generating Lisp interfaces to simple foreign functions. Index: intro.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/intro.texinfo,v retrieving revision 1.19 retrieving revision 1.20 diff -u -d -r1.19 -r1.20 --- intro.texinfo 3 Jun 2009 09:09:52 -0000 1.19 +++ intro.texinfo 6 Jun 2010 20:43:58 -0000 1.20 @@ -209,7 +209,7 @@ @node Defining Constants @comment node-name, next, previous, up @subsection Defining Constants -@findex defconstant +@findex @cl{defconstant} SBCL is quite strict about ANSI's definition of @code{defconstant}. ANSI says that doing @code{defconstant} of the same symbol more than Index: package-locks-extended.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/package-locks-extended.texinfo,v retrieving revision 1.10 retrieving revision 1.11 diff -u -d -r1.10 -r1.11 --- package-locks-extended.texinfo 21 May 2009 09:56:16 -0000 1.10 +++ package-locks-extended.texinfo 6 Jun 2010 20:43:58 -0000 1.11 @@ -49,8 +49,8 @@ @node Implementation Packages @subsection Implementation Packages -@vindex *package* -@findex defpackage +@vindex @cl{@earmuffs{package}} +@findex @cl{defpackage} Each package has a list of associated implementation packages. A locked package, and the symbols whose home package it is, can be @@ -64,27 +64,22 @@ @node Package Lock Violations @subsection Package Lock Violations -@tindex sb-ext:package-lock-violation -@tindex sb-ext:package-locked-error -@tindex sb-ext:symbol-package-locked-error -@tindex package-lock-violation -@tindex package-locked-error -@tindex symbol-package-locked-error -@tindex package-error +@tindex @sbext{package-lock-violation} +@tindex @sbext{package-locked-error} +@tindex @sbext{symbol-package-locked-error} +@tindex @cl{package-error} @subsubsection Lexical Bindings and Declarations -@findex let -@findex let* -@findex flet -@findex labels -@findex macrolet -@findex symbol-macrolet -@findex declare +@findex @cl{let} +@findex @cl{let*} +@findex @cl{flet} +@findex @cl{labels} +@findex @cl{macrolet} +@findex @cl{symbol-macrolet} +@findex @cl{declare} @cindex Declarations -@findex sb-ext:disable-package-locks -@findex sb-ext:enable-package-locks -@findex disable-package-locks -@findex enable-package-locks +@findex @sbext{disable-package-locks} +@findex @sbext{enable-package-locks} Lexical bindings or declarations that violate package locks cause result in a @code{program-error} being signalled at when the form that @@ -300,7 +295,7 @@ @node Package Lock Dictionary @section Package Lock Dictionary -@deftp {Declaration} sb-ext:disable-package-locks +@deffn {Declaration} @sbext{disable-package-locks} Syntax: @code{(sb-ext:disable-package-locks symbol*)} @@ -308,9 +303,9 @@ in the lexical scope of the declaration. Disabling locks on symbols whose home package is unlocked, or disabling an already disabled lock, has no effect. -@end deftp +@end deffn -@deftp {Declaration} sb-ext:enable-package-locks +@deffn {Declaration} @sbext{enable-package-locks} Syntax: @code{(sb-ext:enable-package-locks symbol*)} @@ -318,13 +313,13 @@ in the lexical scope of the declaration. Enabling locks that were not first disabled with @code{sb-ext:disable-package-locks} declaration, or enabling locks that are already enabled has no effect. -@end deftp +@end deffn @include condition-sb-ext-package-lock-violation.texinfo @include condition-sb-ext-package-locked-error.texinfo @include condition-sb-ext-symbol-package-locked-error.texinfo -@defun sb-ext:package-locked-error-symbol symbol-package-locked-error +@defun @sbext{package-locked-error-symbol} symbol-package-locked-error Returns the symbol that caused the @code{symbol-package-locked-error} condition. @@ -340,7 +335,7 @@ @include macro-sb-ext-without-package-locks.texinfo @include macro-sb-ext-with-unlocked-packages.texinfo -@defmac defpackage name [[option]]* @result{} package +@defmac @cl{defpackage} name [[option]]* @result{} package Options are extended to include the following: Index: pathnames.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/pathnames.texinfo,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- pathnames.texinfo 30 Nov 2007 02:16:27 -0000 1.3 +++ pathnames.texinfo 6 Jun 2010 20:43:58 -0000 1.4 @@ -74,8 +74,8 @@ @cindex Logical pathnames @cindex Pathnames, logical -@findex logical-pathname-translations -@findex (setf logical-pathname-translations) +@findex @cl{logical-pathname-translations} +@findex @setf{@cl{logical-pathname-translations}} @c * The existence and meaning of SYS: logical pathnames is @c implementation-defined. (19.3.1.1.1) Index: sbcl.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/sbcl.texinfo,v retrieving revision 1.22 retrieving revision 1.23 diff -u -d -r1.22 -r1.23 --- sbcl.texinfo 19 Nov 2009 16:08:37 -0000 1.22 +++ sbcl.texinfo 6 Jun 2010 20:43:58 -0000 1.23 @@ -3,7 +3,7 @@ @setfilename sbcl.info @settitle SBCL User Manual @c %**end of header - +@afourwide @include texinfo-macros.texinfo @include variables.texinfo @set EDITION 0.1 Index: start-stop.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/start-stop.texinfo,v retrieving revision 1.18 retrieving revision 1.19 diff -u -d -r1.18 -r1.19 --- start-stop.texinfo 8 May 2009 09:32:28 -0000 1.18 +++ start-stop.texinfo 6 Jun 2010 20:43:58 -0000 1.19 @@ -66,8 +66,7 @@ @node Shebang Scripts @comment node-name, next, previous, up @subsection Shebang Scripts -@vindex sb-ext:*posix-argv* -@vindex *posix-argv* +@vindex @sbext{@earmuffs{posix-argv}} Standard Unix tools that are interpreters follow a common command line protocol that is necessary to work with ``shebang scripts''. SBCL supports @@ -215,10 +214,14 @@ @code{--disable-debugger} options. @item --disable-ldb +@cindex ldb +@cindex ldb, disabling +@cindex disabling ldb Disable the low-level debugger. Only effective if SBCL is compiled with LDB. @item --lose-on-corruption +@cindex ldb There are some dangerous low level errors (for instance, control stack exhausted, memory fault) that (or whose handlers) can corrupt the image. By default SBCL prints a warning, then tries to continue and @@ -226,6 +229,7 @@ malfunction or even hang. With this option, upon encountering such an error SBCL will invoke ldb (if present and enabled) or else exit. + @item --script @var{filename} As a runtime option this is equivalent to @code{--noinform} @code{--disable-ldb} @code{--lose-on-corruption} Index: streams.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/streams.texinfo,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- streams.texinfo 11 Nov 2009 18:20:34 -0000 1.6 +++ streams.texinfo 6 Jun 2010 20:43:58 -0000 1.7 @@ -41,7 +41,7 @@ @section External Formats @cindex External formats -@findex stream-external-format +@findex @cl{stream-external-format} The encodings supported by SBCL as external formats are named by keyword. Each encoding has a canonical name, which will be encoding returned by @code{stream-external-format}, and a number of aliases for @@ -49,8 +49,8 @@ @include encodings.texi-temp -@findex open -@findex with-open-file +@findex @cl{open} +@findex @cl{with-open-file} In situations where an external file format designator is required, such as the @code{:external-format} argument in calls to @code{open} or @code{with-open-file}, users may supply the name of an encoding to Index: support-and-bugs.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/support-and-bugs.texinfo,v retrieving revision 1.2 retrieving revision 1.3 diff -u -d -r1.2 -r1.3 --- support-and-bugs.texinfo 28 Mar 2010 17:44:49 -0000 1.2 +++ support-and-bugs.texinfo 6 Jun 2010 20:43:58 -0000 1.3 @@ -57,11 +57,6 @@ feel free to ask for advice on the sbcl-help list. @table @strong -@item Christophe Rhodes -is a long-time SBCL developer, available for custom programming. - -Email: @email{csr21@@cam.ac.uk} - @item Steel Bank Studio Ltd provides commercial SBCL support and custom development, is run by SBCL developer @emph{Nikodemus Siivola}, and has another SBCL @@ -70,6 +65,13 @@ Website: @url{http://sb-studio.net/} Email: @email{info@@sb-studio.net} + +@item Christophe Rhodes +is a researcher and long-time SBCL developer, available for custom +development, particularly in the area of language extension. + +Email: @email{c.rhodes@@gold.ac.uk} + @end table @node Reporting Bugs @@ -126,6 +128,7 @@ @enumerate @item +@cindex ldb Compile sbcl with ldb support (feature @code{:sb-ldb}, see @file{base-target-features.lisp-expr}) and change @code{#define QSHOW_SIGNAL 0} to @code{#define QSHOW_SIGNAL 1} in @file{src/runtime/runtime.h}. @@ -158,6 +161,6 @@ Don't forget to include OS and SBCL version. @item -If available include, information on outcome of the same test with +If available, include information on outcome of the same test with other versions of SBCL, OS, ... @end enumerate Index: texinfo-macros.texinfo =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/manual/texinfo-macros.texinfo,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- texinfo-macros.texinfo 30 Apr 2007 11:26:09 -0000 1.1 +++ texinfo-macros.texinfo 6 Jun 2010 20:43:58 -0000 1.2 @@ -25,3 +25,13 @@ \word\@c @end ifnottex @end macro + +@c Some index prettification helper macros, for tricking the texindex +@c collation "engine" +@macro earmuffs{name} +*\name\* +@end macro +@macro setf{name} +(setf \name\) +@end macro +@include docstrings/package-macros.texinfo |