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

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

Yes, for sure, this is not a 1.2 question.

I was looking at the main paragraph describing <fragref>. I see that the
limitation is stated in the description of @href farther down in the
fragref topic.

	/B

> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com] 
> Sent: Monday, January 25, 2010 5:20 PM
> To: Bruce Nevin (bnevin)
> Cc: dita
> Subject: RE: [dita] Bug: fragref does not allow keyref
> 
> 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.p
> > > hp
> > > >
> > >
> > >
> 
>