RE: [dita-lightweight-dita] Footnotes again

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

http://dita.xml.org/blog/michael-priestley

From:      
 Noz Urbina <>
To:      
 Michael Priestley/Toronto/IBM@IBMCA
Cc:      
 
Date:      
 05/25/2016 10:38 PM
Subject:    
   RE: [dita-lightweight-dita]
Footnotes again
Sent by:    
   <>

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

http://dita.xml.org/blog/michael-priestley

From:        Michael
Priestley/Toronto/IBM@IBMCA
To:        ""
<>
Date:        05/10/2016
10:38 AM
Subject:        RE:
[dita-lightweight-dita] Footnotes again
Sent by:        <>

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

http://dita.xml.org/blog/michael-priestley

From:        Ullakaisa
Kalander <>
To:        ""
<>
Date:        05/10/2016
08:43 AM
Subject:        RE:
[dita-lightweight-dita] Footnotes again
Sent by:        <>

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: [mailto:]
On Behalf Of Noz Urbina
Sent: 07 May 2016 23:15
To: Scott Hudson <>
Cc: Don Day <>;
Michael Priestley <>;

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" <>
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: [mailto:]
On Behalf Of Michael Priestley
Sent: Friday, May 06, 2016 1:35 PM
To: Michael Priestley
Cc: Don Day; 
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

http://dita.xml.org/blog/michael-priestley

From:        Michael
Priestley/Toronto/IBM@IBMCA
To:        Don Day
<>
Cc:        
Date:        04/19/2016
10:51 AM
Subject:        Re:
[dita-lightweight-dita] More on footnotes in HTML5
Sent by:        <>

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

http://dita.xml.org/blog/michael-priestley

From:        Don Day
<>
To:        
Date:        04/19/2016
09:15 AM
Subject:        Re:
[dita-lightweight-dita] More on footnotes in HTML5
Sent by:        <>

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

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