Lightweight DITA SC

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

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 Virus-free. www.avast.com

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 Virus-free. www.avast.com -- 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

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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 On Apr 19, 2016, at 12:45 PM, Don Day < donday@donrday.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 On Apr 19, 2016, at 12:45 PM, Don Day < donday@donrday.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 On Apr 20, 2016, at 12:16 AM, Don Day < donday@donrday.com > wrote: 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 On Apr 19, 2016, at 12:45 PM, Don Day < donday@donrday.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 On Apr 20, 2016, at 12:16 AM, Don Day < donday@donrday.com > wrote: 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 On Apr 19, 2016, at 12:45 PM, Don Day < donday@donrday.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically? On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

In the user manuals we’re working with, the most common use case seems to be the one-line table footnote. However, allowing block-level
content is seen as the safer alternative here too.
 
UK



From: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org]
On Behalf Of Noz Urbina
Sent: 07 May 2016 23:15
To: Scott Hudson <scott.hudson@jeppesen.com>
Cc: Don Day <donday@donrday.com>; Michael Priestley <mpriestl@ca.ibm.com>; dita-lightweight-dita@lists.oasis-open.org
Subject: RE: [dita-lightweight-dita] Footnotes again
 
In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically?

On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote:



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






Virus-free.
www.avast.com









--
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






Virus-free.
www.avast.com

OK so I think we've got clear direction on footnotes needing block content. So here's the next question: - do we allow <fn> in a paragraph to directly contain block elements? (the "single-use footnote" model in full DITA) - or do we allow <fn> only as a block element, which must be referenced by an xref from within a para? ( the "use-by-reference footnote" model in full DITA) Here's the full DITA writeup for details: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn The <fn> element in full DITA can occur in both block and phrase contexts. Its content model also allows both blocks and phrases. This is flexible but also really messy from a content model perspective - we've gotten rid of other examples of this messiness throughout Lightweight DITA, so it will stand out if we allow it here. If we allow <fn> into a phrase context with block-level content, then we give editors the job of dealing with block-level content nested within paragraphs - something we've systematically gotten rid of everywhere else in Lightweight DITA. But if we make <fn> a block-level element only, then we give authors the job of dealing with cross-references using the xref model (which we can make slightly easier by creating a specialized <fnref> element just for footnote references). This would map relatively easily to HTML5, EPUB, and most Markdown extensions (Multimarkdown, Pandoc, PHP Markdown, etc.) Net: - single-use footnote model is easier for authors using XML - use-by-reference model is easier for authoring tools, and easier for authors using HTML5 or Markdown Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Ullakaisa Kalander <Ullakaisa.Kalander@citec.com> To:         "dita-lightweight-dita@lists.oasis-open.org" <dita-lightweight-dita@lists.oasis-open.org> Date:         05/10/2016 08:43 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         <dita-lightweight-dita@lists.oasis-open.org> In the user manuals we’re working with, the most common use case seems to be the one-line table footnote. However, allowing block-level content is seen as the safer alternative here too.   UK From: dita-lightweight-dita@lists.oasis-open.org [ mailto:dita-lightweight-dita@lists.oasis-open.org ] On Behalf Of Noz Urbina Sent: 07 May 2016 23:15 To: Scott Hudson <scott.hudson@jeppesen.com> Cc: Don Day <donday@donrday.com>; Michael Priestley <mpriestl@ca.ibm.com>; dita-lightweight-dita@lists.oasis-open.org Subject: RE: [dita-lightweight-dita] Footnotes again   In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically? On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

