webhelp .properties file

[urbanrobots]

Hi,
I'm new to using the .properties file to set build parameters.

We're currently using DITA-OT 1.8 with Oxygen Webhelp v17, and I'm upgrading our publishing to DITA-OT 2.3.3 with Oxygen Webhelp v19. We have not needed to use .properties files in the past, but now I'd like to use them for testing.

Anyway, how do I specify the webhelp skin in a .properties file?

Here's an example of what I'm trying but that's unsuccessful...

Code: Select all

args.gen.task.lbl = YES

args.cssroot = ${args.input.dir}/css/

nav-toc = full

args.xhtml.toc = toc

generate.copy.outer = 3

Dfix.external.refs.com.oxygenxml = true

webhelp.skin.css = C:/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources/skins/Custom_Webskin.css

Thanks,
Nick

[alin]

Hello,

The rules for the properties file format match the ones specified in the JavaDoc documentation of the java.util.Properties class (please see the documentation of the load method: http://docs.oracle.com/javase/7/docs/ap ... tStream%29).

I do not see any problem in the way you specified the value for the webhelp.skin.css parameter (assuming that the file with that path exists on your local disk).
I have tried to specify a different skin for the WebHelp output using a similar setup and the skin set in the properties file did reflect in the output HTML pages.
Can you test using one of our predefined skins? For example use the Forest skin:

Code: Select all

webhelp.skin.css=C:/DITA-OT/plugins/com.oxygenxml.webhelp/predefined-skins/dita/forrest/skin.css

Here's an example of what I'm trying but that's unsuccessful...

What is the exact problem that you are facing? Does the transformation end with an error? Or, it finishes successfully but the the custom skin isn't applied?

As a side note, I have noticed that you are using the fix.external.refs.com.oxygenxml parameter. Do you have references in your DITA map that are outside the map's directory?

Dfix.external.refs.com.oxygenxml = true

The name of the parameter is prefixed with the "D" character which may come from the fact that, in the command line, you can set a property using the following syntax:

Code: Select all

-D<property-name>=<value>

However, please note that this parameter, takes effect only when the DITA OT transformation process is started from Oxygen XML Editor. If the DITA OT process is started from the command line the parameter is not supported (please see the parameter description in our User Guide: https://www.oxygenxml.com/doc/versions/ ... sic_output).

Regards,
Alin

[urbanrobots]

Hi Alin,
Thank you! This information is helpful. I was able to get the properties file working with paths by using double back quotes, like this:

Code: Select all

args.css = plugins\\com.oxygenxml.webhelp\\oxygen-webhelp\\resources\\fonts\\SourceSansPro.css

Indeed, I added the "D" as an experiment to see if that was the issue. We currently use generate.copy.outer = 2 in DITA-OT v1.7.5 to overcome the issues with file references outside of the ditamap folder hierarchy... however, this has been removed in DITA-OT 2.3.3... how do you suggest showing output if fix.external.refs.oxygenxml is unsupported when running the Oxygen Webhelp plugin from a standalone DITA-OT implementation? I have tried specifying 1 or 3 for generate.copy.outer in the properties file, but to no success.

Take care,
-Nick

[urbanrobots]

I see that the topics indeed render in the file hierarchy, but all links are broken.

[alin]

Hi Nick,

I see that the topics indeed render in the file hierarchy, but all links are broken.

The DITA-OT does not handle it well when references are outside the directory where the published DITA map is found. By default, it does not even copy the referenced topics to the output directory and this is why you are experiencing the broken links.

how do you suggest showing output if fix.external.refs.oxygenxml is unsupported when running the Oxygen Webhelp plugin from a standalone DITA-OT implementation?

We already have an issue registered on this matter. I have added your vote to it and increased its priority.

The only workaround I can think of for this use case is to create another DITA map that is located in a folder path above all referenced folders and reference from it the original DITA map. Then transform this DITA map instead.

Regards,
Alin

[urbanrobots]

boo...

Thanks anyway, Alin. Your feedback has been informative. It looks like we cannot use the standalone webhelp plugin.

[urbanrobots]

We'll stick with the v17 plugin in DITA-OT 1.7.5 instead of updating to v19 and DITA-OT 2.3.3. The responsive design looks pretty useful though.