From 01b53542be411ba6ede003da5e7292e16602ab6e Mon Sep 17 00:00:00 2001 From: Nikodemus Siivola Date: Tue, 17 Aug 2004 17:32:11 +0000 Subject: [PATCH] 0.8.13.70: MORE DOCUMENTATION * Include documentation, however sparse, for SB-PROFILE, SB-GRAY, and SB-SIMPLE-STREAMS. * Beginnings of restructuring the manual: lift SB-BSD-SOCKETS into a full chapter called "Networking", etc. * An unfortunate consequence of the above is that we cannot autogenerate the contrib-doc list anymore, and the contrib documentation structure is less otrhogonal and has tighter coupling to the general manual structure. Since new contribs appear relatively seldom this is hopefully not a big issue. --- NEWS | 4 +- contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo | 23 ++-- .../sb-simple-streams/sb-simple-streams.texinfo | 25 +++++ contrib/sb-sprof/sb-sprof.texinfo | 22 ++-- doc/manual/Makefile | 10 +- doc/manual/beyond-ansi.texinfo | 13 +-- doc/manual/compiler.texinfo | 4 - doc/manual/contrib-modules.texinfo | 24 ++++- doc/manual/debugger.texinfo | 3 - doc/manual/efficiency.texinfo | 4 +- doc/manual/ffi.texinfo | 4 - doc/manual/intro.texinfo | 4 - doc/manual/make-tempfiles.sh | 4 - doc/manual/package-locks-basic.texinfo | 4 - doc/manual/package-locks-extended.texinfo | 4 +- doc/manual/profiling.texinfo | 29 +++++ doc/manual/sbcl.texinfo | 111 +++++++++++++++++--- doc/manual/streams.texinfo | 42 ++++++++ version.lisp-expr | 2 +- 19 files changed, 251 insertions(+), 85 deletions(-) create mode 100644 contrib/sb-simple-streams/sb-simple-streams.texinfo create mode 100644 doc/manual/profiling.texinfo create mode 100644 doc/manual/streams.texinfo diff --git a/NEWS b/NEWS index e0ab0cb..126fda9 100644 --- a/NEWS +++ b/NEWS @@ -7,7 +7,9 @@ changes in sbcl-0.8.14 relative to sbcl-0.8.13: * new feature: on platforms where "dladdr" is available foreign function names now appear in backtraces. (based on Helmut Eller's work for CMUCL) - * documentation: networking interface SB-BSD-SOCKETS' documentation + * documentation: documentation for SB-BSD-SOCKETS, SB-GRAY, + SB-SIMPLE-STREAMS, and SB-PROFILE have been integrated into the user + manual. has been integrated into the user manual. * bug fix: SBCL can now load its contributed modules with REQUIRE even if the system-provided entries have been removed from diff --git a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo index c726638..ab8fdd4 100644 --- a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo +++ b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo @@ -1,10 +1,11 @@ -@node sb-bsd-sockets -@section sb-bsd-sockets +@c This currently appears in the manual as a chapter: if a +@c higher-level interface appear, it will make sense to lower this +@c into a section. @cindex Sockets, Networking -The @code{sb-bsd-sockets} module provides a thinly disguised BSD socket -API for SBCL. Ideas stolen from the BSD socket API for C and Graham -Barr's IO::Socket classes for Perl. +The @code{sb-bsd-sockets} module provides a thinly disguised BSD +socket API for SBCL. Ideas have been stolen from the BSD socket API +for C and Graham Barr's IO::Socket classes for Perl. Sockets are represented as CLOS objects, and the API naming conventions attempt to balance between the BSD names and good lisp style. @@ -19,7 +20,7 @@ conventions attempt to balance between the BSD names and good lisp style. @end menu @node Sockets Overview -@subsection Sockets Overview +@section Sockets Overview Most of the functions are modelled on the BSD socket API. BSD sockets are widely supported, portably @emph{(``portable'' by Unix standards, at least)} @@ -50,7 +51,7 @@ than "network-endian integers". @end itemize @node General Sockets -@subsection General Sockets +@section General Sockets @include class-sb-bsd-sockets-socket.texinfo @@ -77,7 +78,7 @@ than "network-endian integers". @include fun-sb-bsd-sockets-non-blocking-mode.texinfo @node Socket Options -@subsection Socket Options +@section Socket Options A subset of socket options are supported, using a fairly general framework which should make it simple to add more as required - see @@ -105,7 +106,7 @@ sockopt-receive-low-water)}. @include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo @node INET Domain Sockets -@subsection INET Domain Sockets +@section INET Domain Sockets The TCP and UDP sockets that you know and love. Some representation issues: @@ -131,7 +132,7 @@ port, so for example, (socket-connect s #(192 168 1 1) 80). @include fun-sb-bsd-sockets-get-protocol-by-name.texinfo @node Local (Unix) Domain Sockets -@subsection Local (Unix) Domain Sockets +@section Local (Unix) Domain Sockets Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain sockets, but were renamed by POSIX presumably on the basis that they @@ -144,7 +145,7 @@ across a network. @include class-sb-bsd-sockets-local-socket.texinfo @node Name Service -@subsection Name Service +@section Name Service Presently name service is implemented by calling whatever @code{gethostbyname(2)} uses. This may be any or all of diff --git a/contrib/sb-simple-streams/sb-simple-streams.texinfo b/contrib/sb-simple-streams/sb-simple-streams.texinfo new file mode 100644 index 0000000..59db0af --- /dev/null +++ b/contrib/sb-simple-streams/sb-simple-streams.texinfo @@ -0,0 +1,25 @@ +Simple streams are an extensible streams protocol that avoids some +problems with Gray streams. + +Documentation about simple streams is available at: + +@uref{http://www.franz.com/support/documentation/6.2/doc/streams.htm} + +The implementation should be considered Alpha-quality; the basic +framework is there, but many classes are just stubs at the moment. + +See @file{SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP} for +things that should work. + +Known differences to the ACL behaviour: + +@itemize + +@item +@code{open} not return a simple-stream by default. This can be +adjusted; see default-open-class in the file cl.lisp + +@item +@code{write-vector} is unimplemented. + +@end itemize diff --git a/contrib/sb-sprof/sb-sprof.texinfo b/contrib/sb-sprof/sb-sprof.texinfo index 063514a..b487b79 100644 --- a/contrib/sb-sprof/sb-sprof.texinfo +++ b/contrib/sb-sprof/sb-sprof.texinfo @@ -1,13 +1,15 @@ -@node sb-sprof -@section sb-sprof -@cindex Profiler - -The @code{sb-sprof} module provides an alternate profiler which works by -taking samples of the program execution at regular intervals, instead of -instrumenting functions like @code{profile} does. You might find -@code{sb-sprof} more useful than @code{profile} when profiling functions -in the @code{common-lisp}-package, SBCL internals, or code where the -instrumenting overhead is excessive. +@cindex Profiling, statistical + +The @code{sb-sprof} module, loadable by +@lisp +(require :sb-sprof) +@end lisp +provides an alternate profiler which works by taking samples of the +program execution at regular intervals, instead of instrumenting +functions like @code{sb-profile:profile} does. You might find +@code{sb-sprof} more useful than accurate profiler when profiling +functions in the @code{common-lisp}-package, SBCL internals, or code +where the instrumenting overhead is excessive. This module is known not to work consistently on the Alpha platform, for technical reasons related to the implementation of a machine diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 5251918..d74b422 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -1,4 +1,3 @@ - DOCFILES:=$(shell echo *.texinfo) ROOTFILE:=sbcl.texinfo TMPFILES:=sbcl.aux sbcl.cp sbcl.fn sbcl.ky sbcl.log sbcl.pg sbcl.toc sbcl.tp sbcl.vr @@ -13,6 +12,7 @@ HTMLDIR=$(basename $(ROOTFILE)) # DOCSTRINGDIR has to end with a slash or you lose (it's passed to # Lisp's `pathname' function). DOCSTRINGDIR="docstrings/" +I_FLAGS=-I $(DOCSTRINGDIR) -I ../../contrib/ # List of contrib modules that docstring docs will be created for. # FIXME: should check test-passed and not load them. MODULES=':sb-md5 :sb-rotate-byte :sb-grovel :sb-sprof :sb-bsd-sockets' @@ -47,7 +47,7 @@ html: html-stamp html-stamp: variables $(DOCFILES) docstrings @rm -rf $(HTMLDIR) - $(MAKEINFO) -I $(DOCSTRINGDIR) --html $(ROOTFILE) + $(MAKEINFO) $(I_FLAGS) --html $(ROOTFILE) touch html-stamp # Postscript documentation @@ -58,21 +58,21 @@ $(PSFILE): $(DVIFILE) dvips -o $@ $< $(DVIFILE): variables $(DOCFILES) docstrings - texi2dvi -I $(DOCSTRINGDIR) $(ROOTFILE) + texi2dvi $(I_FLAGS) $(ROOTFILE) # PDF documentation .PHONY: pdf pdf: $(PDFFILE) $(PDFFILE): variables $(DOCFILES) docstrings - texi2pdf -I $(DOCSTRINGDIR) $(ROOTFILE) + texi2pdf $(I_FLAGS) $(ROOTFILE) # info docfiles .PHONY: info info: $(INFOFILE) $(INFOFILE): variables $(DOCFILES) docstrings - $(MAKEINFO) -I $(DOCSTRINGDIR) $(ROOTFILE) + $(MAKEINFO) $(I_FLAGS) $(ROOTFILE) # contrib-modules.texinfo includes contrib-doc-list.texi-temp contrib-modules.texinfo: tempfiles-stamp diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 2fb97ab..848fb48 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -1,7 +1,3 @@ -@node Beyond The ANSI Standard -@comment node-name, next, previous, up -@chapter Beyond The ANSI Standard - SBCL is mostly an implementation of the ANSI standard for Common Lisp. However, there's some important behavior which extends or clarifies the standard, and various behavior which outright @@ -38,7 +34,7 @@ implementation. Declarations are generally treated as assertions. This general principle, and its implications, and the bugs which still keep the compiler from quite satisfying this principle, are discussed in -@ref{The Compiler}. +@ref{Compiler}. SBCL is essentially a compiler-only implementation of Common Lisp. That is, for all but a few special cases, @code{eval} creates a @@ -130,8 +126,8 @@ it still has quite a few. @xref{Contributed Modules}. @comment node-name, next, previous, up @subsection Things Which Might Be In The Next ANSI Standard -SBCL provides extensive support for calling external C code, @ref{The -Foreign Function Interface}. +SBCL provides extensive support for calling external C code, +@ref{Foreign Function Interface}. SBCL provides additional garbage collection functionality not specified by ANSI. Weak pointers allow references to objects to be @@ -417,8 +413,7 @@ 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. @xref{The -Debugger}. +accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}. Documentation for @code{inspect} is accessed by typing @kbd{help} at the @code{inspect} prompt. diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo index fa0205c..b1062b5 100644 --- a/doc/manual/compiler.texinfo +++ b/doc/manual/compiler.texinfo @@ -1,7 +1,3 @@ -@node The Compiler -@comment node-name, next, previous, up -@chapter The Compiler - This chapter will discuss most compiler issues other than efficiency, including compiler error messages, the SBCL compiler's unusual approach to type safety in the presence of type declarations, diff --git a/doc/manual/contrib-modules.texinfo b/doc/manual/contrib-modules.texinfo index 308690e..35fba4b 100644 --- a/doc/manual/contrib-modules.texinfo +++ b/doc/manual/contrib-modules.texinfo @@ -1,11 +1,25 @@ -@node Contributed Modules -@comment node-name, next, previous, up -@chapter Contributed Modules - SBCL comes with a number of modules that are not part of the core system. These are loaded via @code{(require :@var{modulename})} (@pxref{Customization Hooks for Users}). This section contains documentation (or pointers to documentation) for the contributed modules. -@include contrib-doc-list.texi-temp +@menu +* sb-aclrepl:: +* sb-grovel:: +* sb-md5:: +* sb-rotate-byte:: +@end menu + +@page +@include sb-aclrepl/sb-aclrepl.texinfo + +@page +@include sb-grovel/sb-grovel.texinfo + +@page +@include sb-md5/sb-md5.texinfo + +@page +@include sb-rotate-byte/sb-rotate-byte.texinfo + diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 493471c..86f6ad2 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -1,6 +1,3 @@ -@node The Debugger -@comment node-name, next, previous, up -@chapter The Debugger @cindex Debugger The SBCL debugger (as the CMUCL debugger it was derived from) has very diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo index 16c3c65..ebd4a36 100644 --- a/doc/manual/efficiency.texinfo +++ b/doc/manual/efficiency.texinfo @@ -1,6 +1,4 @@ -@node Efficiency -@comment node-name, next, previous, up -@chapter Efficiency +@cindex Efficiency FIXME: The material in the CMUCL manual about getting good performance from the compiler should be reviewed, reformatted in diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo index a784b67..5f365d9 100644 --- a/doc/manual/ffi.texinfo +++ b/doc/manual/ffi.texinfo @@ -1,7 +1,3 @@ -@node The Foreign Function Interface -@comment node-name, next, previous, up -@chapter The Foreign Function Interface - This chapter describes SBCL's interface to C programs and libraries (and, since C interfaces are a sort of @emph{ingua franca} of the Unix world, to other programs and libraries in diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 6ad18eb..2c1ed8b 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -1,7 +1,3 @@ -@node Introduction -@comment node-name, next, previous, up -@chapter Introduction - SBCL is a mostly-conforming implementation of the ANSI Common Lisp standard. This manual focuses on behavior which is specific to SBCL, not on behavior which is common to all implementations of ANSI Common diff --git a/doc/manual/make-tempfiles.sh b/doc/manual/make-tempfiles.sh index baa7f65..c0ce125 100644 --- a/doc/manual/make-tempfiles.sh +++ b/doc/manual/make-tempfiles.sh @@ -1,7 +1,6 @@ #!/bin/sh # Create Texinfo snippets from the documentation of exported symbols. -# Also create contrib-docs.texi-temp to include documentation in contrib/. # This software is part of the SBCL system. See the README file for # more information. @@ -42,9 +41,6 @@ DOCSTRINGDIR="${DOCSTRINGDIR:-docstrings/}" 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 -echo /creating contrib-docs.texi-temp -echo "(load \"create-contrib-doc-list.lisp\")" | $SBCL - 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)))"; then diff --git a/doc/manual/package-locks-basic.texinfo b/doc/manual/package-locks-basic.texinfo index a4740b6..9470edc 100644 --- a/doc/manual/package-locks-basic.texinfo +++ b/doc/manual/package-locks-basic.texinfo @@ -1,7 +1,3 @@ -@node Package Locks -@comment node-name, next, previous, up -@chapter Package Locks - SBCL can be built with support for package locks to protect against unintentional modifications of packages. The full documentation for package locks is only built if package locks are enabled in the image diff --git a/doc/manual/package-locks-extended.texinfo b/doc/manual/package-locks-extended.texinfo index b950dc8..18fdece 100644 --- a/doc/manual/package-locks-extended.texinfo +++ b/doc/manual/package-locks-extended.texinfo @@ -1,6 +1,4 @@ -@node Package Locks -@comment node-name, next, previous, up -@chapter Package Locks +@cindex Packages, locked None of the following sections apply to SBCL built without package locksing support. diff --git a/doc/manual/profiling.texinfo b/doc/manual/profiling.texinfo new file mode 100644 index 0000000..d793d53 --- /dev/null +++ b/doc/manual/profiling.texinfo @@ -0,0 +1,29 @@ +@cindex Profiling + +SBCL includes both an accurate profiler, that can collect statistics +on individual functions, and a more ``modern'' statistical profiler. + +Inlined functions do not appear in the results reported by either. + +@menu +* Accurate Profiler:: +* Statistical Profiler:: +@end menu + +@node Accurate Profiler +@comment node-name, next, previous, up +@section Accurate Profiler +@cindex Profiling, accurate + +The package @code{sb-profile} provides a classic, per-function-call +profiler. + +@include macro-sb-profile-profile.texinfo +@include macro-sb-profile-unprofile.texinfo +@include fun-sb-profile-report.texinfo +@include fun-sb-profile-reset.texinfo + +@node Statistical Profiler +@comment node-name, next, previous, up +@section Statistical Profiler +@include sb-sprof/sb-sprof.texinfo diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo index bcc05cd..b144e8a 100644 --- a/doc/manual/sbcl.texinfo +++ b/doc/manual/sbcl.texinfo @@ -56,31 +56,114 @@ provided with absolutely no warranty. See the @file{COPYING} and @insertcopying @menu -* Introduction:: -* The Compiler:: -* The Debugger:: -* Efficiency:: -* Beyond The ANSI Standard:: -* The Foreign Function Interface:: -* Package Locks:: -* Contributed Modules:: -* Concept Index:: -* Function Index:: -* Variable Index:: -* Type Index:: -* Colophon:: +* Introduction:: +* Compiler:: +* Debugger:: +* Efficiency:: +* Beyond the ANSI Standard:: +* Foreign Function Interface:: +* Extensible Streams:: +* Package Locks:: +* Networking:: +* Profiling:: +* Contributed Modules:: +* Concept Index:: +* Function Index:: +* Variable Index:: +* Type Index:: +* Colophon:: @end menu @end ifnottex +@node Introduction +@comment node-name, next, previous, up +@chapter Introduction @include intro.texinfo + +@node Compiler +@comment node-name, next, previous, up +@chapter Compiler @include compiler.texinfo + +@node Debugger +@comment node-name, next, previous, up +@chapter Debugger @include debugger.texinfo + +@node Efficiency +@comment node-name, next, previous, up +@chapter Efficiency @include efficiency.texinfo + +@node Beyond the ANSI Standard +@comment node-name, next, previous, up +@chapter Beyond the ANSI Standard @include beyond-ansi.texinfo + +@node Foreign Function Interface +@comment node-name, next, previous, up +@chapter Foreign Function Interface @include ffi.texinfo + +@node Extensible Streams +@comment node-name, next, previous, up +@chapter Extensible Streams +@include streams.texinfo + +@node Package Locks +@comment node-name, next, previous, up +@chapter Package Locks @include package-locks.texi-temp + +@node Networking +@comment node-name, next, previous, up +@chapter Networking +@include sb-bsd-sockets/sb-bsd-sockets.texinfo + +@node Profiling +@comment node-name, next, previous, up +@chapter Profiling +@include profiling.texinfo + +@node Contributed Modules +@comment node-name, next, previous, up +@chapter Contributed Modules @include contrib-modules.texinfo -@include backmatter.texinfo + +@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 Variable Index +@comment node-name, next, previous, up +@appendix Variable Index +@printindex vr + +@node Type Index +@comment node-name, next, previous, up +@appendix Type Index +@printindex tp + +@node Colophon +@comment node-name, next, previous, up +@unnumbered Colophon + +This manual is maintained in Texinfo, and automatically translated +into other forms (e.g. HTML or pdf). If you're @emph{reading} this +manual in one of these non-Texinfo translated forms, that's fine, but +if you want to @emph{modify} this manual, you are strongly advised to +seek out a Texinfo version and modify that instead of modifying a +translated version. Even better might be to seek out @emph{the} +Texinfo version (maintained at the time of this writing as part of the +SBCL project at @uref{http://sbcl.sourceforge.net/}) and submit a +patch. + @bye diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo new file mode 100644 index 0000000..1cd0595 --- /dev/null +++ b/doc/manual/streams.texinfo @@ -0,0 +1,42 @@ +SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose +instances can be used as Lisp streams (e.g. passed as the first +argument to @code{format}). Additionally, the bundled contrib module +@dfn{sb-simple-streams} implements a subset of the Franz Allegro +simple-streams proposal. + +@menu +* Gray Streams:: +* Simple Streams:: +@end menu + +@node Gray Streams +@section Gray Streams + +@include class-sb-gray-fundamental-stream.texinfo +@include fun-sb-gray-stream-advance-to-column.texinfo +@include fun-sb-gray-stream-clear-input.texinfo +@include fun-sb-gray-stream-clear-output.texinfo +@include fun-sb-gray-stream-finish-output.texinfo +@include fun-sb-gray-stream-force-output.texinfo +@include fun-sb-gray-stream-fresh-line.texinfo +@include fun-sb-gray-stream-line-column.texinfo +@include fun-sb-gray-stream-line-length.texinfo +@include fun-sb-gray-stream-listen.texinfo +@include fun-sb-gray-stream-peek-char.texinfo +@include fun-sb-gray-stream-read-byte.texinfo +@include fun-sb-gray-stream-read-char-no-hang.texinfo +@include fun-sb-gray-stream-read-char.texinfo +@include fun-sb-gray-stream-read-line.texinfo +@include fun-sb-gray-stream-read-sequence.texinfo +@include fun-sb-gray-stream-start-line-p.texinfo +@include fun-sb-gray-stream-terpri.texinfo +@include fun-sb-gray-stream-unread-char.texinfo +@include fun-sb-gray-stream-write-byte.texinfo +@include fun-sb-gray-stream-write-char.texinfo +@include fun-sb-gray-stream-write-sequence.texinfo +@include fun-sb-gray-stream-write-string.texinfo + +@node Simple Streams +@comment node-name, next, previous, up +@section Simple Streams +@include sb-simple-streams/sb-simple-streams.texinfo diff --git a/version.lisp-expr b/version.lisp-expr index 5932698..654d79c 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.13.69" +"0.8.13.70" -- 1.7.10.4