We discussed this at the last SC call, and the majority were in favour of <fn> as a block element, rather than allowing it inside a <p> as an inline element that contains block elements. Keith Schengili-Roberts dissented but was ok with majority view on this, assuming those on the list agree. If we do go with <fn> as a block element, that does make it nicely parallel/equivalent to footnote markup in HTML/EPUB and various Markdown extensions. So here's the formal proposal, as agreed at the last meeting, for discussion/agreement on the list before moving forward: 1. Add <fn> as a new block element, available in all block contexts, with the same content model as table cells         has a required id, to force the use-by-reference model as described here: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn 2. Add <fnref> as a new inline element, specialized from xref, with a fixed type value of fn 3. Rename the table-blocks entity to simple-blocks, so we can reuse it for fn and note content as well as table cells: <!ENTITY % simple-blocks "p ul ol dl pre audio video fn note"> I know I'm sneaking some mentions of the note element into the mix - I'll send a separate note on the proposal there. 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:         "dita-lightweight-dita@lists.oasis-open.org" <dita-lightweight-dita@lists.oasis-open.org> Date:         05/10/2016 10:38 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         <dita-lightweight-dita@lists.oasis-open.org> OK so I think we've got clear direction on footnotes needing block content. So here's the next question: - do we allow <fn> in a paragraph to directly contain block elements? (the "single-use footnote" model in full DITA) - or do we allow <fn> only as a block element, which must be referenced by an xref from within a para? ( the "use-by-reference footnote" model in full DITA) Here's the full DITA writeup for details: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn The <fn> element in full DITA can occur in both block and phrase contexts. Its content model also allows both blocks and phrases. This is flexible but also really messy from a content model perspective - we've gotten rid of other examples of this messiness throughout Lightweight DITA, so it will stand out if we allow it here. If we allow <fn> into a phrase context with block-level content, then we give editors the job of dealing with block-level content nested within paragraphs - something we've systematically gotten rid of everywhere else in Lightweight DITA. But if we make <fn> a block-level element only, then we give authors the job of dealing with cross-references using the xref model (which we can make slightly easier by creating a specialized <fnref> element just for footnote references). This would map relatively easily to HTML5, EPUB, and most Markdown extensions (Multimarkdown, Pandoc, PHP Markdown, etc.) Net: - single-use footnote model is easier for authors using XML - use-by-reference model is easier for authoring tools, and easier for authors using HTML5 or Markdown Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Ullakaisa Kalander <Ullakaisa.Kalander@citec.com> To:         "dita-lightweight-dita@lists.oasis-open.org" <dita-lightweight-dita@lists.oasis-open.org> Date:         05/10/2016 08:43 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         <dita-lightweight-dita@lists.oasis-open.org> In the user manuals we’re working with, the most common use case seems to be the one-line table footnote. However, allowing block-level content is seen as the safer alternative here too. UK From: dita-lightweight-dita@lists.oasis-open.org [ mailto:dita-lightweight-dita@lists.oasis-open.org ] On Behalf Of Noz Urbina Sent: 07 May 2016 23:15 To: Scott Hudson <scott.hudson@jeppesen.com> Cc: Don Day <donday@donrday.com>; Michael Priestley <mpriestl@ca.ibm.com>; dita-lightweight-dita@lists.oasis-open.org Subject: RE: [dita-lightweight-dita] Footnotes again In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically? On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

