Project files, absolute paths and Oxygen publishing templates?

[raybiss]

Hi,
I recently started to learn how to use project files and although it looks promising, I'm facing a couple of issues.
Everything works fine when I target "html5" or "pdf2" in the default folders but fail in other cases.

How should I set absolute paths to parameters "output.dir", "dita.temp.dir", "webhelp.publishing.template", ...?

This is the form that gets me further in the publishing process...
<param name="webhelp.publishing.template" path="file://D:/publishing_templates/sky_one"/>

Then I get this error:
Error: The publishing template package does not exist. Resource is: \\D\publishing_templates/sky_one

Also, what would be the @transtype for "DITA Map PDF - based on HTML5 & CSS"?

Is there any other resource on how to use project files with the Oxygen publishing engine (WebHelp and PDF)?

This would make a nice webinar!

Regards,
Raymond

[Costin]

Hi Raymond,

It is not very clear for us what exactly are you trying to use - an Oxygen project (.xpr), or a DITA project file? We need to clarify this first, in order to provide you accurate information.

Regards,
Costin

[raybiss]

Hi Costin,
I'm trying to use a DITA-OT project file that will target Oxygen Publishing Templates (WebHelp responsive and PDF via CSS).
I also have issues targeting an absolute output folder, regardless of the transtype.
My output folder should be an absolute path and other parameters should also be absolute paths (like the publishing template location).

Example 1 - Webhelp responsive

Code: Select all

<publication id="pub_id" transtype="webhelp-responsive">
    <param name="webhelp.publishing.template" path="file://D:/OneDrive/dita_oxy_pub_templates/sky_one"/>
  </publication>

I tried many formats, with and without protocol, "/" and "\", also tried @href, @path and @value attributes without success.
In the example above, if I use any variation with "\", I get a java.net.URISyntaxException error: Illegal character in opaque part or Illegal character in authority at index...
This version gets me much further

Code: Select all

<param name="webhelp.publishing.template" path="file://D:/OneDrive/dita_oxy_pub_templates/sky_one"/>

But I still get: Error: The publishing template package does not exist. Resource is: \\D\OneDrive\dita_oxy_pub_templates\sky_one
I also tried appending the "sky_one.opt" file name but it did not work.

Example 2 - HTML 5 (reverting to HTML 5 to illustrate output folder problem)

Code: Select all

  <deliverable>
    <context name="Main Map">
      <input href="main.ditamap"/>
    </context>
    <output href="./main_map"/>
    <publication transtype="html5">
      <param name="output.dir" path="file://D:/dita_output"/>
    </publication>
  </deliverable>

I think this should create the output in "D:\dita_output\main_map\" but it still outputs in ${cf}/out/main_map
If I'm not using the "file://" prefix, I get the "opaque part" error...
How can I target an absolute path for the "output.dir"?
The deliverable/output/@href should become a child of output.dir or I'm interpreting something wrong.

I found the transtype for "DITA Map PDF - based on HTML5 & CSS". It is "pdf-css-html5"!

I'm running the project file with Oxygen 24.1 using the "oxygen-publishing-engine-3.x" (Oxygen 24.0, OT 3.6.1)

Sorry for the long post. Hoping my issues are clearer now.

Regards,
Raymond

[chrispitude]

Hi Raymond,

I think the output.dir parameter issue is a current limitation of DITA-OT project file publishing (not specific to Oxygen). The DITA-OT expects the base output directory to be specified on the command line:

Code: Select all

dita --project project.xml --output dita_output

which then yields the desired result:

Code: Select all

$ ls dita_output/main_map/
commonltr.css  commonrtl.css  index.html  topic.html

You can do the same thing in Oxygen by customizing the DITA-OT project file transformation and specifying your desired base output directory using the option:

image.png

Are you familiar with how to do this?

Also, I filed a DITA-OT issue to improve the behavior for output.dir parameter definitions:

3913: In DITA-OT project files, do not quietly ignore an output.dir <param> definition
https://github.com/dita-ot/dita-ot/issues/3913

