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

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

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
> >
> 
>