Shouldn’t we plan for the most flexible approach? I’d hate to restrict footnote to a single para and find some use case where multiple paras or a list are needed. I have seen such footnotes in Higher Ed content, but I doubt they would be using lightweight…
--Scott
From: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org] On Behalf Of Michael Priestley
Sent: Friday, May 06, 2016 1:35 PM
To: Michael Priestley
Cc: Don Day; dita-lightweight-dita@lists.oasis-open.org
Subject: [dita-lightweight-dita] Footnotes again
I'd like to narrow this down to just one question, for the folks who need footnotes for the content:
- Can we limit the contents of a footnote to a single paragraph, or do they need to contain more (multiple paras, lists etc.)?
Answering that question first will help us focus the implementation discussion to a narrower range of possibilities.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From: Michael Priestley/Toronto/IBM@IBMCA
To: Don Day <donday@donrday.com>
Cc: dita-lightweight-dita@lists.oasis-open.org
Date: 04/19/2016 10:51 AM
Subject: Re: [dita-lightweight-dita] More on footnotes in HTML5
Sent by: <dita-lightweight-dita@lists.oasis-open.org>
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="" 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="" idea</p>
<fn id="n1"><p>Not that special</p></fn>
HTML5:
<p>Here's my special<a epub:type="noteref" href="" 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