dita open toolkit deployment with xmetal author enterprise 6

© 2010 JustSystems Inc.© 2010 JustSystems Inc.

in 37 minutes

Episode 12

DITA Open Toolkit Deploymentwith XMetaL Author Enterprise 6.0

Brought to you by XMetaL Technical Services

Derek Read, XMetaL Technical Support

© 2010 JustSystems Inc.

• Audience Knowledge Check

• Refresher: Windows Environment Variables

• Answer these questions about “deployment”:– What (Basic Deployment Logic), Why, Where, and When– Which DITA OT Do I Need to Modify?

• Useful Parameters, Troubleshooting

• DITA OT “Transtypes” & Plug-ins and XMetaL Plug-ins.

• Questions

AgendaAgenda

© 2010 JustSystems Inc.

You should be…

• Familiar with Windows XP, Vista or 7.

• Capable of using Windows Explorer.

• Familiar with generating output from DITA content using XMetaL Author Enterprise.

• Familiar with usage of Windows Environment Variables.

Audience Knowledge CheckAudience Knowledge Check

© 2010 JustSystems Inc.

Environment VariablesEnvironment Variables

© 2010 JustSystems Inc.

Environment Variables Environment Variables (continued…)(continued…)

© 2010 JustSystems Inc.

I define deployment to mean:

“All of the activities that make the

software (the DITA OT) available for use.”

What is “Deployment”?What is “Deployment”?

© 2010 JustSystems Inc.

Basic Requirements:• Microsoft’s Windows application installation compliance.

• Microsoft’s Windows application execution compliance.

• DITA Open Toolkit execution requirements.

Why “Deploy” the DITA OT?Why “Deploy” the DITA OT?

© 2010 JustSystems Inc.

Specifics (‘the facts’):• Windows applications installed in %ProgramFiles%.

• Applications (not “installers”) should not write to %ProgramFiles%.

• DITA OT writes to the location it is run from.

• Most user accounts cannot write to %ProgramFiles% (UAC).

• Multiple users can log into the same physical computer to run the application.

Deployment meets these combined requirements.

Why “Deploy” the DITA OT? Why “Deploy” the DITA OT? (continued…)(continued…)

© 2010 JustSystems Inc.

• Installed copy:%ProgramFiles%\Common Files\XMetaL Shared\DITA OT\

• Deployed copy:%AppData%\SoftQuad\XMetaL Shared\DITA OT\

• RenderX (folder at same level) is used by these deliverables:“Book via RenderX”

“XMetaL Enhanced PDF via RenderX”

“XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller”

• Saxon (folder at same level) is also required to be present.

Where is the DITA OT?Where is the DITA OT?

© 2010 JustSystems Inc.

• First time an author asks to generate output.

- or -

• First time an author configures output settings.

• Deployed if the expected DITA OT folder is not present.

• Configuration parameters force redeployment.

When is the DITA OT Deployed?When is the DITA OT Deployed?

© 2010 JustSystems Inc.

Two Basic Types:

• Developers / Administrators (XSLT / XSL-FO people or IT admins)

• DITA Content Authors (XMetaL Author Enterprise end users)

Which DITA OT Do I Modify?Which DITA OT Do I Modify?

© 2010 JustSystems Inc.

Developers / Admins:

• Modify XSLT / XSL-FO.

• Cycle through modifying and testing / generating output.

• Distribute modified DITA OT to content authors (installations of XMetaL Author Enterprise).

• Use admin parameter named DITA_OT_BUILD_DIR = <path>1. DITA OT deployed to specified <path>.

2. Edit DITA OT in specified <path>.

3. Test run DITA OT from specified <path>.

4. Repeat steps 2 and 3 until done.

5. Copy to users machines or server.

Which DITA OT? Which DITA OT? (continued…)(continued…)

© 2010 JustSystems Inc.

Methods of Providing Modified Copies of DITA OT:

• Manually copy to each user’s “installed copy” of the DITA OT.

• Place DITA OT on shared drive and deploy to each user’s computer using DITA_OT_DIR

• Install and run DITA OT on a server as part of a CMS or other integration (no special support for this from XMetaL side, discuss

with an XMetaL partner or CMS vendor).

Which DITA OT? Which DITA OT? (continued…)(continued…)

© 2010 JustSystems Inc.

Basic Deployment LogicBasic Deployment Logic

Generate OutputGenerate Output

Deployment Parameter?Deployment Parameter?

Deploy theDITA OT

Deploy theDITA OT

EndEnd

Configure Output

Configure Output

DITA OTExists?DITA OTExists?

YesYes

YesYes

NoNo

NoNo

© 2010 JustSystems Inc.

ParametersParameters

Where to set them…

© 2010 JustSystems Inc.

