[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita-lightweight-dita] Footnotes again
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
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: donrdayTwitter: @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: donrdayTwitter: @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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]