[chrispitude]

For your webhelp.publishing.template issue, try specifying the path with @value instead of @path, with no prefix:

Code: Select all

<param name="webhelp.publishing.template" value="D:/OneDrive/dita_oxy_pub_templates/sky_one"/>
                                     <!-- ^^^^^ -->

There are three ways to pass parameter values:

• @href: resolved using project file as a base directory into an absolute URI
• @path: resolved using project file as a base directory into an absolute system path
• @value: passed as-is as a string value

which I learned from a reply in this DITA-OT pull request:

#3907: Add param to publication ref element
https://github.com/dita-ot/dita-ot/pull/3907

And in this case, I think the webhelp.publishing.template parameter expects a simple path string, with no URI/URL prefix.

[raybiss]

Hi Chris,
It's working fine with the additional.args parameter set to -verbose -output=D:\dita_output\tutoriels\out
Which outputs in the sub folder specified by <deliverable><output href="./map01"/>
I cannot add -temp=D:\dita_output\tutoriels\temp because it does not create a sub folder for the temporary files.
Since I need to keep the temp files for some reason, I also need to specify individual temp folder like this.

Code: Select all

    <publication transtype="webhelp-responsive">
      <param name="dita.temp.dir" value="D:/dita_output/tutoriels/temp/map01"/>
      ...
      <param name="clean.temp" value="no"/>
    </publication>

What should be the template parameter for transtype="pdf-css-html5"?
The equivalent to "webhelp.publishing.template" but for "pdf-css-html5".

Thanks for all the support you're providing.

Regards,
Raymond

[raybiss]

The last issue I'm facing (for now) is with a custom HTML plugin I have.
This plugin is working fine when used on a DITA map from Oxygen but fails when used from a project file.
It's failing in the first Ant target that uses a Trax transform... This is what the target looks like.

Code: Select all

    <target name="formedia-assesment-html-add-properties">
        <dirname property="input.dir" file="${args.input}"/>
        <property name="formedia.assesment.html.dir" value="${dita.plugin.ca.formedia.assesment.html.dir}"/>
        <property name="prop-output-filename" value="_map_properties.xml"/>
        <property name="prop-output-filepath" value="${output.dir}${file.separator}${prop-output-filename}"/>

        <!-- setup catalog  -->
        <xmlcatalog id="dita.catalog">
            <catalogpath>
                <fileset dir="${dita.dir}" includes="**/catalog.xml"/>
                <fileset dir="${dita.dir}" includes="**/catalog-dita.xml"/>
            </catalogpath>
        </xmlcatalog>

        <!-- transform -->
        <xslt processor="trax" style="${formedia.assesment.html.dir}${file.separator}xsl${file.separator}map_properties.xsl" in="${args.input}" out="${prop-output-filepath}">
            <xmlcatalog refid="dita.catalog"/>
        </xslt>
        <xmlproperty file="${prop-output-filepath}"/>
    </target>

The error I'm getting is:

Code: Select all

     [exec] formedia-assesment-html-add-properties:
     [exec] Error: input file D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\file:\D:\GoogleDrive\b149-2020_web\dita_content\questions\b149-1_partie_01.fr.ditamap does not exist

Any idea how I could solve this one?

Regards,
Raymond

[Radu]

Hi,

The DITA OT has its own "pipeline" custom task with an "xslt" module, maybe you should try to make this change to the build file, replace the existing <xslt> task call with:

Code: Select all

		<pipeline message="process" taskname="process">
				<xslt style="${formedia.assesment.html.dir}${file.separator}xsl${file.separator}map_properties.xsl" in="${args.input}" out="${prop-output-filepath}">
				            <xmlcatalog refid="dita.catalog"/>
				        </xslt>
		</pipeline>

Regards,
Radu

[raybiss]

Thanks Radu,
I wIll try this later today...
One last question, buried in an earlier reply.
What should be the template parameter for transtype="pdf-css-html5"?
The equivalent to "webhelp.publishing.template" but for "pdf-css-html5".
Regards,
Raymond

