Perfect Edition: A lightweight, responsive web e-book template

https://github.com/robinsloan/perfect-edition

by catacombs • 6 years ago

248 69 6 years ago

github.com

bovermyer• 6 years ago

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"

pronoiac2• 6 years ago

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... - 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."

kurizu4444• 6 years ago

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

thomascgalvin• 6 years ago

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?

pronoiac2• 6 years ago

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

dang• 6 years ago

I tried the demo: https://robinsloan.github.io/perfect-edition/build/web/index.... 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).

yingw787• 6 years ago

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!

limomium• 6 years ago

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

greatgib• 6 years ago

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.

tomcooks• 6 years ago

Exactly, I wonder what's so bad about scrolling on mobile that even reputable news sites need to implement the stupid horizontal swipe.

To the author: Great to see lightweight things anyways, it's nicely done and really swift.

andrepd• 6 years ago

This is addressed specifically in TFA.

MaxBarraclough• 6 years ago

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/

Koshkin2• 6 years ago

https://freebsdfoundation.org/our-work/journal/

Yeroc• 6 years ago

I generally prefer the pagination style of navigation for longer materials unless it's being used as reference material that I want to quickly search through. The reason being is that with scrolling I find it's easy to lose my place via accidental scroll. Again, it depends on the content and its use.

Wowfunhappy• 6 years ago

There's something about this format that makes it significantly easier for me to read.

On the web, my default is to skim. Actually reading a longform piece—line by line through every paragraph—is very hard.

Putting it in a "book" format doesn't completely solve the problem—I think some of it is due to the lower contrast of a screen versus paper or e-ink—but it definitely helps.

IggleSniggle2• 6 years ago

Hard disagree when it comes to reading a novel, at least in the context I generally read these days: on a mobile phone.

Tap/swipe/arrows to turn really switches my brain. And the fact that the goal of this library is to allow native support for everything else for the entire book (like find, etc) really makes this feel like using the Kindle app or the Apple Books app. It's the first time I thought to myself, "no, I wouldn't need to download the ePub and put it on Dropbox so that I can easily import it to my favorite eBook app. The html version is great."

What I didn't notice is if your page number is captured in the url or not (again, because I'm on mobile). That seems like an important feature.

wenc2• 6 years ago

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

[2] https://writing.stackexchange.com/questions/4674/is-emphasiz...

Vrondi• 6 years ago

It is also considered by some to be part of good web design to not remove underlining from links, because doing so breaks the default visual indicator of links.

wenc2• 6 years ago

That's fair, though one might wonder why it's important to link from headings at all.

Underlining in headings just hearkens back to the WWW of early 1990s.

chrismorgan6• 6 years ago

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 underlined links dead? Maybe not quite. Dying? 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• 6 years ago

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

throwaway4133• 6 years ago

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

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!

dvt• 6 years ago

This is awesome! You should do a Show HN:

The example is particularly poignant. It blurs the line between a book and a cartoon. This is what a children's book should be in 2020.

throwaway4133• 6 years ago

Thank you for checking it out!

The inspiration came from wanting to easily make kids' books with my son :)

IggleSniggle2• 6 years ago

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.

throwaway4133• 6 years ago

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.

vngzs• 6 years ago

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

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

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

projektfu• 6 years ago

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.

jessaustin2• 6 years ago

Haha we always reach for javascript first.

chrismorgan6• 6 years ago

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 to see the difference. It can be rather stark.

harshreality2• 6 years ago

Justified text looks pretty, but why does that matter? Most books are bought to be read, not to sit there admiring the right edge justification.

There's even a plausible theory that justified text is bad for readability (perhaps because the brain loses that hint of which line is which). I haven't seen a lot of studies[1] replicating it, but I don't see any studies taking the other side. There's also the problem that it alters the inter-word spacing, which might also reduce readability since the brain can't rely on consistent word spacing.

I sympathize if you're conditioned to be annoyed every time you see an unjustified right column, but that's not a reason to recommend justified text.

Publishers (and authors, when they're considering text style details) need to understand that ebook publishing isn't the same as publishing print books. For print, decisions about font and styling have to be made, because otherwise there's no text.

For an ebook, unless it's a picture book or textbook with careful design[2] or some other kind of book where layout is the primary concern and readability is secondary, no features of the main style of text should be hardcoded. It needs to be left up to the ebook reader, and whatever defaults plus user customization it has.

[1] e.g. https://doi.org/10.1111/j.1467-8535.1986.tb00491.x

[2] These kinds of books, where publisher-dictated styling makes sense, shouldn't even be published as epubs; it often ends up as a disaster no matter how hard they try. They should publish the books as pdfs only.

Shorel4• 6 years ago

To me, you are conditioned to prefer right aligned text.

It is OK, we all configure our readers to our taste.

Shorel4• 6 years ago

Thank you!

With modern 4k screens in very small displays the old argument of "computers don't have enough resolution to show justified text properly" becomes absurdly outdated.

We now have the technology to have nice justified text everywhere. Please use it.

Right aligned jagged text looks ugly.

dragonwriter• 6 years ago

One way to do this is with JavaScript implementations of the LaTeX hyphenation/justification algorithm.

Another is just to use CSS (text-align: justify).

Why use JS for this?

stakkur• 6 years ago

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

chirau• 6 years ago

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

young_unixer• 6 years ago

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.

asicsp2• 6 years ago

I felt like that too until I found that atril [1] and calibre ebook-viewer [2] work very well with epub.

[1] https://github.com/mate-desktop/atril

[2] https://calibre-ebook.com/

Shorel4• 6 years ago

Have you tried Thorium?

https://www.edrlab.org/software/thorium-reader/

robtherobber• 6 years ago

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/

Thorium Reader looks very promising.

chrismorgan6• 6 years ago

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.

jessaustin2• 6 years ago

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.

chrismorgan6• 6 years ago

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.)

krmmalik• 6 years ago

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• 6 years ago

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

jetgirl• 6 years ago

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

chrismorgan6• 6 years ago

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.

yobananaboy• 6 years ago

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?

jm_l• 6 years ago

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/

And you can see the repo here https://github.com/jminjie/zine

Koshkin2• 6 years ago

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

heydenberk• 6 years ago

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/ [1] https://www.robinsloan.com/overworld/week/5/ [2] https://www.robinsloan.com/overworld/week/3/

stevensawtelle• 6 years ago

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• 6 years ago

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.

chrisfinazzo2• 6 years ago

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

harshreality2• 6 years ago

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.

chrisfinazzo2• 6 years ago

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.

tyingq• 6 years ago

Maybe more basic than you want, but this looks helpful to me: https://ebooks.stackexchange.com/questions/1183/what-is-the-...

asicsp2• 6 years ago

I use pandoc [1] to generate pdf/epub from GitHub style markdown. I didn't know css, but learned enough to customize a few settings.

[1] https://learnbyexample.github.io/tutorial/ebook-generation/c...

michaelmrose• 6 years ago

Several issues from viewing 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• 6 years ago

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

aliswe• 6 years ago

Yes that being said the demo is an old version.

Shank• 6 years ago

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. 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• 6 years ago

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 ...

Shorel4• 6 years ago

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

https://doc.rust-lang.org/book/ch01-01-installation.html

Perfect Edition: A lightweight, responsive web e-book template

Related Stories