Just to be clear, this means that you can insert a block foot note anywhere, and it will appear like a note or para (block level), or use the inline xref and point to it from any inline, correct? I ask because I have a client who wants to build a library of notes and reuse the same note sometimes as a block level under a para and sometimes with an inline xref. Noz On 25 May 2016 9:11 p.m., "Michael Priestley" < mpriestl@ca.ibm.com > wrote: We discussed this at the last SC call, and the majority were in favour of <fn> as a block element, rather than allowing it inside a <p> as an inline element that contains block elements. Keith Schengili-Roberts dissented but was ok with majority view on this, assuming those on the list agree. If we do go with <fn> as a block element, that does make it nicely parallel/equivalent to footnote markup in HTML/EPUB and various Markdown extensions. So here's the formal proposal, as agreed at the last meeting, for discussion/agreement on the list before moving forward: 1. Add <fn> as a new block element, available in all block contexts, with the same content model as table cells         has a required id, to force the use-by-reference model as described here: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn 2. Add <fnref> as a new inline element, specialized from xref, with a fixed type value of fn 3. Rename the table-blocks entity to simple-blocks, so we can reuse it for fn and note content as well as table cells: <!ENTITY % simple-blocks "p ul ol dl pre audio video fn note"> I know I'm sneaking some mentions of the note element into the mix - I'll send a separate note on the proposal there. 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:         " dita-lightweight-dita@lists.oasis-open.org " < dita-lightweight-dita@lists.oasis-open.org > Date:         05/10/2016 10:38 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         < dita-lightweight-dita@lists.oasis-open.org > OK so I think we've got clear direction on footnotes needing block content. So here's the next question: - do we allow <fn> in a paragraph to directly contain block elements? (the "single-use footnote" model in full DITA) - or do we allow <fn> only as a block element, which must be referenced by an xref from within a para? ( the "use-by-reference footnote" model in full DITA) Here's the full DITA writeup for details: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn The <fn> element in full DITA can occur in both block and phrase contexts. Its content model also allows both blocks and phrases. This is flexible but also really messy from a content model perspective - we've gotten rid of other examples of this messiness throughout Lightweight DITA, so it will stand out if we allow it here. If we allow <fn> into a phrase context with block-level content, then we give editors the job of dealing with block-level content nested within paragraphs - something we've systematically gotten rid of everywhere else in Lightweight DITA. But if we make <fn> a block-level element only, then we give authors the job of dealing with cross-references using the xref model (which we can make slightly easier by creating a specialized <fnref> element just for footnote references). This would map relatively easily to HTML5, EPUB, and most Markdown extensions (Multimarkdown, Pandoc, PHP Markdown, etc.) Net: - single-use footnote model is easier for authors using XML - use-by-reference model is easier for authoring tools, and easier for authors using HTML5 or Markdown Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Ullakaisa Kalander < Ullakaisa.Kalander@citec.com > To:         " dita-lightweight-dita@lists.oasis-open.org " < dita-lightweight-dita@lists.oasis-open.org > Date:         05/10/2016 08:43 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         < dita-lightweight-dita@lists.oasis-open.org > In the user manuals we’re working with, the most common use case seems to be the one-line table footnote. However, allowing block-level content is seen as the safer alternative here too. UK From: dita-lightweight-dita@lists.oasis-open.org [ mailto:dita-lightweight-dita@lists.oasis-open.org ] On Behalf Of Noz Urbina Sent: 07 May 2016 23:15 To: Scott Hudson < scott.hudson@jeppesen.com > Cc: Don Day < donday@donrday.com >; Michael Priestley < mpriestl@ca.ibm.com >; dita-lightweight-dita@lists.oasis-open.org Subject: RE: [dita-lightweight-dita] Footnotes again In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically? On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com

