OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Footnotes


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

 

 

 

From: <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Tuesday, August 15, 2017 at 8:30 AM
To: DITA TC <dita@lists.oasis-open.org>
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.

  1. 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>.
  2. In my experience, users do not understand this model unless it has been carefully explained and alternate company-specific documentation has been provided.
  3. 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




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]