Generating WebHelp Responsive Output
Edit online

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.

Running from Oxygen XML Editor/Author
Edit online

To publish to the WebHelp Responsive output from a transformation scenario inside Oxygen XML Editor/Author, use one of the following procedures, depending on whether or not you want a feedback section in your output.

WebHelp Responsive Output

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.
    • 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.

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

WebHelp Responsive with Feedback Output

To publish a DITA map as a WebHelp Responsive with Feedback system, follow these steps:
  1. Select the Configure Transformation Scenario(s) action from the DITA Maps Manager toolbar.
  2. Select the DITA Map WebHelp Responsive with Feedback 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.
    • 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 begin the transformation.
  5. Enter the documentation product ID (value for the webhelp.product.id parameter) and the documentation version (value for the webhelp.product.version parameter).

    When the DITA Map WebHelp Responsive with Feedback transformation is complete, your default browser opens the installation.html file. This file contains information about the output location, system requirements, installation instructions, and deployment of the output. Follow the instructions to complete the system deployment.

Running from Command Line
Edit online

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/Mac OS X - 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 to the common DITA-OT transformation parameters and the Modifying or adding generated text.

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/Mac OS X: 
     dita
    --format=webhelp-responsive
    --input=/path/to/mySample.ditamap  
    --output=/path/to/output 
    -Dwebhelp.logo.image=myLogo.jpg

Running from an Integration Server
Edit online

Oxygen XML Editor plugin can be processed from an automatic publishing system, such as Jenkins or Travis.

Automating DITA to WebHelp Output with Jenkins
Edit online

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 Editor plugin.
  2. Go to the root of your Maven project and edit the pom.xml file to include the following fragment:
    <properties>
  <oxygen-webhelp>${basedir}/tools/DITA-OT2.5.2/
       plugins/com.oxygenxml.webhelp.responsive</oxygen-webhelp>
</properties>

<plugin>
  <artifactId>exec-maven-plugin</artifactId>
  <groupId>org.codehaus.mojo</groupId>
  <executions>
    <execution><!-- Run our version calculation script -->
      <id>Version Calculation</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>exec</goal>
      </goals>
      <configuration>
        <executable>${oxygen-webhelp}/ditaWebhelp.bat</executable>
      </configuration>
    </execution>
  </executions>
</plugin>
    Note: In the fragment above it is assumed that you are using DITA-OT version 2.5.4. If you are using another version, adjust the path accordingly.
  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.

Automating DITA to WebHelp Output with Travis CI
Edit online

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 setup 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 output will be published. You can follow the procedure here.