Discussion about how to disable topic nesting in specialized topics

[ehixson@bmc.com]

Michael Priestley and I had a discussion recently that he felt would be useful to post to the DITA list:

------------------

Hi Michael,

In DITA's various .mod files, the root element's content model for all the topic types contains an entity reference that is meant to allow/disable nesting of topics:

For example, from the reference.mod file:

   <!ELEMENT reference      (%title;, (%titlealts;)?, (%shortdesc;)?, (%prolog;)?, %refbody;, (%related-links;)?, (%reference-info-types;)* )>

Absent any overrides from the associated .dtd file, this entity reference is resolved according to an entity declaration a few lines above in the .mod file:  

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

Which resolves in topic.mod to the value "topic".

In the associated reference.dtd file, you have an override for this default behavior from the .mod file that sets the value instead to "reference", which therefore enables nesting of further reference topics after the body of the outermost reference element:

   <!--Redefine the infotype entity to exclude other topic types and disallow nesting-->
   <!--MAT - removed no-topic-nesting per MichaelP -->
   <!ENTITY % reference-info-types "reference">

My questions are these:

How do you disallow nesting entirely?  We've tried setting the entity declaration in the .dtd file to something like
   <!ENTITY % reference-info-types "">
but the parser seems to dislike that and won't validate the DTD.  We've removed the last bit in the content model for the root topic element (%reference-info-types;)* and that works fine of course, but I'm thinking you wouldn't have had the two other entity declarations unless there was a more elegant way to leave this bit in the content model and just toggle nesting on/off or change which topic types could be nested.

How do you allow nesting of more than one topic type?  I'd presume that the following would work in the .dtd file:
   <!ENTITY % reference-info-types "concept | procedure | topic">
but figured I'd check with you on that while I had your attention.


----------------

Hi Eric, 

We have a sneaky way around the issue: we have an element in the DTD called "no-topic-nesting". It's not used anywhere, so it never shows up unless you need to disable nesting. So you can set the infotype entity to "no-topic-nesting", and then that element becomes the only thing allowed at the point that users would otherwise be able to add topics. The element has no processing implications, is empty and has no attributes. It's obviously not an ideal solution, but it works... 

For multiple nesting, yes this is the way to do it. Check out ditabase.dtd for an example. 

As a side note: the reason we have different definitions for each info-type is to make it easier to set nesting rules on a per-type basis. The reason they all map to info-types by default is to make it easier to set global nesting rules when they exist. For example, in ditabase.dtd, everything can nest everything, so we just redefine the info-types entity rather than defining each information-type-specific entity separately. 

Also, would you be willing to copy this discussion to the dita-users list? Just figuring this discussion is probably useful to a wider audience. 

Michael Priestley
mpriestl@ca.ibm.com
Dept PRG IBM Canada phone: 416-915-8262
Toronto Information Development