OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Proposal 13046 (was Re: [dita] Bug: fragref does not allow keyref)


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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]