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: Re: [dita] Key scopes and topicsetref


> A lot of this boils down to whether there's anything 'special' about
> <topicsetref> as distinct from other topicref/mapref types. From a
> processing perspective, is there any difference at all between these
> two elements?
>
> <mapref href="" type="topicset"/>
> <topicsetref href="">

In the tools I've worked with, there is no difference.

In the tools Erik Hennum was working on 5 or 7 years ago, he recognized <topicsetref> and skipped resolution of that reference, so that the "output" for his tool just contained a pointer to another map artifact.

> (But if there
> really is no difference, then <topicset> and <topicsetref> strike me
> as almost entirely useless.)


As I've understood it, <topicset> exists entirely for the extra semantic of "This is a set of info that should always be treated as a unit, and not broken apart". For most processing contexts, the result will not differ. Erik had other output concerns where that mattered - can't remember exactly what, but I think maybe searching for info always took you to the set, rather than into it. I think it's the same as with most specialized elements - specialization adds some meaning that is useful for some people; those people may try to do something different with their content as a result.

As I've understood <topicsetref>, it is just a shortcut for referencing <topicset> - tools can recognize that the target should be <topicset> without having to query that target, and could then do something special with the reference. While the extra semantic of <topicset> makes some sense to me on a theoretical level, I've never thought <topicsetref> is useful.

> The spec language around topicsetref is maddeningly opaque

My summary of the 1.3 language for <topicsetref> would boil down to - "This is supposed to reference a <topicset>. You might be able to do something clever with that. Otherwise, treat it like a normal topicref with format="ditamap".

I could elaborate on how the language ended up as it did, but that would mostly be me explaining what Erik was thinking, which isn't terribly useful (and he's not here to disagree).

Regards,

Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification,
Digital Services Group


E-mail: robander@us.ibm.com
Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA


<dita@lists.oasis-open.org> wrote on 04/14/2016 12:21:49 PM:

> From: Chris Nitchie <chris.nitchie@oberontech.com>

> To: Kristen James Eberlein <kris@eberleinconsulting.com>,
> "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>

