Skip to content

Commit

Permalink
Merge pull request #7 from oerpub/kef-updates
Browse files Browse the repository at this point in the history 
added equation, math, alternates, note about embedding content using alt...
  • Loading branch information
@kathi-fletcher
kathi-fletcher committed Apr 27, 2014
2 parents 9f14334 + 664aa29 commit 7fecaf7
Showing 1 changed file with 150 additions and 18 deletions.
168 changes: 150 additions & 18 deletions specification.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,57 +4,66 @@ Requirements for HTML5 elements in the TextbookHTML specification are below. Thi

The specification differs from HTMLBook and EPUB glosses in the following cases
1. Extensions to support semantic textbook content like exercises.
2. Content that is placement neutral - for instance, footnotes are defined in place with their reference.
2. Content that may be displayed in different places depending on context. For instance, footnotes are defined in place with their reference, rather than being absolutely positioned.

Special semantic inflections for +data-type+ attributes, unless otherwise noted, come from http://idpf.org/epub/vocab/structure/[EPUB 3 Structural Semantics Vocabulary]

Many content models refer to "Block elements" or "Inline elements"; please see <<block_elements, Block Elements>> and <<inline_elements, Inline Elements>> for the corresponding list of HTML5 elements that belong to each of these categories.

If no content model or attribute requirements are explicitly specified, then OERBook adopts the corresponding requirements in the http://www.w3.org/html/wg/drafts/html/master/[HTML5 Specification]
If no content model or attribute requirements are explicitly specified, then TextbookHTML adopts the corresponding requirements in the http://www.w3.org/html/wg/drafts/html/master/[HTML5 Specification]

=== Revision History and Notes

22 February 2014: Added equation, math, alternates, and an embed section.

05 February 2014: Clarifications, links to metadata, put in notes about what is missing, and where I stopped editing the HTMLBook stuff.

17 October 2013: Name changes and catch up on the language.

13 July 2013: Zeroth release of Working Draft, don't pay attention to this yet. Just started with section and para.

=== Still Missing

==== KEF: Also we need to add example, exercise, and proof, multipart, alternates, and just in general look to see what is missing.

=== Compatibilities with github-bookeditor

