Proposal to rework drama to not use tables

[robinwhittleton]

We currently use tables to lay out drama, but this is problematic:

1. Apple Books has a zoomable table viewer mode that shows up when you click on the text, and breaks the reading experience.
2. Screen readers typically have a special table viewing mode that moves the user into a row / column navigation metaphor.

We’ve attempted to work past the first problem in the past with CSS that disallows clicking on tables, but this has the side effects of breaking selection and dictionary lookup.

First attempt to properly fix this

I tried adding role="presentation" to the drama tables. This is the recommended fix for problem 2, and partially resolves 1, but it’s really flaky: some parts of the table no longer produce a viewer mode, but not others. I attempted to add role="presentation" additionally to the table rows with no luck.

Second proposal

This would be considerably more work, but I think we should evaluate using display: table with classed divs instead. To test, I converted The Libation Bearers, replacing <table> with <div class="drama-table">, <tr> with <div class="drama-row">, and <td> with <div class="drama-cell">. I then added appropriate display: table / display: table-row / display: table-cell to local.css.

Testing in Apple Books (with the viewer suppression hack removed), this looks fine:

I don’t have a physical Kindle, but I tested loading the same epub into Kindle Previewer, and it looks fine there too:

Work to be done

If we decide to go ahead with this, then the good thing is that it doesn’t need to be a big bang release. The proposed timeline would be:

1. Test the proposal with physical Kindle, more ereaders, and more dramas, to find latent compatibility issues.
2. Rework the manual, and any supporting how-to guides with the new approach.
3. Produce a script that would do the majority of the rework automatically against a book.
4. Rework lint to remove the drama workarounds from table checks.
5. List all productions with drama, and split them up among volunteers to each do the rework, fix outstanding issues the script didn’t cover, and test.
6. Once all the existing books have been converted, remove the Apple Books compatibility hack from the CSS.

Question

Worth it?

[acabal]

Good work. I think role="presentation" would be the best way forward as it is technically correct while avoiding having to redo the whole corpus.

Using <div>s might also work... our current approach is, after all, semantically incorrect, and we only do it because it's the best solution for our appearance requirements given old bad renderers.

We could even avoid the extra classes by selecting .drama > div{ /* table row */ } and .drama > div > div{ /* table cell */ }.

However I suspect that display: table* isn't going to work on ADE which is still a significant portion of readers. You can test by uploading a plain epub (not kepub) to a Kobo, which will trigger the ADE renderer. You may also still be able to download a desktop version of the ADE reader to test? Haven't looked in a while.

In any case, any solution we select has to work in ADE.

[acabal]

https://www.adobe.com/solutions/ebook/digital-editions/download.html

[acabal]

I think even if none of this shakes out, we should at least add role="presentation" as the standard because that is semantically correct.

[robinwhittleton]

display: table seems to work nicely in ADE 4.5.12 on my mac:

Whatever version of ADE is installed on my Kobo originally looked like a mess (although the display: table layout worked) until as a test I copied over the current release version of The Libation Bearers and got exactly the same result. So we know that this alternative approach isn’t specifically broken at least. Here’s a photo of my custom build:

[robinwhittleton]

I guess the next step would be to test on a physical Kindle? If you (or anyone else reading) has one I’ve attached my reworked display: table AZW3 (zipped to keep GitHub happy). We’re looking for horizontal alignment of persona to their text, as per the screenshots in this issue.

aeschylus_the-libation-bearers_gilbert-murray.azw3.zip

[acabal]

Can you send the compatible epub version that I can try sending to my Kobo?

[robinwhittleton]

Certainly. Here’s the compatible and Kobo variants.

[alerque]

Here are some screenshots of assorted pages from an aging Kindle Paperwhite (Kindle firmware 5.6.1.1):

https://photos.app.goo.gl/4C85aEA4MSxUsGj97

If any other pages or perhaps text size views would be useful just let me know. This is just at the text size and preferences I had from last reading a book.

[acabal]

OK, I tried it on my very old Kindle Voyage and Kobo Aura One and they both look good.

Lastly I think we should try the renderers on some of the bigger ereading apps. Google Books, Kindle app (not the same renderer as the eink Kindle), Nook app, Moon+, FBreader. (FBreader I recall has an especially bad renderer so I'm not super concerned if it doesn't look perfect in that one.)

[robinwhittleton]

Google Play

Kindle macOS

Thorium

FBreader

Moon+ seems to be Android-only, and I don’t have an Android device available currently. And Nook is US-only, it won’t let me download from the Swedish app store.

[acabal]

OK looks good.

The next question is, how would we handle the .together class, e.g. here?

@EmmaSweeney do you have any thoughts on this proposal?

[robinwhittleton]

In Apple Books it seems to work fine. Borders, padding and vertical-align should work in anything that supports display:table. Screenshot from Books with my test build:

[acabal]

But what about multiple speakers together in one dialog? We used rowspan before. We'll have to think of something else.

[robinwhittleton]

Right, yes. Let me have a think about how to handle that.

In the mean time, I’ve started a branch with a convert-drama command. The goal here isn’t that this will be merged in, but it should make it easier to update the corpus by automating the conversion process before checks. At the moment the command just fixes standard drama markup, CSS and .together rowspans will follow.

[EmmaSweeney]

I'm happy that we are improving the reading experience for our plays! I don't think there is anything besides the together class that could cause any problems when switching to this format. Have you tested this on drama dialog in an epigraph (example)?

[robinwhittleton]

The convert-drama command branch now will automatically convert CSS as well, although typically it’ll warn that at least one new rule will need to be moved to a reasonable place.

