philschatz/alternatives.md

## alternatives.md

      
    Raw
  

              alternatives.md
            
          
    Decision

This tries to align to terms in CSS Media Query
We'll switch based on the media. Options include:

screen
print
screenreader

Example XHTML markup:
<div data-type="media-options">
    <p      data-media="print screenreader">This interactive does the following things....</p>
    <iframe data-media="screen" src="https://PHET"/>
    <p      data-media="print"><a href="REX...">I am a link</a></p>
</div>

<!-- The double-underline -->
<u data-type="emphasis" data-effect="double-underline">
  <span data-media="screenreader">double underline</span>
  leave
  <span data-media="screenreader">end double underline</span>
</u>
And corresponding CSS in REX and the PDF:
/* REX web */
@media screen {
  [data-media~=screenreader] { /* move offscreen */ }
  [data-media]:not([data-media~=screen],[data-media~=screenreader]) { display: none }
}

/* REX PDF */
@media print {
  [data-media]:not([data-media~=print]) { display: none }
}

/* PDF */
[data-media]:not([data-media~=print]) { display: none }
Note: The only change to the double-underline is replacing the attribute data-screenreader-only="true" with data-media="screenreader"


Background

We have a few places where we want the content to have multiple formats and, depending on how the content is being rendered, want to choose which format to show or whether to hide a format.
Here are a few ways we render our content:

REX Web
REX Ctrl+P PDF
REX Screenreader ("sr-only")
Downloaded PDF
Printed PDF (future?)
ePub3 (future?)
ePub2 (future?)

Here are alternative formats we may choose to render:

Interactives:

<iframe> (for REX Web)
link to REX (for Downloaded PDF)
QR code (for Printed PDF)
screenshot image (for REX Ctrl+P PDF)


Math:

MathML markup (for ePub3)
Math SVG images (for PDF and ePub3 fallback)
Math PNG images (for ePub2)


Move but don't remove:

Shift screenreader-only text off the visible part of the page (REX Web, Downloaded PDF)


Remove in some renderers:

Hide chapter outlines (REX Web, REX Ctrl+P PDF)


Note: some of these formats like QR code & Math SVG/PNG images could be done after the common-format content has been created. They were added in here to help fill-in options but might just cause over-designing a solution.
Prior Art (ePub3)

Here's how the ePUB spec supports alternate formats. It only allows readers to choose based on this required-namespace attribute.
<epub:switch id="cmlSwitch">
   
   <epub:case required-namespace="http://www.xml-cml.org/schema">
      <cml xmlns="http://www.xml-cml.org/schema">
         <molecule id="sulfuric-acid">
            <formula id="f1" concise="H 2 S 1 O 4"/>
         </molecule>
      </cml>
   </epub:case>
   
   <epub:default>
      <p>H<sub>2</sub>SO<sub>4</sub></p>
   </epub:default>
   
</epub:switch>
Option: Two Options

For the immediate issue we could just have 2 for the renderer to choose from: "static" or "dynamic". It could look like this:
<!-- static/dynamic only has 2 options -->
<div data-type="if-else(?)">
    <p      data-case="static"  ><a href="REX...">I am a link</a></p>
    <iframe data-case="dynamic" src="https://PHET"/>
</div>
sr-only: This doesn't seem to address the screenreader-only problem
Chapter Outline: Chapter Outlines could be shoehorned by being in the data-case="static" section but then would unexpectedly reappear in the REX Ctrl+P PDF rendering
Option: Switch element

We could wrap the options in a switch.
The names could be switch/case or alternatives/option, or ???.
<div data-type="switch">
    <p      data-case="link"   ><a href="REX...">I am a link</a></p>
    <iframe data-case="iframe" src="https://PHET"/>
    <!-- The following are maybes: -->
    <p      data-case="qr"     ><img src="qr.png"/></p>
    <audio  data-case="audio"  src="./reaction.mp3"/>
    <video  data-case="video"  src="./reaction.avi"/>
</div>
Adding a class on the parent element allows renderers to choose using CSS:
<div data-type="switch" class="has-link has-iframe has-qr">
    <p      data-case="link"   ><a href="REX...">I am a link</a></p>
    <iframe data-case="iframe" src="https://PHET"/>
    ...
</div>
/* Now, CSS is able to show/hide whichever element they want */
.has-iframe :not([data-case='iframe']) { display: none; } /* REX-web */
.has-qr     :not([data-case='qr'])     { display: none; } /* REX-PDF */
sr-only: Not sure how this would be marked up yet
Chapter Outline: Chapter Outlines could use this method but it is unclear what the data-case="???" would be
Option: Media element

Instead of inventing a new "switch" element we could just use the existing CNXML <media> element (see Docs).
The <media> element allows children inside it and already sort of acts like alternatives that a renderer chooses from.
With this option, any enki step that adds an option (like cookbook does when it encounters an iframe and adds a link to REX) would update the class attribute on the media element and add the option as a child element. The markup ends up looking just like the "switch" option above and can use CSS to style.
<div data-type="media" class="has-link has-iframe has-qr">
    <p      data-case="link"   ><a href="REX...">I am a link</a></p>
    <iframe data-case="iframe" src="https://PHET"/>
    <!-- The following are maybes: -->
    <p      data-case="qr"     ><img src="qr.png"/></p>
    <audio  data-case="audio"  src="./reaction.mp3"/>
    <video  data-case="video"  src="./reaction.avi"/>
</div>
sr-only: Not sure how this would be marked up yet
Note: Chapter Outlines would need to be solved in a different way
Option: media/switch Hybrid

Since the definition of <media> and <switch> is the same we could use <media> most of the time and <switch> for elements like the Chapter Outline that are not a "type of media" per se.