Re: [dita] Issue #345 and the <abbreviated-form> element

[Eliot Kimber <ekimber@contrext.com>]

 I think I agree with Robert that the DITA 1.3 rules must be defined as rendering expectations, because that's definitely what they are.

I'm fine with abbreviated-form having these rules *when referencing glossary terms* because glossary terms are a specific thing with specific rules. It seems unlikely that anyone (knowingly) using abbreviated-from would be surprised if the rendered result did not match the new 2.0 rules for general keyref resolution.

For the case where abbreviated-form points to something other than glossentry then I think the new 2.0 rules should apply.

Cheers,

E.
--
Eliot Kimber
http://contrext.com
 

ïOn 11/10/20, 8:19 AM, "Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of kris@eberleinconsulting.com> wrote:







        I've gotten (very solid) reviews from each reviewer about #345,
          "New element for defining variable text." But we've uncovered an
          issue about the <abbreviated-form> that we need the TC to
          consider.
        The DITA 1.3 rules for how processors resolve variable text start
          with the following text:

        " 1. For the <abbreviated-form> element,
          see the rules described in abbreviated-form."
           <http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part3-all-inclusive/langRef/technicalContent/abbreviated-form.html>
        Because <abbreviated-form> does not
          exist in the base, I excluded it from the rules that I proposed in
          issue #345. (And the "rules" outlined for <abbreviated-form>
          in 1.3 are quite problematic ...)



        However, reviewers rightfully pointed out
          that we (DITA TC and spec) need to account for
          <abbreviated-form>. Chris Nitchie suggested that we had the
          following options:


        1. We modify this proposal to add it.
          2. When the time comes, abbreviated-form in 2.0 uses some other
          mechanism of its own design (with its own attributes) to reference
          the thing it's pointing to, which is like a keyref, but different
          in its text resolution.
          3. The abbreviated-form element doesn't make the transition to
          2.0, and we mandate that the abbreviated forms be defined as their
          own keys in 2.0.
          4. We decide to go ahead and allow abbreviated-form to have its
          own keytext resolution rules.


        Robert Anderson suggested that we treat
          the DITA 1.3 rules for <abbreviated-form> as DITA 2.0
          rendering expectations.



        Obviously, we need discussion here ...


        Here's a bried summary of what the 1.3
          spec says about <abbreviated-form>:




          1. If the <abbreviated-form> element references a
            non-glossentry topic, render the title of the referenced topic.
            (This conflicts with what is proposed in #345.)
                If the <abbreviated-form> element references a
            glossentry topic, go to #2.
          2. If the <abbreviated-form> element is in an
            "introductory context, go to #3.
                If the <abbreviated-form> element is in a
            "non-introductory context, go to #34.
          3. Render the contents of the following elements, in the
            specified order:
               a. <glossSurfaceForm>
               b. <glossterm>
          4. Render the contents of the following elements, in the
            specified order:
               a. <glossAcronym>
               b. <glossterm>
          We do not define "introductory" or "non-introductory" contexts.
            In fact, we explicitly say "Note that the definition of an
            introductory context will differ for each deliverable format."

        -- 
          Best,
          Kris

          Kristen James Eberlein
          Chair, OASIS DITA Technical Committee
          OASIS Distinguished Contributor
          Principal consultant, Eberlein Consulting LLC
          www.eberleinconsulting.com <http://www.eberleinconsulting.com>
          +1 919 622-1501; 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