Github-bookeditor (http://github.com/oerpub/github-bookeditor) is an HTML5 editor for producing books in the format specified here. There are two major differences with the current (Oct 17 2013) version of the editor.
Github-bookeditor (http://github.com/oerpub/github-bookeditor) is an HTML5 editor for producing books in the format specified here. There are two major differences with the current (Feb 05 2014) version of the editor.

*Class versus data-type*: First, the editor started out using +class+ for specifying the main semantic type of the element and using +data-type+ for specifying the original CNXML +type+. But we decided to switch to +data-type+ so that class could be used for style glosses and it also matches HTMLBook. The original types are now coded as +data-subtype+. However, the editor has not been reformatted to do this yet and still uses class and type.
*Class versus data-type*: First, the editor started out using +class+ for specifying the main semantic type of the element and using +data-type+ for specifying the original CNXML +type+. But we decided to switch to +data-type+ so that class could be used for style glosses and in order to match HTMLBook. The original types are now coded as +data-subtype+. However, the editor has not been reformatted to do this yet and still uses class and type. The intention is to make the swith by end of Feb 2014.

*Sections and headings*: Secondly, the base editor uses headings to represent sections. On load and save, there will be XSL or javascript to convert sections to and from headings. Sections that cannot be represented by headings are left in place. This conversion software is not yet hooked into the editor. The editor will work on documents that still have sections in them, but it will be less efficient.
*Sections and headings*: Secondly, the base editor uses headings to represent sections. On load and save, there will be XSL or javascript to convert sections to and from headings. Sections that cannot be represented by headings are left in place. This conversion software is not yet hooked into the editor. The editor will work on documents that still have sections in them, but it will be less efficient, because it
will create generic semantic blocks around those sections.

=== Deprecated features

It seems odd to have deprecated features in a brand new language. They arise from the need to be compatible with existing content in CNXML.
It seems odd to have deprecated features in a brand new language. They arise, however, from the need to be compatible with the large body of open textbooks in OpenStax, Connexions, and Siyavula's libraries, which were created using CNXML.

*data-label*: CNXML had a label element that could be present on most elements. We need to support it in the language to handle existing content properly. The label element can be used to override any autogenerated label. It is deprecated because rather than using a label element, the label should be included and attached via the +data-type+, +data-subtype+, or author/vendor supplied +class+. Care should be taken to do this in a way that supports translation and internationalization.
*data-label*: CNXML had a label element that could be present on most elements. We need to support it in the language to handle existing content properly. The label element can be used to override any autogenerated label. It is deprecated, because, rather than using a label element, the label should be included and attached via the +data-type+, +data-subtype+, or author/vendor supplied +class+. Care should be taken to do this in a way that supports translation, internationalization, and accessibility.

=== Book Component elements

These elements will be specified later.
These elements will be specified later. Book components are specified via EPUB3 in the .opf and -nav.html files. The language will provide a set of data-type attributes for hanging on components to specify that they are chapter, parts, sections, etc.

==== Sections

*HTML element*: +<section>+

*Attribute requirements*: +id+

*Optional attribues*: +data-label+, +data-type=''sect<#>''+ for compatibility with HTMLBook, +data-subtype+ A user defined type of section, for compatibility with CNXML. Subtype can be any user-defined value that reflects the purpose of the section.
*Optional attributes*: +data-label+, +data-type=''sect<#>''+ for compatibility with HTMLBook, +data-subtype+ A user defined type of section, for compatibility with CNXML. Subtype can be any user-defined value that reflects the purpose of the section. For example, a section might be a homework set, or an introduction.

*Content model*: The first child must be a main heading element corresponding to the title of the section. The hierarchy level can either be +<h1>+ or can correspond to the presumed nesting level of the section to aid older browsers and current screen readers in understanding the document hierarchy. It should be understood that those header levels are merely hints and can be canonicalized as
+<h1>+ when the world catches up with HTML5. Styling of the headings should be done structurally, according to the section nesting, however, rather than using the header level.

The heading is followed by zero or more subheading elements whose hierarchy level is one lower than the main heading (e.g., +<h2>+ for a +sect1+), folloed by zero or more Block elements, followed by zero or more +<section>+ elements
The heading is followed by zero or more subheading elements whose hierarchy level is one lower than the main heading (e.g., +<h2>+ for a +sect1+), followed by zero or more Block elements, followed by zero or more +<section>+ elements

*Example*:

----
<section data-type="sect1" id="sect1">
<h1>A-Head</h1>
<p>If you httpparty, you must party hard</p>
<p>If you party, you must party hard</p>
<!-- Some more paragraphs -->
<section data-type="sect2" id="sect2" data-label="Custom Label">
<h2>B-Head</h2>
Expand All @@ -78,7 +87,7 @@ The heading is followed by zero or more subheading elements whose hierarchy leve

==== CNXML Paragraph's with titles and block content (deprecated)

CNXML had paras that could have titles in them and certain types of block content, like examples and figures. These need to be encoded as divs.
CNXML had paras that could have titles in them and certain types of block content, like examples and figures. These need to be encoded as divs. These weird paras were a mistake, and no one should make any new ones of these.

*HTML element*: +<div data-type="para">+

Expand Down Expand Up @@ -111,7 +120,7 @@ NOTE: HTML5 is kind of confusing on the use of asides. See http://html5doctor.co
*Optional attributes*: For compatibility with CNXML: +
+data-subtype+ (deprecated, use +class+ instead) : A user supplied type. +
+data-display="none"+ (deprecated, use +class+ instead): To hide the element.
+data-label+ (deprecated, use +class+ instead) : A user-defined label that overrides or suppresses the label that would normally be supplied.
+data-label+ (deprecated, use +class+ instead) : A user-defined label that overrides or suppresses the label that would normally be supplied.

*Content model*: Zero or one +<h1>+ - +<h6>+ elements that contains the sidebar title(s)); then zero or more Block elements

Expand Down Expand Up @@ -423,23 +432,63 @@ sidebar title -> h5

*Attribute requirements*: +data-type="equation"+ footnote:[From DocBook; no close match in EPUB 3 Structural Semantics Vocabulary]

*Note: HTMLBook supports embedded MathML in HTML content documents, which can be used here.
*Optional attributes*: @class :

*Content model*: Zero or one +<span data-type="title">++ elements that contains an equation title;
then a math node or a media element, or text.

*Note*: TextbookHTML supports embedded MathML in HTML content documents, which can be used here.

*Example*:

----
<div data-type="equation">
<h5>Pythagorean Theorem</h5>
<span data-type="title">Pythagorean Theorem</span>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<semantics>
<mrow>
<msup><mi>a</mi><mn>2</mn></msup>
<mo>+</mo>
<msup><mi>b</mi><mn>2</mn></msup>
<mo>=</mo>
<msup><mi>c</mi><mn>2</mn></msup>
</mrow>
<annotation encoding="math/tex">a+b=c</annotation>
</semantics>
</math>
</div>
----

=== Math ===

Math should be entered in MathML with a recommended source annotation, which can be
LaTeX, ASCIIMath, or Content MathML.

*Converstion Note*: If using the OERPUB editor, and you have a document that contains only source
math, you can supply bogus MathML and the editor will create legitimate MathML from the
source when reading the document.

*Encodings Supported*

"+<annotation encoding="math/asciimath">+, +<annotation encoding="math/tex">+ (see example under Equation), and +<annotation-xml encoding="MathML-Content">+

*Example*:

----
<math xmlns="http://www.w3.org/1998/Math/MathML">
<semantics>
<mrow>
<msup><mi>a</mi><mn>2</mn></msup>
<mo>+</mo>
<msup><mi>b</mi><mn>2</mn></msup>
<mo>=</mo>
<msup><mi>c</mi><mn>2</mn></msup>
</mrow>
<annotation encoding="math/asciimath">a+b=c</annotation>
</semantics>
</math>
----

=== Inline Elements

==== Emphasis (generally for italic)
Expand Down Expand Up @@ -485,6 +534,8 @@ Example:

==== Footnote, endnote

==== KEF: Everything below this hasn't been edited from the HTMLBook specification. So all these need review

*HTML element*: +<a>+ (for marker); +<div>+ for block of footnote/endnote content; +<aside>+ for footnote or endnote

*Attribute requirements*: +data-type="noteref"+ (for marker); +data-type="footnotes"+ or +data-type="rearnotes"+ for block of footnotes/endnotes; +data-type="footnote"+ or +data-type="rearnote"+ for footnote or endnote
Expand Down Expand Up @@ -555,8 +606,89 @@ Example:
<p>The formula for water is H<sub>2</sub>O</p>
----

==== Alternates mechanism

The alternates mechanism is a way to specify media alternates for different environments. It can
also be used for including source for the given media. In general the first alternate should
be the preferred end-reader version.

*HTML element*: +<div data-type="altnerates">+ Each element inside the alternates is
considered an alternate for the same content. A data-type on each element alternate can be used
to explain their purpose.

*Attribute options on subparts*: +data-type=[online offline source]+; On the elements inside the
alternates, these options can distinguish the purpose of each type and css can be used to hide
the ones that are not relevant.

*Content model*: Any HTML5 elements

*Examples*:

Ex: print alternate for video

----
<div data-type="alternates">
<iframe data-type="online" width="420" height="315"
src="http://www.youtube.com/embed/01viXRa8Hqg?rel=0" allowfullscreen="allowfullscreen">
</iframe>
<div data-type="offline">
<img height="344" width="480" src="http://i1.ytimg.com/vi/01viXRa8Hqg/hqdefault.jpg"
alt="Swedish Chef Squirrel Stew thumbnail" />
<p>The media is available at http://www.youtube.com/watch?v=SmOwn_OEJTo.</p>
</div>
</div>
----

Ex: PSTricks source for graphics

----
<div data-type="alternates">
<img src="../resources/49d35b3aefce33c9c0bab05a370e159f.png"/>
<pre data-type="source" class="pspicture">&lt;code&gt;
(0,-3.)(6.5,6)
\psframe[fillcolor=gray,fillstyle=solid,linecolor=gray!40!black](0.5,.75)(1.5,1.25)
\psframe[fillcolor=gray,fillstyle=solid,linecolor=gray!40!black](2.5,.75)(3.5,1.25)
\psline[linestyle=dotted,linecolor=gray!30!black](2,5)(2,-2)
\psline[linestyle=dotted,linecolor=gray!30!black](4,5)(4,-2)
\psline[linecolor=orange]{-&amp;gt;}(1,2)(1,-1)
\uput[l](1,0){$\vec{p}_i$}
\pscircle[fillcolor=yellow!80!black,fillstyle=solid](1,2){9pt}
</pre>
</div>
----

=== Interactive Elements

==== Embedded content

Many authors will choose to include interactive content as embedded content that uses the
embed code from sites that support oEmbed. This can be combined with the alternates div
to provide a fallback mechanism like the native video controls.

*HTML element*: +<iframe>+

*Attributes*: from HTML5

*Content model*: *empty*

*Example*:

----
<div data-type="alternates">
<iframe data-type="online" width="420" height="315"
src="http://www.youtube.com/embed/01viXRa8Hqg?rel=0" allowfullscreen="allowfullscreen">
</iframe>
<div data-type="offline">
<img height="344" width="480" src="http://i1.ytimg.com/vi/01viXRa8Hqg/hqdefault.jpg"
alt="Swedish Chef Squirrel Stew thumbnail" />
<p>The media is available at http://www.youtube.com/watch?v=SmOwn_OEJTo.</p>
</div>
</div>
----

==== Video

*HTML element*: +<video>+
Expand All @@ -567,9 +699,9 @@ Example:

----
<video id="asteroids_video" width="480" height="270" controls="controls" poster="images/fallback_image.png">
<source src="video/html5_asteroids.mp4" type="video/mp4"/>
<source src="video/html5_asteroids.ogg" type="video/ogg"/>
<em>Sorry, the &lt;video&gt; element not supported in your
<source src="video/html5_asteroids.mp4" type="video/mp4"/>
<source src="video/html5_asteroids.ogg" type="video/ogg"/>
<em>Sorry, the &lt;video&gt; element not supported in your
reading system. View the video online at http://example.com.</em>
</video>
----
Expand Down

0 comments on commit 7fecaf7

Please sign in to comment.