Different pdf Styles

[gcrews]

What would be the best way to go about making different pdf styles?  We need a custom pdf format for a project with different fonts, colors, front matter, page sizes and a bunch of other stuff.  I don’t want to change any of the current formatting of our pdf output but just want a different deliverable format.  The best point I see to branch is by changing the build.xml for the xmfo plug-in so it uses different customization catalog.xml files based on a parameter specified in the output configuration.  Is that the best way to go about modifying pdf output to have different styles of output?

[Derek Read]

I can tell you the best way to do this, but it is going to take me some time to write it up. Please give me a few days.

[Derek Read]

Update --> Looks like I'm a lot busier than I thought I would be. I hope to finish something soon.

[Derek Read]

RX_CUSTOM_DIR
This feature is not documented yet, but it is something our Professional Services team uses.

XMetaL Author Enterprise versions 5.1 and up support a parameter called RX_CUSTOM_DIR. You can use this to direct the product to use a specific folder to generate PDF output using the "XMetaL Enhanced PDF via RenderX XEP" deliverable type (only).

These directions are for 5.5 and 6.0 as these versions actually deploy the DITA OT to your %appdata% folder in order to be per-user friendly (details about DITA OT deployment: http://forums.XMetaL.com/index.php/topic,237.0.html).

These directions have been tested with XMetaL Author Enterprise 6.0.0.122.

1. Copy the following folder in its entirety to a new folder at the same level:
C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\Customization

Example:
C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\MyCustomization

If you do not have permission to access that folder you will need to gain it. This type of configuration (all instructions herein) assumes you are an admin-type that will ultimately be deploying your changes to other machines for other users at your location (at which point you will also, temporarily, need admin access).

Note: If you opt to give the new folder a different name then adjust references to "MyCustomization" below accordingly.

2. Create a new "deliverable": Tools > Configure Output > Add {button}, then select "XMetaL Enhanced PDF via RenderX XEP", then click Continue {button}. Give the new deliverable a nice name like "My PDF" then click OK.

Note: If you opt to give the new deliverable a different name then adjust references to "My PDF" below accordingly.

3. Tools > Configure Output, then select "My PDF", click the Edit (button) and on the Advanced tab add the following "Other output parameter":
RX_CUSTOM_DIR = %DITA_OT_DIR%\demo\xmfo\MyCustomization

4. Tools > Configure Output > Advanced {tab}, in the textbox labeled "Other output parameters" increase the value for the following setting, which should already be present: cmd_dita_ot_per_user_version  =  1.

The new value should trigger XMetaL Author Enterprise to redeploy the DITA OT the next time you generate output. Then when output is generated the deployed copy will include your new "MyCustomization" folder (and any changes made to it). The deployed copy will be used to generate output.

Note: The first time you run through this process I would recommend NOT making any changes to the "MyCustomization" folder. This will allow you to confirm in step 5 (below) that it gives you identical output to the deliverable "XMetaL Enhanced PDF via RenderX XEP". After you confirm it is working then feel free to make changes. XSLT/XSLFO can be tricky to get right so adding that complexity to the mix before confirming that the rest of this config process has been done right is asking for trouble.

5. Generate output and select your "My PDF" deliverable from the list of deliverable types. Because of the value you changed in step 4 you will be asked if you want to redeploy the DITA OT. Answer "yes".

The first time you do this step it should give you the same PDF output as the standard "XMetaL Enhanced PDF via RenderX XEP" because it is using the same files to generate that output (your "MyCustomization" folder is an exact copy of the "Customization" folder).

If you successfully generate a PDF then continue. If not, check to see that you can generate output from the same map using "XMetaL Enhanced PDF via RenderX XEP". If that works, then start checking the previous steps in these instructions to see if you missed something.

6. Modify the XSLT/XSL-FO in the "MyCustomization" folder located in C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\MyCustomization as desired. Perhaps at first just make a simple change to colour paragraphs blue for example, then repeat steps 4 (redeploy) and 5 (generate). If titles are blue you made the right change to the right file and you should be able to continue styling things as you like. If you are already have a bunch of changes and are confident they work then of course you could just dump them in all at once and just do steps 4 and 5.

Repeat steps 4 thru 6 as necessary to modify and check your PDF output.

Note: If you will be making many changes and need to repeatedly test them by generating output you may wish to work directly on the copy of the DITA OT that is deployed to your own %appdata%\SoftQuad\XMetaL Shared\DITA_OT\demo\xmfo (see link to the per-user deployment topic at top of this post for more info). This allows you to skip the deployment step (step 4) during your XSLT/XSLFO development. However, before you "roll out" these changes (in a production environment and/or for multiple users) you would then copy this working folder back to C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo and from then on follow the deployment instructions.

More than One Extra "Style"
Repeat this entire process (create new but differently named "MyCustomization" folders) as necessary to obtain as many different PDF output "styles" as you require (step 1 above). Each one will then be associated with a different "deliverable type" (steps 2 and 3 above). You and any other authors with similarly configured machine can then simply choose a different "My PDF" deliverable when generating output after deployment (steps 4 and 5).

Deploying to Other Machines
Once you are happy with the output on your own machine you may deploy those changes to other machines running the same version of XMetaL Author Enterprise as follows:
1. From your machine copy the folder C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\MyCustomization to the other machine at the same location.
2. Perform step 2 from the previous section, but on the other machine.
3. Perform step 3 from the previous section, but on the other machine.

[gcrews]

Thank you so much for your help. I was thinking about making a copy of the customization folder and doing something similar.  I think I found out a solution that works similarly but is a little more complex. Since the main 2 files that I have had to edit (so far) have been the the custom attrs and xsl file, I found I can just have 2 different catalog files. I changed the build script slightly to check for a parameter of a catalog filename.  This way allows me to only have a few different files that can import/include a common set of changes from an xsl file and only have minimal code.  With having completely different customization folder sets may lead to lot of code duplication.  Down the line it would become hander and harder to make slight changes that have to affect every output format.  Additionally when there are Xmetal updates it would be easier to compare the file structure and migrate my changes to a newer version of the toolkit.

[IF]

Derek - I'm about to attemp this but before I do I wanted to double-check something.

I want to work on the copy that is deployed in %appdata%\SoftQuad\XMetaL Shared\DITA_OT\demo\xmfo

So for step 1, do I copy the folder
C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xmfo\Customization
to the same level?

or do I copy the folder
"C:\Documents and Settings\<user>\AppData\Roaming\SoftQuad\XMetaL Shared\DITA_OT\demo\xmfo\Customization"

Using XMetal 6.0

Thanks
Isabelle

[Su-Laine Yeo]

Good question. The %appdata% folder on your machine is C:\Documents and Settings\<user>\AppData\Roaming\. (If you type %appdata% into the address bar of a Windows folder and press Enter, it will take you there automagically.)