OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Footnotes

    Posted 08-15-2017 13:31
    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)


  • 2.  Re: [dita] Footnotes

    Posted 08-15-2017 13:59
    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: <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. 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


  • 3.  Re: [dita] Footnotes

    Posted 08-15-2017 14:04
    I really like the fnref idea! Also like the dedicated fndiv... --Scott Sent from my iPhone On Aug 15, 2017, at 9:59 AM, Eliot Kimber < ekimber@contrext.com > 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: < 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. 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


  • 4.  Re: [dita] Footnotes

    Posted 08-15-2017 14:44
    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: <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. 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


  • 5.  Re: [dita] Footnotes

    Posted 08-15-2017 14:56
    That makes more sense—in the case of having a footnote referenced multiple times, knowing where to put it is indeed a challenge. People naturally have a hard time with “it doesn’t matter, put it anywhere”. Thus my suggestion of providing a container, even though it’s not strictly necessary.   Cheers,   E.   -- Eliot Kimber http://contrext.com       From: Kristen James Eberlein <kris@eberleinconsulting.com> Date: Tuesday, August 15, 2017 at 9:43 AM To: Eliot Kimber <ekimber@contrext.com>, DITA TC <dita@lists.oasis-open.org> 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 http://contrext.com       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. 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