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

                          OUTSTANDING ISSUES

             Nick Levine, Ravenbrook Limited, 2009-12-04


The purpose of this document is to list outstanding issues with
pre-print extracts from my forthcoming O'Reilly book "Lisp Outside the
Box". It covers chapters 13-16 which were released for public review
in September 2009 and chapters 17-20 which were released in
December. I will try to update this document regularly.

Further feedback is most welcome, either in private by email or in
public by responding to the blog entries which announced individual
chapters.

Links for my email address, the blog, and the current list of
pre-print chapters will be found at <http://lisp-book.org/contents/>.

Explanations of the status against each issue:

    Notified - somebody reckons this is a problem; either I have yet
    to to decide whether I agree, or I have yet to decide whether I
    intend to do anything about it.

    Accepted - I acknowledge that this needs fixing and intend to get
    around to it soon.

    Postponed - I acknowledge that this needs fixing and will deal
    with it when I review the whole book at the end of first draft. I
    imagine most issues will end up with this tag. I don't want to
    keep revisiting chapters which I've mentally filed as "written";
    it's a psychological block on progress and the proofreading
    overhead is high.

    Addressed - corrected in my xml sources; updates to the publicly
    visible HTML are infrequent so you may not see the fix for a
    while.

    Fixed (with a date) - believed fixed in html pre-prints subsequent
    to this date.

    Rejected - I've been asked to change this but am not intending to
    do so.


0. Postponed All chapters

I'm aware that I'm standing on rapidly moving ground; some of the
libraries I'm writing about are undergoing major changes while I'm sat
here trying to write about them. No hope of doing anything about this
until closer to publication date.


1. Postponed Chapters 13-16

I prefixed example code in these chapters with use-package forms, so
as to minimise the need for explicit package qualifiers. I have been
writing 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 will 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.


2. Postponed Chapter 13

Needs a motivational something. "The message of this chapter is..."


3. Postponed Chapters 13-20

Philipp Marek and Ernst van Waning have 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.


4. Postponed Chapter 13

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


5. Postponed Chapter 15

Must mention Bordeaux Threads and refer to their use in the mod_lisp
examples later in the book.


6. Postponed Chapter 15

Expand SMP section.


7. Fixed 2009-12-05 Chapter 15

Peter Seibel wrote to remind me that (citing the ANSI spec.) "it is
implementation-dependent whether dotimes establishes a new binding of
var on each iteration or whether it establishes a binding for var once
at the beginning and then assigns it on any subsequent iterations."


8. Notified Chapter 18

The text in the screenshots could be sharper. Maybe I should find the
time to take them all again.


9. Notified Chapter 18

Gareth Rees comments that the sections on SLIME's inspect / debug are
rather dry. I'm inclined to agree (certainly about the inspector; the
debugger examples form hints for another chapter and might have some
instrinsic value). In any case, time and space are short and I'm
unsure how to proceed. I think I'd like to see a good driving example
(one that fits into the rest of the book) before attempting a complex
change.


10. Notified Chapter 19

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


11. Accepted Chapters 14, 17, 21

In chapter 14 I claim that the full list *chapter-13-links* is
available on the book's web site. In chapters 17 and 21 I discuss the
workings of applications which would be a nuisance for readers to type
in themselves.


12. Notified Chapter 14

This chapter was 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 may have been a mistake - it's unbalanced to devote two
chapters to a single topic when overall space is under such contention
- and I intend to revisit it at the end of first draft. I'll be guided
then by how badly other chapters have overflowed.


13. Postponed Chapter 15

Need 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.)


-----

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