Some confusing things in Chapter 8

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.

justinmeiners / efficient-programming-with-components