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