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

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

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
>