Note: The topicmerge function was updated in DITA-OT 1.3.1, so this item is no longer being developed. Up to date information on the toolkit can be found here: The DITA Open Toolkit

Issue owner(s):
Robert D Anderson (robander _at_ us dot ibm dot com)

Statement of problem or objective:
The topicmerge routine currently included in the toolkit contains several bugs, and does not meet the needs of all users. It needs to be updated to fix the bugs and to meet a wider range of user goals.

Is this architecture, function, fix, or other?
Architecture, function, & fix

Goals of this proposal:
The following objectives have been raised:
Fixes:

• Links between topics must be resolved, so that it is possible to find the target within the same merged file.
• Need a fix for duplicate ID conflicts
• Must be possible to include a topic twice without causing errors
• Users have reported errors or inconsistencies when merging topics that use the <dita> container element.
• The end result should be templatable so that new plugins can easily override the merge

Enhancements:

• Different users require different merged output. It must be possible to get all merged formats from the same program, likely through using a parameter.
• It should be easy to override the merge routine to get tweaked output formats.
• ...

Required output support:

• Must be able to get a merged file that contains all tags from the source maps and topics. If a tag is present in a source file, it is possible that the tag will be needed by processors that work with the merged document.
• Must be able to get a merged document that does not contain the map markup (only merged topics). It should be possible, with an override, to give this merged file a document type. For example, a map of reference topics can create a giant merged reference topic which is valid against the reference DTD.
• Others that have been mentioned, which should be added to this list once somebody has verified they are needed and corrected the description:

• Must be able to get a merged document that does not contain topicgroup elements or reltables
• Must be able to get a merged document that includes hints of the map markup, but with a structure that only reflects the topics.

Use cases:
Coming...

Stakeholders:
The following are known consumers of the merged map:
* PDF generators; the current FOP based and Idiom/XEP based code will need to be updated to use the new topicmerge routine
* Bookmap (related to PDF output)
* Editors that display a merged book-like view of the map
* RDF output (based on the thesaurus plugin/specialization)

Interested parties:
List of people interested in potential meetings or discussions.  Use obfuscated addresses, please.  For example, dond at us dot ibm dot com
Robert Anderson [robander _at_ us [dot] ibm (dot) com]
Deborah Pickett ( deborah UNDERSCORE pickett AT moldflow.com )

The following people have commented on this issue in the past - please remove your name or let Robert know if you wish to be removed:
Paul Prescod
Chris Wong
Yuan Peng Zhang (Stephen)
Hedley Finger

Proposed design:
Design for fix topicmerge
Note: All design discussions should occur on the dita-ot-developer list at the dita-ot sourceforge site.