Passthrough Plugin

This is an abstract base DITA-OT Plug-in to enable files to bypass DITA-OT pre-processing and be copied directly over into the processing directory. It is designed to be extended.

The plugin consists of a no-op file reader and an Antlib library. It offers two extension-points for further processing.

Install

Run the plug-in installation commands:

dita install https://github.com/doctales/org.doctales.xmltask/archive/master.zip
dita install https://github.com/jason-fox/fox.jason.passthrough/archive/master.zip

The dita command line tool requires no additional configuration.

Usage

To mark a file as requiring no processing, label it with @format="passthrough" within the DITA <map> as shown:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    ...etc
    <mapref format="passthrough" href="sample.txt"/>
</bookmap>

The additional file will be added to the build job without processing.

Extension points

This plug-in is designed to be extended and offers two extension points:

passthrough.pre - Runs an additional ANT target before the passthrough pre-processing stage.
passthrough.process - Runs an additional ANT target as part of the passthrough processing stage.

Example

The following plugin.xml will enable the post-processing of all files marked as format=NEW_FORMAT.

<plugin id="com.example.passthrough.dita">
  <feature extension="passthrough.process" value="run-processing"/>
  <feature extension="dita.parser">
    <parser format="NEW_FORMAT" class="fox.jason.passthrough.parser.FileReader"/>
  </feature>
</plugin>

Figure 1. plugin.xml Configuration

<project name="com.example.passthrough.dita">

  <macrodef name="do-something">
    <attribute name="src" />
    <attribute name="dest" />
    <attribute name="title" />
    <attribute name="metadata" />
    <sequential>
      <!-- Further processing -->
    </sequential>
  </macrodef>

  <target name="run-processing">
    <passthrough-iterate format="NEW_FORMAT" macro="do-something"/>
  </target>
</project>

Figure 2. ANT build file

A working example can be found in the DITA-OT Pandoc plug-in repository.

ANT Task

The following ANT task is available from the DITA-OT Pass Through plug-in:

Passthrough-Iterate

Description

Post process all files of a given format using the macro supplied.

Parameters

Attribute	Description	Required
format	The `@format` attribute used with the DITA `<map>`	Yes
macro	The name of the `<macrodef>` to run	Yes

Example

 <passthrough-iterate format="NEW_FORMAT" macro="do-something"/>

Files marked as @format="NEW_FORMAT" should be processed by the macrodef called do-something. The macro must offer an interface with src, dest, title and metadata attributes. All attributes will be pre-supplied by DITA-OT.

Attribute	Description	Required
src	The source file which holds the raw input format	Yes
dest	The destination file for the processed DITA	Yes
title	The title to use for the DITA topic	Yes
metadata	Any additional topic metadata to process (in XML format)	Yes

<macrodef name="do-something">
    <attribute name="src" />
    <attribute name="dest" />
    <attribute name="title" />
    <attribute name="metadata" />
    <sequential>
        <!-- Further processing -->
    </sequential>
</macrodef>