DITA specialization question

Is there any possibility to override element with the same name

f.e: "section" element in topic module to  "section" element in my module with another structure?

I sympathize with your desire to do this, but I strongly advise against it. Here are a few reasons to not reuse section in this fashion:

  • The DITA way to extend semantics is through specialization; specialization does not support overriding element names.
  • It could undermine the automatic processing behavior present in tools such as the DITA Open Toolkit leading to breakage, unpredicatable behavior, or both.
  • It would leave a confusing legacy to whoever your successor will be.

You may want to consider choosing an element name that isn't already in use such as "sect".

I recommend that you extend DITA only through specialization. Confining yourself to specialization will make it likely that your DITA instances will behave reasonably with DITA-compliant tools. This will allow you to take advantage of the large amount of work that has already been done to facilitate the publishing of DITA-compliant documents.


Bob Thomas

Tagsmiths, LLC

Thank you very much.

I fully agree with you that it is not a DITA way. The point is that we try to modeling existing formats(such as DockBook) in DITA. So we have this problem. Maybe you have any recomendations?

Best regards

Alex Avekov

If your source is not DocBook, it is likely to be structurally similar to DocBook. The only mapping that I know of from DocBook to DITA is to express the the DocBook structure as nested topics, preferably through DITA maps. As you imply, DocBook's section element, or its concrete versions (sect1 through sect5), will not map to the DITA section element. Instead, DocBook sections must map to DITA topics with the expectation that the DITA topics will be nested.

Here is one way that you could proceed with a conversion:

  1. Convert a DocBook instance into a monolithic DITA instance that parses against the Composite DTD (ditabase.dtd). Map all chapters, sections, and appendixes to DITA topics using topic nesting.
  2. Prepare to factor the monolithic DITA instance into individual topics by setting the otherprops attribute on each topic to the target topic type. For each topic you would indicate whether it is to become a concept, reference, task, or remain as topic. You may be able to programmatically do some of this work as part of step 1.
  3. Indicate which topics will become DITA maps by setting their outputclass to "map".
  4. Convert the monolithic instance into DITA maps and topics based on the attribute settings from steps 2 and 3. Be sure to disgard the otherprops and outputclass values when creating the topics.

If your existing documentation is like most, your will have several topics that are not written according to information type. In step 2, I would leave topics that require rewriting as topic rather than forcing them into concept, reference, or task. The expectation is that authors would refactor this information into one or more information typed-topic. Rewriting content can potentially take much more time than all of the programming and tagging implied in the above steps. It may be tempting to avoid the rewriting, but the rewriting is absolutely necessary to unlock all of DITA's potential.


Bob Thomas

Tagsmiths, LLC

XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I