Edit online

Generating WebHelp Responsive Output

The publishing process can be initiated from a transformation scenario within Oxygen XML Editor/Author, from a command line outside Oxygen XML Editor/Author, or from an integration server.

Edit online

Running WebHelp Responsive from Oxygen XML Editor/Author

To publish a DITA map as WebHelp Responsive output, follow these steps:
  1. Select the Configure Transformation Scenario(s) action from the DITA Maps Manager toolbar.
  2. Select the DITA Map WebHelp Responsive scenario from the DITA Map section.

  3. If you want to configure the transformation, click the Edit button.

    Step Result: This opens an Edit scenario configuration dialog box that allows you to configure various options in the following tabs:
    • Templates Tab - This tab contains a set of built-in skins that you can use for the layout of your WebHelp system output.
    • Parameters Tab - This tab includes numerous transformation parameters that can be set to customize your WebHelp system output.
    • Feedback Tab - This tab is for those who want to add the Oxygen Feedback comments component at the bottom of each WebHelp page so that you can interact with your readers.
    • Filters Tab - This tab allows you to filter certain content elements from the generated output.
    • Advanced Tab - This tab allows you to specify some advanced options for the transformation scenario.
    • Output Tab - This tab allows you to configure options that are related to the location where the output is generated.
  4. Click Apply associated to process the transformation.

Result: When the DITA Map WebHelp Responsive transformation is complete, the output is automatically opened in your default browser.

Edit online

Running WebHelp Responsive from Command Line

To publish to the WebHelp Responsive output from a command line outside of Oxygen XML Editor/Author, you can use the dita startup script that comes bundled with DITA Open Toolkit distribution.

dita Command Format

DITA-OT dita command has the following format:

DITA-OT-DIR/bin/dita --format=webhelp-responsive --input=input-file options

where the arguments are as follows:

dita
Windows - The dita.bat script located in: DITA-OT-DIR\bin\.
Linux/macOS - The dita script file located in: DITA-OT-DIR/bin/.
--format=webhelp-responsive
Specifies the output format (transformation type) for WebHelp Responsive transformation.
--input=input-file
The input-file represents the path to the DITA map that you want to process.
options

options include the following optional build parameters:

--output=dir
-o dir
Specifies the path of the output directory; the path can be absolute or relative to the current directory. By default, the output is written to the out subdirectory of the current directory.
--filter=file
Specifies filter file(s) used to include, exclude, or flag content.
Relative paths are resolved against the current directory and internally converted to absolute paths.
--temp=dir
-t dir
Specifies the location of the temporary directory.
--verbose
-v
Verbose logging.
--debug
-d
Debug logging.
--logfile=file
-l file
Write logging messages to a file.
--parameter=value
-Dparameter=value
Specify a value for a DITA-OT or Ant build parameter.
--propertyfile=file

Use build parameters defined in the referenced .properties file.

Build parameters specified on the command line override those set in the .properties file.

WebHelp and DITA-OT parameters

In addition to the transformation parameters that are specific to WebHelp Responsive, you can use the common DITA-OT transformation parameters and the HTML-based Output Parameters.

Command-Line Example

  • Windows: 
     dita.bat 
    --format=webhelp-responsive
    --input=c:\path\to\mySample.ditamap  
    --output=c:\path\to\output 
    -Dwebhelp.logo.image=myLogo.jpg
  • Linux/macOS: 
     dita
    --format=webhelp-responsive
    --input=/path/to/mySample.ditamap  
    --output=/path/to/output 
    -Dwebhelp.logo.image=myLogo.jpg
Tip: You can also start the dita process by passing it a DITA OT Project File. Inside the project file you can specify as parameters for the webhelp-responsive transformation type the WebHelp-related parameters.
Edit online

Running WebHelp Responsive from an Integration Server

WebHelp output can be processed from an automatic publishing system, such as Jenkins or Travis.

Edit online

Automating DITA to WebHelp Responsive Output with Jenkins

This procedure assumes that you have already integrated, configured, and registered the Oxygen XML WebHelp Responsive plugin with the DITA Open Toolkit.

To integrate WebHelp output with the Jenkins continuous integration tool, follow these steps:
  1. Create a Maven project to incorporate the DITA-OT that already integrates Oxygen XML WebHelp Responsive plugin.
  2. Go to the root of your Maven project and edit the pom.xml file to include the following fragment:
    <properties>
    <dita-ot-dir>${basedir}/tools/dita-ot</dita-ot-dir>
    <!-- 
        The path to the DITA map that you want to process. 
    -->
    <input-file>path/to/input_file</input-file>
        
    <!-- 
        Specifies the path of the output directory.
    -->
    <output-dir>path/to/output_dir</output-dir>
    
    <!-- 
        The path to the WebHelp publishing template. 
    -->
    <publishing-template>path/to/publishing_template</publishing-template>   
		
    <!--
        DITA-OT optional build parameters.
    -->
    <options>-Dwebhelp.publishing.template=${publishing-template} -v</options>