[julien_lacour]

Hello Raymond,

The equivalent for "webhelp.publishing.template" is "pdf.publishing.template".
I also leave here an example using both output and template absolute path:

Code: Select all

<project xmlns="https://www.dita-ot.org/project">
  <context name="Flowers" id="flowers">
    <input href="flowers.ditamap"/>
  </context>

  <deliverable name="Flowers to WebHelp" id="flowers-wh">
    <context idref="flowers"/>
    <output href="file:/D:/path/to/out/wh"/>
    <publication transtype="webhelp-responsive">
      <param name="webhelp.publishing.template" href="file:/D:/oxygen-24.1/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.webhelp.responsive/templates/ashes"/>
    </publication>
  </deliverable>

  <deliverable name="Flowers to PDF" id="flowers-pdf">
    <context idref="flowers"/>
    <output href="file:/D:/path/to/out/pdf"/>
    <publication transtype="pdf-css-html5">
      <param name="pdf.publishing.template" href="file:/D:/oxygen-24.1/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.webhelp.responsive/templates/ashes"/>
    </publication>
  </deliverable>
</project>

Regards,
Julien

[raybiss]

Thank you Julien! I might get back about a custom parameter but it basically works.

What did not work is replacing :

Code: Select all

<xslt processor="trax" style="${formedia.assesment.html.dir}${file.separator}xsl${file.separator}map_properties.xsl" in="${args.input}" out="${prop-output-filepath}">
            <xmlcatalog refid="dita.catalog"/>
        </xslt>

with :

Code: Select all

<pipeline message="process" taskname="process">
            <xslt style="${formedia.assesment.html.dir}${file.separator}xsl${file.separator}map_properties.xsl" in="${args.input}" out="${prop-output-filepath}">
                <xmlcatalog refid="dita.catalog"/>
            </xslt>
        </pipeline>

which resulted in this error when I run my usual publishing scenario, not through the project file!

Code: Select all

D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\plugins\org.dita.base\build.xml:29: The following error occurred while executing this line:
D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\plugins\org.dita.base\build_preprocess.xml:217: java.lang.RuntimeException: Failed to compile stylesheet 'D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\plugins\org.dita.base\xsl\preprocess\mapref.xsl': Malformed URL plugin:org.dita.base:xsl/preprocess/maprefImpl.xsl(base file:/D:/OneDrive/dita_ot/oxygen-publishing-engine-3.x/plugins/org.dita.base/xsl/preprocess/mapref.xsl)
	at org.dita.dost.module.MaprefModule.init(MaprefModule.java:53)
	<snip/>
	at org.apache.tools.ant.launch.Launcher.main(Launcher.java:101)
Caused by: net.sf.saxon.s9api.SaxonApiException: Malformed URL plugin:org.dita.base:xsl/preprocess/maprefImpl.xsl(base file:/D:/OneDrive/dita_ot/oxygen-publishing-engine-3.x/plugins/org.dita.base/xsl/preprocess/mapref.xsl)
	at net.sf.saxon.s9api.XsltCompiler.compile(XsltCompiler.java:793)
	at org.dita.dost.module.MaprefModule.init(MaprefModule.java:51)

If I try to run it through the project file, I also get a couple of error messages.

Code: Select all

     [exec] formedia-assesment-html-add-properties:
     [exec] XML utils not found from Ant project reference
     [exec] Store not found from Ant project reference
     [exec]   [process] Loading stylesheet D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\plugins\ca.formedia.assesment.html\xsl\map_properties.xsl
     [exec]   [process] Failed to transform document: Failed to transform document: I/O error reported by XML parser processing file:/D:/OneDrive/dita_ot/oxygen-publishing-engine-3.x/file:/D:/GoogleDrive/b149-2020_web/dita_content/questions/b149-1_partie_01.fr.ditamap: D:\OneDrive\dita_ot\oxygen-publishing-engine-3.x\file:\D:\GoogleDrive\b149-2020_web\dita_content\questions\b149-1_partie_01.fr.ditamap (The filename, directory name, or volume label syntax is incorrect)
    

