Eliot, re “users
struggle to figure out WHERE to place the <xref>
elements” -- I flipped <fn> and <xref> in writing my
e-mail. Like my users, I lost track of what needed to go where
:(
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 8/15/2017 9:59 AM, Eliot Kimber
wrote:
The ability to
have multiple references to the same footnote is a hard
requirement, so we can’t simply remove the implications of
an xref to a fn.
However, I
think three things would help quite a bit:
1. Define a
dedicated fnref specialization of xref that sets @type to
“fn”. If this is sensible it might also be useful to have a
dedicated “fn-conref” that helps make a clearer distinction
between multiple references to the same note and re-use of a
note in multiple locations.
2. Remove the
requirement that if a fn element has an ID that you must use
it by reference. The first use of a footnote with an id can
occur inline and subsequent references to it are then done
with xref (and the order of occurrence shouldn’t matter—by
“first” here I mean “the first one authored”, not “first in
document order”).
3. Add a dedicated
“end notes” specialization of div that can occur at the end
of body that is intended to hold footnotes used only by
reference. This serves the authors who don’t like inline
footnotes and also provides a clear structural mapping to
end-note-style presentation (even if the notes ultimately
get referenced at the end of a higher-in-the-hierarchy topic
or at the end of the entire publication).
I’m not sure I
understand this statement: “users struggle to figure out WHERE
to place the <xref> elements”
Xrefs to fn
elements have to go at the point where you want the footnote
reference to occur—how could it be otherwise? But if this is
a problem, I think having an fnref element would help with
the confusion since there’s an obvious parallel between “fn”
and “fnref”.
It would also
be useful to codify a way to indicate the author’s intent
for footnotes within tables—that is, to treat the note as a
table footnote or a page/topic footnote, with the default
behavior being that footnotes within tables are treated as
table footnotes, since that’s the most common case I would
think. Alternatively, we can finally add table footers with
the requirement that table footnotes be placed in the footer
and referenced from within the table, which would make it
clear what the intent is.
Cheers,
Eliot
--
Eliot
Kimber
http://contrext.com
From: <>
on behalf of Kristen James Eberlein
<>
Date: Tuesday, August 15, 2017 at 8:30 AM
To: DITA TC <>
Subject: [dita] Footnotes
My personal take on the state of footnotes in DITA ... Your
mileage might vary. Please post to the list; this was a
general action item for everyone coming out of last week's
call.
Coverage in the spec is poor. There is only the
element reference topic, which I doubt has been updated
since DITA 1.0:
http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part3-all-inclusive/langRef/base/fn.html#fn
If you are not familiar with the DITA footnote
implementation, the topic probably doesn't make much sense.
The example (which actually is three examples jumbled
together) is not robust; it also does not demonstrate the
use of @conref on <fn>.
In my experience, users do not understand this
model unless it has been carefully explained and alternate
company-specific documentation has been provided.
This model is hard for users to author using
the use-by-reference
footnote.
Re #3, users struggle to figure out WHERE to place
the <xref> elements; they are fine with placing the
<fn> elements at the point in the text where the super
scripted footnote indicators will appear -- That makes sense
to them, although some chafe over the way the <fn>
element disrupts the visual flow of the topic in the authoring
environment. And others struggle withe the need to use conref
to reference common footnotes.
But the fact that the <xref> elements can go anywhere
in the topic that contains the <fn>; many writers really
struggle with that. And then they forget to specify type="fn".
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS
TC that generates this mail. Follow this link to all your TCs
in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
