EPUB3 extensions - sbsdev/pipeline-mod-sbs GitHub Wiki

There are a number of SBS-specific extensions to DTBook for which we need to find an alternative in EPUB 3. I will create a table here with the mapping and we can discuss the problematic ones.

  • span[@class='answer']
  • span[@class='answer_1']
  • span[@class='box']
  • @brl:class
  • a[@class='pageref']
  • brl:homograph
  • brl:v-form
  • brl:num[@role=...]
  • brl:place
  • brl:select, brl:when-braille, brl:literal[@brl:grade=...], brl:otherwise
  • brl:emph
  • brl:running-line
  • brl:toc-line
  • brl:volume[@brl:grade=...]
  • @brl:accents
  • brl:computer
  • brl:date
  • brl:time
  • brl:name

Metadata elements:

  • meta[@name='prod:series']
  • meta[@name='prod:seriesNumber']
DTBook EPUB 3
span[@class='answer']

proposal: span[@epub:type='answer']

The Nordic guidelines use "class"

span[@class='answer_1']

proposal: span[@epub:type='nordic:answer_1']

"nordic:" prefix because answer_1 not in default or z3998 vocab

Jostein currently converts to span[@class='answer_1'], and this is also what the Nordic guidelines say.

span[@class='box']

proposal: span[@epub:type='nordic:box']

"nordic:" prefix because box not in default or z3998 vocab

Jostein currently converts to span[@class='box'], and this is also what the Nordic guidelines say.

@brl:class

currently works: @brl:class

proposal: @class

only used for SBSForm at the moment?

prefix classes with "braille-" or "brl-"?

a[@class='pageref']

currently works: a[@class='pageref']

proposal: a[@epub:type='sbs:pageref']

"epub:type" because this is semantics

"sbs:" prefix because nothing similar in default or z3998 vocab

brl:homograph

currently works: brl:homograph

proposal: span[@epub:type='z3998:homograph']

brl:v-form

currently works: brl:v-form

proposal: span[@epub:type='z3998:v-form']

brl:num[@role=...]

@role:
  • cardinal
  • roman
  • fraction
  • mixed
  • isbn
  • phone
  • measure

currently works: brl:num

proposal:

brl:place

currently works: brl:place

proposal: span[epub:type='z3998:place']

brl:select, brl:when-braille, brl:literal[@brl:grade=...], brl:otherwise

currently works: brl:select, brl:when-braille, brl:literal, brl:otherwise

proposal: ?

Something similar in EPUB is the switch element, but I'm not sure it is suitable for our use case. All child elements must be alternate representations of the same content: OK. The switching is done based on namespaces: not quite OK. We're looking more for something that switches based on the target medium (print or braille). In addition we need to switch based on a transcription parameter: the contraction grade (could be considered part of the target locale).

An EPUB feature that is aware of the target media is the multiple renditions feature (see the rendition:media attribute). But this is not suitable for a single-source publishing format.

Another option is CSS. CSS target medium aware. So we could just consider putting the alternatives in separate spans with custom CSS classes. However I'm not sure it is such a good idea to approach this issue as a simple styling matter. Also CSS is not target locale aware. In our specific case, we can do the switching based on the "contraction-grade" parameter in our style sheets, but these style sheets are not generally usable outside of our converter.

DIAGRAM could be another option.

brl:emph

(optional) @brl:render attribute:

  • emph
  • singlequote
  • quote
  • ignore

(optional) @brl:continuation attribute

(optional) @class attribute

attributes also allowed on em and strong

currently works: brl:emph

proposal: em or strong

@class attribute:

  • emph
  • singlequote
  • quote
  • ignore

or:

  • brl-render-emph
  • brl-render-singlequote
  • brl-render-quote
  • brl-render-ignore

"class" because this is styling

It's no problem to combine these classes with other custom classes (which is what the @class attribute in DTBook is for).