According to the full DITA spec, a <fn> with an id is not rendered at all unless it is referenced by an <xref> (or <fnref>, in our proposal). We can't really break that without breaking compatibility with full DITA (which we can decide to do, but it should be for really good reasons - not sure if note/footnote handling is a big enough fish). http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/base/fn.html#fn So it means you can insert a block footnote anywhere a block is allowed, but it does not render at all unless it has a matching <fnref>, in which case it is rendered in standard footnote manner (eg at bottom of page). I think to get the behavior you describe, there would be a couple of options: - if the foot/notes always contain just one element (eg a para, or a list) then the user could create <note> elements with an id on them, that contain an element (<p> or <ul>) with an id on them. When they want a <note> they would conref the note, when they want to reuse the same content into a <fn> they would create a container <fn> and then conref the <p> or <ul> into the container <fn> - if the foot/notes have unpredictable amounts of content, then the user could create a common topic of <note> elements, and then either conref them directly into a note for direct display, or into an <fn> container for footnote display. But then the system would need to override normal <note> processing, within an <fn> context, to remove the Note : label. I hope that made sense... sorry I didn't have time to example it all out, but wanted to get you a reply. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Noz Urbina <b.noz.urbina@gmail.com> To:         Michael Priestley/Toronto/IBM@IBMCA Cc:         dita-lightweight-dita@lists.oasis-open.org Date:         05/25/2016 10:38 PM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         <dita-lightweight-dita@lists.oasis-open.org> Just to be clear, this means that you can insert a block foot note anywhere, and it will appear like a note or para (block level), or use the inline xref and point to it from any inline, correct? I ask because I have a client who wants to build a library of notes and reuse the same note sometimes as a block level under a para and sometimes with an inline xref. Noz On 25 May 2016 9:11 p.m., "Michael Priestley" < mpriestl@ca.ibm.com > wrote: We discussed this at the last SC call, and the majority were in favour of <fn> as a block element, rather than allowing it inside a <p> as an inline element that contains block elements. Keith Schengili-Roberts dissented but was ok with majority view on this, assuming those on the list agree. If we do go with <fn> as a block element, that does make it nicely parallel/equivalent to footnote markup in HTML/EPUB and various Markdown extensions. So here's the formal proposal, as agreed at the last meeting, for discussion/agreement on the list before moving forward: 1. Add <fn> as a new block element, available in all block contexts, with the same content model as table cells         has a required id, to force the use-by-reference model as described here: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn 2. Add <fnref> as a new inline element, specialized from xref, with a fixed type value of fn 3. Rename the table-blocks entity to simple-blocks, so we can reuse it for fn and note content as well as table cells: <!ENTITY % simple-blocks "p ul ol dl pre audio video fn note"> I know I'm sneaking some mentions of the note element into the mix - I'll send a separate note on the proposal there. 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:         " dita-lightweight-dita@lists.oasis-open.org " < dita-lightweight-dita@lists.oasis-open.org > Date:         05/10/2016 10:38 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         < dita-lightweight-dita@lists.oasis-open.org > OK so I think we've got clear direction on footnotes needing block content. So here's the next question: - do we allow <fn> in a paragraph to directly contain block elements? (the "single-use footnote" model in full DITA) - or do we allow <fn> only as a block element, which must be referenced by an xref from within a para? ( the "use-by-reference footnote" model in full DITA) Here's the full DITA writeup for details: http://docs.oasis-open.org/dita/dita/v1.3/csprd01/part1-base/langRef/base/fn.html#fn The <fn> element in full DITA can occur in both block and phrase contexts. Its content model also allows both blocks and phrases. This is flexible but also really messy from a content model perspective - we've gotten rid of other examples of this messiness throughout Lightweight DITA, so it will stand out if we allow it here. If we allow <fn> into a phrase context with block-level content, then we give editors the job of dealing with block-level content nested within paragraphs - something we've systematically gotten rid of everywhere else in Lightweight DITA. But if we make <fn> a block-level element only, then we give authors the job of dealing with cross-references using the xref model (which we can make slightly easier by creating a specialized <fnref> element just for footnote references). This would map relatively easily to HTML5, EPUB, and most Markdown extensions (Multimarkdown, Pandoc, PHP Markdown, etc.) Net: - single-use footnote model is easier for authors using XML - use-by-reference model is easier for authoring tools, and easier for authors using HTML5 or Markdown Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley From:         Ullakaisa Kalander < Ullakaisa.Kalander@citec.com > To:         " dita-lightweight-dita@lists.oasis-open.org " < dita-lightweight-dita@lists.oasis-open.org > Date:         05/10/2016 08:43 AM Subject:         RE: [dita-lightweight-dita] Footnotes again Sent by:         < dita-lightweight-dita@lists.oasis-open.org > In the user manuals we’re working with, the most common use case seems to be the one-line table footnote. However, allowing block-level content is seen as the safer alternative here too. UK From: dita-lightweight-dita@lists.oasis-open.org [ mailto:dita-lightweight-dita@lists.oasis-open.org ] On Behalf Of Noz Urbina Sent: 07 May 2016 23:15 To: Scott Hudson < scott.hudson@jeppesen.com > Cc: Don Day < donday@donrday.com >; Michael Priestley < mpriestl@ca.ibm.com >; dita-lightweight-dita@lists.oasis-open.org Subject: RE: [dita-lightweight-dita] Footnotes again In the banking sector work I'm doing legal notes have multiple paras. And links in case that needs calling out specifically? On 6 May 2016 9:38 p.m., "Scott Hudson" < scott.hudson@jeppesen.com > wrote: 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 Virus-free. www.avast.com -- 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 Virus-free. www.avast.com