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


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


Environment VariablesEnvironment Variables


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


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”?


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?


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…)


• 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?


• 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?


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?


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…)


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…)


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


ParametersParameters

Where to set them…


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


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


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

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

TroubleshootingTroubleshooting


Three ways to open Log File:

1. Select File > View Output Log

TroubleshootingTroubleshooting (continued…)(continued…)


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

cmd_always_open_log = yes



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

Note: setting cmd_always_open_log = yes enables this checkbox.



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



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

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



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


XMetaL Enhanced PDF via RenderX XEP and Acrobat Distiller


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


Thank you for attending!

Next “37 Minute” Webinar:

October 7, 2010

Watch for an announcement at

http://forums.xmetal.com

Q&AQ&A

dita open toolkit deployment with xmetal author enterprise 6

Technology