> Date: 04/14/2016 12:22 PM
> Subject: Re: [dita] Key scopes and topicsetref
> Sent by: <dita@lists.oasis-open.org>
>
> A lot of this boils down to whether there's anything 'special' about
> <topicsetref> as distinct from other topicref/mapref types. From a
> processing perspective, is there any difference at all between these
> two elements?
>
> <mapref href="" type="topicset"/>
> <topicsetref href="">>
> If not, then this is a well-answered question in the existing spec;
> it's processed no differently than any other mapref. (But if there
> really is no difference, then <topicset> and <topicsetref> strike me
> as almost entirely useless.)
>
> The spec language around topicsetref is maddeningly opaque, but I
> think a reasonable reading suggests that it's different from other
> topicrefs because it may be resolved _after_ other DITA processing,
> potentially as late as view-time. (At least, that's how I read it; I
> could be wrong. As I say, it's maddening.) If that's the case, then
> it suggests to me that in static contexts, such as PDF, topicsetref
> resolution is fundamentally different from other topicref
> resolution, and should be deferred to near the end of DITA
> preprocessing, after all keyrefs and conrefs and topic
> contextualization and such like have been handled.
>
> But my experience with topicset and topicsetref are, shall we say,
> limited. I'll be fine - happy, even - if I'm wrong.
>
> Chris
>
>
>
> On 4/14/16, 12:02 PM, "dita@lists.oasis-open.org on behalf of
> Kristen James Eberlein" <dita@lists.oasis-open.org on behalf of
> kris@eberleinconsulting.com> wrote:
>
> >Eliot, I think you are reading too much into topicset and topicsetref. I
> >think we need to stick with the original definitions and use cases for
> >these elements.
> >
> >Best,
> >Kris
> >
> >Kristen James Eberlein
> >Chair, OASIS DITA Technical Committee
> >Principal consultant, Eberlein Consulting
> >www.eberleinconsulting.com
> >+1 919 682-2290; kriseberlein (skype)
> >
> >On 4/14/2016 12:00 PM, Eliot Kimber wrote:
> >> I think I see what Chris is getting at: only through the use of keys can
> >> topicsetref be made sensible.
> >>
> >> But I think there's still an open question of what the key scope
> >> relationship is between topicsetrefs and topicsets.
> >>
> >> After thinking about it more I think the right answer might be to think of
> >> topicsetref as a topicgroup that effectively contains the referenced
> >> topicset rather than a use-by-reference that is replaced by the topicset.
> >> That resolves the question of the key scope implications and makes it
> >> clear that each topicsetref establishes a separately-addressable use of
> >> the topicset.
> >>
> >> In thinking about it now I see that topicsetref does address a use case
> >> that simple peer-map-references do not, namely the "embedding" of subparts
> >> of another deliverable within a referencing deliverable. Whether that
> >> embedding is static or dynamic is not really important: what's important
> >> is that the processing (and thus addressing) context of the topicset is
> >> separate from its eventual inclusion in or reference from some other
> >> deliverable. (One implication is that, from the context of the embedded
> >> topicset I'll be able to navigate to other parts of the larger deliverable
> >> the topicset is part of because the delivered topicset retains its
> >> participation in its containing deliverable).
> >>
> >> I'm still not sure this is a use case many people have but it does seem to
> >> be a real use case that is materially different from basic
> >> cross-deliverable linking.
> >>
> >> My analysis:
> >>
> >> For topicsetrefs that use direct URI references to topicset elements there
> >> is not enough information to know what the root map context of the
> >> topicset is and therefore no way to reliably address topics within the
> >> topicset (for all the reasons that direct URI references to topics from
> >> other topics are not reliable: they don't tell you anything about the use
> >> context of the referenced topic or, in this case, the referenced topicset).
> >>
> >> If you use key references then the ambiguity is resolved because you are
> >> forced to either include the topicset-including map as a submap of the
> >> referencing map or establish the topicset-containing map as a peer map
> >> (otherwise the key would be unresolvable).
> >>
> >> For example, if I have Map B containing a topicset I want to reuse:
> >>
> >> Map-B.ditamap:
> >>
> >> <map>
> >>   <topicset keys="topicset-01" id="dontcare">
> >>     <topicref keys="topic-02" href="">> >>   </topicset>
> >> </map>
> >>
> >> Then from Map A I have two choices: (1) use map B as a submap or (2) use
> >> map B as a peer map:
> >>
> >> 1. Use Map B as a submap:
> >>
> >> Map-A.ditamap:
> >>
> >> <map><title>Map A</title>
> >>   <mapref processing-role="resource-only"
> >>      href="">> >>   />
> >>   <topicsetref keyref="topicset-01"/>
> >>
> >> </map>
> >>
> >> Map B is clearly a submap of Map A and the topicset reference is
> >> unambiguous. Likewise, any key references to topics within the topicset
> >> are unambiguous (because Map B is included in Map A and normal key space
> >> construction and key resolution rules apply).
> >>
> >> 2. Use Map B as a peer map:
> >>
> >> Map-A.ditamap:
> >>
> >> <map><title>Map A</title>
> >>    <mapref scope="peer" keyscope="map-b"
> >>     href="">> >>    />
> >>    <topicsetref keyref="map-b.topicset-01"/>
> >> </map>
> >>
> >>
> >> Again the topicsetref is unambiguous and key references to keys in the
> >> scope "map-b" are resolved normally.
> >>
> >> It becomes a processor task as to how to actually implement delivery of
> >> the topicsetref but the relationship of the topicset to the topicsetref is
> >> clear and key-based addresses to topics in the topicset are clear.
> >>
> >> There's a still a problem when the same topicset is used more than once:
> >>
> >> Map-A.ditamap:
> >>
> >> <map><title>Map A</title>
> >>    <mapref scope="peer" keyscope="map-b"
> >>     href="">> >>    />
> >>    <topicsetref keyref="map-b.topicset-01"/>
> >>    ...
> >>    <topicsetref keyref="map-b.topicset-01"/>
> >>
> >> </map>
> >>
> >> There's no way to address topics in the topicset in the context of one or
> >> the other of these references.
> >>
> >>
> >> That is, if I have the key reference "map-b.topic-02" it is a reference to
> >> the topic in Map B but without regard to any use context from Map A. I'll
> >> get to the topic but the navigation context from Map A is undefined.
> >>
> >> Since the point of topicsetref is to merge navigation it seems likely that
> >> being able to establish use context in the referencing map is important.
> >>
> >> If you put keyscopes on the references you can then distinguish the uses
> >> of the topicset:
> >>
> >> <map><title>Map A</title>
> >>    <mapref scope="peer" keyscope="map-b"
> >>     href="">> >>    />
> >>    <topicsetref keyscope="use-01" keyref="map-b.topicset-01"/>
> >>    ...
> >>    <topicsetref keyscope="use-02" keyref="map-b.topicset-01"/>
> >>
> >> </map>
> >>
> >> Now I can refer to keys in the scopes "use-01.???" and "use-02.???" and
> >> make the Map A navigation context clear.
> >>
> >> The question is still what is the key scope bound to the topicsetref and
> >> what is its relationship to the topicset's key scope?
> >>
> >> Thinking about it this way it now makes sense that the topicsetref's scope
> >> becomes a *parent* scope for the topicset's scope, otherwise the uses
> >> wouldn't be distinct (because they would collapse into a single scope with
> >> multiple names).
> >>
> >> That is, I should be able to refer to the key "use-01.map-b.topic-02" and
> >> get to topic 2 from Map B as used by the second topicsetref. If the scope
> >> "use-01" was just an alias for "map-b" then the use would not be
> >> distinguished.
> >>
> >> That argues against my earlier assertion that topicsetref should be
> >> treated the same as peer map references.
> >>
> >> One way to say this would be to say that topicsetref, rather than being a
> >> direct use-by-reference of the topicset, functions as a topicgroup that
> >> effectively contains or embeds the referenced topicset. That would make
> >> the key scope relationship clear(er) and avoid potential implementation
> >> mistakes like simply throwing away the topicsetref.
> >>
> >> Cheers,
> >>
> >> E.
> >>
> >> ----
> >> Eliot Kimber, Owner
> >> Contrext, LLC
> >> http://contrext.com
> >>
> >>
> >>
> >>
> >> On 4/13/16, 8:09 PM, "Chris Nitchie" <dita@lists.oasis-open.org on behalf
> >> of chris.nitchie@oberontech.com> wrote:
> >>
> >>> My assumption is that any topicsetref resolution should occur *after*
> >>> keyref resolution, and the topicsetref functions as a reference to the
> >>> topicset as contextualized at its location. If that's the case, then
> >>> whether either or both elements specify @keyscope doesn't matter, because
> >>> the topicsetref's resolution occurs after all keyrefs have been resolved
> >>> at both locations.
> >>>
> >>> Chris
> >>>
> >>>
> >>>
> >>>
> >>> On 4/13/16, 9:08 PM, "dita@lists.oasis-open.org on behalf of Eliot
> >>> Kimber" <dita@lists.oasis-open.org on behalf of ekimber@contrext.com>
> >>> wrote:
> >>>
> >>>> In the case of topicsetref and topicset, the 1.3 did not add any language
> >>>> to define what the behavior should be when either or both of the
> >>>> topicsetref and topicset specify a value for @keyscope.
> >>>>
> >>>> There are four possible cases:
> >>>>
> >>>> 1. No key scopes. This is the 1.2 case and nothing is changed
> >>>> 2. Key scope on topicsetref but not on topicset
> >>>> 3. Key scope on topicset but not on topicsetref
> >>>> 4. Key scope on both topicsetref and topicset
> >>>>
> >>>> In cases (2) and (3) I think the correct behavior can only be that there
> >>>> is one effective scope reflecting the scope name specified. While
> >>>> topicsetref is defined as a use-by-reference of the topicset I don't
> >>>> think
> >>>> just throwing away a keyscope specified on it would ever be
> >>>> appropriate--it's not a literal replacement but an application-managed
> >>>> relationship between the navigation point in the referencing map and the
> >>>> navigation structure defined by the topicset and that definitely argues
> >>>> for maintaining the keyscope.
> >>>>
> >>>> In case (4) there are four possible behaviors:
> >>>>
> >>>> 1. The two scope names are merged as for map-to-map references,resulting
> >>>> in one key scope with two names.
> >>>> 2. The topicsetref's scope becomes the parent scope of the topicset's key
> >>>> scope
> >>>> 3. The topicsetref's key scope is ignored
> >>>> 4. The topicset's key scope is ignored
> >>>>
> >>>> Option (1) is consistent with the explicit rules for map-to-map
> >>>> references
> >>>> and is my preference since it has the least surprise.
> >>>>
> >>>> Option (2) is logical but surprising and seems inconsistent with the
> >>>> semantic of topicsetref as a use-by-reference.
> >>>>
> >>>> Options (3) and (4) are conref-type behaviors and in a real conref would
> >>>> be controllable via the -use-conref-target keyword in the attribute
> >>>> value.
> >>>> That option is not available here so I think we can discard these
> >>>> options,
> >>>> especially since the writeup of topicsetref explicitly says it's not a
> >>>> content reference.
> >>>>
> >>>> I don't recall ever discussing the implications of key scopes for
> >>>> topicsetref. Did we?
> >>>>
> >>>> Based on my informal survey on DITA Users it doesn't appear that anyone
> >>>> much uses topicsetref.
> >>>>
> >>>> But probably good for us to decide what the right answer is or explicitly
> >>>> defer a decision to DITA 2.0.
> >>>>
> >>>>
> >>>>
> >>>> ----
> >>>> Eliot Kimber, Owner
> >>>> Contrext, LLC
> >>>> http://contrext.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_workgroups.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
> >>
> >>
> >>
> >
> >
> >---------------------------------------------------------------------
> >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]