[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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 > > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]