[oXygen-user] integrate Oxygen output into build process?

Sorin Ristache
Wed Oct 29 05:35:41 CDT 2014


Hello Tom,

Please let us know if we can further help you. I am not particularly 
familiar with the Mercurial event hooks like post commit, but I suppose 
you would just plug into the post commit hook a shell script like the 
dita.sh attached to my previous message. I could find a list of the 
Mercurial hooks here:

http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html

http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html#sec:hook:ref


Best regards,
Sorin

<oXygen/> XML Editor

http://www.oxygenxml.com


Tom Johnson wrote:
> Sorin, thanks, this is just the information I was looking for. Let me 
> process it and see if I can set something up. Ideally I want to just 
> fire everything off from the command line when I commit.
> 
> Tom
> 
> ---------------------
> 801-822-2241
> blog: idratherbewriting.com <http://idratherbewriting.com>
> twitter: tomjohnson
> 
> On Tue, Oct 28, 2014 at 2:16 AM, Sorin Ristache < 
> <mailto:>> wrote:
> 
>     Hi Tom,
> 
>     In the Oxygen application a transformation can be started only
>     manually, for example with an action available on a toolbar or a
>     menu or with a custom Author mode extension action. A transformation
>     can be started automatically as in your case (registered as a hook
>     on a version control event) only outside the Oxygen application, as
>     an independent Java process or as a CLI shell command.
> 
>     For DITA files we provide only the WebHelp transformation as a
>     independent process (outside the Oxygen application). It is a
>     DITA-OT plugin which can be integrated in a DITA-OT
>     1.6.x/1.7.x/1.8.x installation and which is available as a separate
>     product on the Oxygen website, which means it requires a separate
>     purchased license. The WebHelp pages created by this DITA-OT plugin
>     are the same as the ones created in the Oxygen application applied
>     to the same DITA files. I attach a README file with the DITA-OT
>     integration instructions and also a sample script for starting the
>     WebHelp transformation from a command line. If you need more details
>     please let me know.
> 
>     For other DITA transformations started outside the Oxygen
>     application I suggest running the built-in transformations which
>     come with the DITA-OT kit and which can generate PDF output, Windows
>     Help output, Eclipse Help output, etc. The DITA-OT documentation
>     includes instructions for starting a DITA transformation from a
>     command line:
> 
>     https://dita-ot.github.io/1.8/__readme/tranforming-dita-__content.html
>     <https://dita-ot.github.io/1.8/readme/tranforming-dita-content.html>
> 
> 
>     Best regards,
>     Sorin
> 
>     <oXygen/> XML Editor
>     http://www.oxygenxml.com
> 
> 
>     Mary Anthony wrote:
> 
>         Hi Tom,
> 
>         Most commercial companies would use a continuous integration
>         tool such as Bamboo, Hudson, or Buildbot to kick a build on
>         commit. I've used Bamboo myself to build such a system for
>         Javadoc and Webworks. Depends on your resources.
> 
>         A Mercurial post commit hook might be the way for you to go. I
>         quick google of "mercurial post commit hook build" gave me
>         several results.
>         Good luck,
> 
>         Mary
> 
>         On Mon, Oct 27, 2014 at 11:27 AM, Tom Johnson
>         < <mailto:>
>         <mailto:
>         <mailto:>>> wrote:
> 
>             Does anyone know how to tell Oxygen to initiate
>         transformations when
>             I commit to a version control repository, specifically
>         Mercurial?
>             Just like Javadocs gets auto-kicked off when developers commit
>             source files, I'd like to do the same with Oxygen and my
>         DITA files.
> 
>             Tom
> 
> 
> 
>     INTRODUCTION
>     =============
> 
>     This directory contains the Oxygen Webhelp plugin version
>     @@VERSION@@ for DITA Open Toolkit. The Webhelp output files are
>     exactly the same as for the DITA Webhelp transformations executed
>     inside the Oxygen XML Editor @@VERSION@@ application. The plugin
>     must be first integrated in the DITA Open Toolkit for adding the
>     following transformation types to the DITA Open Toolkit:
> 
>     webhelp           - The Webhelp transformation for desktop output
> 
>     webhelp-feedback  - The Webhelp transformation for desktop output
>     with a section for
>                         user comments at the bottom of each XHTML output
>     page
> 
>     webhelp-mobile    - The Webhelp transformation for mobile devices output
> 
> 
>     More details about all the Webhelp transformations are available on
>     the Oxygen website:
> 
>     http://www.oxygenxml.com/xml_editor/webhelp.html
> 
> 
>     LICENSE TERMS
>     ==============
> 
>     The license terms of the Oxygen Webhelp distribution are set forth
>     in the file EULA_Webhelp.txt located in the same directory as this
>     README file.
> 
> 
>     REQUIREMENTS
>     =============
> 
>     The requirements of the Oxygen Webhelp plugin for DITA Open Toolkit
>     are the following:
> 
>     - Java Virtual Machine 1.6 or later
> 
>     - DITA Open Toolkit 1.6.x, 1.7.x or 1.8.x (the 'full easy install'
>     distribution)
> 
>     - Saxon 9.1.0.8 processor
> 
> 
>     INSTALL THE WEBHELP PLUGIN IN DITA-OT
>     ======================================
> 
>     1. Download and install a Java Virtual Machine 1.6 or later and a
>     DITA Open Toolkit 1.6.x, 1.7.x or 1.8.x (the 'full easy install'
>     distribution) if you don't have them already installed:
> 
>     http://www.oracle.com/technetwork/java/javase/downloads/index.html
> 
>     http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release/
> 
>     2. Copy the parent directory of this README file, called
>     'com.oxygenxml.webhelp', and the directory called
>     'com.oxygenxml.highlight', in the 'plugins' subdirectory of the
>     install directory of the DITA Open Toolkit where you want to run the
>     Oxygen Webhelp transformation.
> 
>     3. Run the following command in the directory of DITA Open Toolkit:
> 
>        ant -f integrator.xml
> 
>     The integrator.xml file is located in the DITA Open Toolkit install
>     directory. This will add two plugins to DITA-OT: Oxygen Webhelp
>     plugin (directory com.oxygenxml.webhelp) and Oxygen highlight plugin
>     (directory com.oxygenxml.highlight).
> 
>     4. Download and unzip on your computer the saxonb9-1-0-8j.zip file
>     containing the Saxon 9.1.0.8 processor from:
> 
>     http://sourceforge.net/projects/saxon/files/Saxon-B/9.1.0.8/
> 
> 
>     REGISTER YOUR OXYGEN LICENSE IN THE WEBHELP PLUGIN
>     ===================================================
> 
>     Create a text file called 'licensekey.txt' in the directory
>     [DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp. Copy and paste
>     in this file your Oxygen Scripting license key which you purchased
>     for your Oxygen Webhelp plugin. The Webhelp transformation will read
>     the Oxygen license key from this file. If this file does not exist
>     or it contains an invalid license key an error message will be
>     displayed.
> 
> 
>     RUN THE WEBHELP TRANSFORMATION in DITA-OT
>     ==========================================
> 
>     The following command will run the Webhelp transformation. This
>     command is available also as a script file in the same directory as
>     this README file, called dita.sh for Unix/Linux based system and
>     dita.bat for Windows systems. Just set the correct values of the
>     script variables at the beginning at the script file before calling
>     the script in an automated process or from a command line.
> 
> 
>     "[JVM-install-dir]/bin/java" -Xmx512m -classpath
>     "[DITA-OT-install-dir]/tools/ant/lib/ant-launcher.jar"
>     "-Dant.home=[DITA-OT-install-dir]/tools/ant"
>     org.apache.tools.ant.launch.Launcher -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/xercesImpl.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/xml-apis.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/xml-apis-ext.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/dost-patches.jar"
>     -lib "[DITA-OT-install-dir]" -lib "[DITA-OT-install-dir]/lib" -lib
>     "[Saxon-9.1.0.8-dir]/saxon9.jar" -lib
>     "[Saxon-9.1.0.8-dir]/saxon9-dom.jar" -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/license.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/log4j.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/resolver.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/ant-contrib-1.0b3.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/lucene-analyzers-common-4.0.0.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/lucene-core-4.0.0.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/xhtml-indexer.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.highlight/lib/xslthl-2.1.0.jar"
>     -lib
>     "[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/lib/webhelpXsltExtensions.jar"
>     -f "[DITA-OT-install-dir]/build.xml"
>     "-Dtranstype=[webhelp.transtype]" "-Dbasedir=[DITA-map-base-dir]"
>     "-Doutput.dir=[DITA-map-base-dir]/out/[webhelp.transtype]"
>     "-Ddita.temp.dir=[DITA-map-base-dir]/temp/[webhelp.transtype]"
>     "-Dargs.filter=[DITAVAL-dir]/[file.ditaval]"
>     "-Ddita.input.valfile=[DITAVAL-dir]/[file.ditaval]"
>     "-Dargs.hide.parent.link=no" "-Ddita.dir=[DITA-OT-install-dir]"
>     "-Dargs.xhtml.classattr=yes"
>     "-Dargs.input=[DITA-map-base-dir]/[input-DITA-map-file.ditamap]"
>     "-Dwebhelp.skin.css=[DITA-OT-install-dir]/plugins/com.oxygenxml.webhelp/predefined-skins/dita/oxygen/skin.css"
>     "-DbaseJVMArgLine=-Xmx384m"
> 
> 
>     where:
> 
>     - [JVM-install-dir] must be replaced with the path of the Java
>     Virtual Machine install directory
> 
>     - [DITA-OT-install-dir] must be replaced with the path of the DITA
>     Open Toolkit install directory
> 
>     - [Saxon-9.1.0.8-dir] must be replaced with the path of the
>     directory were the Saxon 9 archive file (saxonb9-1-0-8j.zip) was
>     unzipped
> 
>     - [webhelp.transtype] must be one of the values: webhelp,
>     webhelp-feedback, webhelp-mobile
> 
>     - [DITA-map-base-dir] must be replaced with the path of the
>     directory of the input DITA map file
> 
>     - [DITAVAL-dir] must be replaced with the path of the directory of
>     [file.ditaval] which sets the DITAVAL input filter
> 
>     - [file.ditaval] must be replaced with the name of the DITAVAL input
>     filter file that will be applied to the input map
> 
>     - [input-DITA-map-file.ditamap] must be replaced with the name of
>     the input DITA map file
> 
> 
>     The '-Dargs.filter' and '-Ddita.input.valfile' parameters are optional.
> 
>     The Webhelp output pages are generated in the directory that is set
>     in the parameter 'output.dir', by default
>     [DITA-map-base-dir]/out/[transtype].
> 
>     The -Dwebhelp.skin.css parameter sets a skin CSS for the Webhelp
>     output pages. In the above example the predefined skin called
>     "Oxygen" was set. A set of predefined skins come with the Webhelp
>     kit in the directory predefined-skins. For building your own custom
>     skin please use the Webhelp Skin Builder from:
> 
>     http://www.oxygenxml.com/webhelp-skin-builder/
> 
>     A company logo image can be optionally added to the main title in
>     the header area of the Webhelp output pages with the parameter:
>     -Dwebhelp.logo.image. A URL can be optionally set for the logo image
>     to point to using the parameter: -Dwebhelp.logo.image.target.url.
> 
> 
>     CONFIGURE DATABASE (ONLY FOR WEBHELP WITH FEEDBACK TRANSFORMATIONS)
>     ====================================================================
> 
>     For the transformations that generate Webhelp pages allowing user
>     comments (webhelp-feedback) the database with the user comments must
>     be configured. This is done by opening the following file in a Web
>     browser and following the installation instructions from this file:
> 
>     [DITA-map-base-dir]/out/[transtype]/oxygen-webhelp/resources/installation.html
> 
> 
>     OTHER PARAMETERS OF WEBHELP TRANSFORMATION
>     ===========================================
> 
>     The Webhelp parameters that can be appended to the command line that
>     runs the Webhelp transformation:
> 
>       -Dwebhelp.copyright (text string value) - The copyright note that
>     will be added in the footer of the Table of Contents frame (the left
>     side frame of the WebHelp output).
> 
>       -Dwebhelp.footer.include (possible values: 'yes', 'no') - If set
>     to 'no' no footer is added to the Webhelp pages. If set to 'yes' and
>     the webhelp.footer.file parameter has a value, then the content of
>     that file is used as footer in each Webhelp output page. If
>     webhelp.footer.file has no value then the default Oxygen footer is
>     inserted in each Webhelp page.
> 
>       -Dwebhelp.footer.file (file path of XHTML file) - Specifies the
>     location of a well-formed XHTML file containing your custom footer
>     for the document body. Corresponds to XSLT parameter
>     WEBHELP_FOOTER_FILE. The fragment must be well-formed XHTML, with a
>     single root element. Common practice is to place all content into a
>     <div>.
> 
>       -Dwebhelp.product.id <http://Dwebhelp.product.id> (text string
>     value, required for the transformations with user feedback) - A
>     short name for the documentation target (product). All user comments
>     that will be posted in the Webhelp output pages and will be added in
>     the comments database on the server will be bound to this product
>     ID. Examples: 'mobile-phone-user-guide', 'hvac-installation-guide',
>     etc. Documentation for multiple products can be deployed on the same
>     server.
> 
>       -Dwebhelp.product.version (text string value, required for the
>     transformations with user feedback) - The documentation version
>     number, for example: 1.0, 2.5, etc. New user comments are bound to
>     this version. Multiple documentation versions can be deployed on the
>     same server.
> 
> 
>     Other DITA-OT parameters that are needed for a customization of the
>     Webhelp transformation can be appended to the above command line
>     following the model of the -D parameters like
>     'args.hide.parent.link' and 'args.xhtml.classattr'. For example the
>     'args.hdr' parameter can be appended in the form:
> 
>     "-Dargs.hdr=/path/to/directory/of/header-file.html"
> 
>     where [dir-of-header-file] will be replaced with the path of the
>     directory containing the header file.



More information about the oXygen-user mailing list