Next up: rowspans.

[robinwhittleton]

Sorry, didn’t see your question @EmmaSweeney. I just tested on Unnatural Death and it works fine. (Incidentally I‘ve been listening to a pretty good radio adaptation of that for the last couple of days 🙂)

[robinwhittleton]

To set the scene for rowspan, we’ve got 40 books in the corpus that use the together class and 13 of those have rowspan, so I think we can get away with manually rebuilding markup if necessary.

Obviously we can’t use rowspan directly as that doesn’t work with CSS display: table (yet). So we’ll need to find an alternative approach.

My initial suggestion is to move to a single row, with the first “cell” div containing multiple <b epub:type="z3998:persona"> references. I’ve mocked this up in Major Barbara:

<div class="drama-row together">
	<div class="drama-cell">
		<b epub:type="z3998:persona">Sarah</b>
		<b epub:type="z3998:persona">Lady Britomart</b>
		<b epub:type="z3998:persona">Barbara</b>
		<b epub:type="z3998:persona">Stephen</b>
	</div>
	<div class="drama-cell">Confession!</div>
</div>

I’ve left the existing .together CSS as it was, but added in the following rule:

.drama-row.together .drama-cell:first-child [epub|type~="z3998:persona"] {
	display: block;
	text-align: right;
}

This results in this rendering, which is pixel perfect to the current:

As a first stab, how does this approach sound?

[acabal]

OK, I think that looks reasonable.

Shouldn't a persona cell have text-align: right in all cases anyway? Why do we have to specify it for children?

Additionally, maybe we can use <div> and not <b> to style the individual children, which will give us display: block for free. <b> is not semantic anyway and the children should already get small caps styling from the parent.

[robinwhittleton]

All good points. The current default drama styling has:

[epub|type~="z3998:drama"] td[epub|type~="z3998:persona"]{
	hyphens: none;
	-epub-hyphens: none;
	text-align: right;
	width: 20%;
}

My current automatic conversion turns that selector to [epub|type~="z3998:drama"] .drama-cell[epub|type~="z3998:persona"] (I’m still open to changing this of course) which doesn’t match the together block. I could move the text-align and width properties to the [epub|type~="z3998:drama"] .drama-cell:first-child rule? That fixes the rendering (here at least) and could be automated. Could move the hyphens properties as well and just dump that selector entirely maybe?

[acabal]

I think we should change the new selector to match [epub|type~="z3998:drama"] > .drama-row > .drama-cell as that's the structural equivalent of the old one. Then we can do as I suggested and get away with less CSS.

[EmmaSweeney]

Let me know if you need help switching the manual's drama section and/or play how-to guide.

[robinwhittleton]

I’m a bit tied up at the moment, will try to get back to this next week.

@EmmaSweeney I’m sure I will after we finalise the approach 🙂

[robinwhittleton]

So I updated the convert-drama to automatically fix together markup; unfortunately I only tested it on things where multiple people are saying the same thing at the same time. I’ve since discovered that there also exists the opposite: one group saying multiple things at the same time. That definitely doesn’t work with my code. So I’d suggest that given that there’s only a handful of repos with this markup, I comment the automated conversion out for together blocks and tackle those manually.

The repos are:

• captain-charles-johnson_a-general-history-of-the-pirates
• edgar-lee-masters_spoon-river-anthology
• eugene-oneill_the-hairy-ape
• george-bernard-shaw_heartbreak-house
• george-bernard-shaw_man-and-superman
• james-joyce_ulysses
• john-webster_the-duchess-of-malfi
• karel-capek_r-u-r_paul-selver_nigel-playfair
• langston-hughes_zora-neale-hurston_the-mule-bone
• leo-tolstoy_short-fiction_louise-maude_aylmer-maude_nathan-haskell-dole_constance-garnett_j-d-duff_l
• leo-tolstoy_the-power-of-darkness_louise-maude_aylmer-maude
• luigi-pirandello_six-characters-in-search-of-an-author_edward-storer

[robinwhittleton]

OK, I’ve updated that branch to remove the markup rowspan conversion code and add a warning that it’ll need to be done manually.

@acabal: if you have time could you run a couple of tests with this to see if you’re happy with the output?

(The tests are currently failing in actions, but as this is a one-and-done branch that won’t be merged I’m not too worried about that.)

[acabal]

OK, looks good I think.

The last point I would bring up, is do we want the drama-row and drama-cell classes at all?

With tables, <tr> is only ever the child of <tbody>, and <td> is only ever the child of <tr>.

So we could remove the classes and use the following selectors instead which would be identical:

.drama-row{
}
/* becomes... */
.drama-table > div{
}

.drama-cell{
}
/* becomes... */
.drama-table > div > div{
}

The upside is that it's less markup, fewer classes for the producer to remember, and less room for error, for example in a copy and paste gone wrong somehow.

The downside is that it might be less readable (or maybe more readable since there's less visual clutter?). Might also be harder to find cells using plain text search, and would result in longer xpaths in lint.

Personally I think not using classes is more in line with the general SE philosophy, and in this case the equivalent selectors are basic and straightforward. But I could could be convinced otherwise.

[vr8hub]

I avoid drama like the plague so my voice doesn't count for much, but I would argue plain divs is much less readable, and understandable. In this case, I think there's benefit to making the HTML provide clarity, over and above just giving something for the CSS to target.

[robinwhittleton]

Sorry, it’s been a seriously stressful week at work and I’m back in the UK for a few days to visit a sick relative, so this is on hold. I’ll pick it up again in the next few days hopefully.

[acabal]

No rush, take your time!