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.