• Print

Best of TOC Collection Now Available as Free Ebook Bundle

Hit a glitch with the cover image, but the full ebook bundle (PDF, EPUB, and Kindle-compatible Mobipocket) is now posted for the Best of TOC collection (details on the content here). They’re also shutting the Espresso machine down within the hour, so you can still try to grab a print one while/if they’re available (no promises, sorry).

tags: , , , ,
  • bowerbird

    very cool to release it at no cost.

    that way, we can use this as content on which dialog will be held,
    a discussion that will focus on the utility of various file-formats,
    functionality needs in viewer-apps, and whatever else pops up…

    to facilitate the discussion, may i post the page-images online?

    i’ll be ready to join (or start) dialog on monday, february 16th…

    would you o’reilly people like to hold the discussion _here_?
    or on some forum or wiki on your site? or should i set it up?

    -bowerbird

  • bowerbird

    o’reilly “mantra” — in this book’s introduction — says:
    > “fail forward fast”

    ok, let’s talk… :+)

    that’s a good motto. let’s see how you’re living up to it…

    we’ll talk about “forward” first. you _are_ moving forward.

    this “best of toc” book was definitely a step forward, and
    you should feel good, and be congratulated, for doing it…

    even if it’s just a self-promotional vehicle (and largely it is),
    that’s beside the point. you up and did it, and that’s good.

    so, congratulations! nice step! good for you! :+)

    that’s the good news.

    ***

    the bad news is that this certainly isn’t “fast”. you might be
    ahead of the slowest of the turtles — i.e., all the rest of the
    world of major publishing — but that ain’t sayin’ very much.

    i was programming my e-books well over 20 years ago, and
    i was spitting books out of my laser-printer — on demand –
    15 years ago. _that_ was fast. today it’s hardly newsworthy.

    so you’re not “fast”. definitely _not_ fast…

    but hey, i ain’t critical. to the blind, a one-eyed man is king.
    so ride herd on your pack of turtles and get them _moving_…

    ***

    so we’ve covered the good and the bad. and now for the ugly:
    the “fail” word in your motto. have you failed with this e-book?

    maybe. maybe not. let’s talk about it…

    but since we’ve already said you’re going _forward_, remember
    that that will help offset things if we judge that you’ve “failed”.
    and — as implied — you can always learn from the experience.

    since you present yourselves as something of “beginners” here,
    it’s probably necessary to remind people that o’reilly _is_ really
    one of the major tech publishers around, and that o’reilly _is_
    seen as a “leader” of today’s publishing, and since o’reilly does
    take pride in “eating its own dogfood”, this really should _not_
    be a novel exercise for you… we might decide that we _could_
    expect more from you, considering what i’ve just mentioned,
    and i certainly don’t think that that would be “unreasonable”…

    but hey, i’m willing to cut you a break, give you beginner slack.

    ***

    as i said, we’ll judge you in the end as to if this is a “success”,
    or whether you did indeed “fail”.

    but here at the outset, let’s see how you yourself would judge it.

    do you think you did a good job? created an effective e-book?

    are you happy with it? are there some things that you’d change?

    you mention — in the introduction — that you learned lessons
    from the experience of doing the links in the way that you did
    – as footnotes. so how would you do such links in the future?

    and what other things would you try to do differently, and how?

    would you step through the book with a page-by-page critique?
    (i’ll do just that later this week. but it’ll be best if you do it first.)

    i expect that you got a bunch of feedback at your conference,
    and you put some thought into an analysis of the experiment,
    so i’d think you could come up with a good list of items already.

    and of course, this will impact your thinking in the long-term…

    but now, in the short-run right after, what are your thoughts?

    -bowerbird

  • http://toc.oreilly.com/mac-slocum Mac Slocum

    Since you asked ;)

    > do you think you did a good job? created an effective e-book?

    Put simply: “Nope.”

    I think we did a good job working internally to make this happen. To me, that’s the win, because it informs other projects and helps move things from the theoretical to the practical. That is what I care about.

    The content in the book was written for, and posted in, its correct form: the Web. The aggregated ebook simply doesn’t give me the same sense of cohesion. It’s a nice promotional piece and it’s a nice way to show the value of curation, but the actual item — this booky thing — doesn’t represent the real value (to me, that is … I’m sure other folks have different perspectives.)

    In terms of the book itself — I don’t love it. I love the *content* in it, I love the effort that went into it, I love the collaboration, the process and the enthusiasm around it. But porting blog entries and essays that were built for a Web format into a “book” format doesn’t work for me. But I’m a Web-centric kinda guy. I like my content open, agile, and highly linkable. When I write, I need the ability to weave material directly into the text via hyperlinks, not footnotes or comments or add-ons or whatever doo-dad we come up with. Links are beautiful things, and when I can’t have them, I get cranky.

    > are you happy with it? are there some things that you’d change?

    Things I’d change:

    1. Create two versions, on-demand: the ebook version will include embedded hyperlinks. Any POD-based version will include footnotes.

    2. Recognition that the footnotes are a courtesy: Let’s face it, no one is going to put down their print copy of this thing and type in a long URL just so they can see the referenced story. I don’t mind including footnotes in a print edition, but the real “utility” only comes from *embedded* links.

    3. More collaboration: I’d prefer to see a 50/50 split between TOC material and material from outside contributors (and it’s my fault it didn’t work out that way — next time, we’ll do better). I’d also like to put out a separate product that includes *only* material from outside contributors — and then distribute this at BEA, IDPF, and every other event simply because good thinking needs to be spread far and wide (and people are suckers for thoughts that pop up in “books”).

    4. Put the Web-based version first: The aggregated material should exist *first* as a mini-site or section and *second* as an aggregated book. Not the other way around.

    5. Editions, editions, editions: Based on feedback and some additional needs, we’re already prepping a second edition of Best of TOC that will be released in the next week or so. Our workflow makes this a snap — and *that* is why I see the behind-the-scenes process as the victory — but the entire notion of “one final book to rule them all” doesn’t work for me. Again, I’m a Web guy, so I expect updates and add-ons, corrections, new versions, etc.

    I’m sure there’s more, so I’ll post when they occur to me.

  • bowerbird

    mac-

    that’s a very good start, a good analysis… :+)

    especially if you’re going to make a second edition,
    it’d be good to do the page-by-page walkthrough.

    or, if that’s it from you, i’ll just do my walkthrough.

    also, i’ve created my version of the book. do i have
    permission to make my version publicly available?
    (if you’d like to see it first, i’d be happy to send it.)

    in the absence of permission, i’ll scramble the text
    – i replace lowercase vowels with another vowel –
    and release it that way. that is what i will do with
    my version of your “iphone missing manual” book,
    since that’s still a money-making entity for o’reilly.

    but since you give away the “toc” book for nothing,
    i’d think you won’t object if i release the text as is,
    especially since the words are already on the web.

    -bowerbird

  • http://toc.oreilly.com/mac-slocum Mac Slocum

    @Bowerbird: You’re welcome to use the O’Reilly material within Best of TOC (anything with the source url: http://toc.oreilly.com …), but posts from external contributors shouldn’t be included because that wasn’t part of their agreements.

  • http://toc.oreilly.com Andrew Savikas

    @bowerbird: To be explicit — I’m fine with you taking the content of the O’Reilly posts contained in that book and spinning them up into your own format, as long as all attribution remains intact, and you include a link back to the original post.

    The rights we cleared from the contributors do not extend to this kind of derivative work, so if you want to include any of those, you’ll need to contact those authors directly.

  • bowerbird

    thanks guys. no problem. i’ll just scramble all of the text.
    no sense in getting anyone’s knickers in a bunch… :+)

    i’ll make it available tomorrow, give you guys a chance to
    do a page-by-page walkthrough yourselves, if you want.

    -bowerbird

  • bowerbird

    no page-by-page walkthrough from you guys?

    ok, i’ll have to do it myself.

    since it will be concentrated on stuff that i think
    you should _change_, most of this will be focused
    on negatives, but it will be constructive criticism…

    however, i will stick to points that a good majority
    of book typographers would agree on, and ignore
    things that are, more or less, “a matter of opinion”.

    (although i suppose people might disagree about
    exactly what constitutes “a matter of opinion” here.)

    for the walkthrough, i will use the .pdf, since that
    probably comes closest to representing the book
    as you envision it. and i’m guessing the .pdf was
    used to create the p.o.d. copies from the espresso.
    after the walkthrough, i’ll contrast .pdf and .epub…

    to trumpet a positive aspect before i begin, though,
    i will note that your .pdf had a pagesize of 5.5*8.5.

    that’s the right size. it indicates you were thinking
    of the book _as_ a book (probably due to espresso),
    and not as something that existed on 8.5*11 paper.

    the 8.5*11 thoughtless choice is the biggest problem
    – and not just the biggest, but the most common –
    with most .pdf files, since it automatically gives you
    badly-fitting portrait pages on a landscape monitor.

    a 5.5*8.5 pagesize, on the other hand, means that
    a _facing-pages_ view fits on a landscape screen –
    the pages are portrait, but the spread is landscape –
    with type still big enough for most people to read…

    so it ends up that this one little choice — pagesize –
    ends up exerting a _huge_ increase in the readability
    of any resultant .pdf. this good choice that you made
    will help offset much of the criticism you’ll hear later.
    well, _some_ of it, anyway… :+)

    -bowerbird

  • bowerbird

    ok, here we go…

    first let’s talk about your book-wide settings…

    your most curious choice was to do ragged-right.
    the vast majority of book-typographers will choke
    on that choice. full-justification is their only mode.

    i’m unsure justification is a slam-dunk decision —
    my slight preference is ragged-right, myself, and
    i’m very glad e-book apps give people a choice –
    but i can’t think of many good reasons to fight it…

    so that’s the first thing i think you should change.

    in light of your choice to forego full-justification,
    however, your following decision was just baffling.
    you used hyphenation. the _only_ good reason to
    turn on hyphenation is to prevent loose lines that
    are caused by full-justification. if you don’t justify,
    you should _never_ hyphenate. it makes no sense.

    hyphenation is _especially_ bad inside of e-books,
    because many e-book applications are not able to
    “work around” the hyphenation while doing search.
    if you break search, you break a big e-book asset.
    hyphenation also results in unnecessary problems
    whenever your users copy text out of the e-book.

    the p-book-typographers might disagree, but we
    _do_ have good reasons to fight them on this one,
    so, in an e-book, you should turn off hyphenation.

    i always turn it off, even in books meant for print,
    so linebreaks in the p-book will match the e-book.

    now, as you can tell from what i just said, you can get
    loose lines when you full-justify without hyphenating.
    that’s regrettable, but i think it’s the right thing to do.

    compared to bad search problems, loose lines aren’t
    all that serious. moreover, it’s possible to minimize
    the occurrence of loose lines with clever engineering.
    (more on that later.)

    in sum, i’d suggest you turn _on_ full-justification
    and turn _off_ hyphenation, and see how it looks…
    if you do actually have a problem with loose lines,
    go ragged-right. but either way, ditch hyphenation.

    -bowerbird

  • bowerbird

    the notes from my walkthrough are
    rather cryptic, so i’ll see if i feel like
    writing them more fully this weekend.

    here are more “general tone” notes…

    ***

    typographers will cheer because you
    indented the paragraphs, rather than
    doing them “block-style”, i.e., with an
    empty line between the paragraphs…

    i don’t mind block-style myself, but
    it’s certainly true that indents make
    a product that “looks like” a book,
    and block-style definitely does not.

    so we’ll have to go with that choice.

    (unless you felt like making a stand…
    but since you already choose indents,
    i expect that you won’t be changing.)

    ***

    but typographers would _not_ cheer
    that you went with a sans-serif font.

    book typography — and indeed most
    print typography — wants serif fonts
    for body-text, because some studies
    (badly done, and from 117 years ago)
    showed serif fonts are more readable.

    i strongly prefer the sans-serif look,
    – to me, it’s a cleaner appearance –
    so maybe this is just my preference,
    but i say we do a challenge on this…

    i’m in favor of your sans-serif choice,
    and i think you should stick with it…

    that said, i feel your _particular_ font
    is too skinny to be readable in a .pdf.
    it might look fine on the printed page,
    but it just doesn’t work in your .pdf.

    so i’d switch to another sans-serif…

    that’s all i’m gonna say about fonts.

    (if you know how much _attention_
    fonts receive from the typographers,
    you will thank me for being so brief.)

    ***

    page-numbering is a sticky thicket…

    book-makers have traditionally used
    two sets of numbers in each book –
    roman numbers for the front-matter,
    and then arabic numbers in the body.

    somehow, when adobe created .pdf,
    they weren’t thinking of _books_, so
    they didn’t include such a capability.

    in a subsequent version, they bolted
    on a kludge — and decided to call it
    “logical page numbers” (huh?) — and
    now support page-numbering sets…

    …provided that you’re willing to jump
    through some hoops when you make
    the .pdf… and — more importantly –
    provided that your users have their
    _preference_ set correctly, so that
    “logical page numbers” are shown…

    the hoop-jumping is one obstacle,
    but that can be cleared with work.

    a user-preference obstacle, though,
    is one that is slightly more difficult…

    no matter how much you educate,
    some users simply are not going to
    have this preference set “correctly”.

    furthermore, other e-book programs
    have demonstrated the same failure
    of vision concerning page-numbering,
    and simply start their numbering with
    “page 1″ and increment from there…

    what this means, in many situations,
    is that a page that is clearly marked
    with “123″ as its page-number will be
    called “page 130″ by adobe acrobat,
    as well as many other e-book apps…

    for instance, you used to see this in
    books you downloaded from google.
    there would be the scan for page 44,
    but the acrobat page-number was 49.

    now, i seem to remember that google
    finally wised up and started using the
    “logical page number” feature of .pdf.
    (but i could have just dreamed that.)

    still, the point is that this is a major
    problem with e-book programs now.

    and it’s a problem that will probably
    extend into the future. the best way
    to “solve” this problem is to avoid it.

    use just one page-number sequence.

    even though the first page of the .pdf
    is really “the cover” or “the title page”,
    depending on how you think about it,
    bite the bullet and call it “page 1″ and
    increment each page-number after that.

    yes, that means by the time you get
    to the first page of the first chapter,
    you might be on “page 9″, but still…

    that way, your page-numbers and the
    acrobat page-numbers always agree…

    so when people use the “go to page”
    command in acrobat, and they specify
    “49″, they’ll actually go to “page 49″,
    not confusedly end up on “page 44″…

    besides, there’s a good side-effect:
    this becomes a nice way to indicate
    that your book was “born digital”…

    ***

    as i said, the first page of your .pdf
    serves as “cover” and “title page”…

    it’s appropriate, since the first thing in
    the file _should_ be the book-title and
    the name of the author. makes sense.

    years of thinking about it, and doing it,
    led me to the solid belief that “page 2″
    should be the book’s table of contents.
    (and that, of course, should be _linked_
    to the actual chapters, as users expect.)

    traditional p-book typography has put
    the copyright information on “page 2″,
    which is what you’ve done in your .pdf.

    the reason for such placement, of course,
    is that — as a verso — “page 2″ in a p-book
    has the status of being an “invisible” page.
    (nobody wants to _see_ that information.)

    on the contrary, however, in an e-book,
    recto and verso have very little meaning;
    both of them share an equal prominence.

    so “page 2″ is a page with a high profile.

    most e-book applications have a “home”
    button that automatically shows “page 1″.
    thus a combo of “home” and “page down”
    means “page 2″ is very highly accessible.

    so we should create an _e-book_tradition_
    that “page 2″ always shows the contents…

    i have been doing all of my e-books that way,
    and have come to count on the convenience.

    the copyright page? i suggest it be moved
    to the _last_ page in the e-book, where it
    equates to the p-book “colophon” tradition.

    note that the “end” key jumps right there,
    so the page still has a rather high visibility,
    just at the _end_, instead of at the front…

    (i’ve also put a copy of the “contents” page
    as the last page — so it’s convenient there –
    and put the “colophon” as the next-to-last.)

    for the sticklers among you, copyright laws
    specifically state that copyright information
    can legally be placed at the end of the book.

    so use page 2 for the table of contents, eh?

    ***

    ok, that’s enough for now. more later… :+)

    -bowerbird

    ***

  • bowerbird

    in my previous post, i should’ve mentioned
    that, alongside “indent” and “block” modes,
    there’s also a “mixed” mode, which utilizes
    an indent on paragraphs _and_ a blank line
    to separate them. this “belt-and-suspenders”
    mode won’t be used for most typical books,
    but in a book like this — which consists of
    articles that were originally blog entries –
    “mixed” mode might actually be appropriate.

    ***

    so let’s start our page-by-page walkthrough.

    ***

    i — a title-page is typically centered.

    ii — contents on page 2, please…
    do not linewrap bill mccoy’s name
    address-block incorrectly linewrapped
    do not linewrap interior designer’s name

    iii — chapter-names are too long…

    iv — …causing toc to run to 2 pages

    as discussed earlier, i’d move the copyright
    information to the back of the book instead.

    this would let the table of contents spread
    be on facing-pages, rather than recto/verso.

    however, i’d rework the contents page(s)
    considerably, starting with chapter-titles.

    in general, you want chapter-names to be
    somewhat uniform in length (and nature).

    so i would’ve reworked the chapter-titles.

    (there’s no reason the titles _have_to_ be
    the same as they were for the blog entries.)

    further, i wouldn’t _number_ the chapters.
    (numbering them doesn’t buy you anything.
    heck, since there’s no particular order here,
    numbering them doesn’t even make sense.)

    also, the indent used is a little too much…

    and finally, a recto/verso table-of-contents
    precludes a reader from getting a sense of
    the entire contents of the book in one shot.

    taken all together, then, i would rework this
    table of contents significantly, with the aim
    of getting it to fit comfortably on one page.

    here’s a working draft of what i came up with:
    > http://z-m-l.com/misc/toc-toc-rework.png

    ***

    #1 — this is the “1.1 introduction” page, and
    will be considered “page 4″ if you don’t have
    “logical page numbers” set as a preference.
    in that case, all page-numbers shown here
    in my walkthrough should be offset by +3.
    (but, better yet, just set that preference.)

    i don’t generally find it necessary to repeat
    the title of the book on the first page, but
    it’s certainly not “wrong” (or _that_ unusual)
    for it to be done, if you reallyreally want to.

    i’m not sure the chapter-heading fontsize is
    big enough — same size as the body-text –
    but its orange color does make it prominent.

    the chapter’s first paragraph is unindented…
    that’s how most typographers treat ‘em, but
    i’ve never much liked the reasoning for that,
    so i decided to indent those first paragraphs
    just like i indent all other paragraphs… but
    that’s my decision, and i cannot fault yours…

    i’ve already discussed the too-thin font, and
    the lack of justification, plus the hyphenation,
    but do so again since i’m looking at the page
    once again and being offended anew… ;+)

    ***

    #2 — the typographers are already wincing.
    the first thing we notice on this page is that
    the introduction should have been copy-fit…

    we’ve got a 5-line paragraph stranded here;
    a typographer would fit it back on page 1…
    rewrite, change the leading, do _something_!

    the one biggest failing with automatic layout
    by the computer is failure to do copy-fitting.

    (not the fault of the computer, which is a wiz
    at copy-fitting, but just inferior programming).

    since it is the biggest failing, it is no surprise
    that it has manifested itself so instantly here…

    the second thing we notice about this page is
    the second chapter starts mid-page. not good.

    even in the world of ink-on-paper typography,
    where blank space actually costs real money,
    book-designers almost always start a chapter
    on a new page. (sometimes they will even go
    so far as to require that it be a _recto_ page.)

    in the realm of e-books, where the “pagecount”
    is almost meaningless (unfilled pages are free),
    there is no reason to start a chapter mid-page.

    and there are many reason to start a chapter on
    a fresh page. (recto/verso doesn’t mean much in
    the realm of e-books; but do start on a new page.)

    blank space is free, but we still shouldn’t _waste_
    vertical space. and the “subhead” on this page
    (and on the subsequent articles) does just that.

    the date could (and should) be brought up to
    (be right-justified) on the line with the author.

    likewise, the words “original link” are unneeded.
    (we could trust that readers can figure that out.)
    further — back on the copy-fitting thing again –
    the link could be shrunk down to fit on one line.

    the footnote numbers are in rather small type,
    which is regrettable since the footnote-numbers
    in the body of the text aren’t live, meaning that
    the reader has to ascertain the footnote-number
    in the body-text, then find that (even smaller?)
    same footnote-number at the page-bottom, and
    then click the u.r.l. that is next to that number…

    since people will often set their fontsize so that
    the body-text size is the “correct” size for them,
    anything you make _smaller_ than the body-text
    is likely to be “too small”, so keep that in mind…

    and, as above, those u.r.l. lines in the footnotes?
    i would either shrink ‘em so they’d fit on one line,
    or run ‘em off the page. but i wouldn’t wrap ‘em.
    readers will click ‘em or copy ‘em, _not_ read ‘em,
    so there’s no reason to treat them like actual text.

    i will repeat the suggestion to drop the numbers
    from the chapter-titles. they serve no purpose…

    oh, one more thing. one of the things you’ll find
    – when you attempt to copy text out of a .pdf –
    is that that text loses any info about indentation.

    this means that you _cannot_ use indentation
    all by itself as a means of flagging _structure_.

    so that block-quote? the indentation alone will
    serve its purpose fine when the .pdf is printed,
    or viewed with acrobat. but it’s _not_enough_.
    you need to do something else to _distinguish_
    that block-quote when it’s copied from the .pdf.
    you might use a different color, for instance, or
    a different font, or a different size, or whatever,
    but indentation — all by itself — is not enough.

    it’s _really_ bad when you’re reading some text,
    and you realize that all the distinctions between
    what a writer said themself and what they quoted
    were lost because the blockquote indent was lost.

    ***

    #4 — we see section 1.2 needs copy-fitting too.
    (actually, after the copy-fitting of section 1.1,
    section 1.2 fits nicely on two pages of its own.)

    ***

    ok, that’s enough for today. more tomorrow…

    -bowerbird

  • bowerbird

    we’re doing a page-by-page walkthrough of
    the “best of toc” .pdf issued 10 days back…

    so let’s talk about those weblinks of yours…

    (in the land of .pdf, any link that opens up a
    page from the web in your browser is called
    a “weblink”, to distinguish it from “internal”
    links that jump around inside the .pdf itself.)

    i wonder why you didn’t make the _link-text_
    – right in the body of the book — the weblink,
    instead of making the _footnote_ the weblink.

    that way, readers could have just _clicked_
    the text at the footnote-number, and boom!

    as it is, your readers have to ascertain the
    number of the footnote-number, find that
    same number in the footnotes at the bottom,
    and then click that footnote. it’s not all that
    _difficult_, but it’s more hassle than needed.
    and, given our web-experience, it’s unintuitive.

    so one thing i have done in my version is to
    change that, so the readers can click either
    the text that anchors the footnote-number,
    or the footnote itself, whichever they want.

    ***

    ok, most of the recurring problems have
    been discussed, so things will go faster…

    #4 — five (5!) hyphenated lines in a row?
    book typographers won’t like that much!

    #5 — selfpublisher written as 1 word?
    “let’s look at” should get space above…
    please don’t use bold run-in headings…
    (readers might want to exercise choice
    when it comes to how headings display,
    and a run-in heading limits their options.)
    “re-/views” and “mu-/sic” are bad splits

    #6 — an end-line-hyphenate split as “ly”…
    and “in-/tended” is a bad split as well…
    “lock in” improperly two words, at [19]…

    #7 — space above on “more coverage”…
    an embarrassing typo on “libarything”…
    bad split on “chang-/ing”, makes orphan…

    #8 — a header split off from its section?
    (plus then an “.html” split to next line.)
    if a whole paragraph is italics, none is…
    (oh, and links don’t need italics either.)

    #9 — full line with one 2-letter word (up)?
    space above on “let’s start with”, please…
    with just _2_ points, do not number ‘em…
    “de-/tails” and “ex-/isting” are bad splits…
    (i won’t mention bad splits from here on.)

    #10 — your page ends with a list-colon:

    #11 — and again, don’t number 2 points…
    typographers will italicize “lingua franca”…

    ***

    ok, enough for today. more tomorrow… :+)

    -bowerbird

  • bowerbird

    continuing with our walkthrough of the o’reilly .pdf…

    #11 — i had managed to miss this one up to now, but
    the first line of a blockquote is not typically indented,
    even if it’s the first line of a paragraph in the original.

    #12 — the top-margin on the blockquote separates it
    too much from the colon-ending line that precedes it.
    (but i won’t mention this recurring problem any more.)

    #13 — it was bad enough, on chapter 1.4, on page 8,
    where heading/subheading were separated from body;
    but here on chapter 1.6 the subheading itself is split…

    #14 — indentation of the e-mail is kind of squirrelly…

    #15 — nothing to criticize here, which is kind of sad,
    because it’s kind of an ugly page. but that happens.
    oh, this: books use _italics_ for emphasis, not *bold.*
    and in addition i see a one-word line at paragraph-end.

    #16 — last time: no need to number a 2-point point.
    and again, avoid the run-in headings; split them out…

    #17 — before, “emphasis added” note was _above_.

    #18 — amazing how many chapters were “just off”
    when it comes to the matter of having been copy-fit.
    i believe explicit labeling of questions-and-answers in
    the text of an interview is preferable to using styling;
    styling too often gets lost, and then you have a mess.

    #19 — another one-word paragraph-end here (telling”).
    and one more, with “form” at the bottom of the page…
    pull those two up, and then you can pull the paragraph
    (i.e., continued answer) from the next page to this one.

    #20 — “sean stewart” line should be copy-fit to one line.

    #21 — finally, a whole page without even one comment!

    #22 — and another! yippee! now we’re on a roll, baby!

    #23 — and look, we have a heading at page-top, our first!
    but crap, we take a step back with the “step back” line at
    the bottom; it should’ve been pushed to the next page…

    #24 — but page 24 looks pretty good, no other faults…
    (since we said we wouldn’t flag any more one-word lines.)

    #25 — …except this pair of chapter-ending orphans lines,
    which should’ve been copy-fit back to the previous page.

    but this seems like a good place for us to stop today…

    -bowerbird

  • bowerbird

    ok, let’s talk a little about the “self-analysis” that
    mac did on this project, in the comments above…

    ***

    mac said:
    > But porting blog entries and essays
    > that were built for a Web format into
    > a “book” format doesn’t work for me.

    i think you’re having a difficult time here
    thinking about your book as a web entity
    because it doesn’t actually live on the web.

    if it did, it would be much easier for you to
    conceptualize it as a thing “built for” the web.

    > But I’m a Web-centric kinda guy. I like
    > my content open, agile, and highly linkable.

    and again, there’s absolutely nothing about
    this content that prevents it from being that,
    if this book did, in fact, really live on the web.
    which is precisely why you want to put it there.

    (and, as we all remember, this content really
    _does_ live on the web, but it’s all spread out.
    when you combine content into a _compilation_,
    that changes its nature, by virtue of its inclusion.
    so this book should live, as a book, on the web.)

    > When I write, I need the ability to weave
    > material directly into the text via hyperlinks,
    > not footnotes or comments or add-ons
    > or whatever doo-dad we come up with.

    i’m not sure why you don’t think of the links
    in this material as actually _being_ real links.
    since they are. you click them, you go there.

    > Links are beautiful things, and when I
    > can’t have them, I get cranky.

    good thing you didn’t grow up 20 years ago.
    or 50 or 100 or 500… :+)

    > 1. Create two versions, on-demand:
    > the ebook version will include embedded hyperlinks.
    > Any POD-based version will include footnotes.

    first, version proliferation is _not_ a good thing.
    it means more work for you, and user confusion.

    second, there’s no real difference between your
    two “versions” anyway. the footnotes you made
    _are_ embedded hyperlinks. i will agree that you
    should have made the actual text (in the body of
    the book) the hyperlinks, rather than making users
    click the footnote, because it makes the links much
    more intuitive to users, but it’s a small _distinction_.

    > 2. Recognition that the footnotes are a courtesy:
    > Let’s face it, no one is going to put down their
    > print copy of this thing and type in a long URL
    > just so they can see the referenced story.

    oh, i see, you’re talking about the _printed_ copy…

    so you conceive of this e-book _not_ as an e-book,
    but as the source-document for a _printed_ copy…

    that’s a shortcoming in your conceptualization is all.

    this is an e-book, as well as being a source-document.
    most readers will use it as an e-book, not print it out…
    your intention (i.e., to use it as a sample book for the
    espresso machine at the toc conference) matters little,
    not compared with the mindset of the people using it.

    and most books in the future will be used as e-books…
    the typical person will rarely bother to print out a book.
    (how often do people print a blog entry? or an e-mail?)

    of 20,000 books a future person might own as e-books
    –which might be an extremely conservative estimate –
    they will print maybe 100, just 1/2 of 1 percent of them.

    > I don’t mind including footnotes in a print edition, but
    > the real “utility” only comes from *embedded* links.

    oh, i see, and you seem to think that a printed copy will
    _not_ exist in parallel on the web. i disagree strongly…

    i believe that every page of every book will have its own
    webpage, where people can gather to discuss that page.

    so there’s no need to “type in a long url” to see a story,
    because you’ll be able to jump to the website for a page
    simply by clicking the weblink on that page of the .pdf,
    and from there clink any of the links there that you like.
    (and of course, the weblinks in the .pdf will also be live.)

    one more thing… an author should have one web-page
    (with a short u.r.l.) which contains _all_ of the links in
    their entire book, so no one would have to “type” them.

    something like this:
    > http://z-m-l.com/misc/toc-links.html

    there’s really no reason not to have something like that.
    because nobody should ever have to “type in a long url”.

    > people are suckers for thoughts that pop up in “books”).

    um, gee, that’s kind of cynical.

    if people know that someone has borne the expense of
    collecting content and printing lots of physical copies,
    they are likely to ascribe greater value to that content,
    but i don’t think that judgment makes them “suckers”.
    i think most of the time it will be the right attribution…

    > Put the Web-based version first:
    > The aggregated material should exist
    > *first* as a mini-site or section and
    > *second* as an aggregated book.
    > Not the other way around.

    um, just as i don’t see the “versions” as being “distinct”,
    neither do i think either of them can have any “priority”.

    i create .pdf and the .html website from the same source,
    so, to me, they are two manifestations of the same thing.

    you will mount the .pdf and the website at the same time.
    indeed, you mount the .pdf in the same folder on the web,
    so it lives right alongside its .html version. they are twins.

    > we’re already prepping a second edition of Best of TOC
    > that will be released in the next week or so. Our workflow
    > makes this a snap

    well, yipee for your workflow. but, as i said previously,
    you’ll soon find that version proliferation is a bad thing.

    it’s much better to exercise care with your first edition,
    enough care that you won’t need for “a second edition”
    to be issued just a few weeks later. that won’t scale…

    > Again, I’m a Web guy, so I expect
    > updates and add-ons, corrections, new versions, etc.

    most of that stuff will happen on the website for the book,
    a natural result of the growth happening around the book
    as it collects a community that wishes to push it forward…

    -bowerbird

  • bowerbird

    and so we continue, on our merry walkthrough… :+)

    ***

    #25 — this 1.10 heading, with its one-word overflow line,
    illustrates for us exactly why headings should be copy-fit.
    note we will need to indicate paragraphs on blockquotes,
    since we said earlier we should not use first-line indents.

    #26 — once again, is “emphasis added” before? or after?
    and run-in headings are bad enough, but what’s up here?

    #27 — pair of orphan lines here that end a numbered item.
    plus that footnote#95 looks pretty silly there, all by itself.
    and, at page-bottom, another heading split from its text…

    #28 — first question needs to have some space above it.
    and (last time) use of bold to mark questions is untenable.

    #29 — once again, a footnote-number is hung out to dry.
    and a two-line question separated from its one-line answer!

    #30 — one-line answer separated from two-line question!

    #31 — and yet another pair of orphan lines on this page…

    #32 — here’s another chapter _subheading_ at page-split!
    what are the odds that 2 of the first 12 would be like this?

    #33 — i said i wouldn’t mention any more one-word lines,
    but there’s a half-word line on this page that looks awful.
    (with yet another one-word line just four lines below it.)

    #34 — bio paragraph needs to have a little breathing room.

    #35 — i would have tightened up those bullet-point lines…
    (and copy-fit the half-word line above it while i was at it.)
    (and removed the one-word line on the top paragraph too,
    but i promise i won’t mention the one-word lines any more.)
    the paragraph introducing the quote is split from its quote.

    #36 — ok, no new or unusual faults here. hip hip hooray!

    #37 — ok, no new or unusual faults here. hip hip hooray!
    (although the half-word line is especially irritating in bold.)

    #38 — ok, no new or unusual faults here. hip hip hooray!

    #39 — ok, no new or unusual faults here. hip hip hooray!
    (but i could made some comment recommending lots of air
    above questions, and a little between question and answer.)

    #40 — ok, no new or unusual faults here. hip hip hooray!

    #41 — this chapter would’ve copy-fit nicely on 2 pages…

    #42 — another one-word slop-over line in the chapter title.

    #43 — ewwh. that quote really needs some copy-fitting…
    and in a set of 4 lines, 3 have 2-letter hyphenated-starts.

    #44 — see how much nicer it looks with header at page-top?
    and no, i still don’t like bolding as a tool to mark structure…

    #45 — ok, no new or unusual faults here. hip hip hooray!

    #46 — ok, no new or unusual faults here. hip hip hooray!

    #47 — four (4!) one-word lines at paragraph-end on this page.
    (said i wouldn’t mention it any more, but there are 4 of ‘em!)
    one-line question split from two-line answer. (ok, last time.)

    #48 — ok, no new or unusual faults here. hip hip hooray!
    (although the half-word line is, as before, irritating in bold.)

    #49 — ok, no new or unusual faults here. hip hip hooray!

    #50 — ok, no new or unusual faults here. hip hip hooray!

    #51 — ok, no new or unusual faults here. hip hip hooray!
    (but hyphenating a 4-letter word — la-/zy — is a bit weird.)

    #52 — ok, no new or unusual faults here. hip hip hooray!

    #53 — the bullet, “note”, number sign, and number itself
    – 4 separate items — and every one of them superfluous…
    those two notes stand on their own, especially as they are
    introduced in the line directly above ‘em as “a few notes”…
    with that out of the way, the “with that…” line needs air…

    #54 — i would suggest an indicator — a horizontal rule? –
    to partition each point/”caveat”/”recommendation” grouping,
    so that particular underlying structure is made more obvious,
    both to humans reading the text and machines processing it.
    i might experiment with placing each group on its own page…

    #55 — and i still don’t care for run-in styled semi-headings…

    #56 — ok, no new or unusual faults here. hip hip hooray!

    #57 — i would suggest the “preface” header needs some air.

    #58 — not typography per se, but “so…” is an awful heading.

    #59 — “key questions” should get more air above than below.

    #60 — the “outline” on this article is a messy hodge-podge…

    #61 — i will rearrange things if a name splits on a pagebreak…
    and the “an anecdotal report…” header needs to be copy-fit…

    #62 — as on #58, the “continuing…” is just an awful heading.

    #63 — ok, no new or unusual faults here. hip hip hooray!

    #64 — like #59, header should get more air above than below.

    #65 — ok, no new or unusual faults here. hip hip hooray!

    #66 — ok, no new or unusual faults here. hip hip hooray!

    #67 — yet another header with a one-word slop-over line…

    #68 — ok, no new or unusual faults here. hip hip hooray!

    #69 — ok, no new or unusual faults here. hip hip hooray!

    ***

    ok, that’s enough for today. back at it tomorrow… :+)

    -bowerbird

  • http://toc.oreilly.com/mac-slocum Mac Slocum

    @bowerbird

    Your analysis of “Best of TOC” touched on a number of things I hadn’t considered, so thanks for expanding my horizons. I appreciate that.

    In regards to one of your points …

    > it’s much better to exercise care with your first edition,

    enough care that you won’t need for “a second edition”

    to be issued just a few weeks later. that won’t scale…

    When it comes to Web content, I don’t think in terms of editions. Web content “lives” — it changes, it’s updated, it’s mashed up, reworked and recombined. In my own work there have been plenty of times where I’ve added/altered material based on feedback from the surrounding communities (changes are noted, of course). To me, each of these changes doesn’t represent an edition; it’s part of a continuum.

  • bowerbird

    mac said:
    > When it comes to Web content,
    > I don’t think in terms of editions.

    yes, but we’re not talking about the web, we’re talking about
    a book, a discrete point of archival, captured as ink-on-paper.

    now, in the course of its life, yes, the book will become “a movie”.

    but any time you “go to print” — whether you actually lay down
    ink, or just make a “frozen” .pdf — you’ve created a _snapshot_.

    and, much like a focus on any one particular frame of a movie,
    any discrete archival point might be a rather arbitrary selection.

    but that doesn’t mean that you can generate them _endlessly_.

    more to the point, you _can_ generate them _endlessly_, but
    it’s an unwise thing to _do_, because it seeds reader confusion.

    the benefit of “going to print”, of making _a_specific_edition_,
    of selecting one frame — however arbitrary — out of a movie,
    is that we then have a “known quantity” we all comprehend…
    that certainty and “fixedness” helps to corral the discussion.

    if you start doing too many “snapshots”, you lose the certainty.
    some people are talking about snapshot 23, while others are
    still looking at snapshot 22, and the rest are on snapshot 24.
    people start talking “past” each other, and dialog disintegrates.
    it’s better to have everyone on “the same page”, even if it is a
    badly-flawed “snapshot”, than to have a boatload of confusion.

    if you’re constantly jerking the snapshot out of people’s hands
    to replace it with an “updated” snapshot, which you will then
    replace with a “newer update”, people will just tune you out…
    and confuse each other… and waste time figuring it all out…
    as i said, the dialog disintegrates, and then people will leave
    because the dialog is no longer worth the time that it takes…

    i mean, sure, up on the web, where the book will be “living”,
    certainly, there it is a constantly evolving, interactive being…
    that’s where we discuss the flaws of the badly-flawed snapshot.
    and people expect that the web will be a volatile environment.
    at the same time, they expect that print is nonvolatile, static.

    so be judicious when creating snapshots. it’s not something
    you can do repeatedly without stressing your audience bond.

    how often is “repeatedly”? well, you’ll have to figure that out.
    but the advice still stands: don’t make new editions too often.
    resist the impulse to put out a new edition, until you cannot
    resist any more…

    -bowerbird

    p.s. i would say that — when you _do_ make new editions –
    “change-logs” can be very instrumental in easing user stress,
    but that’d distract from my general message of “don’t do it.”
    and i’d rather have you looking at the “don’t do it” snapshot…
    which shows this is an overarching aspect of human attention.
    if you want people to focus, don’t keep changing their focus…

  • bowerbird

    ok, let’s finish our walkthrough… :+)

    ***

    #69 — very bad split on the u.r.l. for “exact editions”…

    #70 — ok, no new or unusual faults here. hip hip hooray!

    #71 — once again (last time), no need to number 2 points.

    #72 — the “alpha geeks” header needs breathing room…

    #73 — amazingly we have another fragmented subheader.

    #74 — ok, no new or unusual faults here. hip hip hooray!
    #75 — ok, no new or unusual faults here. hip hip hooray!
    #76 — ok, no new or unusual faults here. hip hip hooray!
    #77 — ok, no new or unusual faults here. hip hip hooray!
    #78 — ok, no new or unusual faults here. hip hip hooray!

    #79 — once again, bad split on the “exact editions” u.r.l.

    #80 — another header that needs some breathing room…

    #81 — last sentence introduces blockquote on next page?

    #82 — confusing indentation, due to blockquote at top…

    #83 — copy-fit that pair of orphan lines (one a one-worder)

    #84 — bold run-in heads=bad; unbold run-in heads=worse.

    #85 — run-in heads with same-indent subheads=worst of all.

    #86 — ok, no new or unusual faults here. hip hip hooray!
    #87 — ok, no new or unusual faults here. hip hip hooray!

    #88 — another pair of orphan lines that could be copy-fit…

    #89 — ok, no new or unusual faults here. hip hip hooray!

    #90 — the “recycling” of the 1-4 numbered-list-items here
    doesn’t communicate successfully that the items are to be
    contrasted with the 1-4 numbered-list-items from _before_.
    maybe making the first n1-n4, and the second s1-s4 would?
    (where “n” stands are “no standard”, and “s” for “standard”.)

    #91 — three lines won’t normally qualify as “orphan”, but
    it’s much nicer when a list like this is copy-fit to one page.

    #92 — two lines at page-top _does_ qualify as “orphan”…
    (but i will not mention the occurrences of this any more.)
    and yet another header/subheader gets split from its body.
    (i could’ve stopped mentioning these, except i am astounded
    just how many times it happened. murphy’s law is still valid!)

    #93 — ok, no new or unusual faults here. hip hip hooray!
    #94 — ok, no new or unusual faults here. hip hip hooray!
    #95 — ok, no new or unusual faults here. hip hip hooray!
    #96 — ok, no new or unusual faults here. hip hip hooray!

    ***

    ok, from here on out, it’s just the one long article, where
    the points are ones i have already made, even repeatedly:
    * one-word (or half-word) lines at the end of paragraphs
    * fix the orphans, and other copy-fitting suggestions
    * headers need more breathing room, especially above
    * my general recommendation against run-in headings
    * a note that books use italics (not bold) for emphasis
    * rearrange so you don’t start a blockquote at page-top

    this takes us up to the very last page. which has 2 lines.
    i would have copy-fit that.

    so, we finished the walkthrough! yay! we made it! :+)

    just a few things more, to take care of the paperwork,
    things i forgot along the way, or decided to save for last.

    ***

    first, each page has a run-head _and_ a footer. overkill.
    (especially since you’ve got “best of toc” in both of ‘em.)

    and the publisher name doesn’t need to go in the footer.
    i know, you _want_ it there. but it really doesn’t belong.
    makes it look like you’re doing _advertising_, which sucks.

    also, your run-head has a page-number on the left side.
    that’s not how books do it. they put it on the _outside_,
    meaning that it’s on the right on a recto page (odd page)
    and it’s on the left for a verso page (the even numbers)…

    and yeah, when single-page viewing a .pdf, it’s disorienting
    to have the page-numbers in two different places, which is
    why i usually _center_ the page-number at _page-bottom_.

    and i don’t usually include a run-head at all. no reason to.
    yeah, yeah, i know it’s traditional, and my default response
    is to respect tradition, but i always question it for validity.
    and i just don’t think there’s much reason for a run-head.
    when they’re reading a physical book, people usually know
    which book it is they are holding in their hands, and thus
    do not need to be “reminded” of the title on every page…
    and when you read the .pdf, the filename is in the titlebar…
    so i don’t see the need for a run-head. instead, what i put
    at page-top is the _u.r.l._ of the web-page for that page…
    i believe every page of every book should have a web-page,
    where people gather to comment on and discuss that page.

    ***

    the other thing i wanted to mention is “bottom-balancing”.

    one of the subtle aspects of books that we always notice
    – albeit usually subconsciously — is that the _bottom_line_
    of most pages always falls at the same place on the page…
    (the most common exception is the last page of a chapter.)

    more specifically, when we open a physical book and look at
    _facing-pages_, the bottom lines on the two pages line up…

    this little bit of compulsiveness is one of many reasons that
    books play to our esthetic sense and make us comfortable…

    (bottom-balancing is also called “vertical justification”, and
    it’s identical to the “horizontal” aspect of “full justification”;
    just as you add space between the words on each line so
    the last word of every line will end up in the same place,
    so too do you add space between the lines on each page so
    the last line of every page will end up in the same place…
    so if you ever ear “vertical justification”, that’s what this is.
    but i’ll continue to call it “bottom-balancing” so as to avoid
    any confusion about exactly what we’re talking about here.)

    ***

    now, if you haven’t thought about it much, you might think
    the last line would always fall on the same place “naturally”.

    and if you always had the same number of lines on a page,
    and the same leading between all of those lines, it would…

    (“leading” is the space between the lines on a page, for
    readers here who might not be familiar with the term.)

    but all pages usually don’t have the same number of lines,
    because the control of widows and orphans disturbs that…

    (a “widow” is what happens if the first line of a paragraph is
    on one page, and the rest of the paragraph is on the next.
    an “orphan” is when the _last_ line of a paragraph is on
    a page by itself, with the rest being on the previous page.
    and maybe i’ve switched the terms, i can never remember.
    but both of them are bad, bad, and bad, to a typographer.
    some typographers hate them so much that they consider
    even _two_ lines split from a paragraph to be undesirable.
    anyway, when you _fix_ widows/orphans, you change the
    number of lines that were previously put on each page.)

    moreover, the leading can differ between lines on a page.
    for instance, you might have a header, in a different size
    and maybe a different font, and that changes the leading.
    and oftentimes, a typographer will put a little extra space
    above each paragraph, or between the text and a table…
    sometimes blockquotes are shown with different leading,
    to give a subtle, subconscious distinction to the reader…

    all of these things will put the last-line location in flux…

    ***

    so bottom-balancing is something that you want to do…

    in your book here, the footnotes are an obvious obstacle
    to any “bottom-balancing”, of course, but even aside from
    the irregularity that they introduce, your bottom lines are
    “all over the page” — some close to footnotes, some not.

    these are the little touches that typographers _look_for_,
    and which lead them to dismiss books done “by computer”.

    if your system doesn’t take care of these “little touches”,
    it will _never_ be accepted by those stuffy typographers…

    ***

    anyway, there’s your walkthrough. i hope you don’t think
    i’ve been “mean” or anything. i just call ‘em like i see ‘em.
    a “real” book typographer might’ve found even more fault.
    and charged you a ton of money for doing you the favor…

    oh, and i’ll put up my version of this book next week, so
    _you_ can have fun picking it apart and paying me back.

    -bowerbird

  • bowerbird

    ok, now that i’ve talked about _your_ .pdf, i’ll post mine.

    then i’ll do a walkthrough of mine. (you can do one too.)

    but first, here’s some orientation to my version…

    ***

    ok, let’s talk about chapter headers.

    i started each chapter on a new page. that’s how it’s done.

    ***

    ok, let’s talk about paragraph style.

    i talked about block paragraphs versus indented paragraphs,
    and it might’ve seemed like these are mutually exclusive, but
    of course, they’re not. you can combine them if you want to.

    that is, you can have a blank line between paragraphs _and_
    still indent paragraphs. this “belt and suspenders” method
    isn’t usually done, since both are sufficient by themselves…

    but there’s no reason you can’t do both. so that’s what i did,
    with my .pdf, so people can see it and decide what they think.

    and while you are evaluating this method, keep in mind that
    there’s even more middle-ground here. specifically, you can
    adjust the blank line between paragraphs so that it doesn’t
    take up the full height of the line; it might only be half-size,
    or even one-quarter of the full height of the non-empty lines.

    viewed this way, it’s worthy to note that many typographers
    actually use a “space-above” component on their paragraphs,
    to get an ever-so-slight subconscious bit of air between ‘em.
    it’s not a full line, not even one-quarter of a full line, but it is
    _something_. only a few typographers use a strict pure grid,
    and they are using it because of the direct benefits of a grid,
    not because they object to air above each paragraph per se.

    so even if you dislike the full empty line between paragraphs,
    think about whether you’d like _some_ air above them…

    ***

    ok, let’s talk about hyphenation.

    i didn’t hyphenate this .pdf. i don’t ever do hyphenation.
    (well, if i’m cloning a paper-book, i mimic its hyphenation.
    but i’d never _introduce_ hyphenation. it’s unnecessary.)

    hyphenation is bad in an e-book. do not do hyphenation.
    turn hyphenation off, and leave it off, now and forever…

    ***

    ok, let’s talk about justification.

    i justified this text. not all of it — blockquotes are ragged,
    as are outdented paragraphs — but i justified body-text…

    some people will tell you that, when you use justification,
    you _have_to_ do hyphenation. indeed, the trade jargon
    is “h&j”, which stands for “hyphenation and justification”.
    they’re siamese twins, in p-book typography, inseparable,
    joined at birth at the hip, can’t have one without the other.

    if that was true, i’d give up justification in e-books, since
    hyphenation just plain causes too many problems.

    fortunately, it’s not true. you can have justification _and_
    eschew hyphenation. you just have to be a little creative…
    i’m here to show you how…

    ***

    ok, let’s talk about controlling widows/orphans.

    you simply must control widows/orphans, or you are _not_
    a typographer doing book-design. there are no exceptions.

    oh sure, you _can_ find p-books with windows or orphans;
    those p-books had a designer who didn’t love ‘em enough.
    surely you’re not gonna be _that_ kind of designer. right?

    show the reader that you actually _cared_ about the book.

    i won’t even allow 2-line widows or orphans in my book…

    ***

    ok, let’s talk about bottom-balancing.

    i bottom-balanced my .pdf, so people could evaluate that.
    but the “color” of the pages is too variable, inconsistent…

    when a typographer goes off about the “color” of a page,
    they are not talking about _color_, but “degrees of gray”.

    viewed from across the room, black-ink-on-white-paper
    blurs to a grayish blob. if you have lots of lines of text,
    placed closely together, the blob appears as _dark_ gray.
    and, with only a few lines, spaced apart, it’s _light_ gray.
    this “color” jargon refers to how light or dark the gray is.

    the main thing a typographer wants is for the “color” to be
    _consistent_ within a page (top to bottom and left to right),
    and consistent within a page-spread (the two facing pages
    you see when you open a book), plus (to a lesser degree)
    consistent across all of the pages of a book.

    that is, you don’t want some pages to be _dark_ gray
    while other pages are _light_ gray. that is “bad color”.
    (as long as they’re all about the same, dark _or_ light,
    it’s fine, although you might prefer one over the other.)

    and, as i said, bad color is precisely what we got here.

    so, bottom-balancing didn’t work well here, and there’s
    a good reason why it didn’t, which i’m going to explain…

    i didn’t do a strictly-mechanistic pagination with this book.

    i _started_ with that. (you should always start with that.)

    but then i modified the output.

    let me explain. first i had the computer insert a page-break
    when it hit a set number of lines. (i think i went with 34.)

    i then had my tool fix the resultant widows and orphans.

    so far, so good.

    if i wanted a mechanistic pagination, i woulda stopped there.

    and if i had stopped there, the bottom-balancing would have
    looked much better. pages would’ve had a uniform “color”,
    because they all would’ve had a very similar number of lines.

    but i didn’t stop there…

    the first big reason for changing page-breaks is to copy-fit…

    essentially, this takes widow/orphan control one step further.

    as an example, you might have a half-dozen lines on a page
    at the end of a chapter. you don’t wanna use a whole page
    for that, so you’ll fold those lines back to the previous page,
    which might then mean you will have to fold three lines from
    _that_ page back to the page before it, for a good balance…

    as another example, you will recall that i prefer to have the
    table-of-contents section on one page, rather than on two.

    you’ll recall there were plenty of cases in my walkthrough
    where i suggested that copy-fitting should have been done.

    it’s just cleaning up the loose ends that always show up.
    if you care about your book, it’s one of the things you do.

    so when i needed to do that kind of copy-fitting, i did it…

    ***

    but i didn’t stop there either. i looked at each page-break,
    and decided whether i felt it had fallen at the “right” place.

    and, if i didn’t like a particular page-break, i’d change it…

    my main reason for changing the page-breaks was so that
    text on a coherent, cohesive topic was on the same page,
    rather than have some on one page, the rest on another…

    i was fairly extreme in doing this, meaning that i did _not_
    care how many lines i moved in order to accomplish this…

    the most extreme example of this was a section containing
    a handful of snippets from other sites on the topic at hand.
    in the o’reilly .pdf, these snippets took a-page-and-a-half.
    (it was text which fell on pages __ and __, for reference.)
    i put ‘em all on one page instead. it’s needless to say that,
    since i squeezed a page and a half of text onto one page
    – the page had 41 lines on it, well over the “regular” 34 –
    the lines were gonna be tight, and the color was very dark.

    ***

    so that’s why the color isn’t very consistent on these pages.

    the number of lines varies wildly from one page to the next,
    and the bottom-balancing _spreads_out_ those lines, thus
    accentuating the variation in color.

    it’s worth observing that, if you don’t do bottom-balancing,
    you can have inconsistency in the number of lines per page,
    and still have consistent color, because color depends upon
    the _leading_. if your leading is the same on all the pages,
    the color will be similar. in that case, though, some pages
    will have text that doesn’t run to the _bottom_ of the page,
    and that’s usually a thing that bugs typographers badly…

    so here’s how the color problem can be resolved:

    i can undo all my “semantic” page-breaks, and go back to
    the “mechanistic” page-breaks based on simple line-count
    (with only the minimal changes for widow/orphan control).

    or i can turn off bottom-balancing, and use uniform leading.

    if anyone has any preferences on what they’d like to see,
    say so. or, if you wanna see both variations, i’ll do that…

    (just a quick note that there _is_ one other solution here,
    which is to place graphic flourishes on the bottom of pages
    that would otherwise be too loose, to eat the excess space.
    to give you a hint of how that works, i’ve placed images at
    the bottom of the end-of-chapter pages. those are pages
    which are not bottom-balanced even in the regular scenario,
    but it’ll give you a visual demo for how this scheme works.
    you can adjust the size of the visual flourish so that your
    leading is perfectly identical, so your color would be ideal.
    remember that, other than slightly inflating the size of the
    e-book, which isn’t all that big of a problem in most cases,
    there is very little cost to including nice big colorful images
    in your e-book, which can brighten the reader’s experience.
    color _significantly_ jacks up the price of printing a p-book,
    so we’ve come to think of books as black-and-white things.
    but there are reasons not to feed that shallow expectation.
    images, especially colorful ones, can be cool, so use them!
    get on that path william blake blazed so many years back!)

    ***

    speaking of color, white is a color too. a very nice color…

    earlier, i had said “white space in cheap in an e-book”, and
    it’s true, there’s no compelling reason to squeeze things in.

    but just because a resource is plentiful, that doesn’t mean
    that you should waste it. so i try to reduce unused pages.
    there’s no use for blank pages in an e-book. no use at all.

    moreover, even if the e-book predominates its hard-copy,
    you still keep in mind the ramifications of printing it out…
    your readers might wanna print it; be considerate of them.

    in this regard, i was very mindful of the book’s page-count.
    the original version was 131 pages. (um, right, that alone
    tells you the preparer wasn’t cognizant about page-count,
    since a book simply cannot have an odd number of pages.
    because, d’uh, every sheet of paper has _two_ sides to it,
    automatically therefore meaning an even number of pages.)

    so i copy-fit the given text so it’d fit in 131 pages as well.
    i added a footnote/url section, which contained 12 pages,
    plus i added a page about z.m.l., taking us to a nice 144.

    144 is a “nice” page-count because it’s divisible by _16_.

    and why does divisible-by-16 create a “nice” page-count?

    well, that’s a good question, i’m glad you asked. :+)

    a print shop that typically prints _books_ has big printers.
    very big printers. way bigger than your puny laserprinter.

    for efficiency, they print extremely large sheets of paper.
    these sheets are so big that 8 book-pages fit on one side,
    with another 8 on the other side… so there’s our _16_!

    so a 144-page book will be printed on 9 sheets of paper.
    (some printers do 32-page signatures, but most do 16.)

    these sheets are then _folded_. (because of this folding,
    some of the pages have to be printed “upside down”, so
    they’ll be “right side up” after the folding; creation of the
    sheets so the pages end up correct is called “imposition”.)
    after folding, the sheets are _cut_, and stitched or glued.

    each of these 16-page “sub-books” is called a “signature”;
    so our 9 signatures are then bound together as the book.

    if you look closely at the top of a book, right at the spine,
    you call actually see the different signatures composing it.

    now, with print-on-demand, they print on smaller sheets.
    an 8.5*11-inch sheet will create a sweet 5*8-inch book,
    (the excess is trimmed), with each sheet making 4 pages.

    if you turn a sheet sideways, and fold it in half, you’ll see.
    (or if you’re a poet who’s made a chapbook, you’ll know.)

    so, if you’re printing a book like this, your page-count will
    have to be a multiple of 4… and, if i remember correctly,
    lulu.com specifies only that the page-count must be even.

    whatever, think of the page-count when you do a book.
    for the most part, you’ll wanna use a 16-page boundary.

    yes, true, it’s only if you do a press-run of 2000-10000
    that you need to worry about making it a multiple of 16.

    but hey, why not think positive? assume that your book
    _is_ going to become big, and that you will _need_ to do
    a big press-run — because it will pay for itself in sales! –
    and plan your book accordingly. it’s good to think ahead.

    but don’t let yourself slop over a “nice” number like 144.
    not even one page over. (most especially not just one!)

    ***

    you might say “why bother?” but it’s no bother. it’s fun!

    because one thing that you can learn very quickly is that
    it’s _very_ easy to make adjustments to the page-count.

    indeed, it’s just a little bit scary how much it can vary…

    first of all, different fonts can make a _huge_ difference.
    some fonts are relatively big, and others relatively small.
    you might think they’re all roughly the same; they aren’t.

    and by changing the pointsize from 12 to 12.5, you can
    add 16 pages (or more!) to a book of the typical size…
    (so imagine what bumping it up to 14-point might do.)

    and if you start fiddling with the leading too, watch out.

    publishers _often_ have their book-designers “meddle”
    with a text to get a certain page-count. if a manuscript
    comes in that’s slight, they’ll “puff it” to bulk the pages.
    if it’s over the contracted word-count, they will shrink it.

    so you have many ways to manipulate the page-count,
    and changing the leading is the most common one used.

    plus, of course you’re always free to do some _editing_.

    that section you weren’t that confident about anyway?
    if you find you are running just a bit too long, delete it!

    that photo you really like? if you’re short, there’s room!
    (in general, you’ll learn that graphics are very malleable,
    if you stay flexible and don’t let yourself become fixated
    on running them at a certain size or a specific location.)

    so, again, plenty of options to manipulate page-count.

    start with settings as you’d like ‘em in an ideal world,
    to see what the page-count is, and know whether you
    need to “stretch” it out a bit to make it turn out nice,
    or whether you need to “compress” it to make it fit…

    best advice is to _listen_to_what_the_book_tells_you_.

    there is some length which will be its “natural” length;
    if you try to stretch it too far, or scrunch it too much,
    it’ll complain. so if you listen to it, you’ll hear its pain.
    be in tune with your book.

    ***

    ok, let’s talk about the links/footnotes.

    i think we agree that turning links into footnotes was
    not a good idea… since .pdf can support the web-link,
    we may as well use it, since that’s what people expect.

    since many .pdf viewer-programs display the link when
    a user hovers over it, which is the same “feedback” that
    a traditional web-browser gives you, i didn’t feel a need
    to place the u.r.l. in a footnote placed on the actual page.

    instead, i collected the footnotes in a section at the end.

    if the user clicks the _body-note_, that opens the link
    in their browser. and if they click the _body-number_,
    they go to the relevant page in the _footnote_section_.
    if they click the footnote-reference, they go to the web.
    if they click the footnote-number, they’ll go back to the
    page in the body of the text where the body-note lives.)

    we can discuss the merits and demerits of what i’ve done.
    i think it’s still a bit of a kludge, but within the constraints
    of .pdf, i don’t know what will be the best course of action.

    except to do all that we can to hasten the death of .pdf.

    which brings me to the last section of this lengthy tract…

    ***

    ok, let’s talk about .pdf in general.

    what a shit format. the _roach_motel_ of text formats
    – “documents go in, but they never come out again.”

    there are a lot of explanations for “why e-books have
    not yet taken off”, because there _are_ lots of reasons.

    but one of those many reasons is _.pdf_sucks,_ and
    .pdf has been the “de facto” format for electronic-text.

    and the worst part about that fact is the “monopoly”
    .pdf has had over any other format is one that adobe
    _bought_and_paid_for_. it’s not because .pdf is the
    “best format”, not by a long shot. it’s because adobe
    bought out its competitors and shelved their products,
    to the point that nobody even _remembers_ them now.

    and any time anyone (like, say, microsoft) went to build
    a competing format, adobe would whine like a little baby.
    on the contrary, however, when microsoft then took the
    “.pdf is a standard” lie/line seriously, adobe whined too.

    .pdf was a cash-cow for them, and they worshipped it,
    and protected it, so they could line their greedy pockets.

    so i hate .pdf, and i’ve hated it for a very long time now.

    i hate .pdf like every e-book programmer hates it,
    because it’s inferior.

    i hate .pdf like ted nelson hates it, because it reinforces
    the electronic-documents-should-mirror-paper mentality.

    i hate .pdf like the vast majority of people hate it,
    because it has too many shortcomings.

    so let me be perfectly clear: i hate .pdf.

    but that doesn’t mean i’m blind to its good qualities, and
    it has some, and i can hate it while still admitting them…

    one of the best things about .pdf was that adobe was
    great about supporting it on every platform out there.

    other companies were shooting themselves in the foot
    by trying to _limit_content_to_their_own_platform_,
    such as microsoft failing to port ms-reader to the mac.
    (or, um, mobipocket’s similar refusal to support macs.)

    but adobe was crafty. they knew they couldn’t get us to
    abandon our platform of choice, so they supported it all.

    so the main appeal of .pdf was that you were confident
    _anybody_ out there, on _any_ machine, could read it.
    and even those of us who hate .pdf had to admit that…

    that’s what was great about .pdf.

    you might have noticed i’m talking in the past tense…

    because that’s no longer true, not like it used to be…

    oh sure, .pdf as a _format_ is still ubiquitous.

    and lord knows there are millions of .pdfs out there…

    but you can no longer be certain that a _viewer-app_
    will be available on _every_ platform, no matter what.

    more and more often, e-book machinery is coming out
    that does not support .pdf. since there _are_ so many
    .pdfs out there in the wild, people bellyache about that.
    (that’s how a bad de facto standard perpetuates itself.)

    in the past, adobe itself took responsibility for the ports.

    but they are increasingly tossing it into the lap of others.

    moreover, in the past, adobe’s viewers were rock-solid…
    they were bloatware, yes, total bloatware, and they were
    often dog-slow (especially with search), but they worked.
    they didn’t crash… they required a lot of memory, sure,
    but they didn’t have memory leaks that wasted memory.

    but adobe has lost its way.

    its programmers seem to have lost their mojo.

    increasingly, their apps crash, even hang your machine.

    their updater programs are now a very bad industry joke.

    and virus exploits have become extremely embarrassing.
    (we’re in the middle of one right now, with a fix to come
    “in april”; 2 long months away, and it’ll probably be late.)

    adobe bought out competitor macromedia a while back,
    because adobe was afraid of the potential of their “flash”.

    unlike the past, when adobe eventually quietly shelved
    technology of the competitors which they’d bought out,
    adobe has made flash the centerpiece of their new stuff.
    (for instance, its “digital editions” viewer-app is in flash.)

    time will tell whether that was ultimately a wise decision,
    but we already know now that, short-term, it’s a disaster.

    flash — as it is being implemented by adobe, anyway –
    eats memory, and it seems to make machines unreliable.

    but the story gets even worse.

    because the sheer number of different implementations
    of .pdf viewers now means a hodge-podge of capability.

    the basic functionality is still there, for the most part, but
    many of the “wrinkles” can’t be reliably counted on now.

    for example, in one of my experiments in the .pdf i made,
    a link does “fit-to-window” with a specific part of a page.
    it works just fine when i put the .pdf in the adobe viewer.
    but it _doesn’t_ work if i use the mac “preview” program.

    as another example, if i view my .pdf in “digital editions”,
    all the text on chapter-header pages is completely gone!
    why it happens (and on those pages and not any other),
    i dunno, i will have to perform troubleshooting to learn,
    and even then, the glitch might not be one that i can fix.
    it might well be an adobe, in their new viewer-program.

    same with the previous example. probably apple’s bug.
    or some capability which they haven’t implemented yet.
    or some capability which they might _never_ implement.

    moreover, we speak about “.pdf” as if it’s _one_ thing,
    but the truth of the matter is there are lots of versions.
    not only has adobe added capabilities to later versions,
    they even spun out one that’s “officially” a “standard”,
    and even got it accepted by the damn _government_!

    so in addition to varying implementations of _viewers_,
    we now have different underlying formats as well, but
    all of them are called under the general name of “.pdf”.
    in the coming decades, the version hell will be horrific.

    what this means is that you can no longer be confident
    someone else will _definitely_ be able to read your .pdf.
    maybe yes, maybe no — but you can’t depend for sure.

    and if they can’t, you likely won’t know how to solve it.
    “i dunno”, you’ll have to say, “it works on my machine”,
    the line technocrats always use to evade responsibility…

    and it looks like the incompatibilities will only increase,
    as we soon experience an explosion of new machines…

    and this d.r.m. crap that adobe is doing now? _that_
    will certainly make everything work smoother, right?
    no implementation difficulties to plague _that_, right?

    but because there’s no _competitor_ to .pdf out there,
    even as dissatisfaction over the incompatibilities grows,
    there’s not really all that much that we can do about it…

    except to cut the technocrats off at their greedy knees,
    and invent new systems that are powerful yet simple…

    which brings me to “z.m.l.” — zen markup language…

    ***

    ok, let’s talk about z.m.l.

    the main reason i created “zen markup language” is
    because i know that an e-book format can be simple,
    and still be a powerful e-book experience for readers.

    that’s because “the magic” ain’t in the format, kids;
    it’s in the _application_ that brings the thing to life.

    all those people yabbering on about file-formats are
    _missing_the_boat_. misguided, maybe even stupid.

    and that’s not all.

    another widely-pitched idea is that e-books are either
    “fixed” display (e.g., .pdf) or “reflowing” (e.g., .html),
    as if it must be either solid (fixed) or liquid (reflowing),
    which is _also_ misguided, to the point of being stupid.

    there’s no reason a format can’t default to fixed-display,
    and yet still be capable of reflow if the user asks for it…

    i invented such a format, and programmed tools for it,
    authoring-tools and viewer-apps, since you need both.

    some of my tools work offline, and others work online,
    because in tomorrow’s world, you’ll need to have both.

    in the long run, my format and my tools will prevail.
    (or perhaps a format like mine with tools like mine,
    mine just first iteration in this revolution of simple.)

    in the meantime, there are two big guns out there…
    the first is .pdf, the second is the web (a.k.a. .html).

    because these two are big guns, my format has to
    be able to _convert_ to them to be viable short-run,
    even if — in the long term — it aims to defeat them.

    .pdf is important because a lot of people ask for it.
    and the end-user is always right. never doubt that.
    as i said, .pdf is a bad format being perpetuated by
    its status as the status quo, but i cannot ignore it…
    so i will make it as powerful as i can, and then show
    specifically and precisely how my stuff is even better.

    .html (and its .xhtml/.css cousin) is another matter…
    because it’s the format of the web, and the _web_ is
    so extremely important, .html has to be one priority.

    .html is also important because so many other e-book
    file-formats can use .html as source for a conversion.
    so the ability to convert my .zml into .html means that
    i don’t have to worry about any _other_ conversions…

    i actually create 3 different versions of the .html-book.

    the first one puts the entire book into a single .html file.

    the second splits the book up into its separate chapters,
    with each put into its own .html file, for hardware that
    is too resource-constrained to swallow the whole book.

    the third .html version is the interesting one, however,
    as it creates a web-page for each _page_ of your book.
    this is where your readership will gather to discuss and
    make comments on the content of that particular page.

    some people, like bob stein, speculate that this is how
    the book of the future will evolve, that the discussion
    will be as meaty as the book itself, or even more so…

    for some books, certainly! but for most of ‘em, not.
    in my opinion, anyway. but that is beside the point,
    because — as an _author_– you absolutely positively
    want to gather your readership together so that you
    can get to know ‘em, interact with ‘em, impress ‘em,
    and so on, because they will be the people who will
    _support_ you, with cold hard cash, if you’re good.
    (and affection, and emotional support, and stimulation,
    and motivation, and whatever help they can give you;
    but mostly cash; they know that’s what pays the rent,
    and they want a roof over your head so you’ll write.)

    the publishers will die off. (and good riddance too!)

    in the future, authors will need to fend for themselves,
    create a direct link and form a strong bond with fans…

    your books — every page — will be the point of contact.

    it’s your responsibility to direct your readership to those
    points of contact, and reward them for gathering there…
    their reward is interaction with you, an author they love!

    this page-by-page web-site is how you gather your fans.

    ***

    so, in spite of the facts that i hate .pdf and .pdf sucks,
    i still have written programs that convert .zml to .pdf…
    the .pdf for “best of toc” is the product of one of them.

    further, i’ve written programs to convert .zml to .html,
    so that a book in z.m.l. format can be put on the web.

    moreover, the .pdf _works_together_ with the .html…

    each page of the .pdf has a link at the very top which
    takes you to the web-page for that page of the book…

    so even if a fan reads your book offline in .pdf form,
    they’re still just one click away from a gathering place.
    (can’t stress the importance of that enough; won’t try.)

    ***

    ok, so there’s your overview on my .pdf…

    but i’m pooped now, so i’ll put the .pdf up tomorrow…

    -bowerbird

  • bowerbird

    ok, i finally put the first draft of my .pdf up:

    > http://z-m-l.com/go/bomoc/bomoc.pdf

    here’s the text-file which created the .pdf:

    > http://z-m-l.com/go/bomoc/bomoc.zml

    and here’s how you access the web-version:

    > http://z-m-l.com/go/bomoc/bomocp001.html

    for a specific page, change the number in the u.r.l.:

    > http://z-m-l.com/go/bomoc/bomocp123.html

    the fact that every page has a unique u.r.l.

    allows us to reference any page in particular,

    but if you want to talk about a specific page,

    do not include the u.r.l. in your comment…

    just tell us the _page-number_, and we can

    ascertain the u.r.l. from that, meaning that

    your comment won’t have to await approval

    after its hold-up by the (stupid) spam filter

    merely because it contained a link…

    this .pdf has _lots_ of ugly aspects, some

    of which are intentional, as it is “the base”,

    from which will spring improved iterations.

    but there’s no need to detail the problems,

    because i can see them too. however, if it

    will make you feel better to attack the thing,

    go right ahead and be my guest… :+)

    (but i’ve already told you bottom-balancing

    was a shipwreck here, so no fair saying that.)

    the thing that you _should_ comment on,

    however, is whether the tricks i have used

    to _allow_justification_ of the body-text

    _without_ resorting to use of hyphenation

    worked to eliminate excessive loose lines.

    to sum up, are there too many loose lines?

    -bowerbird