/fox.jason.passthrough

Abstract base DITA-OT Plug-in to enable files to bypass DITA-OT pre-processing

Primary LanguageJavaApache License 2.0Apache-2.0

Pass Through Plugin for DITA-OT

license DITA-OT 4.2 CI Quality Gate Status

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.

Table of Contents

Install

The DITA-OT Passthrough plug-in has been tested against DITA-OT 3.x. It is recommended that you upgrade to the latest version.

Installing DITA-OT

The DITA-OT Pass Through plug-in is a file reader for the DITA Open Toolkit.

  • Full installation instructions for downloading DITA-OT can be found here.

    1. Download the dita-ot-4.2.zip package from the project website at dita-ot.org/download
    2. Extract the contents of the package to the directory where you want to install DITA-OT.
    3. Optional: Add the absolute path for the bin directory to the PATH system variable.

    This defines the necessary environment variable to run the dita command from the command line.

curl -LO https://github.com/dita-ot/dita-ot/releases/download/4.2/dita-ot-4.2.zip
unzip -q dita-ot-4.2.zip
rm dita-ot-4.2.zip

Installing the Plug-in

  • Run the plug-in installation commands:
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 *.ditamap as shown:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    ...etc
    <chapter 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.xml Configuration
<plugin id="com.example.passthrough.dita">
  <require plugin="fox.jason.passthrough"/>
  <feature extension="passthrough.process" value="run-processing"/>
  <feature extension="dita.parser">
    <parser format="NEW_FORMAT" class="fox.jason.passthrough.parser.FileReader"/>
  </feature>
</plugin>
ANT build file
<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>

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

API

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 *.ditamap 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.

License

Apache 2.0 © 2019 - 2024 Jason Fox