If we want folks to author in unassisted HDITA, then the ePub
example suddenly doesn't seem so inviting. I think the author's
involvement should be as natural as possible, which the DITA
inline model represents.
At this point, perhaps there is value in again looking into HTML5
webcomponent custom tags
(http://w3c.github.io/webcomponents/spec/custom/). These are
intended to provide standard integration of custom markup as
needed. The larger concern in the HTML community is whether such
content can be interchanged. For the sake of content conforming to
a standard profile, that's part of the reason for Lightweight
DITA--everything about HDITA and MDITA is prescriptive and without
validation. Custom elements provide us a user-friendly way of
exposing semantic markup that we can attach behaviors to for
default use and ensure accurate transformation into DITA. What's
to lose?
The best how-to is still this article which we've looked at
before:
https://www.smashingmagazine.com/2014/03/introduction-to-custom-elements/
(look at the <great-apes> example).
We can get started by simply using the element we define; we can
add the HTMLElement API hooks later.
XDITA:
<p>Here's my
special<fn>Not
that special</fn> idea</p>
HDITA:
<p>Here's my
special<dita-fn>Not
that special</dita-fn> idea</p>
Another approach is to extend it
from <aside> in order to pick up that element's processing
semantic intent and behaviors within the DOM.
document.registerElement('dita-fn', {
prototype: fnProto,
extends: 'aside'
});
HDITA:
<p>Here's my special<aside
is="dita-fn">Not
that special</aside> idea</p>
Another advantage: use the template feature in HTML5 to imbue
this element with a default content model, sort of like having an
XSLT match pattern that, on use, imparts a pre-built content model
that can handle the various forms of fn linking, or for the note
element, provide enumerated values for a note type attribute (if I
read this right).
By basing custom elements on closest available core elements, we
provide graceful degradation for content exported outside of the
user community (which is not highly likely, IMO). Within the
profile of use, you'd have your JS wiring for custom behavior
extensions, just as specialization modules do if you want your
specialized DITA elements to do more than fall-through behavior.
I think I took the red pill--the rabbit hole lies before us.
--
Don
On 4/19/2016 9:24 AM, Michael Priestley
wrote:
How about we just map
it directly to the
EPUB semantics? Then in EPUB readers it will display as a
(popup, in-place)
footnote, and in HTML browsers we can get the same with
appropriate
use of CSS/JS.
Option 1: phrase-level inline
footnotes
If we can limit the contents of a
footnote
to phrase-level content (ie no p, ul, etc.) then we can have
<fn>
available inside <p> as a phrase-level element, without
getting into
nasty mixed-content situations that are potentially tough for
editors to
handle.
Assuming we can keep it as
phrase-level,
it would look something like this:
XDITA:
<p>Here's my
special<fn>Not
that special</fn> idea</p>
HTML5:
<p>Here's my special<a
epub:type="noteref"
href="">1</a><aside epub:type="footnote"
id="n1">Not that special</aside> idea</p>
Pro: footnote numbers are
auto-generated
and maintained, at least in the XML model
Con: hard limits on footnote size
may
seem arbitrary especially in non-XML contexts where it's not
validated
by schema
Option 2: block-level
referenced
footnotes
If we want to allow block content
in
a footnote (eg multiple paras) then I think we'd have to move to
the referenced
footnote model from DITA - effectively we'd set <fn> as
block-level
only, require an id, and then say that it shows up only when an
xref with
type="fn" references that id (or we create a specialized xref
- eg fnref).
So block-level footnote would
have to
look something like this:
XDITA:
<p>Here's my
special<xref type="fn"
href="">1</a> idea</p>
<fn id="n1"><p>Not
that special</p></fn>
HTML5:
<p>Here's my special<a
epub:type="noteref"
href="">1</a> idea</p>
<aside epub:type="footnote"
id="n1"><p>Not that special</p></aside>
Pro: more flexible footnote
authoring,
closer match between XDITA and HDITA capabilities
Con: footnote numbering is
hardcoded
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From:
Don Day
<donday@donrday.com>
To:
dita-lightweight-dita@lists.oasis-open.org
Date:
04/19/2016 09:15 AM
Subject:
Re:
[dita-lightweight-dita]
More on footnotes in HTML5
Sent by:
<dita-lightweight-dita@lists.oasis-open.org>
HTML's title attribute has a very footnote-ish
interaction
indeed for desktop views (and assuming you can make the item
recognizable
as being a progressive disclosure by applying color or
typography), but
the hover behavior does not exist for touch interactions, and
I'm not sure
what the accessibility is of hover items in a screen reader.
These concerns
kind of push me toward markup that has more touchable behaviors
with the
ability to link elsewhere (and then back) or use
hide/reveal-in-place rather
than produce hover or pop-over content. Am I constraining myself
too much?--
Don
On 4/19/2016 5:03 AM, Rahel Anne Bailie wrote:
Another thought is that we live with a lot of
conventions
left over from print. For example, a glossary in print made
sense, but
online you can have in situ hover-overs. (This is one thing
that drives
me crazy in ebooks, where the author uses some local slang and
when I get
to the end of the book, there is a glossary that I no longer
need.)
Footnotes definitely have a place in print and
have an
equivalent online, though the implementation would be
different. For example,
a footnote on an endless scroll page wouldn't make sense. So
where does
that go, and does it then cease to be a footnote, per se?
On Tue, Apr 19, 2016 at 6:03 AM, Don Day <donday@donrday.com>
wrote:
Footnotes may not be easily solved for
equivalence across
HTML and Markdown and still return to DITA. The data models
(indeed the
intent behind the designs) is all different.
Markdown has a close proxy to footnotes in its
"reference
links", but HTML has no architected equivalent--rather than
providing
for a semantic structure with footnote-like behavior, HTML5
has you inserting
markup that supports the behavior, but you cannot easily
decompose it back
into the intent of a reference link when converting into DITA.
One Markdown
extension suggests adding a caret into the reference (i.e.,
[^1] to imply
a proper footnote, meaning that extended content can be
ascribed to it
(see http://rephrase.net/box/word/footnotes/syntax/).
But since HTML has no way to be similarly extended, we are
limited to whatever
processing and display semantic are available.
One user has proposed a footnote design for a
future HTML5,
but don't hold your breath. It would be a properly architected
structure
for deferred content, but good ideas take time to win hearts,
if ever.
This proposal article (see http://davidmacd.com/blog/html51-footnotes.html)
actually explains the ePub solution well, and it is compelling
to me for
now--I'm inclined to make use of <aside> for any sort of
deferable
content in HDITA structures (perhaps for <note> as well,
if you can
accept that it is deferable (or at least can be floated
outside of the
normal galley flow).
Meanwhile, although the details/summary markup
does provide
an architected design that represents content that can be
deferred from
the main view, it is more truthfully a visibility toggle, not
a reference
to a block of text. This is soo close, but I understand
perfectly why ePub
eschews its use as a footnote. This markup would better serve
the role
of a FAQ in which the question is the <details> and the
answer is
the <summary> content, with expanding behavior in the
display.
Try pasting this content into a small HTML file
and drop
it onto a browser to see how HTML5 summary/details works.
---------------------------------
<p>The details element in HTML5 works best
as an
interaction that toggles visibility on and off. Normally this
is done with
spans and divs and a tiny bit of _javascript_ for the
interaction. Note how
content pushes down as summary content is toggled into
view:</p>
<details>
<summary>Q: Why are markup architectures so
difficult?</summary>
<p>A: Humans design solutions for different
reasons.</p>
</details>
<details>
<summary>Q: Why do we care about what we
do?</summary>
<p>A: Because we like to prevail over the limitations
handed
to us.</p>
</details>
<p>Note that this markup provides default behavior in
the browser;
no _javascript_ is needed. The downside is that the default
presentation
is ugly and not all browsers provide CSS hooks for styling
yet.</p>
------------------------------------------
So although it is useful to see how
summary/details works,
I consider it to be a UI gadget rather than a useful container
for content.
The nested containers are good, but their behavior precludes
the intent
of a footnote, in my opinion. I'd save this markup for FAQs
and for progressive
disclosure use cases.
I say let's see why the ePub solution is not better, and
whether we can
shoehorn <aside> as footnote into Markdown semantics
like the reference
link. I think this comes closest to lining up with DITA fn
intent (especially
with the caret extension).
I could be convinced that it is a useful design point to allow
Lightweight
DITA to be only as rich as there exist fully equivalent markup
solutions
across all versions (and common Markdown at that--extensions
become liabilities
outside the few environments that support them). 1 Designating
and maintaining the record copy out of 3 near equivalents is a
recipe for
Version Control Induced Insanity.
--
Don
1 Of course, there is always "DITA used lightly" that
I
get a lot of present use out of. ;-)
On 4/18/2016 10:52 AM, Michael Priestley wrote:
Interesting discussion here, on
how
it's being done in EPUB and why:
http://idpf.org/forum/topic-885
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
--
Don
R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don
R. Day Skype:
don.r.day
"Where is the wisdom we have
lost in
knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
-- Rahel Anne Bailie,
Content
Strategy & Ecosystems / Content Management & Design
Content strategies for business impact
Mobile: +44 (0) 7869 643 685 / skype: rahelab
Co-producer: Content
Strategy Workshops
Co-editor: The
Language of Content Strategy
Co-author: Content
Strategy: Connecting the dots between business, brand, and
benefits
--
Don
R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don
R. Day Skype:
don.r.day
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
--
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot