The Universe of Discourse

Typographic conventions in computer books

Buy Perl Medic from Bookshop.org (with kickback) (without kickback)

Buy Perl Debugged from Bookshop.org (with kickback) (without kickback)

I don't remember what (if any) conclusion Peter drew from this, but I was struck by it, because I had been thinking about that myself for a couple of days. Really, what is this section for? Does anyone really need it? Here, for example, is the corresponding section from Mastering Algorithms with Perl, because it is the first book I pulled off my shelf:

Conventions Used in This Book

Italic

Used for filenames, directory names, URLs, and occasional emphasis.

Constant width

Used for elements of programming languages, text manipulated by programs, code examples, and output.

Constant width bold

Used for use input and for emphasis in code

Constant width italic

Used for replaceable values

Several questions came to my mind as I transcribed that, even though it was 4 AM.

First, does anyone really read this section and pay attention to it, making a careful note that italic font is used for filenames, directory names, URLs, and occasional emphasis? Does anyone, reading the book, and encountering italic text, say to themselves "I wonder what the funny font is about? Oh! I remember that note in the preface that italic font would be used for filenames, directory names, URLs, and occasional emphasis. I guess this must be one of those."

Second, does anyone really need such an explanation? Wouldn't absolutely everyone be able to identify filenames, directory names, URLs, and occasonal emphasis, since these are in italics, without the explicit directions?

I wonder, if anyone really needed these instructions, wouldn't they be confused by the reference to "constant-width italic", which isn't italic at all? (It's slanted, not italic.)

Even if someone needs to be told that constant-width fonts are used for code, do they really need to be told that constant-width bold fonts are used for emphasis in code? If so, shouldn't they also be told that bold roman fonts are used for emphasis in running text?

Buy Common Lisp: The Language from Bookshop.org (with kickback) (without kickback)

Some books, like Common Lisp: The Language, have extensive introductions explaining their complex notational conventions. For example, pages 4--11 include the following notices:

The symbol "⇒" is used in examples to indicate evaluation. For example,

        (+ 4 5) ⇒ 9

means "the result of evaluating the code (+ 4 5) is (or would be, or would have been) 9."

The symbol "→" is used in examples to indicate macro expansions. ...

Explanation of this sort of unusual notation does seem to me to be valuable. But really the explanations in most computer books make me think of long-playing record albums that have a recorded voice at the end of the first side that instructs the listener "Now turn the record over and listen to the other side."

Buy Higher-Order Perl from Bookshop.org (with kickback) (without kickback)

I don't think omitted this section from HOP on purpose; it simply never occurred to me to put one in. Had MK asked me about it, I don't know what I would have said; they didn't ask.

HOP does have at least one unusual typographic convention: when two versions of the same code are shown, the code in the second version that was modified or changed has been set in boldface. I had been wondering for a couple of weeks before OSCON if I had actually explained that; after running into Peter I finally remembed to check. The answer: no, there is no explanation. And I don't think it's a common convention.

But of all the people who have seen it, including a bunch of official technical reviewers, a few hundred casual readers on the mailing list, and now a few thousand customers, nobody suggested than an explanation was needed, and nobody has reported being puzzled. People seem to understand it right away.

I don't know what to conclude from this yet, although I suspect it will be something like:

(a) the typographic conventions in typical computer books are sufficiently well-established, sufficiently obvious, or both, that you don't have to bother explaining them unles they're really bizarre,

or:

(b) readers are smarter and more resilient than a lot of people give them credit for.

Explanation (b) reminds me of a related topic, which is that conference tutorial attendees are smarter and more resilient than a lot of conference tutorial speakers give them credit for. I suppose that is a topic for a future blog entry.

(Consensus on my mailing list, where this was originally posted, was that the ubiquitous explanations of typographic conventions are not useful. Of course, people for whom they would have been useful were unlikely to be subscribers to my mailing list, so I'm not sure we can conclude anything useful from this.)

[Other articles in category /book] permanent link