[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