In order to support the difference between em/strong and brl:emph (which is used for other text styles such as capitalized, colored, underlined, etc.) in EPUB we can either call it span. Or we can use em with an additional class. The first option is more similar to the existing approach. The second option requires a bit of a new way of thinking (namely that in HTML5 em and strong can be used for other things than italic and bold styled text). Because the brl:emph element is not rendered in any special way in large print, the class could be called "lp-render-ignore", but maybe better would be to name it according to the style in the original print ("capitalized", "colored", etc.), or just a generic "non-italic" or something.

How to replace @brl:continuation? We borrowed the @continuation attribute from ZedAI, but in EPUB there is only the z3998:continuation epub:type. It can't hold IDREFS so how I don't see how it can be used?? So why don't we just use the @continuation attribute from ZedAI, like before, but call it z3998:continuation instead of brl:continuation from now on.

brl:running-line

currently works: brl:running-line

proposal: ?

Maybe the @alt attribute is an option? => but not allowed on h1

brl:toc-line

currently works: brl:toc-line

proposal: ?

Maybe the @alt attribute is an option? You can't have a running-line that is different from a toc-line but when would you have that situation? => but not allowed on h1

brl:volume[@brl:grade=...]

proposal (currently works): br[@class='braille-volume-break']?

or span?

how to capture grade info?

  • braille-volume-break-grade-0
  • braille-volume-break-grade-1
  • braille-volume-break-grade-2

"class" rather than "epub:type" because this is styling. In CSS this is mapped to `volume-break-before: always`. Compare with [@epub:type='pagebreak']. The difference is justifiable because "pagebreak" is used to denote page breaks in the original book, which is not completely the same as styling.

@brl:accents

  • detailed
  • reduced

currently works: @brl:accents

proposal: @class

  • braille-accents-detailed
  • braille-accents-reduced

Not really styling, but also not semantics; third category: "transcription hints". Since transcription hints have also been included in CSS (see e.g. text-transform property) I'm using "class".

brl:computer

currently works: brl:computer

proposal: span[@class='braille-computer']

TODO: need to rethink: probably epub:type is more appropriate here. E.g.: sbs:computer-braille

brl:date

currently works: brl:date

proposal: span[@epub:type='dc:date'] or span[@epub:type='dcterms:date']

If we want to make clear that this is really about a kind of number format used for a date (rather than a date of some event), we could alternatively create a sbs:date.

brl:time

currently works: brl:time

proposal: ?

or create a sbs:time

brl:name

currently works: brl:name

proposal: span[@epub:type='foaf:name']

or create a sbs:name (same reason as for dc:date)

meta[@name='prod:series']

  • PPP
  • SJW

proposal 1: <meta property='nordic:series'>PPP</meta>

This would be a new entry in the "nordic" vocabulary.

proposal 2: schema.org

<meta id="x" property='schema:isPartOf'>schema:isPartOf</meta>
<meta refines="#x" property='schema:identifier'>PPP</meta>

There are some other interesting things in schema.org such as BookSeries and PublicationIssue.

proposal 3: <meta property='sbs:series'>PPP</meta>

The "sbs" or "prod" prefix would have to be mapped to a URI.

This is the currently working solution, but with prod:series, where "prod" is mapped to "http://www.sbs.ch/prod/".

proposal 4: <meta name='prod:series' content='PPP'/>

According to the EPUB spec the meta element defined in OPF2 has been obsoleted but may still be included. (However I am not sure whether the "prod" would have to be mapped to a URI as well in this case.)

meta[@name='prod:seriesNumber']

proposal 1: <meta property='nordic:seriesNumber'>10</meta>

This would be a new entry in the "nordic" vocabulary.

proposal 2: <meta property='schema:position'>10</meta>

There are some other interesting things in schema.org such as issueNumber.

proposal 3: <meta property='sbs:seriesNumber'>10</meta>

The "sbs" prefix would have to be mapped to a URI.

This is the currently working solution, but with prod:seriesNumber, where "prod" is mapped to "http://www.sbs.ch/prod/".

proposal 4: <meta name='prod:seriesNumber' content='10'/>

According to the EPUB spec the meta element defined in OPF2 has been obsoleted but may still be included. (However I am not sure whether the "prod" would have to be mapped to a URI as well in this case.)

⚠️ **GitHub.com Fallback** ⚠️