My original question about keyref on <fragref> was based on the (incorrect) assumption that it would be meaningful to have a fragment defined in a separate syntax diagram in a separate topic to which you might want to refer. I see that the 1.2 discussion of @href for <fragref> specifically disallows that case. Likewise for <synnoteref>. I can imagine cases where you want to describe fragments of larger complex commands in isolation and have specific commands refer to them, rather than repeat them. But I don't have strong enough feelings about it to argue for expanding the current semantics of syntax diagrams. If this limitation on referencing is acceptable to the community then clearly @keyref is not useful. Thus, I think Robert's original "not a bug" response to my bug report is appropriate and we can retire 13046. If there is community outcry for cross-topic syntax diagram references then we can revisit this at that time, I think. Cheers, E. On 1/26/10 8:52 AM, "Bruce Nevin (bnevin)" <
bnevin@cisco.com> wrote: > 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 >>>>> >>>> >>>> >> >> > > --------------------------------------------------------------------- > 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 -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368
www.reallysi.com www.rsuitecms.com