[Sbcl-commits] CVS: sbcl version.lisp-expr,1.4889,1.4890

[Christophe R. <cr...@us...>]

Update of /cvsroot/sbcl/sbcl
In directory sfp-cvsdas-3.v30.ch3.sourceforge.com:/tmp/cvs-serv29631

Modified Files:
	version.lisp-expr 
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: version.lisp-expr
===================================================================
RCS file: /cvsroot/sbcl/sbcl/version.lisp-expr,v
retrieving revision 1.4889
retrieving revision 1.4890
diff -u -d -r1.4889 -r1.4890
--- version.lisp-expr	6 Jun 2010 19:53:44 -0000	1.4889
+++ version.lisp-expr	6 Jun 2010 20:43:57 -0000	1.4890
@@ -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".)
-"1.0.39.8"
+"1.0.39.9"