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.

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

See also

none