
Perfect Edition: A lightweight, responsive web e-book template - catacombs
https://github.com/robinsloan/perfect-edition
======
heydenberk
The author (of both the book in the demo and this software itself) is Robin
Sloan. He publishes a couple email newsletters, all of which I recommend. Most
recently he's been writing a development diary for a video game he's working
on[0]. He published a handful of GPT-2 generated city descriptions based on a
corpus of fantasy literature that was a lot of fun[1]. There's great content
about the illustration style as well[2]. I recommend the follow.

[0]
[https://www.robinsloan.com/overworld/](https://www.robinsloan.com/overworld/)
[1]
[https://www.robinsloan.com/overworld/week/5/](https://www.robinsloan.com/overworld/week/5/)
[2]
[https://www.robinsloan.com/overworld/week/3/](https://www.robinsloan.com/overworld/week/3/)

~~~
stevensawtelle
It's a seriously cool feeling to see worlds collide like this. The first half
of his book Mr. Penumbra's 24-Hour Bookstore is one of my favorite reads, but
I had no idea he was actively programming as well (although it totally makes
sense in retrospect).

~~~
tqi
I also really enjoyed Mr. Penumbra's 24-Hour Bookstore. Looking back on it now
I felt like it captured a more hopeful / innocent time in the way it
technology and the ways it has changed our modern society.

------
michaelmrose
Several issues from viewing [https://robinsloan.github.io/perfect-
edition/build/web/](https://robinsloan.github.io/perfect-edition/build/web/)

\- Having the pages you can't actually read on each side is distracting and
wastes a ton of horizontal space.

\- Moving the browser window to a different monitor with a different
resolution can result in you being stuck half way between pages and needing to
scroll to reset positioning. Resizing has the same effect. Anything that
changes the window size should probably do a better job of resetting position.
Its an interesting question as to where the page should reflow to but it seems
like it would be optimal if the newly flowed page started at the same
position.

\- When scrolling by touch on my touchscreen laptop there is a fair bit of
inertia when flicking it hard and not much at all when moving it lightly
making it easy to end up not exactly centered. Given that you actually can't
read it that way and nobody on planet earth is trying to end up halfway it
should be hard to end up in that condition. It ought to snap the rest of the
way if you scroll it part of the way to the next page. Where the threshold to
end up on the prior page and the threshold to end up on the next is, is
another question just don't let it end up halfway!

~~~
tangjurine
Yeah, I'm on Android (pixel 3a) and it's really hard to scroll only one page
at a time for me.

~~~
aliswe
Yes that being said the demo is an old version.

------
vngzs
If you open most books on the shelf you will notice that text is not left-
aligned, but is in fact justified to create a consistent vertical margin on
the right-hand side[0]. It's the big thing I always miss when I try reading on
the web.

One way to do this is with JavaScript implementations of the LaTeX
hyphenation/justification algorithm. Check out [1] and [2] for examples.

[0]: [https://i.imgur.com/65ICUVW.png](https://i.imgur.com/65ICUVW.png)

[1]: [https://github.com/robertknight/tex-
linebreak](https://github.com/robertknight/tex-linebreak)

[2]:
[https://github.com/bramstein/typeset](https://github.com/bramstein/typeset)

~~~
projektfu
I haven't looked through fully to make sure it has no ill effects, but if you
add to the css on p:

    
    
       text-align: justify;
       text-justify: inter-word;
    

you should get what you're looking for. At least it worked in Firefox
inspector.

~~~
chrismorgan
Don’t think I’ve _ever_ seen anyone suggest setting text-justify. It’s one of
those properties that I could imagine having been used in anger and with cause
(justifiedly :P) less than a hundred times _in total_ , though the true number
is probably higher than that. Anyway, in this case it won’t change anything,
because the text is English, and the default value of auto will be equivalent
to inter-word. (If the text was Japanese, it would actively harm things,
because auto would be equivalent to inter-character, and you’d mess that up.)

Anyway, in all current browsers, `text-align: justify` does greedy text
layout, where it fits as many words in each line as it can before wrapping.
This is technically trivial, but visually inferior to Knuth-Plass line
breaking, which tries to find the most visually-pleasing place to break lines.
Look at the screenshots of [https://github.com/robertknight/tex-
linebreak](https://github.com/robertknight/tex-linebreak) to see the
difference. It can be rather stark.

~~~
cosmojg
Are there any implementations of Knuth-Plass line breaking in HTML or CSS
libraries? Maybe in a static site generator?

~~~
mpetroff
It's possible, but the markup is very, very messy. I made a proof-of-concept
by hand a couple months ago [1], but it would require quite a bit more work to
automate it. It's probably best to just wait for browsers to implement CSS
Text Module Level 4, which includes a property for enabling use of better line
breaking algorithms.

[1] [https://mpetroff.net/files/pre-calculated-line-breaks-
demo/](https://mpetroff.net/files/pre-calculated-line-breaks-demo/)

------
greatgib
The work is nicely done.

But each time I see a website presenting a book content or catalog in pages
like that, like if it was a real book, it really pisses me off.

It is a design move that goes against ergonomy.

Harder/slower to browser, harder/slower to seek, you have to do a mental break
while pages are changing with effect that does not get the same efficiency
feeling than a real book.

~~~
MaxBarraclough
Agreed. The best way to deliver text over the web, is to make an ordinary web
page. The web not a paper-based technology, and shouldn't emulate paper.

I recently discovered the FreeBSD Journal. [0] These days it's only available
online, but your only options are to download a PDF, or to view it in the
browser in what seems to be a JavaScript-based PDF viewer. Their viewer seems
to lack vital features such as zoom levels. A pity, as the content is very
good.

[0] [http://www.freebsdjournal.com/](http://www.freebsdjournal.com/)

~~~
Koshkin
[https://freebsdfoundation.org/our-
work/journal/](https://freebsdfoundation.org/our-work/journal/)

------
throwaway413
Nice! I recently built something similar, but less longform:

[https://booklitapp.com](https://booklitapp.com)

(The demo on the homepage is swipeable on mobile and draggable on desktop.)

My goal was to be mobile-first. One thing I haven't added yet is a table of
contents generator - I like how you have the TOC toggle at the bottom!

~~~
IggleSniggle
This is nice! Since you mentioned you wanted to be mobile first, I should
mention a couple issues I ran into on my phone:

The header bar, with Login and Signup on the right, did not fit on my screen
(stopped right around the "S" of Signup), and I was not able to horizontal
scroll the header to get to that link, even though it _look_ like it would be
horizontal scrollable.

It seemed like while I was interacting with the book on the front page, either
the book jumped up and down or the vertical scroll jumped up and down (I'm not
sure which) as the sell-text was written and removed.

~~~
throwaway413
Thanks for this feedback! Really appreciated - I'm working on an overhaul of
the landing page but I'm going to quickly fix these two issues in the mean
time.

------
wenc
Just had some feedback about the demo: I noticed chapter headings were being
underlined (anchor links).

I wonder if I might persuade the layout editor that the aesthetics would be
improved if the underlining was removed?

Underlining is a holdover from the days of typewriters, and considered
unaesthetic in professional typesetting [1, 2]. It's really only done in
scripts, manuscripts and other non-published documents.

[1]
[https://practicaltypography.com/underlining.html](https://practicaltypography.com/underlining.html)

[2] [https://writing.stackexchange.com/questions/4674/is-
emphasiz...](https://writing.stackexchange.com/questions/4674/is-emphasizing-
a-point-by-underlining-still-appropriate)

~~~
chrismorgan
I agree with almost all of the content of Practical Typography. But “stop
underlining links on the web” is the point I disagree the most violently with.
Removing link underlines is user-hostile. There’s a large body of research to
that effect: underlined blue text means a link, not-underlined text in a
colour different from the surrounding text… _might_ be a link? But many will
miss it. “Are un­der­lined links dead? Maybe not quite. Dy­ing? For sure.”
Nope. Not dying in the slightest. If anything they’ve been making a comeback
as people come to their senses and realise that æsthetics aren’t the only
thing to worry about. (You know what has really beautiful æsthetics? A pure
white screen.)

Now _in this particular case_ , I don’t feel the chapter headings should be
underlined—because I don’t feel they should _be_ links. As it stands they
don’t even look like links, just like underlined headings. If you want to
provide a link to this heading, do it otherwise: probably as a character
outside the left margin of the heading or after the text of the heading,
commonly using # or ¶ or U+1F517 LINK SYMBOL, potentially only visible on
hover (not many people want to interact with those things, after all, so it’s
fairly OK to conceal them).

~~~
smichel17
How do you feel about underline on hover, as a compromise between aesthetics
and functionality? Eg,
[https://sdproto.gitlab.io/](https://sdproto.gitlab.io/)

~~~
chrismorgan
I say it’s simply a bad technique.

But here’s what I think is a good compromise in this space: a semi-transparent
underline, made opaque on hover. I’ve taken to doing this for sites I make in
the last couple of years as I find it makes links more pleasant to look at,
_and_ it gives a convenient way of indicating when you’re hovering over a
link, which I think is also desirable. For example
[https://chrismorgan.info](https://chrismorgan.info) unvisited links are #03d
with text-decoration-color #03d4. (It was #03d6 when I released the site, I
reduced it to #03d4 after a while.)

Sadly this currently requires adding a text-decoration-color property beside
every link colour declaration, so if you vary your link colours in different
contexts it requires a little more work, and if you want to make it themeable
by variable you’ll have to use a preprocessor that can modify colours (e.g.
scale-color($link-color, $alpha: -75%) in Sass), or use multiple CSS custom
properties (--link-color: #03d; --link-underline-color: #03d4). I look forward
to being able to just say `:link:not(:hover), :visited:not(:hover) { text-
decoration-color: color-mod(currentColor alpha(25%)) }`.

------
chrisfinazzo
This is nice, but I'd still like to find a no frills, to-the-point explainer
on how to assemble an epub from standard tools. After all, it's really just a
zip archive with a couple directories and some specially named files.

All of the tutorials I find are either woefully out of date - usually they
can't create valid EPUB3 content, require stupid software like Java due to
epubcheck, or just punt the whole issue to something like Calibre, Sigil, or
worse, InDesign.

Have no actual, working programmers - save for John Siracusa - ever seen an
epub file?

/rant

~~~
harshreality
Create an empty epub in calibre or vellum or any other editor that will create
epubs for you; then unzip it and edit it raw.

You can do the same thing with a professionally published epub.

In either case, you can rip out the metadata files (opf, ncx, etc.) and create
templates from them, which you can reuse in your own projects without
beginning in an epub editor or generator.

You still probably want to run an epub through checking before you publish it,
to make sure the metadata is consistent with the contents, and that you're not
violating epub[23] rules (unless you know the standard perfectly as it applies
to to subset you're using, and you never make any mistakes), but you don't
have to be using any bloated tooling during the main phase of writing and
editing the book.

~~~
chrisfinazzo
That would work, up until I actually try to re-zip the contents. Last I looked
at the spec, it requires things to be done in a particular order (as @tyingq's
link indicates) and although I've used pandoc to convert some other documents,
coming up with the proper incantation to feed into it seems like more trouble
than just doing it yourself.

More to the point, things like my Oral Defense required certain elements to be
on a given page (e.g, p.1-2 were front matter and the text began on p.3) and I
don't know if that kind of control is possible in pandoc.

With regard to validation, there used to be a web form at validator.idpf.org
which let you upload a finished book and it would scan for errors, but that
page seems to be gone.

I don't doubt that epubcheck works, it's just a shame that it requires a huge
download to enable its functionality and one which doesn't really play well in
macOS.

I'm perfectly ok with doing the creation and editing by hand, but come on,
this is a UNIX system (!) and the absence of a better command line tool for
validating output is imho inexcusable.

------
yingw787
Nice! Not sure if you're looking for feedback, but I had two interesting
observations:

1\. Ctrl + back arrow (to go back to previous webpage) doesn't work, I think
there's a redirect loop to the primary index.html page (easy enough to go
around)

2\. Zoom in/out doesn't resize the selector, instead the window stays the same
size while the text changes, and some part of the previous/next page are in
focus (not a big deal).

Looks really cool, thank you for sharing!

------
Shank
I really would appreciate more sites trying to copy the Holloway reader (seen
in the equity compensation guide here: [https://www.holloway.com/g/equity-
compensation](https://www.holloway.com/g/equity-compensation). The most ideal
readers have things like interactive tables of contents, a huge focus on
typography, in-line citations and organization. Books on the web should take
full advantage of the web without going overboard on javascript -- it's
totally possible but this format is almost never used.

~~~
sah2ed
Your holloway link is completely unreadable on mobile. After a few scrolls, it
hijacks the viewport with an undismissable modal that forces you to sign in
...

------
jm_l
I did something similar using Github pages (no serverside stuff needed) for an
e-zine I recently published. Hopefully removing the server-side component
makes it easier for other creators:

The zine is here:
[https://jminjie.github.io/zine/](https://jminjie.github.io/zine/)

And you can see the repo here
[https://github.com/jminjie/zine](https://github.com/jminjie/zine)

------
thomascgalvin
This is very cool.

Can the artifacts generated in `build` be served as static content? EG can I
just upload it to a website, rather than running the ruby server?

~~~
pronoiac
Yes, the demo's hosted on a github.io page.

------
limomium
Has the slowest scrolling by wheel I've ever seen. I scroll and scroll and
watch the next page inch over for an eternity.

------
young_unixer
I've given up on reading epubs on my computer. All epub readers are crap:
inappropiate fonts, weird spacing, no sheet margins (like the ones pdf readers
have), etc.

PDFs, on the other hand, look nice 95% of the time, unless someone uses
calibre to convert an epub to pdf.

~~~
Shorel
Have you tried Thorium?

[https://www.edrlab.org/software/thorium-
reader/](https://www.edrlab.org/software/thorium-reader/)

~~~
robtherobber
What an excellent little tool! Thanks for suggesting this.

I've settled for an epub reader (after testing many others) with which I'm not
entirely happy: [https://icecreamapps.com/Ebook-
Reader/](https://icecreamapps.com/Ebook-Reader/)

Thorium Reader looks very promising.

------
Shorel
I really like the e-book template used for the rust book.

[https://doc.rust-lang.org/book/ch01-01-installation.html](https://doc.rust-
lang.org/book/ch01-01-installation.html)

------
jetgirl
Very nice, my scroll wheel makes it go really slow but that is probably an
issue on my end.

~~~
chrismorgan
Not your fault. It’s impossible to do a good job of what’s being attempted
here on the web, because the web doesn’t expose the right primitives to make
it possible. Notwithstanding that, it _is_ possible to do better than this has
done.

I ever say that scrolljacking is _always_ bad.

------
kurizu4444
Love this idea, are you looking for open source help?

------
Koshkin
This is great. It is indeed the web browser that should be seen today as _the_
e-book reader (among other things).

------
krmmalik
I would pay for an out of the box version of this with a bookmark feature. I
am an author that can't code. Help

~~~
pwdisswordfish2
Seems easy enough. What are your requirements exactly? The bookmark would have
to be stored somewhere. Some options in order of complexity:

1\. In the URL, eg. “example.com/#line1234”

2\. In the user’s browser (cookie, local storage)

3\. On the server, requiring users to have accounts and be logged in

------
yobananaboy
I think it's really interesting that it's hard to find exactly what the
meaning of "Perfect Edition" is in the English internet. I was curious about
what it means in the manga world, and all I can guess at is that it's multiple
manga issues bundled into one hardcover book printed on glossy paper. Anyone
know anything else (or more accurate) about the etymology of the term?

------
stakkur
It looks nice, but--am I and my friends the only ones that never read a long-
form book in a web browser?

~~~
chirau
Not sure if it is exactly long-form, but I use O'Reilly Learning and its
online textbooks are wonderful.

------
bovermyer
I love this and will use it.

I also love one of the lines of text in the slider image:

"The burrito cannons blared at noon"

~~~
pronoiac
It's part of the demo, Annabel Scheme and the Adventure of the New Golden Gate
- [https://robinsloan.github.io/perfect-
edition/build/web/index...](https://robinsloan.github.io/perfect-
edition/build/web/index.html) \- which I'm reading now. The creator of the
project is Robin Sloan, fiction author; I liked his book "Mr. Penumbra's
24-Hour Bookstore."

------
chrismorgan
I deem that almost all of the value of pagination on most devices¹ is in
_static_ pagination: that you can refer to things by page numbers, that it
helps your memory, things like that.

I am a Christian and read my Bible daily, and I know just where on the page a
great many things that I might look for, which helps me to find them rapidly
when I don’t remember the chapter and verse. In the not-too-distant past (say,
1800–2010), those people that cared about the Bible would mostly have a
primary Bible that they used, and would get such advantages from; but
increasingly people shift to using software Bibles, and Bible software is
uniformly _terrible_ for being one’s primary Bible. (Uniformly; there does not
exist any software that is not terrible for this purpose.) I have thought long
and hard about these problems, and have software in mind that, combined with
the right hardware (which has to start with a high-resolution tablet with
pen), could make a decent primary Bible. Operating _primarily_ by static
pagination (trying to pick the best features of the digital and paper worlds)
will be an important part of this. It remains to be seen just how well spatial
memory will work once the pages are not physically embodied; to my mind
that’ll be the greatest hazard, and define whether I can switch to it myself.

To be sure, operating solely by static pagination in software is challenging:
what do you do if you don’t have a known static device size? Shrink everything
down tiny so that it’s not readable? Have done multiple columns on the page so
that you can show just a _column_ at a time? (That may be a possibility with
Bibles which are commonly two columns per A5-or-not-much-larger page, but it’s
not common outside Bibles.) Most commonly it’ll be better to give up on the
pagination. So such static pagination is the sort of thing that Kindle can do
to a large extent, but a general-purpose ebook that might be viewed on a
phone, a laptop, _& c._ really can’t. Any reference materials like textbooks
that are presented in PDF form for its static pagination will tend to cause at
least some pain in matters of page sizing, and they’ll normally be accessed
with vertical scrolling of pages rather than attempting to emulate a paper
book too closely.

But other than when you have static pagination, on the aforementioned “most
devices”, pagination is fairly strongly inferior to scrolling in its
experience. For starters, you’re replacing a well-understood and consistently-
implemented primitive with something that’s just… _different_. Different is
normally bad. Different is even more normally badly implemented.

This project is going for pagination without static pagination. I think that’s
a terrible mistake given how people interact with most works that might be
framed in this thing (that is: mostly works of fiction that people will
typically want to read from start to end). Its implementation is seriously
dodgy: Shift+Space, Home, End, Page Up and Page Down don’t work. Scrolling
with a wheel is just completely wrong and breaks the pagination model into
smithereens.² Panning with touch breaks the pagination model into as many
smithereens again. Swiping from outside the portrait page area doesn’t work at
all.

To correct the final sentence on the first page of the demo:

Basically, nothing works properly.

Horizontal pagination like this is simply a poor fit for the web (and is very
tricky to get right, or as close as you can to right, on general-purpose
OSes).

But props on handling the no-JS case pretty well. :)

———

¹ “Most devices” means “devices that can handle scrolling well”, which means
approximately any device with a high-speed display (such as an LCD or OLED
display, and typically excluding e-ink displays) and some form of rapid and
relatively precise means of scrolling (e.g. touchscreen panning, or a touchpad
with scrolling, or to a very slightly lesser extent Space/Shift+Space/arrow
navigation, so long as the user knows about them, and depressingly many don’t;
ugh, the times I’ve seen people slowly move the mouse cursor across to the
scroll bar with the ill-calibrated touch pad that they don’t realise offers
two-finger scrolling, and click and drag the scrollbar thumb to scroll the
page). For devices that _don’t_ handle scrolling well, such as most e-paper
reader devices, pagination has rather more obvious benefits.

² As an aside, it’s fundamentally impossible to implement scrolling fully
correctly on top of a paginated source on the web, firstly because there’s no
such thing as correct—users will want and prefer different things, all of them
between hard and impossible—and secondly because hardware varies too much so
that any attempts to make dual-axis scrolling work on the web _will_ fail
smoothness tests at the very least, and typically fail much more than that;
and attempts to do things like scroll snapping to pages will irritate at the
very least a substantial fraction of your users because it messes with their
declared intent, and hardware varies enough in what it supports and reports in
scrolling that it’s very impossible to do well for everyone. Outside the web
platform you can do better on both these points, but general-purpose
perfection is still pretty much unobtainable due to input hardware variation.

~~~
jessaustin
You might have a point in general, but the Bible is a poor example of the
issue you highlight. The Bible has had the solution to your problem built-in
for centuries already. Bible passages are identified by chapter and verse; no
one refers to Biblical passages by page numbers. Bible software shouldn't
bother with pages at all. It should instead allow reading to flow smoothly
from one verse to the next, and only create hard breaks at chapter boundaries.

[EDIT:] Anyway it seems like conversion to PDF is what you want.

~~~
chrismorgan
Human memory is a funny thing. Overall, people are comparatively poor at
remembering words and numbers. We’re much better at remembering various other
things, so people set words to music because it makes remembering them
_vastly_ easier. Spatial matters are like this too: we’re simply better at
remembering spatial positions of things we’ve experienced than other
linguistic references to them. If you ask me where the parable of the sheep
and the goats is, I can tell you it’s at the bottom of the fourth column, and
find it very rapidly, immediately framed in its context of all that Jesus was
expounding in Matthew 24–25.

(That’s also why hard breaks at chapter boundaries is a horrible idea. They
split stories artificially all the time. If you must do scrolling, make it
infinite scrolling.)

When I have to use a different Bible from my primary one, it’s _really_ hard
finding everything I want to find, because it’s just not in the right place on
the page! It’s similar for spatial memory of things relative to other books,
or relative to the length of the Bible as a whole: you just get a better sense
of how it all fits together. (That’s what I was going for with the parable
reference last paragraph.) Accessing things only by references and searches
and scrolling disembodies it and I am convinced does a great deal of harm in
comprehension.

For purely _reading_ the Bible, yes, PDF is a good solution. But that reduces
it to a very poor imitation of paper, discarding almost all the potential
strengths of the computer (weak search is the only one retained).

I can keep my finger in two or three places in the Bible and flip between them
and other such things—it comes naturally and can genuinely be called
intuitive. Unless you go skeuomorph, no interface for achieving anything
similar on the computer is ever intuitive, and obtaining even halfway good
ergonomics is extremely difficult. (A skeuomorph is no panacea here, but I
think it can make things easier. My point is more about the conceptual
advantages of the old medium, with a view to attempting to integrate its
virtues rather than just discarding it because we’re on a different physical
medium now.)

------
dang
I tried the demo: [https://robinsloan.github.io/perfect-
edition/build/web/index...](https://robinsloan.github.io/perfect-
edition/build/web/index.html). It's very nice.

Since I was using the space key to page forward, it would be nice if
shift+space would page backward (by analogy with scrolling up and down on mac
os).

