[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Bug: fragref does not allow keyref
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 > > > > > > > > > > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]