If you can, come see my webinar today on DITA's form for HTML5's
function. I use your HDITA task example, with just the section
modifications, to demonstrate some round tripping through an
editing cycle. I had come to the same agreement about keeping
obvious HTML5 features, and this is untouched since before I saw
your note. I do like the much simpler section syntax, FWIW. And of
course, the method works as surmised. We'll talk in the next
meeting, I'm sure, about what you see (live or in the replay).
Webinar link:
http://www.dclab.com/webinars/amplify-html5-features-using-ditas-form
Sample:
<article data-hd-class="task">
<h1>How to do something</h1>
<p>Introduction to this specific task</p>
<section-context>
<p>Use only when ready</p>
</section-context>
<section-steps>
<ol>
<li><p>Plan something</p></li>
<li><p>Do something</p></li>
<li><p>Evaluate something</p></li>
</ol>
</section-steps>
<section-example>
<p>Like this</p>
</section-example>
</article>
On 4/20/2016 8:15 AM, Carlos Evia
wrote:
I put on my safety goggles (safety first), took the monkeys out of
their cages, and went to the lab to experiment. Not really, but I
think if we use something like, say, <hdita-concept> as a
custom element, we lose the semantic punch of <article
data-hd-class="task”>. In big DITA terms, we can’t tell the
human author and machine browser that hdita-concept is
“specialized” (or extended) from article unless we do a lot of DOM
magic… and that ain’t very lightweight.
And I think mixing custom elements and data
attributes would make authors cry…
Carlos
---
Carlos Evia,
Ph.D.
Director of
Professional and Technical Writing
Associate
Professor of Technical Communication
Department
of English
Center for
Human-Computer Interaction
Virginia
Tech
Blacksburg,
VA 24061-0112
(540)200-8201
Michael is not crazy, yet. His use of the
permitted @data-hd-class mechanism mimics the DITA
trick of using schema-provided class attributes for
specialization. The base semantic itself is fully
transformable between <section-example> and your
HDITA example (which I agree is not as simple to
remember in an unassisted interface like Textpad).
By the way, custom tags require a hyphen,
and the "base-custom"
pairing to me seems to be a good way to carry both
semantics in place of the attribute. So thank you for
making the next connection in this story. I think the
pattern is regular enough to be reliable. Do you have
time to make up a table of the HDITA oddities and see
how they map to base/custom plain names? I can see
another potential research project here. ;-)
--
Don
On 4/19/2016 6:47 PM,
Carlos Evia wrote:
I think that if we were to embrace the custom tags in
HDITA for footnote, people would ask (and I am
“people”) why are we using data attributes for DITA to
HDITA mappings and how come, say, example
is <section data-hd-class="topic/example”> and
not just <example>?
Carlos
--
Carlos Evia, Ph.D.
Director of Professional and
Technical Writing
Associate Professor of
Technical Communication
Department of English
Center for Human-Computer
Interaction
Virginia Tech
Blacksburg, VA 24061-0112
(540)200-8201
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
--
"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
|