RE: [dita] Bug: fragref does not allow keyref

[Robert D Anderson <robander@us.ibm.com>]

I certainly can't argue that one would never have a valid reason to
reference content in another diagram or outside of the topic. However, what
I can argue is that the DITA Specification from 1.0 up to the latest draft
says that the target of these references should be in the same diagram, and
that as such it's not really something worthy of a last-minute change in
the 1.2 specification. I don't think that the missing keyref was an
oversight, and thus wasn't a bug - it went along with the previous
description and understanding of the elements. It's always worth discussing
when something in the spec seems too limiting, but that doesn't mean that
the existing markup or description is broken.

For this specific request - to add keyref to <fragref> and <synnoteref> -
an update requires that we change the definition of each element and of
their attributes. It also means allowing behaviors that were previously
forbidden. So far, it sounds like the primary incentives to make this
change are 1) completeness and 2) the theoretical position that the spec
should not limit what is possible. Unless there is actually a demonstrated
requirement that makes this critical for 1.2, I think we have to push this
change to 1.3.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

"Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote on 01/25/2010 03:46:26 PM:

> RE: [dita] Bug: fragref does not allow keyref
>
> Yes, thanks, I understand.
>
> I also understand that it is easy to use <fragment> and <fragref> in a
> way that mere humans would find impenetrably obscure and useless. That's
> a limit of practicality. And there may be current limitations on what
> can be processed and rendered. I've inferred that from parts of this
> thread. But those issues are different from a principled "Thou shalt not
> put <fragref> in a different topic from the referenced <fragment> (and
> that's why the absence of @keyref is irrelevant)."
>
> The fragment topic in the lang ref now says only that you can break out
> logical chunks of a large syntax diagram into named fragments. The few
> hints of what for are only in the fragref topic. There, in addition to
> the two cases you mention ([1] discuss one fragment at a time, and [2]
> reuse a fragment within the same diagram), the text suggests (or does
> not preclude) another case, where the same chunk of marked-up syntax
> occurs in more than one diagram, and could therefore be in <fragment> in
> one disgram and profitably reused in other diagrams with <fragref>. This
> could be for variants of a diagram in one topic. However, it does not
> say that both <fragment> and <fragref> have to be in the same topic.
> Should it?
>
> Suppose an organization sees value in reusing a large, complex
> <fragment> in this way, and are willing and able to shoulder the
> maintenance of it. They can do so now with @href but not with @keyref.
> Hence, Eliot's question. (I see that there's no @conref on <fragment>.)
>
> > -----Original Message-----
> > From: Robert D Anderson [mailto:robander@us.ibm.com]
> > Sent: Monday, January 25, 2010 12:53 PM
> > To: Bruce Nevin (bnevin)
> > Cc: dita
> > Subject: RE: [dita] Bug: fragref does not allow keyref
> >
> > Hi Bruce,
> >
> > > According to that shortdesc, "to break out a chunk of
> > syntax to render
> > > on its own" is not "the" purpose but rather just one of the
> > two stated
> > > purposes of <fragref>. The other purpose is analogous to
> > @conref, to
> > > "reference a syntax fragment multiple times".
> >
> > The purpose of the fragment element itself is to break out
> > content; the purpose of the fragref is to reference that
> > content. The fragment may be broken out because it is large
> > and better understood on its own, or it may be broken out
> > because it is used several times in the diagram. Use of the
> > <fragref> inside a diagram simply indicates where that
> > fragment belongs in the order of the statement you're describing.
> >
> > Robert D Anderson
> > IBM Authoring Tools Development
> > Chief Architect, DITA Open Toolkit
> >
> > "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote on 01/25/2010
> > 12:16:02 PM:
> >
> > >
> > > RE: [dita] Bug: fragref does not allow keyref
> > >
> > > There is no doubt, I think, that a set of complex syntax
> > formulae can
> > > have partial structures in common. It sounds like reuse of such
> > > recurrent partials with <fragref> is not a "best practice"
> > , because
> > > "fragref would be difficult to understand if it takes you
> > out of the
> > > current diagram to syntax that is part of another set of syntax."
> > >
> > > A perhaps stronger reason it's not a best practice is that the
> > > parallelism might break over time--the referenced content might be
> > > subject to change independently of the referencing syntax diagrams.
> > > This is a main reason that @conref referencing something in an
> > > ordinary topic is not a best practice, and special topics are
> > > constructed for @conref to reference.
> > >
> > > The lang ref (both 1.1 and 1.2) says:
> > >
> > >    The fragment reference (<fragref>) element
> > >    provides a logical reference to a syntax
> > >    definition fragment so that you can reference
> > >    a syntax fragment multiple times, or pull a
> > >    large section of syntax out of line for
> > >    easier reading.
> > >
> > > According to that shortdesc, "to break out a chunk of
> > syntax to render
> > > on its own" is not "the" purpose but rather just one of the
> > two stated
> > > purposes of <fragref>. The other purpose is analogous to
> > @conref, to
> > > "reference a syntax fragment multiple times".
> > >
> > > Would that second usage be OK for cross-topic references if the
> > > referenced content were stored in a special topic created only to
> > > contain referenced content? It works for @conref, in the
> > face of the
> > > same concern about reuse and the stability (and
> > understandability) of
> > > referenced content.
> > >
> > > If not, or if the answer is "use @conref for that", or if something
> > > more specific is intended where it says "reference ... multiple
> > > times", then the description in the lang ref needs to change.
> > >
> > >    /B
> > >
> > > > -----Original Message-----
> > > > From: Eliot Kimber [mailto:ekimber@reallysi.com]
> > > > Sent: Monday, January 25, 2010 9:23 AM
> > > > To: Robert D Anderson
> > > > Cc: dita
> > > > Subject: Re: [dita] Bug: fragref does not allow keyref
> > > >
> > > > On 1/25/10 8:15 AM, "Robert D Anderson"
> > <robander@us.ibm.com> wrote:
> > > >
> > > > > As I've always understood these elements, they do not make
> > > > sense when
> > > > > used to reference a fragment or synnote in another
> > diagram. I know
> > > > > that the tools we use to render syntax diagrams in IBM do not
> > > > > allow these to reference elements in other diagrams.
> > > > >
> > > > > The DITA 1.1 langspec for fragref/@href says that the
> > > > target fragment
> > > > > "should" be in the same diagram. I have always viewed this as a
> > > > > "must". The purpose of <fragment> is to break out a chunk
> > > > of syntax to
> > > > > render on its own; it seems that fragref would be difficult to
> > > > > understand if it takes you out of the current diagram to
> > > > syntax that is part of another set of syntax.
> > > > >
> > > > > For synnoteref, the 1.1 spec begins with "The syntax note
> > > > > (<synnoteref>) reference element references a syntax
> > note element
> > > > > (<synnote>) that has already been defined elsewhere in
> > the syntax
> > > > > diagram." The synnoteref/@href description also says that
> > > > the target must be in the same diagram.
> > > >
> > > > I was basing my analysis on this statement under synnoteref:
> > > >
> > > > " The same notation can be used in more than one syntax
> > definition. "
> > > >
> > > > That suggests that you might define a syntax note in one
> > diagram and
> > > > reference it from another diagram. Otherwise the
> > statement does not
> > > > appear to make sense.
> > > >
> > > > I think that limiting the addressing syntax in order to
> > enforce an
> > > > essentially arbitrary restriction is the wrong thing to
> > do. First,
> > > > the @href syntax in no way limits the scope of the
> > address, so that
> > > > by itself cannot enforce the "same diagram" requirement. It also
> > > > creates a special case that processors have to handle to
> > no obvious
> > > > purpose.
> > > >
> > > > If the intent of the standard is that *there is no
> > possible universe
> > > > in which references from one diagram to another would
> > ever be useful
> > > > or
> > > > meaningful* then the definition of these elements should say that
> > > > and let processors validate the addresses, URI or key-based.
> > > >
> > > > But if we cannot say with certainty that cross-diagram references
> > > > are
> > > > *never* meaningful then we *must* allow keyref by the basic
> > > > principle of consistency.
> > > >
> > > > Cheers,
> > > >
> > > > E.
> > > >
> > > > --
> > > > Eliot Kimber
> > > > Senior Solutions Architect
> > > > "Bringing Strategy, Content, and Technology Together"
> > > > Main: 610.631.6770
> > > > www.reallysi.com
> > > > www.rsuitecms.com
> > > >
> > > >
> > > >
> > --------------------------------------------------------------------
> > > > - 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_workgr
> > > > oups.php
> > > >
> > > >
> > >
> > >
> > ---------------------------------------------------------------------
> > > 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
> > >
> >
> >