Re: [dita] 12010 Domain and topic integration

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Paul:

DITA 1.1 has a requirement that all specialized elements provided by a specialization module must have a base element defined in the same module (or in the some module as one of its base elements).

For instance, if a module specializes task, all of the elements in the module must derive from either task or topic.

Let me give a concrete example why this limitation is a problem for designers.

The Java API specialization has a *def element to represent the declaration of a Java method and a Java field. Methods and fields have different declarations sharing some but not all properties.

For instance, both methods and fields can have an access property. The access property means the same thing, and the enumeration of possible access values are the same (public, protected, private, and default / package).

The natural way to model this information in XML, of course, would be for the Java class and Java field topics to share some kind of <accessProperty> element.

Because DITA 1.1 prohibits a topic type from either making domain elements required in a content model or specializing domain elements (see above), the only possible way to have structural elements that are shared between two topics types is to put the shared elements in a common base module. If, however, there are reasons to have distinct ancestors, you have to use different elements with similar names.

For that reason, the current Java API specialization has <javaMethodAccess> and <javaFieldAccess> -- distinct elements for identical data.

Similar, to declare the type of a method or field, the current specialization has <javaMethodClass>, <javaMethodInterface>, <javaMethodPrimitive>, and <javaMethodArray> with mirroring <javaFieldClass>, <javaFieldInterface>, <javaFieldPrimitive>, and <javaFieldArray>. Again, pairs of distinct elements for identical data.

It works, but the design would be more efficient and clearer if the Java method and field topic types could get the subelements of their declarations from a shared domain that provides <javaAccess>, <javaClassType>, <javaInterfaceType>, <javaPrimitive>, <javaArray>, and so on.

That's a particularly prominent case but not the only case where topics would benefit from sharing subelements that aren't global alternatives for the base elements (like domains) but also aren't inherited from a common ancestor.

I think we can come up with a solution that isn't scary, but no doubt the review of the design proposal will confirm whether or not that's the case.

If it would be useful to look at the example more closely, here's the inheritance hierarchy for the containers for the Java declarations:

... <section> in topic
....... (nothing in reference)
........... <apiDef> in apiRef
............... <apiOperationDef> in apiOperation
................... <javaMethodDef> in javaMethod
............... <apiValueDef> in apiValue
................... <javaFieldDef> in javaField

And here's the inheritance hierarchy for the access properties:

... <state> in topic
....... (nothing in reference)
........... <apiQualifier> in apiRef
............... (nothing in apiOperation)
................... <javaMethodAccess> in javaMethod
............... (nothing in apiValue)
................... <javaFieldAccess> in javaField


Hoping that's clarifies,


Erik Hennum
ehennum@us.ibm.com


"Grosso, Paul" <pgrosso@ptc.com> wrote on 08/15/2007 07:17:09 AM:

> I don't understand the suggestion, the use case, or
> much of any of it, but I note it says that the scope
> is major and that we are "Chang[ing] the current notion
> of module inheritance into the more general notion of
> module dependency managed by the architecture, including
> dependencies on multiple modules" which, whatever that
> means, sounds scary to me.