Part of Plans for DITA Open Toolkit 1.5

Design for implementing "push conref " in the DITA Open Toolkit

What user need will be met by this feature?

Users can use conaction pairs combined with @conref to push the content to a specific location.

What is the technical design for the change

Design assumption:

The following design assumption are used to track the technical constraints of current implementation. If later, the containts are broken, we might change the design and implementation.

1. XSLT cannot generate multiple outputs in a single transformation
   Note: conref push is in the reverse direction to solve @conref. When resolving normal @conref, we need to read from multiple input and put the content in one output. So in conref push, we need to read single input and push it to differenct outputs. XSLT 1.0 we are using now does not support generate to multiple outputs and XSLT 2.0 standard support that. If later, XSLT 2.0 is adopted, we might need to refactor design and implementation to new ways.

Since XSLT 1.0 is not capable enough to resolve and action on conref push, we need to create new module among preprocess steps. The preference location in preprocess to add this new step is after Debug&Filter and before conref resolution. The name of the new step is called Push and consists three Java Class, PushModule, PushReader, PushParser. The responsibility of the Java classes are listed as followings:

• PushModule reads the file list provided by Genlist module. The file list contains all files which contains conref push information.Then it goes through the list and trigger PushReader to read the conref push information and store the result of read into a table. After that, it reads info in the table and calls PushParser to move the content into specific location per each file.
• PushReader reads the conref push information in specified files and call PushParser to write the information it reads to specified conref push target
• PushParser parses the specified conref push target file provided by PushModule and write the content to the specific location.

Basically, PushParser and PushReader don't have communication for the purpose of loose coupling and processing performance. If several conref push have the same target, we expect them to be pushed to target in batch and the processor should not read and write the same file several times. For this purpose, we need a nested table as data structure to store the info read by PushReader.

The first table use file names as the key and the value is another table which contains detailed location id in that file and push content as pair.

Note: it is not legal to use "pushreplace" twice with the same target, because an element can only be replaced once. However it is legal to push multiple items before or after a single target. There is no defined order when this is done.

What sections of the toolkit will be impacted by the change?

The current step will be impacted in toolkit is current conref resolution and genlist module.

Genlist module need to scan for conref push elements and record the file with those features in conrefpush list.

Current conref resolution need to avoid processing @conref which has conref push action.

See also

none

Notes

We need to be aware of a few conditions:

• If the element that does the "push" contains domain elments that are not valid in the target, those domain elements must be generalized (like with normal conref).
• If the element that does the "push" contains cross references or conref values with relative paths, those relative paths need to be adjusted.
• If an element pushes a conref into a topic/file that did not use conref, we need to be sure to run conref.xsl on the updated file.