Possibility to transform DocBook to PDF using Chemistry and HTML

[fsteimke]

Dear Oxygen Staff,
the XML with XSLT Transformation scenarios allow to add a FO-to-PDF transformation, which is applied to the output of the XSLT Transformation. It uses the FOP Processor. The XSLT transformation must produce XSL-FO. A popular use case is DocBooc with XSLT 1.0 Stylesheets. My feature Request is to add a similar HTML+CSS to PDF Transformation for transformations steps. It should use Oxygen Chemistry CSS as default processing engine. The XSLT Transformation must produce HTML in this case. A use case would be DocBook with xslTNG Stylesheets.

Up to now i have to define and apply two scenarios:

1. XML with XSLT Scenario to produce HTML
2. CSS to PDF (with chemistry) Scenario.

This is annoying, because there is an intermediate result, which should be ignored but may irritate users.

The requested feature would allow to define one scenario which would chain both steps, without any intermediate result visible for users.

Thanks, Frank Steimke

[julien_lacour]

Hello,

If I understand correctly your feature request is to add a "DocBook PDF - based on HTML5 & CSS" scenario similar to DITA Map PDF - based on HTML5 & CSS?

Have you tried to run directly Chemistry over your DocBook documents? The option is available when clicking New in the dialog.

image.png

Regards,
Julien

[fsteimke]

Hi Julien,
the "XML to PDF Transformation with CSS" uses the Oxygen PDF Chemistry processing engine to obtain PDF output by applying CSS styling to the edited XML document. It can't be applyied to DocBook Source files directly. In a first step, you have to transform DocBook Sources to (X)HTML. My feature request is to combine two steps in one transformation scenario.

A "DocBook PDF - based on HTML5 & CSS" scenario feels to be to restricted. I would suggest a more general approach which allows not only DocBook, but any "XML to PDF - based on HTML5 & CSS" as part of the Oxygen XML Editor product.

Your "XML transformation with XSLT" is the perfect way to start. It allows to apply a FO Processor to the transformation result. My feature request is to allow not only FO-Processor but a CSS Processor (Chemistry) instead. Please see the attached image (Oxygen in german, sorry). Alternavly, you could add something like "Apply XSLT Stylesheet first" to the "XML to PDF Transformation with CSS" scenario.

grafik.png

Thanks, Frank

[fsteimke]

Hi Julien,

your suggestion to run "XML to PDF Transformation with CSS" directly on DocBook sources does not work. See my (updated) post above.
Greetings, Frank

[julien_lacour]

Hi Franck,

I don't understand why you said "XML to PDF Transformation with CSS" directly on DocBook sources does not work"?
I successfully transformed samples\docbook\v5\photo-album.xml with this scenario:

photo-album.zip

In this example I've used a custom CSS stylesheet with:

Code: Select all

imagedata {
  max-width: 100%;
}

Regards,
Julien

[fsteimke]

Hi Julien,
it's true, you can convert very simple DocBook XML to PDF with CSS only, which is what your suggested solution does. And the sample photo-album.xml is simple enough, so that we don' t recognize the limitations.
But DocBook has so many features which cannot be supported with this approach:

• a cross reference to a section (let's say Installation in your sample) can be made with the <xref .../> element and should generate some text like "see section 2". This is not supported in the CSS solution.
• How would you generate a table of content?
• How would you generate text in foreign languages ("Kapitel 3" instead of "Chapter 3" when @xml:lang='de')?
• How could a Bibliography be supportet

DocBook is made for Books, and all these features (and a lot more) are supported by Stylesheets that transform the DoccBook source into XHTML,. They generate tables of content, they generate text for cross references, they make the bibliography and glossary and index and so on. You would apply CSS to the result of this transformation.

Please have a look at the DocBook Stylesheets shipped with Oxygen in frameworks/docbook/xsl

My feature wish is exactly this: first apply this stylesheet which supports these features, then apply CSS. In on transformation scenarion.

Greetings, Frank

[julien_lacour]

Hi Frank,

One solution could be to create a custom Ant scenario with the following build.xml file:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<project basedir="." default="docbook-pdf-css-html" xmlns:if="ant:if">
  <target name="docbook-pdf-css-html" description="DocBook to PDF using HTML and CSS"
    depends="init-properties, delete-files, docbook-html, html-pdf"/>

  <target name="init-properties" description="Initialize properties">
    <property name="extensions.dir" value="${docbook.xsl.dir}/extensions"/>
    <property name="html.xslt" value="${docbook.xsl.dir}/html/docbook_custom.xsl"/>

    <dirname property="input.dir" file="${input.path}"/>
    <basename property="input.file" file="${input.path}" suffix=".xml"/>
    <property name="output.html" value="${input.dir}/out/pdf-html/${input.file}.html"/>
    <property name="output.pdf" value="${input.dir}/out/pdf-html/${input.file}.pdf"/>
  </target>

  <target name="delete-files" description="Delete both HTML and PDF files">
    <delete file="${output.html}" verbose="true"/>
    <delete file="${output.pdf}" verbose="true"/>
  </target>

  <target name="docbook-html" description="DocBook to HTML">
    <path id="extensions">
      <file file="${saxon.path}"/>
      <fileset dir="${extensions.dir}">
        <include name="xslthl*.jar"/>
        <include name="saxon65.jar"/>
      </fileset>
    </path>

    <property name="xslt.classpath" refid="extensions"/>
    <echo>XSLT Classpath ${xslt.classpath}</echo>

    <xslt in="${input.path}" out="${output.html}" style="${html.xslt}" classpath="${xslt.classpath}">
      <factory name="com.icl.saxon.TransformerFactoryImpl"/>
      <param name="admon.graphics" expression="1"/>
      <param name="admon.graphics.extension" expression=".png"/>
      <param name="draft.mode" expression="no"/>
      <param name="highlight.source" expression="1"/>
      <param name="img.src.path" expression="../../"/>
    </xslt>
  </target>

  <target name="html-pdf" description="HTML to PDF using Chemistry">
    <echo>Using Oxygen PDF Chemistry ${chemistry.path}</echo>
    <echo>Processing ${output.html} to ${output.pdf}</echo>

    <exec executable="${chemistry.path}">
      <!-- Not necessary if JAVA_HOME environment variable is set. -->
      <env key="JAVA_HOME" value="${java.home}"/>

      <arg value="-licensekey-dir" if:set="license.dir"/>
      <arg value="${license.dir}" if:set="license.dir"/>
      <arg value="-css"/>
      <arg value="${css.path}"/>
      <arg value="-in"/>
      <arg value="${output.html}"/>
      <arg value="-out"/>
      <arg value="${output.pdf}"/>
      <!--<arg value="-dump-styled-content"/>-->
      <!--<arg value="-dump-fo"/>-->
    </exec>
  </target>
</project>

Here is an example of scenario with the parameters it needs to work:

scenario.png

The parameters values are the following:

• chemistry.path must be oxygenChemistry.bat or chemistry.bat
• css.path must point to your custom CSS stylesheet
• docbook.xsl.dir must point to a DocBook XSL instance (there's one in [OXYGEN_INSTALL_DIR]\frameworks\docbook\xsl but you could use an external one)
• input.path must be set to the input DocBook file
• license.dir must be set to the directory containing the licensekey.txt file (if you are running the build.xml file from command line only - it will use Oxygen's license if not)

Regards,
Julien