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] @domains for base Topic and Map Types


Michael points out that a @domains value of e.g. "(topic foo)" is
ambiguous as to whether "foo" is a domain or a structural type.

Domain short names should be "*-d", so one could argue that "foo" must be
a structural type because it's not "foo-d". However, that's probably not
sufficient since short name conventions are not mandatory (but are
followed by all TC-provided domains and structural types, so the confusion
could never occur using only TC-defined topic types and domains).

As Michael says, this has been a problem since DITA 1.2, when we allowed
(and effectively required) specifying structural types in @domains.

Michael and Robert also point out that in the case of nested topics
defined in a shell, all the topic elements should have the same @domains
value. This is done by defining the @domains value in the shell and then
referencing that value from all topic element type attribute list
declarations. I agree that this is the correct behavior. It might be
useful to state this requirement explicitly: it's implicit in the coding
rules for shells but not explicit in the definition of @domains itself.

For DITA 1.3 I think we have the following questions to answer:

1. For topic and map shells where no domains are integrated, what should
the value of @domains be? I think the options are:

   A. "(topic)" or "(map)"

   B. An empty string: domains=""

   C. "(topic topic)" or "(map map)"

   Per my previous analysis, I think option (A) is the most correct, but
Robert asserts that some tools expect @domains groups to always be pairs
and will fail with case (A). Option (B) is allowed by the spec. Since the
TC does not today provide a no-domain map or topic shell, we don't have to
worry about the fact that SHOULDs are effectively MUSTs for TC-provided
shells, meaning we are obligated to list structural types in @domains for
all TC-provided shells. I think we are in agreement that option (C) is
nonsensical and can be eliminated from consideration.
2. Should we address the structural/domain ambiguity Michael identified or
continue to leave it unaddressed as it was in DITA 1.2. Possible solutions

   A. State that if the token doesn't include -d or -c (constraint) in the
short name, assume it's a structural type or require examination of the
@class values of all topic types integrated in the shell to determine if
the value is or is not a structural type.

   B. Add a new label, "s", before the parens to indicate structural
types, e.g. domains="s(topic foo) (topic learning2-d)"

   Option (A) is essentially the status quo, since it's pretty much what a
processor would have to do today if it tries to actually distinguish
structural and domain types. Option (B) is consistent with the current
@domains design but we'd have to then make its use optional, which
somewhat erodes its value.


Eliot Kimber, Owner
Contrext, LLC

On 10/7/14, 11:27 AM, "Eliot Kimber" <ekimber@contrext.com> wrote:

>Reviewing the previous 1.3 review draft, the current language says:
>"Each structural, element, and attribute domain defines its module
>ancestry as a parenthesized sequence of space-separated module names from
>root module to provided module."
>Thus, for a topic type of "reference" the @domains value would be "(topic
>reference)", not "(topic)". That is, the type itself is included in the
>ancestry specification.
>By that logic, for topics of type "topic" and maps of type "map" the
>@domains value should be "(topic)" and "(map)".
>The next paragraph defines the @domain syntax for *element domains*.
>However, there is no syntax definition for *structural* domains.
>So, we could read that as implicitly allowing "(topic)" (because it's not
>explicitly disallowed) and leave the current language as it is.
>Or we could add a new syntax definition for structural domains that allows
>a single type token.
>Based on Robert's argument and the text as written, I think that the 1.3
>map and topic shells (base map, base topic, tech content map, tech content
>topic) should specify "(map)" or "(topic)" as their structural domain
>Because the specification says that structural types should specify their
>structural ancestry I think we are obligated to provide a domains
>contribution for all TC-provided structural types.
>Note also that the spec says that for the purposes of conref compatibility
>the @domains value is used to compare *domains* not structural types:
>"The @domains attribute allows processors to determine whether two
>elements use compatible domains."
>Thus a comparison of maps to topics for the purpose of allowing conref
>from maps to topics would only consider domains, with the common elements
>effectively being a domain (or set of domains) that all topics and maps
>inherently share. 
>The OT currently allows conrefs from maps to topics (I have a client with
>exactly that case that I've been working with just in the last few days),
>so we can presume it was always intended that it be allowed. That suggests
>that we should probably make that case explicitly allowed for elements
>that are common between maps and topics.
>Note also that it must be the case that conref constraints related to
>specialization (target same or more specialized than reference) can only
>be defined in terms of @class values as long as @domains is not required
>for structural types, so any rules related to allowing maps to conref from
>topics would need to be defined in terms of @class values. That is, for
>the purpose of checking conref constraints, @domains is still only used to
>compare domains used, not structural types. Structural type comparison is
>done using @class.
>Finally, on the subject of actually using @domains to dynamically
>construct working grammars for documents: With RNG this is now actually
>possible since RNG domains are self-integrating: One could literally use
>the @domains value to construct an inclusion list of domain modules given
>a mapping from domain module names to module files (which should always be
>a one-to-one mapping since you should never have two different versions of
>the same domain module for a given DITA version). This was not really
>practical with DTD or XSD, but I think it is practical with RNG. If
>somebody did implement this it would make it easier to interchange DITA
>files without having to also interchange the grammars since useful RNG
>shells could be reconstituted on demand by the receiver.
>Eliot Kimber, Owner
>Contrext, LLC
>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:

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