Re: [dita] Policy Decision: Loose or Not

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

Dana Spradley wrote:
> What edits was Eliot suggesting?

What I'm suggesting is that the normative value of info-types be "topic 
| concept | reference | task | glossentry", which is the value used in 
the ditabase declaration set. We further say that the shell document 
types "concept.dtd", "reference.dtd", and "task.dtd" are *examples* of 
how the loose constraints can be tightened using the provided 
configuration mechanisms.

This has the effect of removing the need to explain why there are two 
different effective "contained by" statements for various elements and 
makes it clear that the standard is not imposing *required* constraints 
as reflected in the topic-type-specific shell document types.

Note that this doesn't require any change to the existing declarations, 
just a clarification that the type-specific shells are *examples*.

Note that I *am not* saying that the "dita" element as currently defined 
is inherently good or bad--that's irrelevant to this discussion. I'm 
just asserting that the normative constraints defined by the 
specification should be clearly stated as being "as far as the standard 
is concerned, any topic type can contain any other topic type". This 
does not preclude adding (or retaining, if there is one) statements to 
the effect that, in practice, one should only nest topics of different 
types when it is clearly appropriate. I think the specification is very 
clear that using <dita> to contain elements has no processing implications.

Note that as a practical matter, there *has to be* a general containing 
element that allows, as direct children, any topic type. This is needed 
simply so that authors have full choice over how they organize topics 
into documents *for storage purposes*. But allowing a container like 
"dita" to contain, as direct children, any topic type  is not the same 
as allowing those child topics to contain any topic type: the 
declarations are specifically designed to allow you to still control, on 
a topic type basis, what they can and can't contain.

That is, I can (more or less easily) configure the ditabase declarations 
to allow <dita> to contain any topic type but not to allow those topics 
to contain any topics types I don't want them to contain. Looking at 
ditabase.dtd, the only change that I think would be useful would be to 
change the declaration of the dita element to use a new parameter 
entity, dita-info-types, declared as follows:

<!ENTITY % dita-info-types
   "%info-types;"
 >

This makes it parallel with the other shell document types and allows a 
configurator to control the topics allowed within <dita> separate from 
those allowed within the individual types, by replacing "%info-types;" 
with an explicit list of topic types (and the existing mechanism of just 
setting info-types would also work).

While I appreciate JoAnn's concerns about people misusing DITA, that is 
outside the purview of the standard--it's not the standard's job to 
enforce good practice, only to allow it and encourage it. Misuse of 
<dita> is both a matter of opinion and a matter of education. The most 
we can say in the standard is that that use of <dita> is considered to 
be poor practice.

Cheers,

Eliot

-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com