Setting ResultDITA_OT_BUILD_DIR = <path>

e.g. DITA_OT_BUILD_DIR = C:\DITA_OT_TestBed

Meant for “admin” usage.

Location to create a deployable copy of the DITA OT in. Must have write permission to create folder. Automatically copies all needed folders: DITA_OT, RenderX and Saxon from installed copy of DITA OT. With this setting enabled the DITA OT will also run from this location (if run permissions are enabled).

Do not use to run from a server (except 1 person at a time) otherwise sharing violations will occur.

DITA_OT_DIR = <path>\DITA_OT

e.g. DITA_OT_DIR = M:\SharedFolder\DITA_OT

Specifies the location of the OT to deploy from. Default path is the “installed” copy. RenderX and Saxon folders are found relative to this location (same level). May be a network share. Should avoid many users at once to reduce sharing violations. OT runs on local machine after deployment.

cmd_dita_ot_per_user_version = # If # is larger than previous value forces OT redeployment.

cmd_dita_ot_per_user_version = disable Disables OT deployment.

Deployment ParametersDeployment Parameters

© 2010 JustSystems Inc.

Setting Resultcmd_always_open_log = yes Log file opens by default after generating output (“Open

the output log file” checkbox is checked).

cmd_synchro_mode = 2 Allows immediate return to editing in XMetaL Author Enterprise while OT generates output in a different detached thread.

Other Useful ParametersOther Useful Parameters

© 2010 JustSystems Inc.

The “Log File” includes:• Default and overridden settings.

• Paths, transtype, and other parameters passed to DITA OT.

TroubleshootingTroubleshooting

© 2010 JustSystems Inc.

Three ways to open Log File:

1. Select File > View Output Log

TroubleshootingTroubleshooting (continued…)(continued…)

© 2010 JustSystems Inc.

2. Set the following in Other output parameters on the Advanced tab in the Tools > Configure Output Options dialog:

cmd_always_open_log = yes

TroubleshootingTroubleshooting (continued…)(continued…)

© 2010 JustSystems Inc.

3. Enable the checkbox labeled “Open the output log file” after generating output.

Note: setting cmd_always_open_log = yes enables this checkbox.

TroubleshootingTroubleshooting (continued…)(continued…)

© 2010 JustSystems Inc.

XMetaL “Deliverable” transtype Path

Docbook docbook <DITA_OT>\xsl\map2docbook.xsl

Eclipse Content eclipsecontent <DITA_OT>\DITA_OT\xsl\map2eclipse.xsl<DITA_OT>\DITA_OT\xsl\map2plugin-cp.xsl

Eclipse Help eclipsehelp <DITA_OT>\DITA_OT\xsl\map2eclipse.xsl<DITA_OT>\DITA_OT\xsl\map2plugin.xsl

HTML Help (CHM) htmlhelp <DITA_OT>\xsl\map2hhp.xsl<DITA_OT>\xsl\map2hhc.xsl

Java Help javahelp <DITA_OT>\xsl\map2javahelptoc.xsl<DITA_OT>\xsl\map2javahelpmap.xsl<DITA_OT>\xsl\map2javahelpset.xsl

PDF via FO with default processing

pdf <DITA_OT>\xsl\dita2fo-shell.xsl

Rich Text Format (RTF) wordrtf <DITA_OT>\xsl\dita2rtf.xsl

The Text Processor for Typesetters (troff)

troff <DITA_OT>\xsl\dita2troff-step1-shell.xsl<DITA_OT>\xsl\dita2troff-step2-shell.xsl

Multiple HTML files xhtml <DITA_OT>\xsl\dita2xhtml.xsl

DITA OT: Standard TranstypesDITA OT: Standard Transtypes

© 2010 JustSystems Inc.

XMetaL “Deliverable” transtype Path

Book via RenderX pdf2 <DITA_OT>\demo\fo\

DITA OT: Standard Plug-insDITA OT: Standard Plug-ins

© 2010 JustSystems Inc.

XMetaL “Deliverable” transtype Path

Single HTML file xhtmls <DITA_OT>\demo\xhtmls\

WebHelp webhelp <DITA_OT>\demo\webhelp\

XMetaL Enhanced PDF via Antenna House XSL Formatter

pdf3 <DITA_OT>\demo\xmfo\

XMetaL Enhanced PDF via RenderX XEP

pdf3 <DITA_OT>\demo\xmfo\

XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller

pdf3 <DITA_OT>\demo\xmfo\

DITA OT: XMetaL Plug-insDITA OT: XMetaL Plug-ins

© 2010 JustSystems Inc.

Thank you for attending!

Next “37 Minute” Webinar:

October 7, 2010

Watch for an announcement at

http://forums.xmetal.com

Q&AQ&A