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

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

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