Monday, July 15, 2013

e0 Incarnate, and a Note on Navigation

e0 Incarnate

The first e0 file is, of course, Moby-Dick, available for download here. Those of you who have followed the conversation will notice that it is much like the original proposal, with one exception.

A Note on Navigation, Reading Order, and index.html

The major change is the handling of the primary navigation in index.html. On the mailing list, we reached a consensus that the role attribute would be the primary method of adding semantics to HTML5 elements, thus avoiding namespaced attributes (epub:type), HTML5 data- attributes, and other such horrors.

The primary vocabulary for @role will be the EPUB3 Structural Semantics Vocabulary, extended as needed. How can this help with index.html? I'm hoping this will allow us to use a single nav element to function as both nav and spine.

For the first nav element in index.html, we will define the default behaviour to be as if every element was role="toc spine". This means:
  1. The element appears in the default navigation structure ("toc")
  2. The element appears in the document's linear reading order ("spine"), as in EPUB's linear="yes".
So if an element is marked as role="toc" it means it does appear in default nav, but is not in the default linear reading order. If an element is marked as role="spine" it appears in the linear reading order, but does not appear in default navigation. If you don't want either function, just leave the section out of index.html//nav[1]. There is no obligation to list all content documents in the e0 folder.

One can choose to hide the default navigation from displaying on the index.html page by using the hidden attribute.


  1. sorry, dave, but that's not even close.

    first, your file-naming convention is terrible.

    when mounted on the web, those filenames
    become deep-links into the content, so you
    want to have them make a lot more sense...

    embedding the section-number at the start
    of filenames is an awful idea for that reason.

    there are other problems that will arise from
    a programmer's perspective, which seems to
    be the major problem with your scheme here,
    namely that you don't seem to have one, but
    please feel free to inform me that i'm wrong,
    because it would be entertaining for me to
    hear somebody explain why, and i'd enjoy it.

    meanwhile, take it back to the drawing-board.


    p.s. if you want to hear my suggestions,
    i'm more than happy to give them to you.
    or you might just want to take a look at
    the work i've been putting out recently...

  2. E0 doesn't have a filenaming convention, beyond index.html. So I'm free to display my ignorance by choosing terrible filenames, and you're free to display your erudition by choosing brilliant filenames.

    But my filenames sort into the order of the book, which I find useful when troubleshooting. They tell me what kind of thing each file is, which I also find useful.

    And if the filename is a deep-link into the content, I have no problem with:

    especially when compared to something like:

    In fact, many people could look at my URL and recite the first three words of the book, which would be much more difficult with the second URL :)

  3. dave-

    well, at least you looked at some work i did.
    even if it was stuff i did several years ago...

    that's what i like about you, dave, you are
    a pro, who's got his sleeves rolled up and
    gets his hands dirty doing the real thing...

    i also know that you are smart enough and
    practical enough to change your mind if you
    see a better alternative, so i'll show you one.

    here's a good-looking deep-link for you:

    or, even better in the vast majority of cases:

    (unfortunately, that latter one doesn't work, in this case.
    but it certainly should, and you can bet that i'll fix that.)

    or, once society makes its global cyberlibrary:


    (all books would have an 8-letter name, so the fact that
    the one for "moby dick" is "mobydick" is a "coincidence".
    it could equally well be, say, "pwfprnte", or "bigfishy" or
    "thewhale" or "albatros". for an informative comparison,
    look at the letters you see in a u.r.l. for a youtube video.)

    at any rate...

    these are better links because the average person will
    wanna link right to a specific chapter in moby dick, and
    they aren't gonna know how to do it with your system,
    because they don't know what 's###' number to put
    in front of the "chapter-001" part of your link there.

    they probably also won't know they need to put a dash
    between "chapter" and the chapter-number, because
    -- as you frankly admitted -- you have no convention
    for your file-naming, so they can't expect consistency.
    (and, sure enough, you have no hyphen in the 's005'.)

    furthermore, are you always gonna pad to three digits?
    or just if -- as in this case -- they are 100+ chapters?

    what happens if you realize you forgot a section in the
    front-matter, so you add it, and all of a sudden, that
    means that every link following that one has gone bad,
    because the 's###" prefix now needs to be 's###+1'?

    now, i don't blame you for not understanding the range
    of possible problems that your file-naming can produce
    as it morphs from individual book into the global library.
    i've been studying this stuff very closely for a decade,
    and i still see cases where a unique problem surfaces.

    and this mistake that you have made is one that many
    first-time-out-doing-this people have made, so it's
    not like it's unexpected or something. but despite that,
    it _is_ a terrible system, and it's perfectly proper and
    _correct_ that we call it out as a terrible system, and
    understand the reasons why, and go on to change it.

    so, be a pro, dave, and change it.

    making the mistake doesn't change my opinion, which
    you _know_ i have stated several times, that you are
    one of the smartest guys in the e-book sphere today.

    it's only if you refuse to acknowledge the mistake, or
    refuse to correct it, that'd make me change my mind.

    but as it is, i fully expect that, since you _are_ one of
    the smartest guys in the sphere, you _will_ learn this.