Any idea on what I could try next?

Regards,
Raymond

[Radu]

Hi Raymond,

Using the <pipeline> custom ANT task with the embedded <xslt> task should work, I do not fully understand how you customized the DITA Open Toolkit, you seem to have your own build file with a custom XSLT stylesheet, usuallly the "dita.catalog" xml catalog is defined like this in the base DITA OT build files:

Code: Select all

  <xmlcatalog id="dita.catalog">
    <catalogpath path="${dita.plugin.org.dita.base.dir}/catalog-dita.xml"/>
  </xmlcatalog>

and can be referenced as it is from the build targerts, but you seem to re-define it in your build file.
It's hard to understand and debug DITA OT customizations or plugins based on small snippets of content. Also this is not part of our technical support policy, it's like buying a car and modifying its engine.
If you can put together a small sample project containing a very small DITA project, your customization and precise steps to set it up and run it you could zip the project, upload it to our tech support form:
https://www.oxygenxml.com/techSupport.html
and we could try to see if we can find time to debug this on our side.

Regards,
Radu

[raybiss]

Hi Radu,

I understand the policy and appreciate your offer to have a look at it.
This is an HTML plugin that simply runs a target to generate the header and footer files before setting "args.hdr" and "args.ftr" in another (init) target.
This approach was shown to me by Bob Thomas in the context of a pdf2 plugin, but I needed to add the <xmlcatalog> element when I tried to apply the same method to an HTML plugin.
The way I’m doing it was suggested in this forum a while ago. I’m not that familiar with Ant, the inner OT working and have not yet looked in detail at the base build file.
I will try to create a trimmed down version of the plugin that shows the issue in the next few days.

Thank you,
Raymond

[chrispitude]

Hi Raymond,

DITA-OT 3.7.2 (when released) will warn that the output.dir, transtype, args.input, and args.filter cannot be set with <param> in a project file, and must be set via other project file attributes/elements instead:

https://github.com/dita-ot/dita-ot/issues/3913

https://github.com/dita-ot/dita-ot/pull/3915

- Chris

[julien_lacour]

Hello Raymond,

One possible solution is to create a temporary property (input.fragment) that converts the args.input into a path (removing the file:/ prefix from URI if the parameter is an URI):

Code: Select all

<target name="formedia-assesment-html-add-properties">
    <!--<basename property="input-filename" file="${args.input}"/>-->
    <dirname property="input.dir" file="${args.input}"/>
    
    <property name="formedia.assesment.html.dir" value="${dita.plugin.ca.formedia.assesment.html.dir}"/>
    <property name="prop-output-filename" value="_map_properties.xml"/>
    <property name="prop-output-filepath" value="${output.dir}${file.separator}${prop-output-filename}"/>
    
    <!-- filter "file:/" from args.input if present, empty if not -->
    <pathconvert property="input.fragment">
        <propertyresource name="args.input"/>
        <mapper type="regexp"
            from="file\:\/(.*)"
            to="\1"/>
    </pathconvert>
    
    <!-- get source ditamap from either input.fragment nor args.input -->
    <condition property="source.ditamap" value="${input.fragment}" else="${args.input}">
        <and>
            <isset property="input.fragment" />
            <not>
                <equals arg1="${input.fragment}" arg2=""/>
            </not>
        </and>
    </condition>
    
    <!-- transform -->
    <xslt processor="trax" style="${formedia.assesment.html.dir}${file.separator}xsl${file.separator}map_properties.xsl" in="${source.ditamap}" out="${prop-output-filepath}">
        <xmlcatalog classpath="">
            <xmlcatalog refid="dita.catalog"/>
        </xmlcatalog>
    </xslt>
    
    <xmlproperty file="${prop-output-filepath}"/>
</target>

With this process, everytime the source.ditamap property will start by the drive letter or the separator (if you're running on a Linux machine).

Regards,
Julien

[raybiss]

Thank you!
I'm now successfully using this solution in a couple of targets.
Regards,
Raymond