[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] DITA v1.2 Review | @keys in a conref
I get a slightly different answer from Tarun's. In particular, topicsetref does *not* act like a conref so the child topicref of topicsetref is processed normally, meaning the keys "E", and M5 are part of the key space. (See my complete analysis below). ---------------------- However, this example does raise a point that is not explicitly addressed in the current architecture spec, namely the reference to specific topicrefs within submaps without referencing the map as a whole. Tarun's example reflects the assumption that only directly-addressed topicrefs contribute to the map tree. However the spec as written certainly implies that the first reference to any component of a map includes that map in the key space map tree and therefore includes all of its key definitions at that point in the key definition precedence hierarchy. That raises the question: is Tarun's assumption correct or incorrect? That is, does a reference to *any* topicref within a submap require including all the keys in that map in the key space or do you only consider the directly-addressed topicrefs and their descendants when constructing the key space? I can see that users and implementors might reasonably expect things to behave as Tarun has them (that is, only directly-addressed topics contribute to the key space). However, at this late date I would be hesitant to suggest that behavior. In thinking about it now I don't think it adds sufficient value to justify the additional implementation complexity and would likely break existing implementations. It doesn't enable anything you couldn't do another way (that is, precisely controlling key definition precedence). If we accepted the "only directly-addressed topicrefs" approach, it would mean the following: 1. The spec language would have to be updated to define key spaces in terms of the effective topicref tree and map tree, not just the map tree. 2. For the purposes of keyspace construction a reference to a map document as a whole would be effectively a reference to all of its descendant topicrefs. 3. Through direct references to topicrefs, keys defined in the same submap could have different positions in the key space topicref tree and thus have different precedence than they would if the first reference to anything in a map included all key definitions in that map. I suspect that most, if not all, existing key space constructors do not behave this way. For example, consider this root map where the submap defines the keys "A" and "B": <map> <!-- Defines key "A" --> <topicref href="submap.ditamap#keydef-a"/> <topicref keys="B"/> <topicref href="submap.ditamap#keydef-b"/> </map> If we say that the first reference to a map includes all of its key definitions into the keyspace, then the binding of key name "B" in the submap is effective, but if we say that only directly-addressed topicrefs contribute to the key space, then the binding of key name "B" in the root map is effective, because it occurs before the direct reference to the definition of "B" in the submap. I've attached a working instance of Tarun's test case. Topic 1.dita contains a reference to each of the keys defined in the maps and an indication of whether or not the key should be resolvable. The 1.5.2M2 Toolkit does not process it correctly in that it doesn't handle the case of key "B" correctly. It includes all the keys defined in map2.ditamap in the key space--the open question is whether or not that behavior is or is not correct. Likewise, Oxygen 11 includes all the keys defined in map2.ditamap in the key space (as indicated by it making them available for selection when creating key references). ---------------------------------- Here's my analysis of Tarun's example reflecting the "only referenced topicrefs contribute" behavior (with the "only maps" behavior, then all the keys defined in map2.ditamap are part of the key space because none conflict with keys defined in the root map): Key Space --------- A -> 1.dita Plain topicref that defines a key M2 -> b.dita Conref to tr02 where conref element does not specify @key, so key on conref target is effective. M22 -> b22.dita Child of conref target. B -> c.dita Conreffing element specifies @key so it's value is effective. Definition of keyname "C" ignored because of conref. M33 -> c33.dita Child of conref target is effective. M4 -> d.dita Topicref to topicref tr04 M44 -> d44.dita Child of topicref tr04 D -> map2.ditamap#tr05 Normal topicref. Note that semantics of topicsetref do not change semantics of key space construction. E -> 3.dita Child of normal topicref M5 -> 3.dita Topicref included in map tree via reference M55 -> e55.dita Child of normal topicref Cheers, Eliot On 9/4/10 1:37 AM, "Tarun Garg" <tarung@adobe.com> wrote: > Now with this understanding, suppose we have two maps as follows: > > Map1.ditamap: > ============= > <map> > <topicref keys="A" href="1.dita"/> > <topicref conref="map2.ditamap#tr02"/> > <topicref keys="B" conref="map2.ditamap#tr03"> > <topicref keys="C" href="2.dita"> > </topicref> > <topicsetref href=" map2.ditamap#tr04"/> > <topicsetref keys="D" href="map2.ditamap#tr05"> > <topicref keys="E" href="3.dita"> > </topicsetref> > </map> > > > Map2.ditamap: > ============= > <map> > <topicref id="tr01" keys="M1" href="a.dita"> > <topicref keys="M11" href="a11.dita"> > </topicref> > <topicref id="tr02" keys="M2" href="b.dita"> > <topicref keys="M22" href="b22.dita"> > </topicref> > <topicref id="tr03" keys="M3" href="c.dita"> > <topicref keys="M33" href="c33.dita"> > </topicref> > <topicref id="tr04" keys="M4" href="d.dita"> > <topicref keys="M44" href="d44.dita"> > </topicref> > <topicref id="tr05" keys="M5" href="e.dita"> > <topicref keys="M55" href="e55.dita"> > </topicref> > </map> > > > > Now for Map1.ditamap, the keyspace shall be as follows: > > Key | Target > ================== > A | 1.dita > M2 | b.dita > M22 | b22.dita > B | c.dita > M33 | c33.dita > M4 | d.dita > M44 | d44.dita > D | map2.ditamap#tr05 > M55 | e55.dita > > - Keys C & E are ignored due to conref & topicsetref resolution. > - Key M3 is not there as due to conref resolution key B; the already existing > @keys value gets used. > - Key M5 is not there as due to topicsetref resolution key D; the already > existing @keys value gets used. > > Please correct me if I am getting it wrong somewhere. > > Regards, > Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com > > > -----Original Message----- > From: Eliot Kimber [mailto:ekimber@reallysi.com] > Sent: Thursday, September 02, 2010 4:39 PM > To: Tarun Garg; dita > Subject: Re: [dita] DITA v1.2 Review | @keys in a conref > > For the purpose of constructing a key space, the system should resolve any > non-key-based conrefs in the maps, determine the effective map tree, and > then construct the key space. Key-based conrefs between maps and maps or > topicrefs and topicrefs cannot be resolved until the key space has been > constructed and therefore cannot affect the key space. > > Once the key space has been constructed then all remaining key-based conrefs > can be resolved, which determines the final map tree, but cannot change the > effective key space. Because any use of a key for conref must ultimately use > an href to address the document that contains the conref target (in this > case, map documents for the case of topicref-to-topicref conrefs), then > every map document will be part of the map tree. The only question is > *where* in the map tree the map's topicrefs occur for the purpose of > determining the key space. > > That is, you could have a key-based conref of a key-defining topicref that > occurs before the direct reference of the map containing that key > definition. If a definition of the same key name occurs between the conref > and the inclusion of the map containing the conref target topicref, then the > intervening key definition will be the effective definition (because of the > precedence rules of key definitions). > > Said simply, only directly-conreffed (that is addresed by hrefs) topicrefs > and maps can be resolved during key space construction. Or even more simply, > only directly-addressed maps contribute to the key-space-defining map tree > (which subsumes direct conrefs of topicrefs since a direct conref of a > topicref must first address the map document that contains the topicref, > adding that map to the effective key space map tree). > > In practice this should not be an issue because there is no good use case > that I can think of for conreffing topicrefs and this very limitation would > further argue against using conrefs in maps, given that there are other > facilities for combining map components into composite maps. > > Note that the DITA 1.x spec *cannot* mandate a processing sequence because > of backward compatibility issues (see the non-normative interoperability > appendix, which explains some of the issues around this fact). So whether > conref resolution is performed before or after key space construction is up > to processors, but since keyref is an entirely new feature one hopes that > processors will implement it consistently. > > Cheers, > > Eliot > > On 9/2/10 3:50 AM, "Tarun Garg" <tarung@adobe.com> wrote: > >> I thought we don't use conref, topicsetref, keyref & conkeyref resolution for >> determining the keyspace. For keyref & conkeyref, it is very obvious that >> since they depend on keyspace, these shall not be resolved until the keyspace >> is determined completely. But for conref & topicsetref, it is possible that >> these elements (prior to resolution), have key definitions on themselves or >> on >> any of their descendants. >> >> That brings the following questions to my mind: >> 1) For determining keyspace, should the conref & topicsetref be resolve? >> 2) If (1) is yes, should the key definitions be included from any of the >> descentants of the conref/topicsetref target/referenced element (for conref >> range this shall also means siblings from the target) >> 3) if (1) is no, should the key definitions be included from any of the >> descentants of the conref/topicsetref referencing element >> >> >> Regards, >> Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com >> >> >> -----Original Message----- >> From: Eliot Kimber [mailto:ekimber@reallysi.com] >> Sent: Wednesday, September 01, 2010 10:34 AM >> To: Tarun Garg; dita >> Subject: Re: [dita] DITA v1.2 Review | @keys in a conref >> >> In your example, the effective element after conref resolution is: >> >> <topicref id="tr-02" keys="TR02" href="abc.dita"/> >> >> By the rule that conreffing elements' attributes take precendence over the >> attributes of the conref target. >> >> Assuming that map1.ditamap is otherwise included in the map tree, then both >> key TR01 and TR02 would be bound and both would be bound to resource >> "abc.dita". >> >> Cheers, >> >> Eliot >> >> On 8/31/10 11:55 PM, "Tarun Garg" <tarung@adobe.com> wrote: >> >>> I am not able to identify the use of @keys at an element that is actually a >>> conref. In case of a conref, the @href may be generally missing as that >>> shall >>> be derived from the referenced element. >>> >>> Say for example, in a map there is topicref element which is actually a >>> conref >>> to a topicref element in another map. >>> >>> In map1.ditamap: >>> <map> >>> SS. >>> <topicref id=²tr-01² keys=²TR01² href=²abc.dita²/> >>> SS. >>> </map> >>> >>> In map2.ditamap: >>> <map> >>> SS. >>> <topicref id=²tr-02² keys=²TR02² conref=²map1.ditamap#tr-01²/> >>> SS. >>> </map> >>> >>> What shall the key TR02 resolve to? As I understand, that resolves to >>> nothing. >>> Also, is there any specific use of such a key in a conref element, apart >>> from >>> defining a key that points to nothing. I am not ruling out the cases where >>> such an element carries an @href as well. But in that case, the purpose of >>> conref is undermined. >>> >>> Regards, >>> Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com >>> >> >> -- >> Eliot Kimber >> Senior Solutions Architect >> "Bringing Strategy, Content, and Technology Together" >> Main: 512.554.9368 >> www.reallysi.com >> www.rsuitecms.com >> > > -- > Eliot Kimber > Senior Solutions Architect > "Bringing Strategy, Content, and Technology Together" > Main: 512.554.9368 > www.reallysi.com > www.rsuitecms.com > -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com
test-direct-ref-to-keydefs.zip
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]