Numbered paragraphs

[AndersEkl]

Some books have numbered paragraphs. This should be handled.

[jonaslil]

I assume that at least in some books we want to preserve the paragraph numbering and present it to readers, visually and/or auditorily.

There are no semantic tags or attributes suitable for this that I am aware of. So I have tried to come up with a solution using generic tags an classes.

There are three approaches I can think of:

1) Auto-generate the paragraph numbering with CSS counters. In this approach, the numbers aren't present in the html at all. 2) Use an empty span at the beginning of the paragraph, where the number is contained in some attribute (for example aria-label). For display purposes, the number can be fetched from the attribute with CSS. I have seen this approach being used with page numbers. 3) Include the paragraph number as text content in a span at the beginning of the paragraph. The span, and possibly the paragprah containing it, are given class attributes for styling.

I have a preference for the last solution.

1) Does not seem robust enough. It would require tweaking the styleheets for specific books, and changes in CSS will make the numbering disappear or change. It will probably not work with TTS. 2) Is more robust, but my in my tests, the TTS of reading systems didn't read content displayed in this way (tested in Colibrio app and Thorium). 3) Works in TTS and screen readers.

Sample html for approach 3:

<p class="numbered"><span class="parnum">1</span>Paragraph text.</p>

Using CSS, you can display the numbers in different ways.

Display example 1: paragraph number in the margin (Thorium)

Display example 2: inline paragraph number in brackets (Thorium)

(Note: Displaying the numbers inline as in example 2 seems more realiable across reading systems. The margins seem to be controlled by the reading system in different ways. For example, styles that create enough space for numbers in the margin in Thorium will not work well in some mobile apps.)

If you want to display the number but not have it read out by screenreaders or TTS, you can add aria-hidden="true" to the span.

Ideally, the reader would be given the option to skip paragraph numbers in TTS/Media overlays. But I don't see how we could achieve this.

Any thoughts? @martinpub @AndersEkl @oscarlcarlsson

[martinpub]

Hi @jonaslil!

Great work! I agree with you that the third approach is the better one, especially for a Media Overlays context, where it's preferable to have all text content as text nodes in elements.

Good points on CSS also.

For skippability, it could be achieved using epub:type="aside" for the corresponding SMIL segments. I think this is a correct implementation.

Another idea would be to use <aside> instead of <span> for paragraph numbering, for which skippability should be inherent generally (and in a Media Overlays context, matched by epub:type="aside" for the corresponding SMIL segments. So we could use a class on asides. However, it's not a good idea as asides are block level elements and cannot not be children of <p>s. Right? Semantically, the paragraph numbers should definitely be children of the paragraph elements. Compare to line numbers that we already have in place.

[oscarlcarlsson]

If we want the parnum to be visible, but nor read aloud by tts, could we use something similar to the CSS for pagenumbers?

Example: use then add something like this into the css: content: .parnum:empty:before { content: attr(title); }

[martinpub]

@oscarlcarlsson Yes, we do something similar for page numbers, however, for Media Overlays we (MTM) process the files expanding the attribute text with the page number into a text node as a child to the span/div element. Perhaps we should do the same here, is that what you're thinking?

[oscarlcarlsson]

For university-titles, it should probably be included. For library-titles, that might not be needed. The details of this might be an agency-specific discussion?

[martinpub]

Sure, we could leave this up to agency-specific CSS/instructions, and only specify the HTML part.

[jonaslil]

I added a section about this to the guidelines draft, based on solution 3 above.

[jonaslil]

I added the sample file I used for testing to this repo