Re: [dita] @domains -- structural/domain ambiguity

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 <>

To:	Eliot Kimber <>, dita <>

Date:	10/14/2014 11:43

Subject:	Re: [dita] @domains for base Topic and Map Types

Sent by:	<>

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" <> 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