While I was reading chapter 8, I was confused by a couple of things. Others might not find them confusing, but I thought it was worth mentioning them.

Section headings that are lisp keywords

I was initially confused by a section heading that was just the word 'Car'. Because of the capitalization, I didn't associate it with the car operation. Could you break the style guide for these, to keep them lower case, or format them as code? (see below for a potentially better suggestion)

list_type is not defined until very late

list_type gets used 15 times before it is actually defined. That was super confusing to me, because I naturally assumed that it must be some non-trivial class type.

It would have been very helpful to know that list_type is just an integer representing an index into the node vector. Members of node_t are referenced a number of times before they are actually defined, too.

I assume the order you've got things is the order that Alex introduces them. But if possible it would be really helpful to see list_type, node_t, pool and free_list defined early on. It seems like they would fit quite naturally into the code block where the list_pool class is introduced:

 #include <vector>
 template<typename T, typename N>
 // T is semi-regular.
 // N is integral
 class list_pool {
 typedef N list_type;
 struct node_t {
 T value;
 N next;
 };
 std::vector<node_t> pool;
 list_type free_list;
 // ...
 };

list_pool methods

On first reading, it wasn't clear to me that value, next, free etc... were actually member functions of list_pool. Partly because I didn't know what list_type was, so they could easily have been free functions.

In my chapter 8 typos PR (#27), I tried to clarify things by replacing this:

Now we are going to implement cons, car, cdr, and free, but we need appropriate names for a younger generation.

with this:

Now we are going to implement cons, car, cdr, and free as member functions of list_pool, but we need appropriate names for a younger generation.

It might help further to adjust the section headings to read like "### Implementing a member function to represent car". That would also serve to solve the header capitalization issue I mentioned above.

rplaca / set-car confusion

I've not really played with lisp, so I'd not come across rplaca and rplacd before. It was confusing to me that the hyperlinks for both of them went to a single thing called 'set-car'. It was only after Googling that I discovered the names were short for 'replace address part' and 'replace decrement part'.

I think it would be really helpful to have a footnote or something explaining that:

• rplac is short for 'replace'
• Lisp and Scheme use different keywords for these operations(???)

Later in the chapter there is a piece of Scheme code that uses set-cdr, but the corresponding Lisp code doesn't use rplacd. I still don't understand that.