Lisp Outside the Box
                         ====================

                          OUTSTANDING ISSUES

             Nick Levine, Ravenbrook Limited, 2011-05-31

Here is a list of the problems that I'm aware about, concerning the
eleven chapters from my abandoned O'Reilly book "Lisp Outside the Box"
which I have now published. I will be happy to update the list if
further problems are brought to my attention.


1. It might be out of date

I was always standing on rapidly moving ground; some of the libraries
I was writing about were undergoing major changes while I was sat
there trying to write about them. There was no hope of doing anything
about this until closer to publication date and that's now never going
to happen. So please check that the version of the library which
you're using bears any resemblance to the version I wrote about,
before taking what I said about it too seriously.


2. Explicit use-package forms

I prefixed example code in chapters 13-16 (AllegroCache; Persistence;
Memory) with use-package forms, so as to minimise the need for
explicit package qualifiers. I wrote subsequent chapters the other
way. In retrospect, package qualifiers are not a hindrance in the text
and they do make the exposition clearer. So, without implying anything
detrimental about packages using each other in production code, I did
intend that when I got the chance I would switch these four chapters
over to work with explicit package qualifiers throughout.

Thanks to Peter Lindahl and Rusty Johnson for keeping me sharp on this
one.


3. Motivate chapter 13 (AllegroCache)

This needed a little motivational something. "The message of this
chapter is..."


4. Omnipresent typos

Philipp Marek and Ernst van Waning very kindly sent me a gratifying
number of comments, mainly about wording, puncutation and layout. Some
stylistic, others plain mistakes. It's amazing how many times I (and
several other people) can stare at a body of text and not notice the
typos.


5. Poor example in chapter 13 (AllegroCache)

Andreas Fuchs pointed out -- correctly -- that "backing store for a
web server" is a poor example use for standalone AllegroCache
connections (poor MP concurrency).


6. Bordeaux Threads and the chapter 15 (Concurrency)

I should have mentioned Bordeaux Threads and refered to their use in
the mod_lisp examples later in the book.


7. Symmetric Multiprocessing in chapter 15 (Concurrency)

This section needed massive expansion.


8. Screenshots in chapter 19 (SLIME)

The text in the screenshots could be sharper.


9. Dry examples in chapter 19 (SLIME)

Gareth Rees commented that the sections on SLIME's inspect / debug
were rather dry. I'm inclined to agree (certainly about the inspector;
the debugger examples form hints for exercises in another chapter and
so might have some instrinsic value).


10. Defpackage and ASDF in chapter 19

Kevin Reid wrote an interesting blog piece about use of defpackage in
.asd files. I wanted to review some of my own wording in the light
of his comments.


11. Code on website

In chapter 14 (Further AllegroCache) I claimed that the full list
*chapter-13-links* was available on the book's web site. It wasn't
then, but now it is, here:

   https://nicklevine.org/lisp-book/code/chapter-13-links.lisp

In chapters 17 (Image Processing) and 21 (Serving HTTP) I discussed
the workings of applications which would be a nuisance for readers to
type in themselves. These are now available (caveat emptor) here:

   https://nicklevine.org/lisp-book/code/spiralize.lisp
   https://nicklevine.org/lisp-book/code/mod-lisp.lisp


12. Iteration - the lost chapter

This chapter was originally going to include (non exhaustive list):
AllegroCache's support for walking over instances of persistent
classes; and Richard Waters' "series" package. I was looking forward
to having an excuse to finally get my head round that. But I found
while writing 13 that I had about 50% more material than I could fit
into my budget of about 4000 words per chapter. So I took the decision
to drop "Iteration" and merge the AC material for that chapter into
the overflow from 13 to create a new chapter 14 ("Further
Persistence").

This decision was probably a mistake - it was unbalanced to devote two
chapters to a single topic when overall space was under such
contention - and I intended to revisit it at the end of first draft.


13. Process-kill in chapter 15 (Concurrency)

I needed to say: calling process-kill (or in Chapter 21 the bt
equivalent) might interrupt a thread at an inconvenient moment,
leaving structures in an inconsistent state. So use with
caution. (Thanks to Paul Khuong for pointing this out.)


14. Each chapter rendered separately

The PDF you see was generated chapter by chapter. So they each claim
to start at "page 1", and some of the references from one chapter to
another are broken.


15. Other PDF issues

Hyphenation of symbols in code font is plain broken.

Page breaks sometimes strand the last 1-2 lines of a code example on
a different page.


16. Difficulty of exercises

In some but not all of the chapters, the exercises were graded. The
preface which explained the grades never got written, so:

     Lambdas   Interpretation (for novice reader at this stage of the
               book) -- the time should is my guess at an upper bound
               for how long the task should take and you might well
               get there quicker.

        1      Trivial (5 minutes)

        2      Straightforward task (20 minutes)

        3      Some effort required (1 hour)

        4      Tricky (6 hours)

        5      Major project (several days)




-----

$Id: //info.ravenbrook.com/project/olb/master/site/issue/index.txt#10 $