Contradiction in Documentation

[JeffHendricks]

Hello,

I'm trying to write some customization for Oxygen Editor for PDF output. When googled I get this URL:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ation.html

But when I open the Customization directory out of the Oxygen install, you have a readme.txt that says this:

About fo/Customization
======================

This directory is where the custom files live that make up customized
versions of the OpenTopic publishing outputs. The FO publishing output
will look for certain files here to override the standard ones. Things
you can currently override include:

- Custom XSL via fo/xsl/custom.xsl, xhtml/xsl/custom.xsl and
fo/attrs/custom.xsl
- Font overrides via fo/font-mappings.xml
- Per-locale variable overrides via common/vars/[locale].xml
- I18N configuration via fo/i18n/[locale].xml
- Index configuration via fo/index/[locale].xml

When customizing any of these areas, modify the relevant file(s) in
fo/Customization. Then, to enable the changes in the publishing process,
you find the corresponding entry for each file you modified in
fo/Customization/catalog.xml. It should look like this:

<!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->

Remove the comment markers "!--" and "--" to enable the change:

<uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>

Your customization should now be enabled as part of the publishing process.

We have provided template files that you can start with throughout
this directory structure. These files end in the suffix ".orig" (for
example, "catalog.xml.orig"). To enable these files, make a copy of
them and remove the ".orig" suffix. For example, copy
"catalog.xml.orig" to "catalog.xml". You can then make modifications
to the copy.

The Fo output also provides a general configuration file called
"build.properties" that allows you to control the publishing process.
To modify these settings, copy "build.properties.orig" to
"build.properties" and then modify the relevant options.

What is the right way? Are you guys are the same page as the documentation for 16? Why are there 2 very different instructions to do the same thing? One is easier, one is spaghetti code.

Thanks for any direction
Jeff

[Radu]

Hi Jeff,

Please see some answers below:

Are you guys are the same page as the documentation for 16?

The documentation page which you have already found in our user's manual:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ation.html

should work (if you follow it step by step) with the DITA Open Toolkit included in an Oxygen 16.0 distribution.
The online documentation page is more task oriented, it describes what a PDF XSLT customization can be made by trying to achieve the goal of customizing the front matter page of the PDF.

Why are there 2 very different instructions to do the same thing?

Each Oxygen installation comes with a DITA Open Toolkit distribution. The DITA Open Toolkit is an open source engine which is used by Oxygen to produce output (PDF, XHTML, etc) from DITA content.
The "readme.txt" you found in the Customization folder is part of the DITA Open Toolkit distribution, it was not written by us.

One is easier, one is spaghetti code.

Maybe we could try to change the online documentation and break the existing topic in two parts, an overview of the PDF customization and a small goal-oriented task which describes how a frontmatter can be customized. Would you consider this a better alternative to what we currently have?

There is also a book called DITA For Print:

http://xmlpress.net/publications/dita/dita-for-print/

which should explain a lot more things about PDF customization.

Regards,
Radu