OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Evaluation of the subject scheme review

    Posted 02-06-2015 18:12
    It was very interesting to evaluate the comments made in the review of the subject scheme material. Several points became very clear: It was the first time that most people had read this content, and probably the first time that it has been reviewed. The draft 1.3 topics contained some examples that illustrate processor behavior that is either not described normatively or described in inadequate detail. I'm working on this, but will definitely need help. There also are limits to what we can do and get DITA 1.3 out this year. The draft 1.3 topics focus primarily on controlled values and do not discuss (much) what can be done with taxonomic subjects, especially in conjunction with the classification domain. I think we'll just need to accept this as a shortcoming for 1.3. Keys and key references function differently in the context of subjectScheme maps. This is especially evident in the following situations, and I think we must clarify our collective, TC stance about the expected processing of @keyref in the context of a subject scheme: Using <schemeref> to extend an enumeration of controlled values or to broaden subject categories Using an addressing attribute to link to a detailed explanation of a subject from a <subjectdef> element. Here I think one must use @href; using @keyref would open up the possibility of lots of circular processing. If subject scheme maps have special rules for processing @keyref, do they also have special rules for key scopes? Are key scopes even valid for subject scheme maps? Back story: There was one subjectScheme topic in the 1.2 Architectural Spec , and then lots of material in the Language Reference examples. For 1.3, I broke the content into multiple topics, and moved material out of the (non-normative) examples in the Language Reference . The original spec material had been taken from proposals drafted by Erik Hennum (IBM), who left IBM before 1.2 was released. Erik's tendency was to define through example,  which is how so many of the rules and processor expectations ended up in the Language Reference examples. -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)


  • 2.  Re: [dita] Evaluation of the subject scheme review

    Posted 02-06-2015 18:44
    There shouldn't be any issue with using key-based references to topics from subject definitions--the same rules for resolving keys (and not having circular key references) must still apply. Of course, since subject-defining topicrefs are resource-only, there's not a compelling reason to use keys for references to the defining resources unless the same resource is used by multiple subjects (which would call the sensibility of your taxonomy into question, since you'd expect a given definition to apply to exactly one subject). When a subject scheme is processed as a normal DITA map, the key processing is as it is for any other map. It is in the processing of a subject scheme as a set of enumerated values used to match to attribute values that the interpretations of the keys might be different. But the addressing-related rules for keys must be the same as for all other maps. And I will say that I did closely read the subject scheme topics for 1.2 and in the process of writing the chapter on subject schemes in DITA for Publishers. But it all made sense to me (I had questions about the design choices made but not questions about what the spec said the design meant). And we certainly didn't have the luxury of rethinking the writing for DITA 1.2. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 2/6/15, 12:11 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote: > > > > > > > It was very interesting to evaluate the comments made in the review > of the subject scheme material. Several points became very clear: > > > >* It was the first time that most people had read this > content, and probably the first time that it has been > reviewed. > > >* The draft 1.3 topics contained some examples that illustrate > processor behavior that is either not described normatively or > described in inadequate detail. I'm working on this, but will > definitely need help. There also are limits to what we can do > and get DITA 1.3 out this year. > >* The draft 1.3 topics focus primarily on controlled values > and do not discuss (much) what can be done with taxonomic > subjects, especially in conjunction with the classification > domain. I think we'll just need to accept this as a > shortcoming for 1.3. > >* Keys and key references function differently in the context > of subjectScheme maps. This is especially evident in the > following situations, and I think we must clarify our > collective, TC stance about the expected processing of @keyref > in the context of a subject scheme: > > > > > * Using <schemeref> to extend an enumeration of > controlled values or to broaden subject categories > > > * Using an addressing attribute to link to a detailed > explanation of a subject from a <subjectdef> element. > Here I think one must use @href; using @keyref would open up > the possibility of lots of circular processing. > > > >* If subject scheme maps have special rules for processing > @keyref, do they also have special rules for key scopes? Are > key scopes even valid for subject scheme maps? > > > > > > > Back story: > > > >* There was one subjectScheme topic in the 1.2 Architectural > > Spec, and then lots of material in the Language > Reference examples. For 1.3, I broke the content into > multiple topics, and moved material out of the (non-normative) > examples in the Language Reference. > >* The original spec material had been taken from proposals > drafted by Erik Hennum (IBM), who left IBM before 1.2 was > released. Erik's tendency was to define through example, > which is how so many of the rules and processor expectations > ended up in the Language Reference examples. > > > -- > Best, > Kris > > Kristen James Eberlein > Chair, OASIS DITA Technical Committee > Principal consultant, Eberlein Consulting > www.eberleinconsulting.com < http://www.eberleinconsulting.com > > +1 919 682-2290; kriseberlein (skype) > > > > > > > > >--------------------------------------------------------------------- >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 > >


  • 3.  Re: [dita] Evaluation of the subject scheme review

    Posted 02-06-2015 19:19
    Re your comment "It is in the processing of a subject scheme as a set of enumerated values used to match to attribute values that the interpretations of the keys might be different. I think key processing is different not just in the case of "enumerated values used to match to attribute values," but also in scenarios where one uses the <schemeref> element to extend the controlled values or taxonomic subjects defined in a subject scheme map. We clearly state in both the 1.2 and draft 1.3 specs that "The <schemeref> element provides a reference to another scheme. Typically, the referenced scheme defines a base set of controlled values that are extended by the current scheme. The values in the referenced scheme are merged with the current scheme; the result is equivalent to specifying all of the values in a single subject scheme map." I agree with Chris Nitchie's comment in DITAweb: ""That's not how keyref normally works. We definitely need normative language describing the expected processing of keyref in the context of a subject scheme. It's completely different from normal keyref behavior. Normally, a keyref is a reference to the content referenced by the key-defining topicref, not a reference to the topicref itself. And there's no transclusion or extension, as is implied here. So it's completely different processing rules for keys in a subject scheme, and it needs normative description." Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 2/6/2015 1:43 PM, Eliot Kimber wrote: There shouldn't be any issue with using key-based references to topics from subject definitions--the same rules for resolving keys (and not having circular key references) must still apply. Of course, since subject-defining topicrefs are resource-only, there's not a compelling reason to use keys for references to the defining resources unless the same resource is used by multiple subjects (which would call the sensibility of your taxonomy into question, since you'd expect a given definition to apply to exactly one subject). When a subject scheme is processed as a normal DITA map, the key processing is as it is for any other map. It is in the processing of a subject scheme as a set of enumerated values used to match to attribute values that the interpretations of the keys might be different. But the addressing-related rules for keys must be the same as for all other maps. And I will say that I did closely read the subject scheme topics for 1.2 and in the process of writing the chapter on subject schemes in DITA for Publishers. But it all made sense to me (I had questions about the design choices made but not questions about what the spec said the design meant). And we certainly didn't have the luxury of rethinking the writing for DITA 1.2. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 2/6/15, 12:11 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote: It was very interesting to evaluate the comments made in the review of the subject scheme material. Several points became very clear: * It was the first time that most people had read this content, and probably the first time that it has been reviewed. * The draft 1.3 topics contained some examples that illustrate processor behavior that is either not described normatively or described in inadequate detail. I'm working on this, but will definitely need help. There also are limits to what we can do and get DITA 1.3 out this year. * The draft 1.3 topics focus primarily on controlled values and do not discuss (much) what can be done with taxonomic subjects, especially in conjunction with the classification domain. I think we'll just need to accept this as a shortcoming for 1.3. * Keys and key references function differently in the context of subjectScheme maps. This is especially evident in the following situations, and I think we must clarify our collective, TC stance about the expected processing of @keyref in the context of a subject scheme: * Using <schemeref> to extend an enumeration of controlled values or to broaden subject categories * Using an addressing attribute to link to a detailed explanation of a subject from a <subjectdef> element. Here I think one must use @href; using @keyref would open up the possibility of lots of circular processing. * If subject scheme maps have special rules for processing @keyref, do they also have special rules for key scopes? Are key scopes even valid for subject scheme maps? Back story: * There was one subjectScheme topic in the 1.2 Architectural Spec, and then lots of material in the Language Reference examples. For 1.3, I broke the content into multiple topics, and moved material out of the (non-normative) examples in the Language Reference. * The original spec material had been taken from proposals drafted by Erik Hennum (IBM), who left IBM before 1.2 was released. Erik's tendency was to define through example, which is how so many of the rules and processor expectations ended up in the Language Reference examples. -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com < http://www.eberleinconsulting.com > +1 919 682-2290; kriseberlein (skype) --------------------------------------------------------------------- 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


  • 4.  Re: [dita] Evaluation of the subject scheme review

    Posted 02-06-2015 19:53
    I think we're talking about two different things here and that my statement holds: the pure addressing aspects are always the same, the way the things addressed are subsequently interpreted is specific to subject schemes. We have to be careful not to talk about the subject-scheme-specific *semantic* interpretation in a way that suggests it somehow changes how the *addresses* are initially processed. What points to what is always the same--what you do with the results of those pointers can be different based on the semantic you apply to the direct or indirect relationships established by the addresses. I think the potential confusion here is distinguishing the normal address processing involved from the subject-scheme-specfic semantic processing, meaning the interpretation of the subject scheme as a set of related subjects. The two are related but different. Addressing is purely mechanical and must always produce the same result (A points to B and B points to C). Semantics is whatever you want it to be. So we can say that if subject A points to subject B that establishes a subject-scheme-specific relationship among the two subjects, even if subject B's topicref also points to a resource as the definition of subject B. If we apply the normal *navigation link resolution* semantic to the key for subject A it will get us to subject B's definition, because that's the semantic we're applying. But if we apply the *subject-scheme semantic* to subject A we get to subject B as a related subject. There's no conflict there, just two different *semantics*, for different purposes, applied to the same set of base relationships as defined solely by the addresses involved (the key references). This is analogous to how we define special processing for specializations of xref, such as <coderef> and <mathmlref>, where the addressing implications are unchanged (the thing addressed is invariant) but how you interpret the address for further processing is specific to that specialization. For example, the addresses say "A points to B and B points to C". That *cannot change*. The subject scheme then says "Given that A points to B and that A and B are both subjects, then there is *subject-to-subject* relationship between subjects A and B, as well as a *subject-to-definition* relationship between subject B and resource C. That's the subject-scheme-specific implication of the addresses. The normal navigation implication is ignored in the context of subject scheme handling (determining the abstract set of subjects and their relations to each other). The fact that you can get from subject A to resource C via subject B is simply not relevant in the subject scheme context. Or said another way, the subject scheme processing is conceptually: 1. Determine the key spaces and resolve all the key references to determine what *directly* points to what. This processing is general to all possible uses of the map (that is, it doesn't matter how the relationships will be interpreted because the addressing implications cannot be changed by the semantic processing). 2. Use the relationships determined in step (1) to determine the subject-to-subject relationships that define the (abstract) subject scheme, as well as the (direct) subject-to-definition relationships for those subjects. Note that even in normal key processing you have to retain knowledge about each step in a multi-step key reference for a number of reasons, so it's not like the intermediate key definitions are invisible or something. Thus there shouldn't be any problem in a general key-aware processor with distinguishing direct key-to-subject references from multi-step key-to-resource references. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com On 2/6/15, 1:18 PM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote: >Re your comment "It is in the processing of a subject scheme as a set of >enumerated values used to match to attribute values that the >interpretations of the keys might be different. > >I think key processing is different not just in the case of "enumerated >values used to match to attribute values," but also in scenarios where >one uses the <schemeref> element to extend the controlled values or >taxonomic subjects defined in a subject scheme map. > >We clearly state in both the 1.2 and draft 1.3 specs that "The ><schemeref> element provides a reference to another scheme. Typically, >the referenced scheme defines a base set of controlled values that are >extended by the current scheme. The values in the referenced scheme are >merged with the current scheme; the result is equivalent to specifying >all of the values in a single subject scheme map." > >I agree with Chris Nitchie's comment in DITAweb: ""That's not how keyref >normally works. We definitely need normative language describing the >expected processing of keyref in the context of a subject scheme. It's >completely different from normal keyref behavior. Normally, a keyref is >a reference to the content referenced by the key-defining topicref, not >a reference to the topicref itself. And there's no transclusion or >extension, as is implied here. So it's completely different processing >rules for keys in a subject scheme, and it needs normative description." > >Best, >Kris > >Kristen James Eberlein >Chair, OASIS DITA Technical Committee >Principal consultant, Eberlein Consulting >www.eberleinconsulting.com >+1 919 682-2290; kriseberlein (skype) > >On 2/6/2015 1:43 PM, Eliot Kimber wrote: >> There shouldn't be any issue with using key-based references to topics >> from subject definitions--the same rules for resolving keys (and not >> having circular key references) must still apply. Of course, since >> subject-defining topicrefs are resource-only, there's not a compelling >> reason to use keys for references to the defining resources unless the >> same resource is used by multiple subjects (which would call the >> sensibility of your taxonomy into question, since you'd expect a given >> definition to apply to exactly one subject). >> >> When a subject scheme is processed as a normal DITA map, the key >> processing is as it is for any other map. It is in the processing of a >> subject scheme as a set of enumerated values used to match to attribute >> values that the interpretations of the keys might be different. >> >> But the addressing-related rules for keys must be the same as for all >> other maps. >> >> And I will say that I did closely read the subject scheme topics for 1.2 >> and in the process of writing the chapter on subject schemes in DITA for >> Publishers. But it all made sense to me (I had questions about the >>design >> choices made but not questions about what the spec said the design >>meant). >> And we certainly didn't have the luxury of rethinking the writing for >>DITA >> 1.2. >> >> Cheers, >> >> E. >> ————— >> Eliot Kimber, Owner >> Contrext, LLC >> http://contrext.com >> >> >> >> >> On 2/6/15, 12:11 PM, "Kristen James Eberlein" >> <kris@eberleinconsulting.com> wrote: >> >>> >>> >>> >>> >>> >>> It was very interesting to evaluate the comments made in the review >>> of the subject scheme material. Several points became very clear: >>> >>> >>> >>> * It was the first time that most people had read this >>> content, and probably the first time that it has been >>> reviewed. >>> >>> >>> * The draft 1.3 topics contained some examples that illustrate >>> processor behavior that is either not described normatively >>>or >>> described in inadequate detail. I'm working on this, but will >>> definitely need help. There also are limits to what we can do >>> and get DITA 1.3 out this year. >>> >>> * The draft 1.3 topics focus primarily on controlled values >>> and do not discuss (much) what can be done with taxonomic >>> subjects, especially in conjunction with the classification >>> domain. I think we'll just need to accept this as a >>> shortcoming for 1.3. >>> >>> * Keys and key references function differently in the context >>> of subjectScheme maps. This is especially evident in the >>> following situations, and I think we must clarify our >>> collective, TC stance about the expected processing of >>>@keyref >>> in the context of a subject scheme: >>> >>> >>> >>> >>> * Using <schemeref> to extend an enumeration of >>> controlled values or to broaden subject categories >>> >>> >>> * Using an addressing attribute to link to a detailed >>> explanation of a subject from a <subjectdef> element. >>> Here I think one must use @href; using @keyref would open >>>up >>> the possibility of lots of circular processing. >>> >>> >>> >>> * If subject scheme maps have special rules for processing >>> @keyref, do they also have special rules for key scopes? Are >>> key scopes even valid for subject scheme maps? >>> >>> >>> >>> >>> >>> >>> Back story: >>> >>> >>> >>> * There was one subjectScheme topic in the 1.2 Architectural >>> >>> Spec, and then lots of material in the Language >>> Reference examples. For 1.3, I broke the content into >>> multiple topics, and moved material out of the >>>(non-normative) >>> examples in the Language Reference. >>> >>> * The original spec material had been taken from proposals >>> drafted by Erik Hennum (IBM), who left IBM before 1.2 was >>> released. Erik's tendency was to define through example, >>> which is how so many of the rules and processor expectations >>> ended up in the Language Reference examples. >>> >>> >>> -- >>> Best, >>> Kris >>> >>> Kristen James Eberlein >>> Chair, OASIS DITA Technical Committee >>> Principal consultant, Eberlein Consulting >>> www.eberleinconsulting.com < http://www.eberleinconsulting.com > >>> +1 919 682-2290; kriseberlein (skype) >>> >>> >>> >>> >>> >>> >>> >>> >>> --------------------------------------------------------------------- >>> 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 > >