</properties>
    
<plugin>
    <artifactId>exec-maven-plugin</artifactId>
    <groupId>org.codehaus.mojo</groupId>
    <executions>
        <execution>
            <!-- Run WebHelp Responsive transformation -->
            <id>run-webhelp-responsive</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>exec</goal>
            </goals>
            <configuration>
                <executable>${dita-ot-dir}/bin/dita.bat --format=webhelp-responsive
                     --input=${input-file} --output=${output-dir} ${options}</executable>
            </configuration>
        </execution>
   </executions>
</plugin>
  3. Go to the Jenkins top page and create a new Jenkins job. Configure this job to suit your particular requirements, such as the build frequency and location of the Maven project.
Edit online

Automating DITA to WebHelp Responsive Output with Travis CI

This topic assumes you have a DITA project hosted on a GitHub public or private repository.

The goal of this tutorial is to help you set up a Travis continuous integration job that automatically publishes your DITA project to GitHub pages after every commit. The published website will contain a feedback link on each page that would allow a contributor to easily suggest changes to the documentation by creating a pull request on GitHub with just a few clicks.

Enable the Travis CI Build

  1. Sign in to Travis CI with your GitHub account, accepting the GitHub access permissions confirmation.
  2. Once you are signed in, and you have synchronized your GitHub repositories, go to your profile page and enable Travis CI for the repository you want to build.

Configure the Travis CI Build in your GitHub Project

  1. Checkout your GitHub project locally.
  2. Copy the .travis folder from here to the root directory of your project.
  3. In the root of your GitHub project, add a file called .travis.yml with the following content:
    language: dita
install:
  - echo "Installed"
script:
  - sh .travis/publish.sh
after_success:
  - sh .travis/deploy.sh
env:
  global:
    - DITAMAP=/path/to/your/ditamap/file
    - DITAVAL=/path/to/your/ditaval/file
    - ANT_OPTS=-Xmx1024M
    Note: Replace /path/to/your/ditamap/file and /path/to/your/ditaval/file with the appropriate paths to your DITA map and ditaval files.
  4. Create a GitHub personal access token by following this procedure.
  5. Define an environment variable in the repository settings that has the name GH_TOKEN and the value equal with the GitHub personal access token created earlier.

Register Your License Key

  1. Edit your .gitignore file (or create it if it does not already exist) and add the following line: 
    licenseKey.txt
  2. Copy your WebHelp license to the root of your GitHub project in a file called licenseKey.txt.
    Important: The licenseKey.txt file should not be committed to GitHub as it contains a license key that is issued only to you.
  3. Encrypt the license key file and add it to the .travis.yml configuration file. This way only the Travis CI server will be able to decrypt it during the build process.

Commit to GitHub

  1. Commit the following files and folders and push the commit to GitHub: 
    git add .gitignore licenseKey.txt.enc .travis.yml .travis/
git commit -m "Set up the Travis CI publishing system"
git push
  2. Create a gh-pages branch in your GitHub project where the WebHelp Responsive output will be published. You can follow the procedure here.
Edit online

Running WebHelp Responsive from a Docker image

This topic explains how to install the WebHelp Responsive plugin in a Docker image.

To install the Oxygen XML WebHelp Responsive plugin in a Docker image, follow these steps:

  1. Download and install Docker.
  2. Create a folder (for example, webhelp-docker).
  3. Move the licensekey.txt file for the WebHelp Responsive plugin to the newly created folder.
  4. Create a new file named Dockerfile with the following content and store it in the newly created folder: 
    # Use the latest DITA-OT image as parent
FROM ghcr.io/dita-ot/dita-ot:3.6.1

# Build argument form the WebHelp download link
ARG WEBHELP_DOWNLOAD_LINK

# Download the WebHelp zip kit.
RUN curl -o /tmp/oxygen-webhelp.zip ${WEBHELP_DOWNLOAD_LINK}

# Unzip the WebHelp kit to the plugins directory of the DITA-OT distribution.
RUN unzip /tmp/oxygen-webhelp.zip -d /opt/app/plugins

# Remove the WebHelp zip.
RUN rm /tmp/oxygen-webhelp.zip

# Copy the license key.
COPY licensekey.txt /opt/app/

# Install the WebHelp plugins.
RUN dita --install
  5. Build an image from the Dockerfile by running the following command: 
    docker image build --build-arg WEBHELP_DOWNLOAD_LINK=https://www.oxygenxml.com/InstData/WebHelp/oxygen-webhelp-dot-3.x.zip -t webhelp-docker:23.1 ${PATH_TO_DOCKERFILE}
  6. Run a WebHelp Responsive transformation from docker: 
    docker run -it \
-v ${PATH_TO_DITAMAP}:/src webhelp-docker:23.1 \
-i /src/map.ditamap \
-o /src/out \
-f webhelp-responsive -v
    Attention: Make sure that you do not violate the license model. More information can be found in the Oxygen XML WebHelp Responsive plugin End-User License Agreement.