Export Oxygen transformation scenario to a command

[AnnetteSo]

Hi, after setting up an Oxygen transformation scenario, how do you export that scenario to a command that you can run on the command line using Oxygen publishing engine, for automation purposes etc?

[chrispitude]

Hi Annette,

If you are using PDF Chemistry and/or Webhelp, you could take a look at Oxygen publishing templates:

Oxygen Publishing Templates

Creating a Publishing Template to Customize WebHelp and PDF Output using CSS

Publishing templates allow you to capture many different aspects of these transformations, including some that you cannot configure from DITA-OT command-line parameters.

When our writers want to interactively publish their content in Oxygen, they use transformations defined in our Oxygen project that reference the publishing templates:

image.png

image.png

To perform the final publishing in an automated way, we invoke the Oxygen Publishing Engine with these same publishing templates:

Code: Select all

dita \
  --input map.ditamap \
  --format pdf-css-html5 \
  -Dpdf.publishing.template.descriptor synopsys-pdf.opt
dita \
  --input map.ditamap \
  --format webhelp-responsive \
  -Dpdf.publishing.template.descriptor synopsys-webhelp.opt

This provides the following advantages:

• Automation - We can build scripts around Oxygen Publishing Engine to obtain content from revision control, summarize key transformation warning/error messages, check transformation success, build CI/CD pipelines, etc.
• Platform independence - Writers publish with Oxygen on their Windows 10 laptops, but we publish with Oxygen Publishing Engine in a linux environment.
• Consistency - We can be confident that the production-published content matches the interactively-published content.
• Maintenance - When we update a publishing template, both publishing environments reflect the change.

Another useful tool is DITA-OT project files, a DITA Open Toolkit feature that allows you to further automate how the DITA-OT is invoked to run transformations:

DITA-OT - Using Project Files

DITA-OT project files can be used for all DITA-OT transformation types, not just PDF Chemistry and/or Webhelp.

You can see some examples of how my company uses DITA-OT project files in the following Oxygen blog post (the preprocessing is temporary until DITA-OT 4.0 is released):

Oxygen Blog - Preprocessing DITA-OT Project Files

Publishing templates and DITA-OT project files work very well together. For example, we configure our DITA-OT project file publications to use the Oxygen publishing templates:

Code: Select all

  <!-- review PDF -->
  <publication id="pub-pdf-review" transtype="pdf-css-html5">
    <profile>
      <ditaval href="../_warehouse/_ditaval/filter_pdf.ditaval"/>
      <ditaval href="../_warehouse/_ditaval/flag_review.ditaval"/>
    </profile>
    <param name="args.draft" value="yes"/>
    <param name="pdf.publishing.template" href="../_common/_template"/>
    <param name="pdf.publishing.template.descriptor" value="synopsys-pdf.opt"/>
  </publication>

  <!-- final PDF -->
  <publication id="pub-pdf-final" transtype="pdf-css-html5">
    <profile>
      <ditaval href="../_warehouse/_ditaval/filter_pdf.ditaval"/>
      <ditaval href="../_warehouse/_ditaval/flag_final.ditaval"/>
    </profile>
    <param name="args.draft" value="no"/>
    <param name="pdf.publishing.template" href="../_common/_template"/>
    <param name="pdf.publishing.template.descriptor" value="synopsys-pdf.opt"/>
  </publication>

  <!-- review OLH -->
  <publication id="pub-olh-review" transtype="webhelp-responsive">
    <profile>
      <ditaval href="../_warehouse/_ditaval/filter_olh.ditaval"/>
      <ditaval href="../_warehouse/_ditaval/flag_review.ditaval"/>
    </profile>
    <param name="args.draft" value="yes"/>
    <param name="webhelp.publishing.template" href="../_common/_template"/>
    <param name="webhelp.publishing.template.descriptor" value="synopsys-webhelp.opt"/>
  </publication>

  <!-- final OLH -->
  <publication id="pub-olh-final" transtype="webhelp-responsive">
    <profile>
      <ditaval href="../_warehouse/_ditaval/filter_olh.ditaval"/>
      <ditaval href="../_warehouse/_ditaval/flag_final.ditaval"/>
    </profile>
    <param name="args.draft" value="no"/>
    <param name="webhelp.publishing.template" href="../_common/_template"/>
    <param name="webhelp.publishing.template.descriptor" value="synopsys-webhelp.opt"/>
  </publication>

then we configure our DITA-OT project file deliverables to use these publication definitions:

Code: Select all

   <!-- WebHelp deliverables -->
    <deliverable id="del-olh-final-pt" name="olh-final-pt">
        <context idref="context-olh_pt"/>
        <output href="final/olh_pt"/>
        <publication idref="pub-olh-final"/>
    </deliverable>

   <!-- PDF Chemistry deliverables -->
    <deliverable id="del-pdf-final-gca1" name="pdf-final-gca1">
        <context idref="context-gca1"/>
        <output href="final/olh_pt/pdf"/>
        <publication idref="pub-pdf-final"/>
    </deliverable>

and then we can publish these deliverables equally well from within Oxygen by clicking the Run Transformation buttons:

image.png

or from the command line with Oxygen Publishing Engine:

Code: Select all

dita --project project.xml --deliverable del-olh-final-pt
dita --project project.xml --deliverable del-pdf-final-gca1

Both the publishing templates and the DITA-OT project files are stored in our Git repository, so I can configure aspects of publishing centrally from the publishing templates (modify CSS, change DITA-OT parameters), the writers can configure details of their deliverables (add/remove maps or DITAVAL conditions), and all publishing (interactive and automated) inherits the changes immediately.