Leaving the first question about (topic) and (map) alone for the moment...
The other issue is Question 2 - how to tell the difference between a structural domain token like (topic task) and an element domain like (topic hi-d).
From reading the spec topics over and over, the only things I'm sure of are that there are a lot of syntax requirements, and that they're hard to follow / understand / get right.
The domains attribute was originally meant for element domains like hi-d, then came attributes, then came constraints and structural declarations. Each has a different syntax, some with strict name controls, some without. It looks like what it is: a feature added to a feature added to a feature. In other words, this looks like another item we should address (read: simplify) in DITA 2.0.
The specific issue here was present in 1.2 but did not raise concerns until it came up as part of another discussion. I don't think there's any benefit to adding yet another syntax convention at this point, especially as it couldn't be mandatory. As far as I can tell, while the "-c" token for constraints is clearly laid out, the -d token is not actually defined in our spec (1.2 or 1.3); it's just a convention used in examples. This means we cannot rely on -d to distinguish element domains from structural ones.
Overall, I think the best approach is the status quo - leave this alone, knowing that there is no reliable way for processors to distinguish between the two types of domain tokens. It hasn't caused a problem so far, and we should consider a more comprehensive design update in DITA 2.0.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (
http://dita-ot.sourceforge.net/ )
Eliot Kimber ---10/14/2014 11:43:28---Update: Michael points out that a @domains value of e.g. "(topic foo)" is
From: Eliot Kimber <
ekimber@contrext.com>
To: Eliot Kimber <
ekimber@contrext.com>, dita <
dita@lists.oasis-open.org>
Date: 10/14/2014 11:43
Subject: Re: [dita] @domains for base Topic and Map Types
Sent by: <
dita@lists.oasis-open.org>
Update:
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
include:
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.
Cheers,
E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com 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
>contribution.
>
>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.
>
>Cheers,
>
>E.
>
>
>—————
>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