Experiences of typesetting a book with lout

[Mark Summerfield]

Hi,

The book "C++ GUI Programming with Qt 3" (ISBN 0-13-124072-2) has just
been published in the US (and is available online, at amazon for
example). This book was typeset entirely with lout. (Jeff also wrote a
book typeset with lout of course.)

I co-wrote the book and was responsible for the typesetting, so I
thought I'd share some of my experiences in case anyone else is thinking
of using lout for a book.

- I found that for some things def and macro were insufficient so I
  ended up writing a pre-processor to supplement the defs and macros I
  created.

- I ended up having to copy and modify book (naturally), bookf and dsf.
  I needed to change bookf because I needed several preface-like parts;
  I had to change dsf to allow me to add a @CaptionGap parameter for
  figures, and also to apply a patch that Jeff gave me to give nicer
  hyphenation in index entries. Lout could do with far more options on
  forematter and endmatter, and should offer far more formatting control
  over tables of contents.

- I did not have much success with the @Colophon symbol and ended up
  having to suppy the very last page as a separate file.

- Lout lacks some symbols that I think would be widely welcomed:
  @Sidebar, @Shadow, and @ZeroVertical (which Jeff gave me -- it
  prevents unwanted whitespace at the bottom of diagrams if you put
  nodes after the //).

- Lout doesn't support two-page spreads; I managed a sort-of workaround
  for the one place I needed it.

- Lout doesn't offer a way of flowing text around figures, but I rarely
  needed it and could always fake it using @Tbl, or raw lout.

- From scratch I needed 11 runs (1¼ hours) to produce a final postscript
  file. For any change to the index I needed 2 runs to make it
  effective, and these took a total of 20 minutes. In practice most
  updates just required 2 runs because I kept the *.{li,ld} files.
  During the writing of the book I did not generate the index (thanks to
  the pre-processor), and worked on one chapter at a time, so it was
  fast except in the week before I was due to hand over to the
  publisher.

- I often got messages like this:
  259,79: 0.3c object too high for -0.0c space; will try elsewhere
  Which meant I had to check that the image really had found a place. I
  did not find this a problem in practice.

- The worst part was indexing. Lout expects you to write index entries
  inline in the text justlikethis @Index { Just Like This }, which has
  two drawbacks: firstly it considerably clutters the text, and secondly
  you have to come up with a unique index key for ordering for every
  index term. I solved this using the preprocessor so that I could write
    [[Just Like This]]
  and the preprocessor would do the right thing. (I also had syntax for
  specifying ranges, sub-terms, etc.) The other problem with indexes is
  that they are awfully slow to generate. My suggestions are that lout
  should offer a command line option that switches off index generation
  (for when you just want to check the text), and that it takes a
  different approach to index terms altogether. I think that every
  symbol that handles a 'chunk' of text, e.g. @PP, @LP, @DP, @Figure,
  @Tbl, etc., should offer an optional left parameter (or a named right
  parameter) that contains index terms:

    { # Index terms
        This is a term
        Each term is newline delimited
        Subterms|Subterms are vertical bar delimited
        Subterms|Subsubterms|sub sub terms are similar
        {index_20terms_2C_20braces}Index Terms, braces
    }
    @PP
    This is the para to which the terms apply.
    Index keys are generated automatically by some simple
    canonicalisation process, e.g. letters are lowercased and everything
    else is converted to _HH where HH is the hex number of the character
    -- this gives ASCII ordering, but with braces you can override.

  The disadvantage of this system is that when paragraphs are split over
  a page boundary the page number will be for the beginning of the para,
  yet some of the terms may only occur at the end of the para on the
  following page. In such cases some terms would have to be moved to the
  following para. I think this is a small price to pay -- in practice we
  didn't have that many split paras and they were easy to check.

- Lout's @Tbl and @Diag symbols are superb. I can't draw, yet the book
  has lots of diagrams, every one of which was produced using lout. We
  also used @Graph in a few places, and again this was easy to use and
  did exactly what we wanted. The only .EPS files we imported were for
  screenshots. We put all our diagrams inline; next time we'll probably
  do them in separate files and use @Include.

- Lout's ability to use any installed postscript font was a real help.
  We created a custom Courier font that is horizontally scaled so that
  we could get more characters per line for code snippets, and making
  this font available to lout was easy. (We wrote a small Python script
  for embedding fonts to ensure the publisher didn't have any problems.)

- With the exception of the index, working with lout was straightforward
  and did not intrude upon the writing process. We put each chapter in
  its own file and used @Include in a main file. This made it easy to
  comment out what we weren't working on and to focus just on the
  relevant chapter.

- Lout provides excellent fine control: we created a macro for C++ to
  kern this word exactly as we wanted.

- We wanted bullet lists where the text was indented by @ParaIndent, but
  where the bullets were mid-way between the left margin and the text.
  Again, this was easily achieved using macros.

- In a few places we needed a schematic-type diagram of an application's
  main window, but each of which needed the main area to have different
  contents. This was easily achieved by extending @Diag with our own
  @MainWindowDiag definition.

If you want to write a book, then lout is a good tool to use. Our book
has much more complex typesetting needs than say, a novel, with its
numerous code snippets, diagrams and screenshots, and all of this lout
handles very well. Although lout doesn't offer as many options for
forematter and endmatter as we wanted, we were able to modify bookf to
meet our requirements: just about everything we've wanted to do we've
been able to do, and the book as published is typeset exactly as we
intended. (And yes the bottom margin is too narrow, but that was my
misjudgement, no fault of lout's.) My only caveat is that lout's
indexing system is cumbersome; but in many cases the publisher hires a
professional indexer so the problem won't apply.

In addition to the book, I use lout to produce whitepapers and a
quarterly newsletter. Because lout is plain text with markup it is
really easy to use with version control systems and easy to see changes
that have been made using a diff tool. The user guide is easy to read
and understand and you can learn enough in a couple of hours to start
producing useful documents.

I admire the work that Jeff's put into lout and I'm very glad that I use
it.

-- 
Mark.