DITA Open Toolkit 2 - documentation.help · The DITA Open Toolkit (DITA-OT) is an open-source...

DITAOpenToolkit2.0ThisdocumentdescribestheDITAOpenToolkitproject—whattheprojectis,andhowtousethesite.

WhatistheDITAOpenToolkit?

TheDITAOpenToolkit,orDITA-OTforshort,isasetofJava-based,opensourcetoolsthatprovideprocessingforDITAmapsandtopiccontent.YoucandownloadtheOTandinstallitforfreeonyourcomputertogetstartedwithtopic-basedwritingandpublishing.TheDITA-OTislicensedundertheCPL1.0andApache2.0opensourcelicenses.

Note:WhiletheDITAStandarditselfisownedanddevelopedbyOASIS,theDITAOpenToolkitisanindependent,opensourceimplementationofthestandard.

Keyoutputformatsforthetoolkitinclude:

PDF(formerlyknownasPDF2)

ODT(OpenDocumentFormat)

EclipseHelp

TocJS(XHTMLwithaJavaScriptframeset)

HTMLHelp

JavaHelp

EclipseContent(normalizedDITAplusEclipseprojectfiles)

WordRTF(withsomelimitations)

Docbook

Toolkitdocumentation

Therearetwoprimarysourcesfordocumentationaboutthetoolkit.

Stabledocumentationabouttoolkitusage,parameters,andprojectmanagementcanbefoundonthispage,usingthenavigationpanelontheleft.

Newinformationaboutthelatesttoolkitbuilds,plansforthenextrelease,andotherchanginginformationcanbefoundontheDITA-OTlandingpageatthedita.xml.orgsite(linkbelow).Thatsitealsocontainsthereleasenotesforallupcomingandpreviousreleases.

RelatedconceptsDistributionpackages

RelatedinformationMainDITA-OTpageatdita.xml.orgProjectNewsforDITAOpenToolkit

ShortcutstoimportantinformationDITA-OTstablereleaseDITA-OTlatestdevelopmentbuild

GettingStartedwiththeDITAOpenToolkitTheGettingStartedGuideisdesignedtoprovideaguidedexplorationoftheDITAOpenToolkit.ItisgearedforanaudiencethathaslittleornoknowledgeofbuildscriptsorDITA-OTparameters.Itwalksthenoviceuserthroughinstallingthefull-easy-installversionofthetoolkitandrunningapromptedbuild.

1. Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.

2. RunningthedemobuildAfteryouinstallthefull-easy-installpackage,runthedemobuildtoseethetypeofoutputthatisproducedbytheDITAOpenToolkit.

3. BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.

Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.

Beforeyoubegin

EnsurethatyouhaveJavaJREorJDK,version7orlaterinstalled.

EnsurethatyouhaveHTMLHelpWorkshopinstalled,ifyouwanttogenerateHTMLHelp.

Procedure

1. Downloadthefull-easypackagefromSourceForge.

Operatingsystem Filename

LinuxorMacOSX

DITA-OT2.0.M3_full_easy_install_bin.tar.gz

Windows DITA-OT2.0.M3_full_easy_install_bin.zip

2. ExtractthecontentsofthepackagetothedirectorywhereyouwanttoinstalltheDITA-OT.

3. Runthestartcmdfilethatisapplicableforyouroperatingsystem.ThisdefinesthenecessaryenvironmentvariablesandopensaDOSpromptorterminalwindowinwhichyoucaninvokethetoolkit.Youcanusethewindowtorunasmanybuildsasyouwant;ifyouclosethewindow,youwillneedtoruntheapplicablestartcmdfileagain.

Parenttopic:GettingStartedwiththeDITAOpenToolkitNexttopic:Runningthedemobuild

RunningthedemobuildAfteryouinstallthefull-easy-installpackage,runthedemobuildtoseethetypeofoutputthatisproducedbytheDITAOpenToolkit.

Procedure

1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.

2. FromtheDITA-OTshell,enterthefollowingcommand:

ant-fbuild_demo.xml

Youreceivethefollowingprompt:

[echo]PleaseenterthefilenamefortheDITAmapthatyou

[echo]wanttobuildincludingthedirectorypath(ifany).

[echo]Thefilenamemusthavethe.ditamapextension.

[echo]Notethatrelativepathsthatclimb(..)arenotsupportedyet.

[echo]Tobuildthesample,pressreturnwithoutenteringanything.

[input]TheDITAmapfilename:[C:\DITA-OT2.0.M3\samples\hierarchy.ditamap]

3. PressEnter.Youreceivethefollowingprompt:

[echo]

[echo]Pleaseenterthenameoftheoutputdirectoryorpressreturn

[echo]toacceptthedefault.

[input]Theoutputdirectory(out):[out]

4. PressEnter.Youreceivethefollowingprompt:

[echo]Pleaseenterthetypeofoutputtogenerate.

[echo]Optionsinclude:eclipse,tocjs,htmlhelp,javahelp,pdf,orweb

[echo]Uselowercaseletters.

[echo]

[input]Theoutputtype:(eclipse,tocjs,htmlhelp,javahelp,pdf,[web],docbook)

5. PressEntertoacceptthedefaulttransformationtype:web.ThiswillbuildXHTMLfilesfromtheDITAsource.

Youreceivethefollowingprompt:

[echo]ReadytobuildC:\DITA-OT2.0.M3\samples\hierarchy.ditamap

[echo]forwebinout

[echo]

[input]Continue?(Y,[y],N,n)

6. PressYorytostarttheDITA-OTtransformation.TheDITA-OTlogsinformationtothecommand-promptorterminalwindow.Attheend,youseethefollowinginformation:

prompt.output:

[echo]

[echo]outputintheoutdirectory

[echo]

[echo]Beforerebuilding,pleasedeletetheoutputorthedirectory.

BUILDSUCCESSFULTotaltime:XminutesXseconds

7. Gototheout/directoryandopenthetoc.htmlfileinaWebbrowser.Figure1.XHTMLoutputforthesamplefiles

Results

TheDITA-OTtransformedthehierarchy.ditamapfile(locatedinthesamplesdirectory)toXHTML;itwrotetheoutputtotheout/directory.

Parenttopic:GettingStartedwiththeDITAOpenToolkitPrevioustopic:Installingthefull-easy-installpackageNexttopic:Buildingyourowncontentusingthedemobuild

BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.

Procedure

1. Ifnecessary,runthestartcmdfilethatisapplicableforyouroperatingsystem.Youdonotneedtorunthestartcmdfileifyoualreadyhaveacommand-promptorterminalwindowthatwasinvokedbythestartcmdfileopen.

2. FromtheDITA-OTshell,enterthefollowingcommand:

ant-fbuild_demo.xml

3. Whenprompted,typethenameofamap.YoumustspecifythepathfortheDITAmap.Youeithercanspecifyafullyqualifiedfilename,forexample,C:\DITA-OT1.6.M5\doc\userguide.ditamap,oryoucanspecifyarelativepath,forexample,doc\userguide.ditamap

4. Whenprompted,typethenameoftheoutputdirectory.

5. Whenprompted,typethevalueforthetransformationtype.

Ouputformat ValueDocbook docbookEclipsehelp eclipseHTMLhelp htmlhelpPDF pdfXHTML webXHTMLwithaJavaScriptframeset tocjs

6. Whenprompted,pressEntertostartthetransformation.

Results

TheDITA-OTgeneratesoutputforthespecifiedDITAcontent.Itrunsthetransformationthatyouspecified,andwritestheoutputtothedirectorythatyouspecified.

Whattodonext

ExploreinvokingtheDITA-OTfromeitherAntorthecommand-linetool.Thisenablesyoutospecifyawiderarrayofparametersthanthosesupportedbythedemobuild.

UsingAntorthecommand-linetool,youcanperformthefollowingtasks(andmore):

AddacustomCSSfiletothetransformation

Generatelabelsforthesectionsoftasktopics

Specifythatdraftcommentsareincludedintheoutput

Turnon"Relatedlink"sectionsinaPDFfile

Parenttopic:GettingStartedwiththeDITAOpenToolkitPrevioustopic:Runningthedemobuild

DITAOpenToolkitUserGuideTheDITAOpenToolkitUserGuideisdesignedtoprovidebasicinformationabouttheDITA-OT.Itisgearedforanaudiencethatneedsinformationaboutinstalling,running,andtroubleshootingthetoolkit.ItcontainsdocumentationoftheDITA-OTparameters;italsocontainsreleasenotesandinformationaboutwhatcomponentshavebeentested.

OverviewoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISDITAspecification,whichisdevelopedbytheOASISDITATechnicalCommittee.TheDITA-OTisasetofJava-based,open-sourcetoolsandAntscriptsthattransformDITAcontent(mapsandtopics)intodeliverableformats,includingEclipseHelp,HTMLHelp,JavaHelp,PDF,andXHTML.

InstallingtheDITAOpenToolkitYoucaninstalltheDITAOpenToolkit(DITA-OT)onLinux,MacOSX,andWindows.TheprocessforinstallingandsettinguptheDITA-OTdependsonthetypeofdistributionpackagethatyouselect.

PublishingDITAcontentYoucanuseeitherAntorthecommand-linetooltotransformDITAcontenttothevariousoutputformatsthataresupportedbytheDITAOpenToolkit(DITA-OT).

ExtendingtheDITAOpenToolkitPlug-inscanbeusedtoextendthefunctionalityandconfiguretheDITAOpenToolkit.

GlobalizingDITAcontentTheDITAstandardsupportscontentthatiswritteninortranslatedtoanylanguage.Ingeneral,theDITAOpenToolkit(DITA-OT)passescontentthroughtotheoutputformatunchanged.TheDITA-OTusesthevaluesforthe@xml:lang,@translate,and@dirattributesthataresetinthesourcecontenttoprovidesglobalizationsupport.

ErrormessagesandtroubleshootingThissectioncontainsinformationaboutproblemsthatyoumightencounterandhowtoresolvethem.

ReferenceThissectionisdesignedtohelpuserstolocateinformationeasilyandquickly.ItincludesdocumentationfortheDITAOpenToolkit(DITA-OT)parametersandconfigurationproperties.

OverviewoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISDITAspecification,whichisdevelopedbytheOASISDITATechnicalCommittee.TheDITA-OTisasetofJava-based,open-sourcetoolsandAntscriptsthattransformDITAcontent(mapsandtopics)intodeliverableformats,includingEclipseHelp,HTMLHelp,JavaHelp,PDF,andXHTML.

WhiletheDITAstandardisownedanddevelopedbyOASIS,theDITA-OTprojectisgovernedseparately;theDITA-OTisanindependent,open-sourceimplementationoftheDITAstandard.TheDITA-OTisavailablewithoutchargeandislicensedundertheCPL1.0andApache2.0open-sourcelicenses.

DITAOpenToolkitRelease2.0

DITA1.2SpecificationSupportDITAOpenToolkit2.0supportstheDITA1.2specification.Initialsupportforthisspecificationwasaddedinversion1.5ofthetoolkit;versions1.5.1and1.5.2containminormodificationstokeepupwiththelatestdrafts.ThespecificationitselfwasapprovedatapproximatelythesametimeasDITA-OT1.5.2,whichcontainedthefinalversionsoftheDTDandSchemas.DITA-OT1.6updatedtheDITA1.2XSDstoaddressminorerratainthestandard;theDTDsremainuptodate.

TestedplatformsandtoolsTheDITAOpenToolkit(DITA-OT)hasbeentestedagainstcertainversionsofAnt,ICUforJava,JDK,operatingsystems,XMLparsers,andXSLTprocessors.

Parenttopic:DITAOpenToolkitUserGuide

RelatedinformationCommonPublicLicense,version1.0ApacheLicense,version2.0

DITAOpenToolkitRelease2.0Parenttopic:OverviewoftheDITAOpenToolkit

GeneralEnhancementsandChanges

Migrationfrompreviousreleases

Issues

ThefollowingitemsareincludedinDITAOpenToolkitRelease2.0.IssuenumberscorrespondtothetrackingnumberintheGitHubissuestracker.

Featurerequests

#1192Empty<ul></ul>killsFOP(milestone1)

#1267PDFsupportforfigurelink/tablelink.style(milestone1)

#1347Issuewith"xsl/dita2xhtml.xsl"?(milestone1)

#1506Newcommandlinetool(milestone1)

#1507ConvertXSLTtoversion2.0(milestone1)

#1511UseIvyfordependencymanagement(milestone1)

#1522AddHTML5transtype(milestone1)

#1523ReduceHTML/XHTMLcodeduplication(milestone1)

#1524UseDITAVALforprintfiltering(milestone1)

#1548SupportRFC5147incoderef(milestone1)

#1561Combinechunkedtopiclistsintofullditatopiclist(milestone1)

#1569IndexcapabilitywithFOP(milestone1)

#1601ChangeoutputforrenderingasingletopictoPDF(milestone1)

#1602Addplug-ininstallationoperationtointegration(milestone1)

#1608imgshouldbeusedinsteadofembedinXHTMLoutputforallimagetypes(milestone1)

#1610FilteredcontentleadstototalfailofPDFrenderingduplicate(milestone1)

#1612UpdateAntto1.9.2(milestone1)

#1614antbuildshouldnotbailoutwhenfopdirectoryhasnolibfolder(milestone1)

#1616RemovelegacyPDFfromdefaultdistributions(milestone1)

#1509Removedeprecatedcode(inprogress)

#1649SupportDITA1.3linksyntax(milestone2)

#1644AddmoreHTMLentitiestofileentities.propertiesindost.jar(milestone2)

#1643Integratortaskconstructspropertyconstructswithplatform-dependentpathseparators(milestone2)

#1636SupportDITA1.3cascadeattribute(milestone2)

#1635ImplementDITA1.3profiling(milestone2)

#1631Processkeyrefsbeforeconref(milestone2)

#1673Removesupportforgenerate.copy.outer=2(milestone3)

#1671AddsupportforgeneratingbackcoveronPDF(milestone3)

#1667RemoveFrameMakerindexsyntaxsupport(milestone3)

#1512Alternativepreprocessingplug-in(inprogress)

#1544UseURIandFileinsteadofString(inprogress)

#1654AddDITA1.3divelement(inprogress)

#1652AddDITA1.3markupandxmldomainsupport(inprogress)

#1651AddnewDITA1.3highlightingelements(inprogress)

#1095EmptytagsresultininvalidHTML(milestone1)

#1239EssentiallyneedsXercesImpl(milestone1)

#1247EnablespecifyingMathMLfileasimage/@href(milestone1)

#1272chapternumberingconfusedwhenchaptersandpartsinbookmap(milestone1)

#1407"Ambiguousrulematch"inPDFprocessingXSLTwhen<imagemap>isusedintopic(milestone1)

#1421WarningswhenconvertingtoPDFwithXEP(milestone1)

#1462Supportfor<table>rowheaderinPDFoutput(milestone1)

#1486PDFtransformdoesnotapply@rowsepcorrectly(milestone1)

#1607Keyrefnotprocessedforpushedconrefs(milestone1)

#1620ODTpluginfailsduetomissinggetMax()(milestone2)

#1619Addvalidationforattributegeneralization(milestone2)

#1103DITA-OTdoesn'trewitelq/@href(milestone2)

#1668Fixtablecell@idand@headersattributes#1596(milestone3)

#1634XMLCatalogwhichhasaDOCTYPEdeclarationisnotproperlyparsedbyIntegratortask(milestone3)

#1596xreftotablecellofDITAsimpletabledoesnotresultincorrecttargetin<a>element(XHTMLoutput)(milestone3)

#1539TopicMergegeneratesmultipletopicentriesinthemergedmiddlefile.(milestone3)

#1231<screen>and<codebock>donotsupportallframeattributes(milestone3)

#1086metadatainancestormapnotinheritedbytopicsinchildmap(milestone3)

#1600Indirectreferencetokeyserasesonefile,causesfailures(inprogress)

DITA1.2SpecificationSupportDITAOpenToolkit2.0supportstheDITA1.2specification.Initialsupportforthisspecificationwasaddedinversion1.5ofthetoolkit;versions1.5.1and1.5.2containminormodificationstokeepupwiththelatestdrafts.ThespecificationitselfwasapprovedatapproximatelythesametimeasDITA-OT1.5.2,whichcontainedthefinalversionsoftheDTDandSchemas.DITA-OT1.6updatedtheDITA1.2XSDstoaddressminorerratainthestandard;theDTDsremainuptodate.

EarlierversionsoftheDITAOpenToolkitcontainedasubsetofthespecificationmaterial,includingdescriptionsofeachDITAelement.Thismaterialwasshippedinsource,CHMandPDFformat.Thiswaspossibleinpartbecauseversions1.0and1.1oftheDITASpecificationcontainedtwoseparatespecificationdocuments:oneforthearchitecturalspecification,andoneforthelanguagespecification.

InDITA1.2,eachofthesehasbeenconsiderablyexpanded,andthetwohavebeencombinedintoasingledocument.Theoveralldocumentismuchlarger,andincludingthesamesetofmaterialwoulddoublethesizeoftheDITA-OTpackage.Ratherthanincludethatmaterialinthepackage,we’veprovidedthelinksbelowtothelatestspecificationmaterial.

HighlightsofDITA1.2supportinthetoolkitinclude:

Processingsupportforallnewelementsandattributes

Linkredirectionandtextreplacementusingkeyref

Newprocessing-roleattributeinmapstoallowreferencestotopicsthatwillnotproduceoutputartifacts

Newconrefextensions,includingtheabilitytoreferencearangeofelements,topushcontentintoanothertopic,andtousekeysforresolvingaconrefattribute.

Theabilitytofiltercontentwithcontrolledvaluesandtaxonomies,

usingthenewSubjectSchemeMap

Processingsupportforbothdefaultversionsoftask(original,limitedtask,andthegeneraltaskwithfewerconstraintsonelementorder)

Acronymandabbreviationsupportwiththenew<abbreviated-form>element

Newlinkgroupingabilitiesavailablewithheadersinrelationshiptables

OASISSubcommitteespecializationsfromthelearningandmachineindustrydomains(notethatthecoretoolkitcontainsonlybasicprocessingsupportforthese,butcanbeextendedtoproducerelatedartifactssuchasSCORMmodules)

Tofinddetailedinformationaboutanyofthesefeatures,seethespecificationdocumentsatOASIS.TheDITAAdoptionTechnicalCommitteehasalsoproducedseveralpaperstodescribeindividualnewfeatures.Ingeneral,thewhitepapersaregearedmoretowardsDITAusersandauthors,whilethespecificationisgearedmoretowardstoolimplementors,thoughbothmaybeusefulforeitheraudience.TheDITAAdoptionpaperscanbefoundfromthatTC’smainwebpage.

Parenttopic:OverviewoftheDITAOpenToolkit

RelatedinformationDITA1.2Specification(XHTML)DITA1.2Specification(PDF)DITA1.2Specification(zipoftheDITAsource)DITA1.2Specification(zipoftheHTMLHelp)DITAAdoptionTechnicalCommitteeBuildingsubsetsofthespecification

TestedplatformsandtoolsTheDITAOpenToolkit(DITA-OT)hasbeentestedagainstcertainversionsofAnt,ICUforJava,JDK,operatingsystems,XMLparsers,andXSLTprocessors.

Application Testedversion

AntAnt1.7.1

Ant1.8.2—1.8.4,1.9.2

ICUforJavaICU4J3.4.4

ICU4J49.1

IBM1.6

OpenJDK1.7

Oracle1.6

Operatingsystem

MacOSX10.6—10.9

SLES10

WindowsXP

Windows7

XMLparserXerces2.9.0

Xerces2.11.0

XSLTprocessor

Saxon6.5

Saxon9

Saxon-B9.1

Saxon-PE/EE9.3

Parenttopic:OverviewoftheDITAOpenToolkit

InstallingtheDITAOpenToolkitYoucaninstalltheDITAOpenToolkit(DITA-OT)onLinux,MacOSX,andWindows.TheprocessforinstallingandsettinguptheDITA-OTdependsonthetypeofdistributionpackagethatyouselect.

DistributionpackagesTheDITAOpenToolkitisdistributedinfourpackages:minimal,standard,client,andfull-easy-install.ThesourcecodeisavailablebothasaGitrepositoryandaZIPfile.

PrerequisitesoftwareTheprerequisitesoftwarethattheDITA-OTrequiresdependsonthetypeofdistributionpackagethatyouintendtoinstallandthetypesoftransformationsthatyouwanttouse.

InstallingtheclientpackageForthesimplestinstallationexperience,installtheclientpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.

InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

DistributionpackagesTheDITAOpenToolkitisdistributedinfourpackages:minimal,standard,client,andfull-easy-install.ThesourcecodeisavailablebothasaGitrepositoryandaZIPfile.

Minimalpackage

Thispackageisdesignedforvendorsthatembedthetoolkitwithinaproduct.Itcontainsallofthecoreprocessingcode:CSSandXSLTfiles,Antbuildscripts,Javacode(dost.jar),resourcefiles,andtheOASISDITADTDsandSchemas.UsersneedtohavetheirownversionsofAntandotherlibraries;theyalsoneedtosetupenvironmentvariablesforeachlibrary.TheonlyexternalfilesthatareincludedaretheDTDsandSchemas,alongwiththefollowingopen-sourcelibraries:

ApacheCatalogResolver,version1.1

ApacheCommonsCodec,version1.8

ApacheXerces,version2.11.0

Theminimalpackagehasthefollowingfilenames:

DITA-OT2.0.M3_minimal_bin.zip

DITA-OT2.0.M3_minimal_bin.tar.gz

Standardpackage

Thispackageisdesignedforpeoplewhowantthecoretoolkitfunctionality,butwhoalreadyhavelocally-installedcopiesofAntandotherrequiredtools.Itcontainseverythingintheminimalpackage,plusdocumentation,democode(forexample,legacysupportfortheoldbookmap),sampleAntscripts,andsampleDITAfiles.Thestandardpackageincludesthefollowingopen-sourcelibraries:

Thestandardpackagehasthefollowingfilenames:

DITA-OT2.0.M3_standard_bin.zip

DITA-OT2.0.M3_standard_bin.tar.gz

Clientpackage

Thispackageisdesignedforuserswhowantthesimplestinstallationexperience.InadditiontothecoreDITA-OTcodeandtheexternallibrariesthatareintheminimalandstandardpackages,itcontainsApacheAntandFOP.TheclientpackagealsocontainsscriptsforaguideddemooftheDITA-OT.Theclientpackageincludesthefollowingexternallibraries:

ApacheAnt,version1.9.2

ApacheFOP,version1.1

ICUforJava,version52.1

Saxon,version9.1.0.8

Theclientpackagehasthefollowingfilenames:

DITA-OT2.0.M3_client_bin.zip

DITA-OT2.0.M3_client_bin.tar.gz

Full-easy-installpackage

Thispackageisdesignedforuserswhowantthesimplestinstallationexperience.InadditiontothecoreDITA-OTcodeandtheexternallibrariesthatareintheminimalandstandardpackages,itcontainsApacheAntandFOP.Thefull-easy-installpackagealsocontainsbatchfilesdesignedtosetupabuildenvironmentusingthosetools,aswellasascriptsforaguideddemooftheDITA-OT.Thefull-easy-installpackageincludesthefollowingexternallibraries:

ApacheAnt,version1.9.2

ApacheFOP,version1.1

ICUforJava,version52.1

Saxon,version9.1.0.8

Thefull-easy-installpackagehasthefollowingfilenames:

DITA-OT2.0.M3_full_easy_install_bin.zip

Parenttopic:InstallingtheDITAOpenToolkit

RelatedinformationDITAOpenToolkitdistibutionpackagedownloadsDITAOpenToolkitsource

PrerequisitesoftwareTheprerequisitesoftwarethattheDITA-OTrequiresdependsonthetypeofdistributionpackagethatyouintendtoinstallandthetypesoftransformationsthatyouwanttouse.

SoftwarerequiredforcoreDITA-OTprocessing

TheDITA-OTrequiresthefollowingsoftwareapplications:

JREorJDK,version7orlater

ProvidesthebasicenvironmentfortheDITA-OT.YoucandownloadtheOracleJREorJDKfromhttp://www.oracle.com/technetwork/java/javase/downloads/index.htmlIfyouopttousethefull-easy-installpackage,thisistheonlyprerequisitesoftwarethatyouneedtoinstall.

Ant,version1.7.1orlater

Providesthestandardsetupandsequencingofprocessingsteps.YoucandownloadAntfromhttp://ant.apache.org/.

XSLTprocessor

Providesthemaintransformationservices.ItmustbecompliantwithXSLT2.0.TheDITA-OTistestedwithSaxon.YoucandownloadSaxon,version9.1.0.8fromhttp://saxon.sourceforge.net/.

Softwarerequiredforspecifictransformations

Dependingonthetypeofoutputthatyouwanttogenerate,youmightneedthefollowingapplications:

ICUforJava

ICUforJavaisacross-platform,Unicode-based,globalizationlibrary.Itincludessupportforcomparinglocale-sensitivestrings;formattingdates,times,numbers,currencies,andmessages;detectingtextboundaries;andconvertingcharactersets.YoucandownloadICUforJavafromhttp://www.icu-project.org/download/.

MicrosoftHelpWorkshop

RequiredforgeneratingHTMLhelp.YoucandownloadtheHelpWorkshopfromhttp://msdn.microsoft.com/en-us/library/windows/desktop/ms669985%28v=vs.85%29.aspx.

XSL-FOprocessor

RequiredforgeneratingPDFoutput.YoucandownloadFOPfromhttp://xmlgraphics.apache.org/fop/download.html;youalsocanuseAntennaHouseFormatterorRenderX.

SeeTestedplatformsandtoolsfordetailedinformationaboutversionsoftheprerequisiteapplicationsthathavebeentestedwiththecurrentDITA-OTrelease.

InstallingtheclientpackageForthesimplestinstallationexperience,installtheclientpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.

Beforeyoubegin

Procedure

1. DownloadtheclientpackagefromSourceForge.

LinuxorMacOSX

DITA-OT2.0.M3_client_bin.tar.gz

Windows DITA-OT2.0.M3_client_bin.zip

3. Optional:AddbindirectorytoPATHsystemvariable.Thisdefinesthenecessaryenvironmentvariabletoruntheditacommandfromthecommand-line.

Beforeyoubegin

Procedure

1. Downloadthefull-easypackagefromSourceForge.

LinuxorMacOSX

Windows DITA-OT2.0.M3_full_easy_install_bin.zip

3. Runthestartcmdfilethatisapplicableforyouroperatingsystem.ThisdefinesthenecessaryenvironmentvariablesandopensaDOSpromptorterminalwindowinwhichyoucaninvokethetoolkit.Youcanusethewindowtorunasmanybuildsasyouwant;ifyouclosethewindow,youwillneedtoruntheapplicablestartcmdfileagain.

InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

Beforeyoubegin

Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:

Javaruntimeenvironmentordevelopmentkit,version7orlater

XSLT2.0processor.YoucanuseSaxon,version9.1.0.8orlater.

Inaddition,determinethespecificDITA-OTtransformationsthatyouintendtosupportandensurethatyouhavetheprerequisitesoftwareinstalledforthem.

Formoreinformation,seePrerequisitesoftwareandTestedplatformsandtools.

Procedure

1. DownloadtheminimalorstandardpackagefromSourceForge.

Package FilenameMinimal DITA-OT2.0.M3_minimal_bin.tar.gz

StandardDITA-OT2.0.M3_standard_bin.tar.gz

Forproductionuse,werecommendthatyouusethelateststablerelease.

2. Extractthecontentsofthepackageintoaninstallationdirectory.

Note:Youcanextractthefileseithertoyourprivatehomedirectoryforyourexclusiveuseortothe/usr/local/share/directory,ifyouwanttosharetheDITA-OTwithotherusers.

3. VerifythattheJAVA_HOMEenvironmentvariableisset.

exportJAVA_HOME=<JRE_dir>

4. VerifythattheANT_HOMEenvironmentvariableisbeenset.

exportANT_HOME=<Ant_dir>

5. VerifythatthePATHenvironmentvariableincludestheJavaandAntexecutablefiles.

exportPATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH

6. SettheDITA_HOMEenvironmentvariabletopointtotheDITA-OTinstallationdirectory.

exportDITA_HOME=<DITA-OT_dir>

7. SetuptheCLASSPATHenvironmentvariable.

exportCLASSPATH=$DITA_HOME/lib/dost.jar:$CLASSPATH

exportCLASSPATH=$DITA_HOME/lib:$CLASSPATH

exportCLASSPATH=$DITA_HOME/lib/resolver.jar:$CLASSPATH

exportCLASSPATH=$DITA_HOME/lib/commons-codec-1.8.jar:$CLASSPATH

8. Optional:IfyouuseAnt,version1.8orlater,setuptheCLASSPATHenvironmentvariabletoincludeApacheXerces.

exportCLASSPATH=<xerces_dir>/xercesImpl.jar:<xerces_dir>/xml-apis.jar:$CLASSPATH

9. SetuptheXSLTprocessor:

SetuptheCLASSPATHenvironmentvariabletoincludetheSaxonJARfiles,forexample:

exportCLASSPATH=<saxon_dir>/saxon9.jar:<saxon_dir>/saxon9-dom.jar:$CLASSPATH

SetuptheANT_OPTSenvironmentvariable,forexample:

exportANT_OPTS=$ANT_OPTS-Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl

10. Optional:Forindexprocessing,setupICUforJava.exportCLASSPATH=<icu4j_dir>/icu4j.jar:$CLASSPATH

11. Optional:ForJavaHelp,settheJHHOMEenvironmentvariable.exportJHHOME=<javahelp_dir>

12. Optional:ForPDFoutput,setuptheXSL-FOprocessor:

ProcessorAction

AddtheFOPinstallationdirectorytothelocal.propertiesfileasthefop.homeproperty,forexample:

fop.home=/usr/share/java/fop

RenderX

AddtheRenderXinstallationdirectorytothelocal.propertiesfileasthexep.dirproperty,forexample:

xep.dir=/usr/share/java/xep

AntennaHouse

AddtheAHFormatterinstallationdirectorytothelocal.propertiesfileastheaxf.pathproperty,forexample:

axf.path=/usr/share/java/AHFormatterV6

13. TesttheDITA-OTinstallationbytransformingthesamplefiles.Thesamples\ant_sampledirectorycontainsAntscriptsdesignedtobuildvariousoutputformats.

/usr/local/share/DITA-OT2.0.M3$ant-fsamples/ant_sample/sample_all.xml

ThegeneratedoutputiswrittentotheDITA-dir\out\samplesdirectory.Thefollowingoutputformatsaregenerated:

Docbook

Eclipsehelp

HTMLHelp

JavaHelp

InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

Beforeyoubegin

Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:

Javaruntimeenvironmentordevelopmentkit,version7orlater

XSLT2.0processor.YoucanuseSaxon,version9.1.0.8orlater.

Inaddition,determinethespecificDITA-OTtransformationsthatyouintendtosupportandensurethatyouhavetheprerequisitesoftwareinstalledforthem.

Formoreinformation,seePrerequisitesoftwareandTestedplatformsandtools.

Procedure

1. DownloadtheminimalorstandardpackagefromSourceForge.

Package FilenameMinimal DITA-OT2.0.M3_minimal_bin.zip

StandardDITA-OT2.0.M3_standard_bin.zip

Forproductionuse,werecommendthatyouusethelateststablerelease.

2. Extractthecontentsofthepackageintoaninstallationdirectory.Forexample,C:\pkg\DITA-OT2.0.M3.

3. VerifythattheJAVA_HOMEenvironmentvariableisset.

setJAVA_HOME=<JRE_dir>

4. VerifythattheANT_HOMEenvironmentvariableisset.

setANT_HOME=<Ant_dir>

5. VerifythatthePATHenvironmentvariableincludestheJavaandAntexecutablefiles.

setPATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%

6. SettheDITA_HOMEenvironmentvariabletopointtotheDITA-OTinstallationdirectory.

setDITA_HOME=<DITA-OT_dir>

7. SetuptheCLASSPATHenvironmentvariable.

setCLASSPATH=%DITA_HOME%\lib\dost.jar;%CLASSPATH%

setCLASSPATH=%DITA_HOME%\lib;%CLASSPATH%

setCLASSPATH=%DITA_HOME%\lib\resolver.jar;%CLASSPATH%

setCLASSPATH=%DITA_HOME%\lib\commons-codec-1.8.jar;%CLASSPATH%

8. Optional:IfyouuseAnt,version1.8orlater,setuptheCLASSPATHenvironmentvariabletoincludeApacheXerces.

setCLASSPATH=<xerces_dir>\xercesImpl.jar;<xerces_dir>\xml-apis.jar;%CLASSPATH%

9. SetuptheXSLTprocessor:

SetuptheCLASSPATHenvironmentvariabletoincludetheSaxonJARfiles,forexample:

setCLASSPATH=<saxon_dir>\saxon9.jar;<saxon_dir>\saxon9-dom.jar;%CLASSPATH%

SetuptheANT_OPTSenvironmentvariable,forexample:

setANT_OPTS=%ANT_OPTS%-Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl

10. Optional:Forindexprocessing,setupICUforJava.setCLASSPATH=<icu4j_dir>\icu4j.jar;%CLASSPATH%

11. Optional:ForJavaHelp,settheJHHOMEenvironmentvariable.setJHHOME=<javahelp_dir>

12. Optional:ForHTMLHelp,addtheinstallationdirectoryfortheHTMLHelpWorkshoptothelocal.propertiesfileasthehhc.dirproperty.

hhc.dir=C:\\ProgramFiles(x86)\\HTMLHelpWorkshop

13. Optional:ForPDFoutput,setuptheXSL-FOprocessor:

ProcessorAction

AddtheFOPinstallationdirectorytothelocal.propertiesfileasthefop.homeproperty,forexample:

fop.home=C:\\ProgramFiles\\fop

AddtheRenderXinstallationdirectorytothe

RenderX local.propertiesfileasthexep.dirproperty,forexample:

xep.dir=C:\\ProgramFiles\\xep

AntennaHouse

AddtheAHFormatterinstallationdirectorytothelocal.propertiesfileastheaxf.pathproperty,forexample:

axf.path=C:\\ProgramFiles\\AHFormatterV6

14. TesttheDITA-OTinstallationbytransformingthesamplefiles.Thesamples\ant_sampledirectorycontainsAntscriptsdesignedtobuildvariousoutputformats.

C:\DITA-OT2.0.M3>ant-fsamples\ant_sample\sample_all.xml

ThegeneratedoutputiswrittentotheDITA-dir\out\samplesdirectory.Thefollowingoutputformatsaregenerated:

Docbook

Eclipsehelp

HTMLHelp

JavaHelp

PublishingDITAcontentYoucanuseeitherAntorthecommand-linetooltotransformDITAcontenttothevariousoutputformatsthataresupportedbytheDITAOpenToolkit(DITA-OT).

DITA-OTtransformationsTheDITAOpenToolkit(DITA-OT)shipswithseveralcoretransformations.EachcoretransformationrepresentsanimplementationofallprocessingthatisdefinedbyOASISintheDITAspecification.

PublishingDITAcontentwithditacommandDITA-OTincludesaditacommand-linetool.YoucaninvoketheDITA-OTfromthecommand-linetoolandgenerateoutput.

PublishingDITAcontentfromAntYoucanuseAnttoinvoketheDITAOpenToolkit(DITA-OT)andgenerateoutput.ThisisthemostrobustmethodoftransformingDITAcontent;youcanusethecompletesetofparametersthataresupportedbythetoolkit.

PublishingDITAcontentfromthecommand-linetoolTheDITAOpenToolkit(DITA-OT)includesacommand-linetooldesignedforuserswhoareunfamiliarwithAnt.YoucaninvoketheDITA-OTfromthecommand-linetoolandgenerateoutput.ThismethodislessrobustthanAnt.

DITA-OTtransformationsTheDITAOpenToolkit(DITA-OT)shipswithseveralcoretransformations.EachcoretransformationrepresentsanimplementationofallprocessingthatisdefinedbyOASISintheDITAspecification.

DITAtoDocbookThedocbooktransformationconvertsDITAmapsandtopicsintoaDocbookoutputfile.ComplexDITAmarkupmightnotbesupported,butthetransformationsupportsmostcommonDITAstructures.

DITAtoEclipseContentTheeclipsecontenttransformationgeneratesnormalizedDITAfilesandEclipsecontrolfiles.ItoriginallywasdesignedforanEclipseplug-inthatdynamicallyrenderedDITAcontent,buttheoutputfromthetransformationcanbeusedbyotherapplicationsthatworkwithDITA.

DITAtoEclipsehelpTheeclipsehelptransformationgeneratesXHTMLoutput,CSSfiles,andthecontrolfilesthatareneededforEclipsehelp.

DITAtoHTML5Thehtml5transformationgeneratesHTML5outputandatableofcontents(TOC)file.

DITAtoHTMLHelp(CHM)ThehtmlhelptransformationgeneratesHTMLoutput,CSSfiles,andthecontrolfilesthatareneededtoproduceaMicrosoftHTMLHelpfile.

DITAtoOpenDocumentTypeTheodttransformationproducesoutputfilesthatusetheOpenDocumentformat,whichisusedbytoolssuchasOpenOffice.

DITAtoPDF(PDF2)Thepdf(orpdf2)transformationgeneratesPDFoutput.

DITAtoRichTextFormatThewordrtftransformationproducesanRTFfileforusebyMicrosoftWord.

DITAtoTocJSThetocjstransformationgeneratesHTML5output,aframeset,andaJavaScript-basedtableofcontentswithexpandableandcollapsibleentries.ThetransformationwasoriginallycreatedbyShawnMcKenzieasaplug-inandwasaddedtothedefaultdistributioninDITAOT,release1.5.4.

DITAtoTroffThetrofftransformationproducesoutputforusewiththeTroffvieweronUnix-styleplatforms,particularlyforprogramssuchastheManpageviewer.

DITAtoXHTMLThexhtmltransformationgeneratesXHTMLoutputandatableofcontents(TOC)file.ThiswasthefirsttransformationcreatedfortheDITAOpenToolkit,anditisthebasisforalltheHTML-basedtransformations.

Parenttopic:PublishingDITAcontent

DITAtoDocbookThedocbooktransformationconvertsDITAmapsandtopicsintoaDocbookoutputfile.ComplexDITAmarkupmightnotbesupported,butthetransformationsupportsmostcommonDITAstructures.

Parenttopic:DITA-OTtransformations

DITAtoEclipseContentTheeclipsecontenttransformationgeneratesnormalizedDITAfilesandEclipsecontrolfiles.ItoriginallywasdesignedforanEclipseplug-inthatdynamicallyrenderedDITAcontent,buttheoutputfromthetransformationcanbeusedbyotherapplicationsthatworkwithDITA.

NormalizedDITAfileshavebeenthroughtheDITAOpenToolkitpre-processingoperation.IncomparisontothesourceDITAfiles,thenormalizedDITAfilearemodifiedinthefollowingways:

Map-basedlinks,suchasthosegeneratedbymaphierarchyandrelationshiptables,areaddedtothetopics.

Linktextisresolved.

AnyDTDorSchemareferenceisremoved.

ClassattributesthataredefaultedintheDTDorSchemaaremadeexplicitinthetopics.

Mapattributesthatcascadearemadeexplicitonchildelements.

ThenormalizedDITAfileshaveanextensionof.xml.

RelatedreferenceAntparameters:EclipsecontenttransformationCommand-linetoolparameters:Eclipsecontenttransformation

DITAtoEclipsehelpTheeclipsehelptransformationgeneratesXHTMLoutput,CSSfiles,andthecontrolfilesthatareneededforEclipsehelp.

InadditiontotheXHTMLoutputandCSSfiles,thistransformationreturnsthefollowingfiles,wheremapnameisthenameofthemasterDITAmap.

Filename Descriptionplugin.xml ControlfilefortheEclipseplug-inmapname.xml Tableofcontentsindex.xml Indexfileplugin.properties META-INF/MANIFEST.MF

RelatedreferenceAntparameters:EclipsehelptransformationCommand-linetoolparameters:Eclipsehelptransformation

RelatedinformationOfficialEclipseWebsite

DITAtoHTML5Thehtml5transformationgeneratesHTML5outputandatableofcontents(TOC)file.

TheHTML5outputisalwaysassociatedwiththedefaultDITA-OTCSSfile(commonltr.cssorcommonrtl.cssforright-to-leftlanguages).Youcanusetoolkitparameterstoaddacustomstylesheetstooverridethedefaultstyles.

ToruntheHTML5transformation,setthetranstypeparametertohtml5.

RelatedreferenceAntparameters:HTML5andXHTMLtransformationCommand-linetoolparameters:HTML5andXHTMLtransformation

DITAtoHTMLHelp(CHM)ThehtmlhelptransformationgeneratesHTMLoutput,CSSfiles,andthecontrolfilesthatareneededtoproduceaMicrosoftHTMLHelpfile.

InadditiontotheHTMLoutputandCSSfiles,thistransformationreturnsthefollowingfiles,wheremapnameisthenameofthemasterDITAmap.

Filename Descriptionmapname.hhc Tableofcontentsmapname.hhk Sortedindexmapname.hhp HTMLHelpprojectfile

mapname.chm

CompiledHTMLHelp

Note:ThisfileisgeneratedonlyiftheHTMLHelpWorkshopisinstalledonthebuildsystem.

RelatedreferenceAntparameters:HTMLHelptransformationCommand-linetoolparameters:HTMLhelptransformation

DITAtoOpenDocumentTypeTheodttransformationproducesoutputfilesthatusetheOpenDocumentformat,whichisusedbytoolssuchasOpenOffice.

ThistransformreturnsanODTdocument,whichisazipfilethatcontainstheODFXMLfile(content.xml),referencedimages,anddefaultstyling(inthefilestyles.xml).

RelatedreferenceAntparameters:ODTtransformationCommand-linetoolparameters:ODTtransformation

DITAtoPDF(PDF2)Thepdf(orpdf2)transformationgeneratesPDFoutput.

Thistransformationwasoriginallycreatedasaplug-inandmaintainedoutsideofthemaintoolkitcode.ItwascreatedasamorerobustalternativetothedemoPDFtransformationintheoriginaltoolkit,andthuswasknownasPDF2.Theplug-inwasbundledintothedefaulttoolkitdistributionwithrelease1.4.3.

RelatedreferenceAntparameters:PDFtransformationCommand-linetoolparameters:PDFtransformation

DITAtoRichTextFormatThewordrtftransformationproducesanRTFfileforusebyMicrosoftWord.

ThestructureofthegeneratedRTFfileisthesameasthenavigationstructureintheDITAmap.Toavoidlosingfilesinthefinaloutput,makesuretheDITAmapcontainsalltopicsthatarereferencedfromanyindividualtopics.

Thewordrtftransformationhasthefollowinglimitations:

Flagging,filtering,andrevisionbarsarenotsupported.

Styleattributesfortablesarenotsupported.

Tableswithinlistitemsarenotsupported.

OutputstylessupportedbyotherDITA-OTtransformations,forexample,XandY,arenotsupported.

DITAtoTocJSThetocjstransformationgeneratesHTML5output,aframeset,andaJavaScript-basedtableofcontentswithexpandableandcollapsibleentries.ThetransformationwasoriginallycreatedbyShawnMcKenzieasaplug-inandwasaddedtothedefaultdistributioninDITAOT,release1.5.4.

ThetocjstransformationwasupdatedsothatitproducesHTML5outputandusesadefaultframeset.Thistransformationalsowasaddedtothebuild_demo.xmlscriptasatransformation-typeoption.

DITAtoTroffThetrofftransformationproducesoutputforusewiththeTroffvieweronUnix-styleplatforms,particularlyforprogramssuchastheManpageviewer.

EachDITAtopicgenerallyproducesonetroffoutputfile.ThetrofftransformationsupportsmostcommonDITAstructures,butitdoesnotsupport<table>or<simpletable>elements.MosttestingoftroffoutputwasperformedusingtheCygwinLinuxemulator.

DITAtoXHTMLThexhtmltransformationgeneratesXHTMLoutputandatableofcontents(TOC)file.ThiswasthefirsttransformationcreatedfortheDITAOpenToolkit,anditisthebasisforalltheHTML-basedtransformations.

TheXHTMLoutputisalwaysassociatedwiththedefaultDITA-OTCSSfile(commonltr.cssorcommonrtl.cssforright-to-leftlanguages).Youcanusetoolkitparameterstoaddacustomstylesheetstooverridethedefaultstyles.

ToruntheXHTMLtransformation,setthetranstypeparametertoxhtml.Ifyouarerunningthedemobuild,specifywebratherthanxhtml.

RelatedreferenceAntparameters:HTML5andXHTMLtransformationCommand-linetoolparameters:HTML5andXHTMLtransformation

PublishingDITAcontentwithditacommandDITA-OTincludesaditacommand-linetool.YoucaninvoketheDITA-OTfromthecommand-linetoolandgenerateoutput.

BuildingoutputusingtheditacommandYoucaninvokeDITA-OTandbuildoutputusingtheditacommand.

Procedure

Fromthecommandprompt,issuethefollowingcommand:installation-directory\bin\dita-iinput-file-ftransformation-type

where:

input-fileistheDITAmaporDITAfilethatyouwanttoprocess.

transformation-typeisthetransformationtype.

parameter-nameisthenameofanoptionalparameter.

valueisanapplicablevaluefortheoptionalparameter.

Ifyouaddinstallation-directory\bindirectorytoPATHsystemvariable,youcaninvoketheditacommandwithouttheabsolutepath.

Ifyoudonotspecifyanoutputdirectory,bydefault,theDITA-OTwritestheoutputtooutsubdirectoryofcurrentdirectory.

Example

ThefollowingcommandgeneratesHTML5outputforthesequence.ditamapfileandspecifiestheoutputiswrittentothetestdirectory

dita-isamples/sequence.ditamap-otest-fhtml5

Parenttopic:PublishingDITAcontentwithditacommand

PublishingDITAcontentfromAntYoucanuseAnttoinvoketheDITAOpenToolkit(DITA-OT)andgenerateoutput.ThisisthemostrobustmethodoftransformingDITAcontent;youcanusethecompletesetofparametersthataresupportedbythetoolkit.

AntAntisaJava-based,open-sourcetoolthatisprovidedbytheApacheFoundation.Itcanbeusedtodeclareasequenceofbuildactions.Itiswellsuitedforbothdevelopmentanddocumentbuilds.Thefull-easy-installversionofthetoolkitshipswithacopyofAnt.

BuildingoutputusingAntYoucanbuildoutputbyrunningtheantcommandandspecifyingtheDITA-OTparametersatthecommandprompt.YoualsocanuseanAntbuildscripttoprovidetheDITA-OTparameters

CreatinganAntbuildscriptInsteadoftypingtheDITA-OTparametersatthecommandprompt,youmightwanttocreateanAntbuildscriptthatcontainsalloftheparameters.

RelatedconceptsAnt

RelatedreferenceAntparameters

AntAntisaJava-based,open-sourcetoolthatisprovidedbytheApacheFoundation.Itcanbeusedtodeclareasequenceofbuildactions.Itiswellsuitedforbothdevelopmentanddocumentbuilds.Thefull-easy-installversionofthetoolkitshipswithacopyofAnt.

TheDITA-OTusesAnttomanagetheXSLTscriptsthatareusedtoperformthevarioustransformation;italsousesAnttomanageintermediatestepsthatarewritteninJava.

ThemostimportantAntscriptisthebuild.xmlfile.Thisscriptdefinesandcombinescommonpre-processingandoutputtransformationroutines;italsodefinestheDITA-OTextensionpoints.

Parenttopic:PublishingDITAcontentfromAnt

RelatedtasksBuildingoutputusingAntCreatinganAntbuildscriptPublishingDITAcontentfromAnt

RelatedreferenceAntparametersApacheAntdocumentation

BuildingoutputusingAntYoucanbuildoutputbyrunningtheantcommandandspecifyingtheDITA-OTparametersatthecommandprompt.YoualsocanuseanAntbuildscripttoprovidetheDITA-OTparameters

Procedure

2. ToprovidetheDITA-OTparametersfromthecommandprompt,issuethefollowingcommand:

ant-Dargs.input=input-file-Dtranstype=transformation-type-D

where:

Ifyoudonotspecifyanoutputdirectory,bydefault,theDITA-OTwritestheoutputtotheinstallation-directory\outdirectory.

3. Ifyouuseabuildscript,issuethefollowingcommand:

ant-fbuild-scripttarget

where:

build-scriptisnameoftheAntbuildscript.

targetisanoptionalswitchthatspecifiesthenameoftheAnttargetthatyouwanttorun.Ifyoudonotspecifyatarget,thevalueofthe@defaultattributefortheAntprojectisused.

RelatedconceptsAnt

RelatedtasksCreatinganAntbuildscript

CreatinganAntbuildscriptInsteadoftypingtheDITA-OTparametersatthecommandprompt,youmightwanttocreateanAntbuildscriptthatcontainsalloftheparameters.

Procedure

1. CreateanXMLfilethatcontainsthefollowingcontent:

<?xmlversion="1.0"encoding="UTF-8"?>

<projectname="@project-name@"default="@default-target@"basedir=".">

<propertyname="dita.dir"location="@path-to-DITA-OT@"/>

<targetname="@target-name@">

<antantfile="${dita.dir}${file.separator}build.xml">

<propertyname="args.input"value="@DITA-input@"/>

<propertyname="transtype"value="html5"/>

</ant>

</target>

</project>

Youwillreplacetheplaceholdercontent(indicatedbythe@signs)withcontentapplicabletoyourenvironment.

2. Specifyprojectinformation:

1. Setthevalueofthe@nameattributetoX.

2. Setthevalueofthe@defaultattributetothenameofatargetinthebuildscript.Ifthebuildscriptisinvokedwithoutspecifyingatarget,thistargetwillberun.

3. Setthevalueofthedita.dirpropertytothelocationoftheDITA-OT.Thiscanbeafullyqualifiedpath,oryoucanspecifyitrelativetothelocationoftheAntbuildscriptthatyouarewriting.

4. CreatetheAnttarget:

1. Setthevalueofthe@nameattribute.

2. Specifythevaluefortheargs.inputproperty.

3. Specifythevalueofthetranstypeproperty.

5. Savethebuildscript.

Example

ThefollowingAntbuildscriptgeneratesCHMandPDFoutputfortheuserguide.ditamapfile.

<projectname="Toolkit-documentation"default="all"basedir=".">

<propertyname="dita.dir"location="C:\DITA-OT1.6.M5"/>

<targetname="all"description="buildCHMandPDF"depends="chm,pdf"/>

<targetname="chm"description="buildCHM">

<antantfile="${dita.dir}\build.xml">

<propertyname="args.input"value="C:\dita-ot\src\main\doc\userguide.ditamap"/>

<propertyname="args.gen.task.lbl"value="YES"/>

<propertyname="output.dir"value="C:\kje\temp\out"/>

<propertyname="transtype"value="htmlhelp"/>

</ant>

</target>

<targetname="pdf"description="buildPDF">

<antantfile="${dita.dir}\build.xml">

<propertyname="args.input"value="C:\dita-ot\src\main\doc\userguide.ditamap"/>

<propertyname="args.gen.task.lbl"value="YES"/>

<propertyname="args.rellinks"value="nofamily"/>

<propertyname="output.dir"value="C:\kje\temp\out"/>

<propertyname="transtype"value="pdf"/>

</ant>

</target>

</project>

Inadditiontothemandatoryparameters(args.inputandtranstype),thechmandpdftargetseachspecifysomeoptionalparameters:

Theargs.gen.task.lblpropertyissettoYES,whichensuresthatheadingsareautomaticallygeneratedforthesectionsoftasktopics.

Theoutput.dirpropertyspecifieswheretheDITAOTwritestheoutputofthetransformations.

ThepdftargetalsospecifiesthatrelatedlinksshouldbegeneratedinthePDF,butonlythoselinksthatarecreatedbyrelationshiptablesand<link>elements.

Finally,thealltargetsimplyspecifiesthatboththechmandpdftargetshouldberun.

Whattodonext

AnotherresourceforlearningaboutAntscriptsarethefilesinthesamples/ant_samplesdirectory.ThisdirectorycontainstheAntbuildfilesusedbythedemobuild,aswellastemplatesthatyoucanusetocreateAntscripts.

RelatedconceptsAnt

RelatedtasksBuildingoutputusingAnt

PublishingDITAcontentfromthecommand-linetoolTheDITAOpenToolkit(DITA-OT)includesacommand-linetooldesignedforuserswhoareunfamiliarwithAnt.YoucaninvoketheDITA-OTfromthecommand-linetoolandgenerateoutput.ThismethodislessrobustthanAnt.

Command-linetoolTheDITAOpenToolkit(DITA-OT)providesacommand-linetoolforuserswithlittleknowledgeofAnt.Thecommand-linetoolsupportsasubsetoftheparametersthatareavailabletotheAntbuilds.

Buildingoutputusingthecommand-linetoolIfyouareunfamiliarwithAnt,youcaninvoketheDITAOpenToolkit(DITA-OT)andbuildoutputfromthecommand-linetool.

RelatedconceptsCommand-linetool

RelatedreferenceCommand-linetoolparameters

Command-linetoolTheDITAOpenToolkit(DITA-OT)providesacommand-linetoolforuserswithlittleknowledgeofAnt.Thecommand-linetoolsupportsasubsetoftheparametersthatareavailabletotheAntbuilds.

Thecommand-linetoolisawrapperaroundtheAntinterface;ittakesthesimplifiedparametersasinput,convertsthemtoAntparameters,andthenrunsanAntbuild.TheAntparametersthatarepassedtotheDITA-OTaresavedtotheproperty.tempfilethatiswrittentotheoutputdirectory.

Forindividualbuilds,theadditionalJavaoverheadisminimal,butforrepeatedorserver-basedbuilds,theextramemoryusagemightbecomeanissue.ApplicationsthatembedthetoolkitshouldinvokeAntdirectly.

Parenttopic:PublishingDITAcontentfromthecommand-linetool

RelatedtasksBuildingoutputusingthecommand-linetoolPublishingDITAcontentfromthecommand-linetool

Buildingoutputusingthecommand-linetoolIfyouareunfamiliarwithAnt,youcaninvoketheDITAOpenToolkit(DITA-OT)andbuildoutputfromthecommand-linetool.

Procedure

2. Fromthecommandprompt,issuethefollowingcommand:

java-jarlib/dost.jar/i:input-file/transtype:transformation-type

where:

Ifyoudonotspecifyanoutputdirectory,bydefault,theDITA-OTwritestheoutputtotheinstallation-directory\outdirectory.

Example

ThefollowingcommandgeneratesHTML5outputforthesequence.ditamapfileandspecifiestheoutputiswrittentothetestdirectory

java-jarlib/dost.jar/i:samples/sequence.ditamap/outdir:test/transtype:html5

Parenttopic:PublishingDITAcontentfromthecommand-linetool

ExtendingtheDITAOpenToolkitPlug-inscanbeusedtoextendthefunctionalityandconfiguretheDITAOpenToolkit.

Installingplug-insPlug-insaredistributedaszipfilesandcanbeinstalledusingeitherthecommandlinetoolorAnt.

Removingplug-insPlug-inscanbeinstalledbyrunninguninstallationprocess.

Installingplug-insPlug-insaredistributedaszipfilesandcanbeinstalledusingeitherthecommandlinetoolorAnt.

Procedure

Runplug-ininstallationprocess.

Usingtheditacommandlinetool,runtheinstallationcommand:

dita-installplug-in-zip

UsingAnt,fromthetoolkitdirectoryruntheinstallationtarget:

ant-fintegrator.xmlinstall-Dplugin.file=plug-in-zip

Theplug-in-zipcanbeeitheralocalfilepathoraURL.

Parenttopic:ExtendingtheDITAOpenToolkit

Removingplug-insPlug-inscanbeinstalledbyrunninguninstallationprocess.

Procedure

Runplug-inuninstallationprocess.

Usingtheditacommandlinetool,runtheuninstallationcommand:

dita-uninstallplug-in-id

UsingAnt,fromthetoolkitdirectoryruntheuninstallationtarget:

ant-fintegrator.xmluninstall-Dplugin.id=plug-in-id

GlobalizingDITAcontentTheDITAstandardsupportscontentthatiswritteninortranslatedtoanylanguage.Ingeneral,theDITAOpenToolkit(DITA-OT)passescontentthroughtotheoutputformatunchanged.TheDITA-OTusesthevaluesforthe@xml:lang,@translate,and@dirattributesthataresetinthesourcecontenttoprovidesglobalizationsupport.

GlobalizationsupportofferedbytheDITA-OTTheDITAOpenToolkit(DITA-OT)offersglobalizationsupportinthefollowingareas:Generatedtext,indexsorting,andbi-directionaltext.

Supportedlanguages:HTML-basedtransformationsTheDITAOpenToolkit(DITA-OT)supportsover50languagesandlanguagevariantsfortheHTML-basedtransformations,forexample,EclipseHelp,HTMLHelp,andTocJS.

Supportedlanguages:PDFtransformationsTheDITAOpenToolkit(DITA-OT)supportsasmallersetoflanguagesforthePDF(pdf2)transformation.ThistransformationwasdonatedtotheDITA-OTprojectaftertheprojectinception,anditusesadifferentandlargersetofgeneratedtextthantheHTML-basedtransformations.

RelatedreferenceLocalizationoverviewintheOASISDITAstandard

GlobalizationsupportofferedbytheDITA-OTTheDITAOpenToolkit(DITA-OT)offersglobalizationsupportinthefollowingareas:Generatedtext,indexsorting,andbi-directionaltext.

Generatedtext

GeneratedtextistextthatisrenderedautomaticallyintheoutputthatisgeneratedbytheDITA-OT;thistextisnotlocatedintheDITAsourcefiles.Thefollowingareexamplesofgeneratedtext:

Theword"ChapterinaPDFfile.

Thephrases"Relatedconcepts,""Relatedtasks,"and"Relatedreference"inXHTMLoutput.

Indexsorting

TheDITA-OTcanuseonlyasinglelanguagetosortindexes.

Bi-directionaltext

TheDITA-OTcontainsstylesheets(CSSfiles)thatsupportbothleft-to-right(LTR)andright-to-left(RTL)languages.

WhentheDITA-OTgeneratesoutput,ittakesthefirstvalueforthe@xml:langattributethatitencounters,andthenitusesthatvaluetocreategeneratedtext,performindexsorting,anddeterminewhichdefaultCSSfileisused.Ifnovalueforthe@xml:langattributeisfound,thetoolkitdefaultstoUSEnglish.

Parenttopic:GlobalizingDITAcontent

Supportedlanguages:HTML-basedtransformationsTheDITAOpenToolkit(DITA-OT)supportsover50languagesandlanguagevariantsfortheHTML-basedtransformations,forexample,EclipseHelp,HTMLHelp,andTocJS.

Table1.Supportedlanguages:HTML-basedtransformations

Language LanguagecodeArabic arorar-egBelarusian beorbe-byBrazilianPortuguese pt-brBulgarian bgorbg-bgCatalan ca-esChinese(simplified) zh-cnorzh-hansChinese(traditional) zh-tworzh-hantCroatian hrorhr-hrCzech csorcs-czDanish daorda-dkDutch nlornl-nlDutch(Belgian) nl-beEnglish(US) enoren-usEnglish(British) en-gbEnglish(Canadian) en-caEstonian etoret-eeFinnish fiorfi-fiFrench frorfr-frFrench(Belgian) fr-beFrench(Canadian) fr-caFrench(Swiss) fr-chGerman deorde-deGerman(Swiss) de-chGreek elorel-grHebrew heorhe-il

Hindi hiorhi-hiHungarian huorhu-huIcelandic isoris-isIndonesian idorid-idItalian itorit-itItalian(Swiss) it-chJapanese jaorja-jpKazakh kkorkk-kzKorean koorko-krLatvian lvorlv-lvLithuanian ltorlt-ltMacedonian mkormk-mkMalay msorms-myNorwegian noorno-noPolish plorpl-plPortuguese ptorpt-ptRomanian roorro-roRussian ruorru-ruSerbian(Cyrillicscript) sr,sr-rs,orsr-spSerbian(Latinscript) sr-latn-rsSlovak skorsk-skSlovenian slorsl-siSpanish esores-esSpanish(LatinAmerican) es-419Swedish svorsv-seThai thorth-thTurkish trortr-trUkrainian ukoruk-uaUrdu urorur-pk

RelatedreferenceHowtoaddsupportfornewlanguagesinXHTML

Supportedlanguages:PDFtransformationsTheDITAOpenToolkit(DITA-OT)supportsasmallersetoflanguagesforthePDF(pdf2)transformation.ThistransformationwasdonatedtotheDITA-OTprojectaftertheprojectinception,anditusesadifferentandlargersetofgeneratedtextthantheHTML-basedtransformations.

Table1.Supportedlanguages:PDFtransformation

Language LanguagecodeChinese(simplified) zh-cnorzh-hansDutch nlornl-nlEnglish(US) enoren-usFinnish fiorfi-fiFrench frorfr-frGerman deorde-deHebrew heorhe-ilItalian itorit-itJapanese jaorja-jpRomanian roorro-roRussian ruorru-ruSlovenian slorsl-SISpanish esores-esSwedish svorsv-se

ErrormessagesandtroubleshootingThissectioncontainsinformationaboutproblemsthatyoumightencounterandhowtoresolvethem.

DITA-OTerrormessagesTheerrormessagesgeneratedbytheDITAOpenToolkitcontainamessageID,severityinformation,andmessagetext.Thistopiclistseacherrormessagegeneratedbythetoolkitandprovidesadditionalinformationthatmightbehelpfulinunderstandingandresolvingtheerrorcondition.

OthererrormessagesInadditiontoerrormessagesgeneratedbytheDITAOpenToolkit,youmightalsoencountererrormessagesgeneratedbyJavaorothertools.

LogfilesWhenyouruntheDITA-OT,keyinformationisloggedonthescreen.Thisinformationcanalsobewrittentoalogfile.Ifyouencounteraproblem,youcananalyzethisinformationtodeterminethesourceoftheproblemandthentakeactiontoresolveit.

Accessinghelpfromthecommand-linetoolYoucanaccessalistofsupportedparametersforthecommand-linetoolbyissuingthe-helpparameter.

DetermingtheversionoftheDITAOpenToolkitYoucanusethecommand-linetooltodeterminetheversionoftheDITAOT.

EnablingdebugmodeWhenthedebugmodeisenabled,additionaldiagnosticinformationiswrittentothelogfile.Thisinformation,whichincludesenvironmentvariablesandstacktracedata,canhelpyoudeterminetherootcauseofaproblem.

IncreasingJavamemoryallocation

Ifyouareworkingwithlargedocumentswithextensivemetadataorkeyreferences,youwillneedtoincreasethememoryallocationfortheJavaprocess.Youcandothisfromthecommand-linepromptforaspecificsession,oryoucanincreasethevalueoftheANT_OPTSenvironmentalvariable.

DITA-OTerrormessagesTheerrormessagesgeneratedbytheDITAOpenToolkitcontainamessageID,severityinformation,andmessagetext.Thistopiclistseacherrormessagegeneratedbythetoolkitandprovidesadditionalinformationthatmightbehelpfulinunderstandingandresolvingtheerrorcondition.

EachmessageIDiscomposedofamessageprefix,amessagenumber,andaletterthatindicatestheseverity(I,W,E,orF).Thetoolkitusesthefollowingseverityscale:

Informational(I)

Thetoolkitencounteredaconditionofwhichyoushouldbeaware.Forexample,draftcommentsareenabledandwillberenderedintheoutput.

Warning(W)

Thetoolkitencounteredaproblemthatshouldbecorrected.Processingwillcontinue,buttheoutputmightnotbeasexpected.

Error(E)

Thetoolkitencounteredamoresevereproblem,andtheoutputisaffected.Forexample,somecontentismissingorinvalid,orthecontentisnotrenderedintheoutput

Fatal(F)

Thetoolkitencounteredaseverecondition,processingstopped,andnooutputisgenerated.

MessageID Severity Messagetext Additionaldetails

"%1"isnotarecognizedtransformation

Defaulttransformationtypesthatshipwiththetoolkitincludexhtml,eclipsehelp,pdf(orpdf2),

DOTA001F Fataltype.Supportedtransformationtypesaredocbook,eclipsecontent,eclipsehelp,html5,htmlhelp,javahelp,net.sourceforge.dita-ot.html,odt,pdf,pdf2,tocjs,troff,wordrtf,xhtml.

tocjs,htmlhelp,javahelp,odt,eclipsecontent,troff,docbook,andwordrtf.transformationtypesmaybeavailableiftoolkitplug-insareinstalled.

DOTA002F Fatal Inputfileisnotspecified,orisspecifiedusingthewrongparameter.

Theinputparameterwasnotspecified,sothereisnoDITAorDITAMAPfiletotransform.Ensuretheparameterissetproperly;seeargumentsCommandlinetoolargumentsyouareunsurehowtospecifytheinputfile.

DOTA003F Fatal CannotfindtheuserspecifiedXSLTstylesheet'%1'.

AnalternatestylesheetwasspecifiedtoruninplaceofthedefaultXSLToutputprocess,butthatstylesheetcouldnotbeloaded.Pleasecorrecttheparametertospecifyavalidstylesheet.

DOTA004F Fatal InvalidDITAtopicextension'%1'.Supportedvaluesare'.dita'and'.xml'.

ThisoptionalparameterisusedtosetanextensionforDITAtopicdocumentsinthetemporaryprocessingdirectory.Only"dita",".dita","xml",or".xml"areallowed.

DOTA006WWarning

AbsolutepathsonthelocalfilesystemarenotsupportedfortheCSSPATHparameter.PleaseusearelativepathorfullURIinstead.

IftheCSSPATHusesanabsolutepath,itshouldbeonethatcanstillbeaccessedafterthefilesaremovedtoanothersystem(suchashttp://www.example.org/

Absolutepathsonthelocalfilesystemwillbebrokenifthecontentismovedtoanewsystem.

DOTA007E ErrorCannotfindtherunning-footerfile"%1".Pleasedoublecheckthevaluetoensureitisspecifiedcorrectly.

Therunningfooterfile,whichcontainscontenttobeaddedtothebottomofeachXHTMLoutputtopic,cannotbelocatedorread.Thisisusuallycausedbyatypointheparametervalue.Youshouldalsoensurethatthevalueisnotspecifiedwith"file:"asaprefix.

DOTA008E ErrorCannotfindtherunning-headerfile"%1".Pleasedoublecheckthevaluetoensureitisspecifiedcorrectly.

Therunningheaderfile,whichcontainscontenttobeaddedtothetopofeachXHTMLoutputtopic,cannotbelocatedorread.Thisisusuallycausedbyatypointheparametervalue.Youshouldalsoensurethatthevalueisnotspecifiedwith"file:"asaprefix.

DOTA009E ErrorCannotfindthespecifiedheadingfile"%1".Pleasedoublecheckthevaluetoensureitisspecifiedcorrectly.

Therunningheadingfile,whichcontainscontenttobeaddedtothe<head>sectionofeachXHTMLoutputtopic,cannotbelocatedorread.Thisisusuallycausedbyatypointheparametervalue.Youshouldalsoensurethatthevalueisnotspecifiedwith"file:"asaprefix.

DOTA011W WarningArgument"%1"isdeprecated.Thisargumentisnolongersupportedinthetoolkit.

DOTA012WWarning Argument"%1"isdeprecated.Pleaseusetheargument"%2"instead.

DOTA066F Fatal CannotfindtheuserspecifiedXSLTstylesheet'%1'.

AnalternatestylesheetwasspecifiedtoruninplaceofthedefaultXSL-FOoutputprocess,butthatstylesheetcouldnotbeloaded.Pleasecorrecttheparametertospecifyavalid

stylesheet.

DOTA067WWarning

Ignoringindex-see'%1'insideparentindexentry'%2'becausetheparentindextermcontainsindextermchildren.AccordingtotheDITASpecification,theindex-seeelementshouldbeignorediftheparentindextermcontainsotherindextermchildren.

Thisconditionisignored,asinstructedintheOASISDITAStandard.

DOTA068WWarning

Ignoringindex-see-also'%1'insideparentindexentry'%2'becausetheparentindextermcontainsindextermchildren.AccordingtotheDITASpecification,theindex-see-alsoelementshouldbeignorediftheparentindextermcontainsotherindextermchildren.

Thisconditionisignored,asinstructedintheOASISDITAStandard.

DOTA069F FatalInputfile'%1'cannotbelocatedorread.Ensurethatfilewasspecifiedproperlyandthatyouhavepermissiontoaccessit.

Pleaseensurethattheinputfilepathandfilenamewereenteredcorrectly.

DOTA069WWarningTarget"%1"isdeprecated.RemovereferencestothistargetfromyourcustomXSLTorplug-ins.

DOTJ001F Fatal

Invalidcommandlinesyntaxfortheparameter'%1'.Parameterstothecommandlinetoolshouldusethesyntax/parameter:value.

Seeparametersparametersandvalues.

DOTJ002F FatalUnsupportedparameter'%1'.PleaserefertotheDITA-OTUserGuideforsupportedparameters.

DOTJ003F Fatal

Parameter'%1'wasspecifiedwithoutavalue.Parameterstothecommandlinetoolshouldusethesyntax/parameter:value.

Thetransformwasunabletocreateatemporaryprocessingdirectory;thisisusuallycausedbyaccountcontrolsettingsthatpreventcreatingatemporarydirectoryinthespecified

DOTJ004F FatalCannotcreatetemporaryprocessingdirectory'%1'.Pleaseensurethatyouhavepermissiontocreatethedirectory'%1'.

location.Pleaseverifythatyouhavepermissiontowritetothedefaultlocation,orspecifyanalternatetemporarydirectorylocation.SeeargumentsCommandlinetoolargumentsfordetailsonhowtospecifythetemporarydirectory.

DOTJ005F FatalFailedtocreatenewinstancefor'%1'.Pleaseensurethat'%1'existsandthatyouhavepermissiontoaccessit.

DOTJ006F Fatal

AnAntbuildfileusedthefollowingillegalsyntaxwhencallingAntInvoker:extparam='%1'.PleasecorrectthecalltoAntInvokerwhendirectlycallingDITA-OTJavacodefromAnt;forexample,extparam="maplinks=XXXX;other=YYYY".

ThismessageoccurswhenanAntbuildcallsaDITA-OTpipelinemoduledirectlyinsteadofusingthedefaultcalltothatmodule.PleasecheckthatallparametersaresetcorrectlyinyourAntbuild.Thesyntaxforextparamis"name1=value1;name2=value2".

DOTJ007E ErrorDuplicateconditioninfilterfileforrule'%1'.Thefirstencounteredconditionwillbeused.

Ifaconditionisdefinedmorethanonce(suchassettingaudience="all"toinclude,thenresettingittoexclude),onlythefirstdefinitionwillbeused.

DOTJ009E Error

Cannotoverwritefile'%1'withfile'%2'.Themodifiedresultmaynotbeconsumedbythefollowingstepsinthetransformpipeline.Checktoseewhetherthefileislockedbysomeotherapplicationduringthetransformationprocess.

Thetransformwasunabletocreatefilesproperlyduringthetransform;resultsmaynotbeasexpected.

Thismessagemayindicateaninvalidinputfile(suchasaccidentallyspecifyingaPDFfileasinputratherthanaDITAmapfile),aninputfilethatuses

DOTJ012F Fatal Failedtoparsetheinputfile'%1'.TheXMLparserreportedthefollowingerror:

elementswhicharenotallowed,arenotpartoraDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.

DOTJ013E ErrorFailedtoparsethereferencedfile'%1'.TheXMLparserreportedthefollowingerror:

Thismessagemayindicateareferencetoaninvalidfile(suchasaccidentallyreferencingaPDForunknownXMLfileasifitwasDITA),areferencedfilethatuseselementswhicharenotallowed,orareferencedDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.

DOTJ014W Warning Foundanindextermelementwithnocontent.Settingthetermto***.

Anempty<indexterm>elementwasfound,andwillappearintheindexas***.Thisindextermshouldberemovedfromthesource.

DOTJ015F Fatal Logdirectorycannotbenull.Pleasespecifyavaliddirectoryforthebuildlog.

DOTJ016F Fatal Failedtocreatelogdirectory'%1'.Pleasespecifyavaliddirectoryforthebuildlog.

DOTJ017F Fatal Noinputfilewasspecified;failedtoinitializelognamebasedoninputfile.

Thetransformfailedbecausetheinputfilewasnotspecified;logfilenamesarebasedonthenameoftheinputfile,sonologcouldbegenerated.

DOTJ018I Informational

Logfile'%1'wasgeneratedsuccessfullyindirectory'%2'.Anymessagesfromthetransformationprocessareavailableinthelogfile;additionaldetailsabouteachmessageareavailableintheDITA-OTuserguide.

DOTJ020W Warning

Atleastoneplug-inin'%1'isrequiredbyplug-in'%2'.Plug-in'%2'cannotbeloaded.Checkandseewhetherallprerequisiteplug-insareinstalledintoolkit.

Thiswillappearwhenoneinstalledplug-inrequiresanotherinordertofunctioncorrectly,buttherequiredplug-inisnotfound.Theinstalledplug-inwillbeignored.

DOTJ021W Warning

File'%1'willnotgenerateoutputsinceitisinvalidorallofitscontenthasbeenfilteredoutbytheditavalfile.Pleasecheckthefile'%1'andtheditavalfiletoseeifthisistheintendedresult.

Thismayappeariffilterconditionsontherootelementofatopiccausetheentiretopictobefilteredout.Toremovethismessage,youcouldplaceanyfilterconditionsonthereferencetothisfile,whichwillpreventthebuildfromaccessingthisfile.

DOTJ022F Fatal

Failedtoparsetheinputfile'%1'becauseallofitscontenthasbeenfilteredout.Thiswillhappeniftheinputfilehasfilterconditionsontherootelement,andaditavalexcludesallcontentbasedonthoseconditions.

Eithertheinputfileortheditavalfileshouldchange,otherwiseyourbuildisexplicitlyexcludingallcontent.

DOTJ023E Error Failedtogetthespecifiedimagefile'%1',soitwillnotbeincludedwithyouroutput.

Checkwhethertheimageexistsinthesourcelocationoralreadyexistsintheoutputdirectory.Thismessageshouldonlyappearinthefollowingcases:

DOTJ025E Error

Theinputtothe"topicmerge"transformprocesscouldnotbefound.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.

DOTJ026E Error

The"topicmerge"didnotgenerateanyoutput.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.

ThismessageshouldonlyappearifanAntbuildorplug-inisdirectlycallingthetoolkit'stopicmergemodule,orifearliererrorsresultedinproblemswithsomeofthecontent.Ifthetopicmergemoduleiscalledcorrectly,thenthisindicatesaprogramerrorthatshouldbereportedtotheDITA-OTdevelopmentteam,atbugandfeaturetracker

DOTJ028E Error

Noformatattributewasfoundonareferencetofile'%1',whichdoesnotappeartobeaDITAfile.Ifthisisnota

Whenreferencinganon-DITAfile,theformatattributeshouldindicatethetypeoffilereferenced(suchas"html"forHTMLtopicsor"pdf"forPDF

DITAfile,settheformatattributetoanappropriatevalue,otherwisesettheformatattributeto"dita".

files).Otherwise,thetransformmayattempttoparsethereferenceddocumentasaDITAtopic.

No'domains'attributewasfoundforelement'<%1>'.ThisgenerallyindicatesthatyourDTDorSchemawasnotdevelopedproperlyaccordingtotheDITAspecification.

ThedomainsattributeisusedinspecializedDITAdocumentstohelpdeterminewhichdomainelementsarelegal.ThismessagewillonlyappearifDITAspecializationwasnotdefinedproperly.

No'class'attributeforwasfoundforelement'<%1>'.ThisgenerallyindicatesthatyourDTDorSchemawasnotdevelopedproperlyaccordingtotheDITAspecification.

AllspecializedDITAelementsmustdefineaclassattributetoprovideancestryinformation.ThismessagewillonlyappearaspecializedDITAelementdidnotdefineaclassattribute.

Nospecifiedrulefor'%1'wasfoundintheditavalfile.Thisvaluewillusethedefaultaction,oraparentpropactionifspecified.Toremovethismessage,youcanspecifyarulefor'%1'intheditavalfile.

Thisinformationalmessageisintendedtohelpyoucatchfilterconditionsthatmayhavebeenspecifiedimproperly;ifthevalueiscorrect,noactionisneeded.

DOTJ033E ErrorNovalidcontentisfoundintopicref'%1'duringchunkprocessing.Pleasespecifyanexistingandvalidtopicforthetopicref.

DOTJ034F Fatal

Failedtoparsetheinputfile'%1'(thecontentofthefileisnotvalid).Iftheinputfile'%1'doesnothaveaDOCTYPEdeclaration,pleasemakesurethatallclassattributesarepresentinthefile.

DITAprocessingisbasedonclassattributesdefinedforeveryelement.UsuallythesearedefaultedintheDTDorSchema;ifnoDTDorSchemaisused,theclassattributesmustbeexplicitlyincludedinthemaportopic.

Thefile"%1"referencedby"%2"is

Thisoutsidethescopeofthemap;forexample,ifthemaininputmapreferences

DOTJ035F Fatal

outsidethescopeoftheinputdita/mapdirectory.Ifyouwanttolowertheseveritylevel,pleaseusetheAntparameter'outer.control',andsetthevalueto"warn"or"quiet".Otherwise,movethereferencedfile"%1"intotheinputdita/mapdirectory.

directory/some.dita"

resultwouldcauseanoutputfiletobecreatedoutsideoftheoutputdirectory.PleaseseeDITA-OTAntarguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)

DOTJ036W Warning

Thefile"%1"referencedby"%2"isoutsidethescopeoftheinputdita/mapdirectory.Ifyoudonotwanttoseethewarningmessage,pleaseusetheAntparameter'outer.control',andsetthevalueto"quiet".Otherwise,movethereferencedfile"%1"intotheinputdita/mapdirectory.

Thisoutsidethescopeofthemap;forexample,ifthemaininputmapreferencesdirectory/some.dita"

resultwouldcauseanoutputfiletobecreatedoutsideoftheoutputdirectory.DITA-OTAntarguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)

DOTJ037W Warning

TheXMLschemaandDTDvalidationfunctionoftheparseristurnedoff.PleasemakesuretheinputisnormalizedDITAwithclassattributesincluded,otherwiseitwillnotbeprocessedcorrectly.

DITAprocessingisbasedonclassattributesdefinedforeveryelement.UsuallythesearedefaultedintheDTDorSchema;ifvalidationagainsttheDTDorSchemaisturnedoff,theclassattributesmustbeexplicitlyincludedinthemaportopic.

DOTJ038E Error

Thetag"%1"isspecializedfromunrecognizedmetadata.Pleasemakesurethattag"%1"isspecializedfromanexistingmetadatataginthecoreDITAvocabulary.

Thisappearstoindicateanerrorincreatingspecializedmetadataelements.Pleaseverifythatthedocumenttypeyouareusingiscompleteandcomplieswith

DITASpecializationrules.

DOTJ039E Error

Thereisnotargetspecifiedforconrefpushaction"pushafter".Foundinfile="%1",element="%2".Pleaseadd<elementnameconref="pushtarget"conaction="mark">beforecurrentelement.

PleaseseethetopiconPushfordetailsonexpectedsyntaxforthisfunction.

DOTJ040E Error

Anelementusestheattributeconaction="replace",butaconrefattributeisnotfoundintheexpectedlocation.Foundinfile="%1",element="%2".

PleaseseethetopiconPushfordetailsonexpectedsyntaxforthisfunction.

DOTJ041E Error

Theattributeconref="%1"usesinvalidsyntax.Thevalueshouldcontain'#'followedbyatopicormapID,optionallyfollowedby'/elemID'forasub-topicelement.

TheconrefattributemustbeaURIreferencetoaDITAelement.PleaseseethetopiconURI-basedaddressingDITAspecificationfordetailsontheexpectedsyntax.

DOTJ042E ErrorTwoelementsbothuseconrefpushtoreplacethetarget"%1".Pleasedeleteoneoftheduplicate"replace"actions.

Theconrefpushfunctionwasusedtoreplaceasingleelementwithtwoormorealternatives.Onlyoneelementmaydirectlyreplaceanotherusingconrefpush.SeeDITAspecificationformoreinformationabouttheconrefpush"replace"function.

DOTJ043W WarningTheconrefpushfunctionistryingtoreplaceanelementthatdoesnotexist(element"%1"infile"%2").

Thetargetforaconrefpushactiondoesnotexist;pleasemakesurethatthesyntaxiscorrectandthatthetargetexists.Seethetopiconbasedaddressingspecificationfordetailsontheexpectedsyntax.Ifthesyntaxiscorrect,itispossiblethatthetargetwasfilteredoutofyourbuildusingaDITAVALfile.

Thereisaredundantconrefaction Pleaseseethetopicon

DOTJ044W Warning "pushbefore".Foundinfile="%1",element="%2".Pleasemakesurethat"mark"and"pushbefore"occurinpairs.

Pushfordetailsonexpectedsyntaxforthisfunction.

DOTJ045I InformationalThekey"%1"isdefinedmorethanonceinthesamemapfile.Thereferencehref="%2"isignored.

Noresponseisneededifthekeysaredefinedasexpected;thisisinformationalonly,tohelpcatchincorrectlydefinedkeys.

DOTJ046E Error

Conkeyref="%1"cannotberesolvedbecauseitdoesnotcontainakeyorthekeyisnotdefined.Thebuildwillusetheconrefattributeforfallback,ifoneexists.

Seedetailsonexpectedsyntaxandusage.

DOTJ047I InformationalUnabletofindkeydefinitionforkeyref="%1",hrefmaybeusedasfallbackifitexists.

Thismessageisintendedtohelpyoulocateincorrectlyspecifiedkeys;ifthekeywasspecifiedcorrectly,thismessagemaybeignored.

DOTJ049W Warning

Theattributevalue%1="%3"onelement"%2"doesnotcomplywiththespecifiedsubjectscheme.Accordingtothesubjectschememap,thefollowingvaluesarevalidforthe%1attribute:%4

ADITAwasusedtolimitvaluesthatareavailabletothespecifiedattribute.Pleasecorrecttheattributesothatitusesoneoftheallowedvalues.

DOTJ050W WarningFoundan<index-see>or<index-see-also>referencetotheterm'%1',butthattermisnotdefinedintheindex.

TheEclipseindexwillcontainavaluesuchas"SeealsootherEntry",butotherEntrydoesnotexistinthisindex.Theindexreferencewillbebrokenunlessthisplug-inisEclipsewithanotherplug-inthatdefinesotherEntryasanindexterm.Thetargetforacoderefelement,whichspecifiesanexternaltext-basedfile,couldnotbelocatedorloaded.Pleaseverifythatthereferenceiscorrect.

DOTJ051E Error Unabletoloadtargetforcoderef"%1".

Notethatforsecurityreasons,referencestocodesamplesoutsideofthescopeofthemapdirectoryarenotsupportedbydefault,asthiscouldallowareferencetoaccessanddisplayanyrestrictedorhiddenfileonthesystem.Ifyouarecertainthatthepathisvalidandthefileshouldbeloaded,thecurrentworkaroundistosetaparametertoallowthesereferences.Seearguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)

DOTJ052E Error

Codereferencecharset"%1"notsupported.SeetheDITA-OTUserguideforsupportedcharsetvaluesontheformatattribute.

TheDITA-OTsupportsaspecialsyntaxoncoderefelementstospecifythecharactersetofthetargetdocument.Seefunctionalityexpectedsyntax.

DOTJ053W Warning

Inputfile'%1'isnotvalidDITAfilename.Pleasecheck'%1'toseeifitiscorrect.Theextensions".dita"or".xml"aresupportedforDITAtopics.

Bydefault,theDITA-OTsupportstheextensions"dita"and"xml"forDITAtopics,asmandatedbytheDITASpecification.Pleaseverifythatyourtopicsuseoneoftheseextensions,orconfigurethetoolkittoallowadditionalextensions.

DOTJ054E Error Unabletoparseinvalid%1attributevalue"%2"

DOTJ055E Error Invalidkeyname"%1".

DOTJ056E Error Invalidxml:lang"%1".

DOTJ057E Error Theidattributevalue"%1"isnotuniquewithinthetopicthatcontainsit.

DOTJ058E Error

Both%1and%2attributesdefined.Asingleelementmaynotcontainbothgeneralizedandspecializedvaluesforthesameattribute.

DOTJ059E Error Invalidkeyscopename"%1".

DOTJ060W Warning

Key"%1"wasusedinconkeyrefbutisnotboundtoaDITAtopicormap.Cannotresolveconkeyrefvalue"%2"asavalidconrefreference.

DOTX001WWarning

Nostringnamed'%1'wasfoundforlanguage'%2'.Usingthedefaultlanguage'%3'.Addamappingbetweendefaultlanguageanddesiredlanguageforthestring'%1'.

Thisbuildusesgeneratedtext,suchasthephrase"Relatedinformation"(whichisgeneratedabovemanylinkgroups).Thetoolkitwasunabletolocatethestringlanguage,sothestringwillappearinthedefaultlanguage.Thisgenerallyindicatesthatthetoolkit'sstringsneedstobeupdatedtosupportyourlanguage,orthatyourlanguagesettingisincorrect.

DOTX002WWarning ThetitleelementorattributeintheditamapisrequiredforEclipseoutput.

TheEclipsehelpsystemrequiresatitleintheprojectfilesgeneratedfromyourmap.PleaseaddatitletoyourinputmaptogetvalidEclipsehelpoutput.

DOTX003I Informational

TheanchorrefattributeshouldeitherreferenceanotherditamaporanEclipseXMLTOCfile.Thevalue'%1'doesnotappeartoreferenceeither.

EclipseusesanchorreferencestoconnectwithotherTOCfiles.ForthistoworkincontentgeneratedfromaDITAmap,theanchorrefelementmustreferenceeitheranexistingEclipseTOCXMLfile,or

anotherDITAmap(whichwillpresumablyalsobeconvertedtoanEclipseTOC).

Foundanavrefelementthatdoesnotreferenceanything.ThenavrefelementshouldeitherreferenceanotherditamaporanEclipseXMLfile.

EclipsebuildsuseDITA's<navref>elementtopullinotherEclipseTOCfiles.Thebuildfounda<navref>elementthatdoesnotreferenceanyotherfile;theelementwillbeignored.

DOTX005E Error

Unabletofindnavigationtitleforreferenceto'%1'.Thebuildwilluse'%1'asthetitleintheEclipseTableofContents.

Toremovethismessage,provideanavigationtitleforthereferencedobjectinthemaportopic,orensurethatyouarereferencingavalidlocalDITAtarget.

DOTX006E Error

Unknownfileextensioninhref="%1".Referencestonon-DITAresourcesshouldsettheformatattributetomatchtheresource(forexample,'txt','pdf',or'html').

Settheformatattributetoidentifytheformatofthefile.IfthereferenceistoaDITAdocument,ensurethatthedocumentusesavalidDITAextension(defaultsupportedextensionsare"dita"and"xml").

OnlyDITAtopics,HTMLfiles,andimagesmaybeincludedinyourcompiledCHMfile.Thereferenceto"%1"willbeignored.Toremovethismessage,youcansetthetoc="no"orprocessing-role="resource-only"attributeonyourtopicref.

TheHTMLHelpcompilerwillonlyincludesometypesofinformationinthecompiledCHMfile;thecurrentreferencewillnotbeincluded.

DOTX008E Error File'%1'doesnotexistorcannotbeloaded.

Ensurethatthefileexistsandcanberead.ofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX008WWarningFile'%1'cannotbeloaded,andnonavigationtitleisspecifiedforthetableofcontents.

Tofixthetableofcontents,specifyanavigationtitleinyourmaporensurethatthereferencedfileislocalandcanbeaccessed.nameofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX009WWarning Couldnotretrieveatitlefrom'%1'.Using'%2'instead.

Notitlewasfoundinthespecifiedtopic,sothetableofcontentswillusetheindicatedfallbackvalueforthistopic.

DOTX010E Error Unabletofindtargetforconref="%1".

TheconrefattributemustbeaURIreferencetoanexistingDITAelement.PleaseseethetopiconintheDITAspecificationfordetailsontheexpectedsyntax.Notethatthenameofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

Ifthetargetelementexistsinyoursourcefile,checktomakesureitisnotfilteredoutofthebuildwithaDITAVALfile(whichwillremovethetargetbefore

conrefprocessingruns).

DOTX011WWarning

Thereismorethanonepossibletargetforthereferenceconref="%1".Onlythefirstwillbeused.Removetheduplicateidinthereferencedfile.

Whenpullingcontentwithaconrefattribute,youmayonlypullfromasingleelement,butthetargetIDappearstwiceinthereferencedtopic.thenameofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX012WWarning

Whenyouconrefanothertopicoraniteminanothertopic,thedomainsattributeofthetargettopicmustbeequaltoorasubsetofthecurrenttopic'sdomainsattribute.Putyourtargetunderanappropriatedomain.Youcanseethemessagesguideformorehelp.

Thismessageisdeprecatedandshouldnolongerappearinanylogs.

DOTX013E ErrorAelementwithattributeconref="%1"indirectlyincludesitself,whichresultsinaninfiniteloop.

Thismayappearif(forexample)youhaveareferencesanotherphrase,butthatphraseitselfcontainsareferencetotheoriginal.Thiswillresultinaninfiniteloop.Thetoolkitwillstopfollowingtheconreftrailwhenthisisdetected;youwillneedtocorrectthereferenceinyoursourcefiles.ofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythe

file;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX014E Error

Theattributeconref="%1"usesinvalidsyntax.Conrefreferencestoamapelementshouldcontain'#'followedbyanID,suchasmymap.ditamap#mytopicrefid.

TheconrefattributemustbeaURIreferencetoaDITAelement.PleaseseethetopiconURI-basedaddressingDITAspecificationfordetailsontheexpectedsyntax.

DOTX015E Error

Theattributeconref="%1"usesinvalidsyntax.Thevalueshouldcontain'#'followedbyatopicormapID,optionallyfollowedby'/elemID'forasub-topicelement.

TheconrefattributemustbeaURIreferencetoaDITAelement.PleaseseethetopiconURI-basedaddressingDITAspecificationfordetailsontheexpectedsyntax.thenameofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX016WWarning

Areferenceto"%2"appearstoreferenceaDITAdocument,buttheformatattributehasinheritedavalueof"%1".ThedocumentwillnotbeprocessedasDITA.

Thiswarningisintendedtocatchinstanceswhereanon-DITAformatsettingunexpectedlycascadestoaDITAtopic,whichwillpreventthetopicfrombeingprocessed.Toremovethismessage,settheformatattributedirectlyontheindicatedreference.thenameofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextension

usedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.

DOTX017E ErrorFoundalinkorcrossreferencewithanemptyhrefattribute(href="").Removetheemptyhrefattributeorprovideavalue.

Foundavaluesuchas<xrefhref="">linktext</xref>.Theemptyhrefattributeisnotservingapurposeandhascausedproblemswithsometoolsinthepast;youshouldremovetheattributeentirelyorspecifyavalue.

Thetypeattributeonatopicrefwassetto'%1',butthetopicrefreferencesamorespecific'%2'topic.Notethatthetypeattributecascadesinmaps,sothevalue'%1'maycomefromanancestortopicref.

ThetypeattributeinDITAisintendedtodescribethetypeofthetarget;forexample,areferencetoaconcepttopicmayusetype="concept".Generally,thisattributeisoptional,andtheDITA-OTbuildwillautomaticallydeterminethevalueduringprocessing.Inthiscase,thetypeattributelistsamoregeneraltypethanwhatisactuallyfound.Thisisnotanerrorbutmayresultinunexpectedsortingforlinkstothistopic.

DOTX019WWarning

Thetypeattributeonatopicrefwassetto'%1',butthetopicrefreferencesa'%2'topic.Thismaycauseyourlinkstosortincorrectlyintheoutput.Notethatthetypeattributecascadesinmaps,sothevalue'%1'maycomefromanancestortopicref.

ThetypeattributeinDITAisintendedtodescribethetypeofthetarget;forexample,areferencetoaconcepttopicmayusetype="concept".Generally,thisattributeisoptional,andtheDITA-OTbuildwillautomaticallydeterminethevalueduringprocessing.Inthiscase,thespecifiedtypevaluedoesnotmatchthetarget,which

maycauseyourlinkstosortinappropriately.

DOTX020E Error

Missingnavtitleattributeorelementforpeertopic"%1".ReferencesmustprovidealocalnavigationtitlewhenthetargetisnotalocalDITAresource.

TheDITA-OTisonlyabletodynamicallyretrievetitleswhenthetargetisalocal(notpeerorexternal)DITAresource.

DOTX021E Error

Missingnavtitleattributeorelementfornon-DITAresource"%1".ReferencesmustprovidealocalnavigationtitlewhenthetargetisnotalocalDITAresource.

TheDITA-OTisonlyabletodynamicallyretrievetitleswhenthetargetisalocalDITAresource.

DOTX022WWarningUnabletoretrievenavtitlefromtarget:'%1'.Usinglinktext(specifiedintopicmeta)asthenavigationtitle.

Thebuildwasunabletogetatitlefromthereferencedtopic;instead,anavigationtitlewillbecreatedbasedonthespecified<linktext>elementinsideof<topicmeta>.

DOTX023WWarning Unabletoretrievenavtitlefromtarget:'%1'.

IfthetargetisalocalDITAtopic,ensurethereferenceiscorrectandthetopicisavailable.Otherwise,provideatitle,andensurethescopeandformatattributesaresetappropriately.

DOTX024E Error

Missinglinktextandnavtitleforpeertopic"%1".ReferencesmustprovidealocalnavigationtitlewhenthetargetisnotalocalDITAresource.

TheDITA-OTisonlyabletodynamicallyretrievetitlesandlinktextwhenthetargetisalocal(notpeerorexternal)DITAresource.

DOTX025E Error

Missinglinktextandnavtitlefornon-DITAresource"%1".ReferencesmustprovidealocalnavigationtitlewhenthetargetisnotalocalDITAresource.

TheDITA-OTisonlyabletodynamicallyretrievetitleswhenthetargetisalocalDITAresource.

DOTX026WWarning Unabletoretrievelinktextfromtarget:'%1'.Usingnavigationtitleasfallback.

Thereferenctothisdocumentdidnotspecifyanylinktextforgeneratedmap-basedlinks;thenavigationtitlewillbeusedasfallback.Thereferencedfiledidnot

DOTX027WWarning Unabletoretrievelinktextfromtarget:'%1'.

specifyanylinktextforgeneratedmap-basedlinks,andnofallbacktextcouldbelocated.Anylinksgeneratedfromthisreferencewillhaveincorrectlinktext.

DOTX028E ErrorLinkorcrossreferencemustcontainavalidhreforkeyrefattribute;nolinktargetisspecified.

Thelinkorcrossreferencehasnotargetspecifiedandwillnotgeneratealink.

Thetypeattributeona%1elementwassetto%3,butthereferenceistoamorespecific%4%2.Thismaycauseyourlinkstosortincorrectlyintheoutput.

ThetypeattributeinDITAisintendedtodescribethetypeofthetarget;forexample,areferencetoaconcepttopicmayusetype="concept".Generally,thisattributeisoptional,andtheDITA-OTbuildwillautomaticallydeterminethevalueduringprocessing.Inthiscase,thetypeattributelistsamoregeneraltypethanwhatisactuallyfound.Thisisnotanerrorbutmayresultinunexpectedsortingforlinkstothistopic.

DOTX030WWarning

Thetypeattributeona%1elementwassetto%3,butthereferenceistoa%4%2.Thismaycauseyourlinkstosortincorrectlyintheoutput.

ThetypeattributeinDITAisintendedtodescribethetypeofthetarget;forexample,areferencetoaconcepttopicmayusetype="concept".Generally,thisattributeisoptional,andtheDITA-OTbuildwillautomaticallydeterminethevalueduringprocessing.Inthiscase,thespecifiedtypevaluedoesnotmatchthetarget,whichmaycauseyourlinkstosortinappropriately.Thebuildattemptedtoaccess

DOTX031E Error Thefile%1isnotavailabletoresolvelinkinformation.

thespecifiedfileinordertoretriveatitleorshortdescription,butthefilecouldnotbefound.Ifthefileexists,itispossiblethatusedtoremovethefile'scontentsfromthebuild.Beawarethatthepathinformationabovemaynotmatchthelinkinyourtopic.

DOTX032E Error

Unabletoretrievelinktextfromtarget:'%1'.Ifthetargetisnotaccessibleatbuildtime,ordoesnothaveatitle,providethelinktextinsidethereference.

Whenalinkorcrossreferencedoesnothavecontent,thebuildwillattempttopullthetarget'stitleforuseaslinktext.Ifthetargetisunavailable,besuretosetthescopeattributetoanappropriatevalue.Ifthetargetdoesnothaveatitle(suchaswhenlinkingtoaparagraph),besuretoprovidelinktextinsidethecrossreference.

DOTX033E Error Unabletogeneratelinktextforacrossreferencetoalistitem:'%1'

An<xref>elementspecifiestype="li",whichindicatesalinktoalistitem,buttheitemnumbercouldnotbedeterminedtouseaslinktext.Pleasespecifylinktextinsidethereference,orensurethatyouarereferencinganavailablelistitem.

DOTX034E Error Unabletogeneratelinktextforacrossreferencetoanunderedlistitem:'%1'

Thecrossreferencegoestoalistiteminanunorderedlist.Theprocesscouldnotautomaticallygeneratelinktextbecausethelistitemisnotnumbered.Pleaseprovidelinktextwithinthecrossreference.An<xref>elementspecifies

DOTX035E Error Unabletogeneratethecorrectnumberforacrossreferencetoafootnote:'%1'

type="fn",whichindicatesalinktoafootnote,butthefootnotenumbercouldnotbedeterminedtouseaslinktext.Pleasespecifylinktextinsidethereference,orensurethatyouarereferencinganavailablefootnote.

DOTX036E ErrorUnabletogeneratelinktextforacrossreferencetoadlentry(thedlentryortermcouldnotbefound):'%1'

An<xref>elementspecifiestype="dlentry",whichindicatesalinktoadefinitionlistentry,butthetermcouldnotbelocatedtouseaslinktext.Pleasespecifylinktextinsidethereference,orensurethatyouarereferencinganavailabledefinitionlistentry

DOTX037WWarning Notitlefoundforthisdocument;using"***"inXHTMLtitlebar.

Notitlewasfoundforthecurrentdocument,sotheXHTMLoutputfilewillsetthe<title>to"***".Thisvaluegenerallyappearsinthetitlebaratthetopofabrowser.

Thelongdescrefattributeontag'%1'willbeignored.Accessibilityforobjectelementsneedstobehandledanotherway.

The<object>elementinXHTMLdoesnotsupportusinglongdescrefforaccessibility.Tomaketheobjectaccessible,youmayneedtoaddtextbeforeoraftertheelement.Youmayalsobeabletohandleitwitha<param>elementinsidetheobject.

DOTX039WWarning

Requiredcleanupareafound.Toremovethismessageandhidethecontent,buildyourcontentwithoutusingtheDRAFTparameter.

Thismessageisgeneratedwhencreatingdraftoutputinordertohelpyoulocatealltopicsthatneedtobecleanedup;thecleanupitemswillappearinyouroutputwithstylingthatmakesitstandout.

Thecontentwillbehiddenwhenthedraftparameterisnotactive.

Draftcommentareafound.Toremovethismessageandhidethecomments,buildyourcontentwithoutusingtheDRAFTparameter.

Thismessageisgeneratedwhencreatingdraftoutputinordertohelpyoulocatealltopicsthathavedraftcomments.EachcommentwillappearinyourXHTMLoutput;thecommentswillbehiddenwhenthedraftparameterisnotactive.

DOTX041WWarningFoundmorethanonetitleelementinasection.Usingthefirstoneforthesection'stitle.

BecauseofthewayXMLandDITAaredefined,itisgenerallynotpossibletoprohibitaddingasecondtitletoasectionduringediting(ortoforcethattitletocomefirst).However,theDITAspecificationstatesthatonlyonetitleshouldbeusedinasection.Whenmultipletitlesarefound,onlythefirstonewillappearintheoutput.

DOTX042I InformationalDITAVALbasedflaggingisnotcurrentlysupportedforinlinephrasesinXHTML;ignoringflagvalueon'%1'attribute.

Ifitisimportanttoflagthispieceofinformation,tryplacingaflagontheblockelementthatcontainsyourphrase.Ifyoujustwanttohaveanimagenexttothephrase,youmayplaceanimagedirectlyintothedocument.

DOTX043I Informational Thelinkto'%1'mayappearmorethanoncein'%2'.

TheDITA-OTisabletoremoveduplicatelinksinmostcases.However,iftwolinkstothesameresourceusedifferentattributesorlinktext,itispossibleforthemtoappeartogether.Forexample,ifthesamelinkshowsupwithrole="next"andagainwithno

specifiedrole,itmayshowupasboththe"Nexttopic"linkandasarelatedlink.Notethatlinksgeneratedfroma<reltable>inaDITAMapwillhavetheroleattributesetto"friend".

DOTX044E Error

Theareaelementinanimagemapdoesnotspecifyalinktarget.Pleaseaddanxrefelementwithalinktargettotheareaelement.

The<area>elementinanimagemapmustprovidealinktargetforthespecifiedarea.Pleaseaddan<xref>elementasachildof<area>andensurethatitspecifiesalinktarget.

DOTX045WWarning

Theareaelementinanimagemapshouldspecifylinktextforgreateraccessibility.LinktextshouldbespecifieddirectlywhenthetargetisnotalocalDITAresource.

Crossreferencetextinsidethe<area>elementisusedtoprovideaccessibilityforscreenreadersthatcanidentifydifferentareasofanimagemap.IftextcannotberetrievedautomaticallybyreferencingaDITAelement,itshouldbespecifieddirectlyinthecrossreference.

DOTX046WWarningAreashapeshouldbe:default,rect,circle,poly,orblank(novalue).Thevalue'%1'isnotrecognized.

Thespecifiedvaluewaspassedas-isthroughtotheareaelementintheXHTML.

DOTX047WWarning Areacoordinatesareblank.Coordinatepointsfortheshapeneedtobespecified.

Theareaelementisintendedtodefinearegioninanimagemap;coordinatesmustbespecifiedinordertodefinethatregion.

Inordertoincludepeerorexternaltopic'%1'inyourhelpfile,youmayneedtorecompiletheCHMfileaftermakingthe

ThebuildwillnotlookforpeerorexternaltopicsbeforecompilingyourCHMfile,sotheymaynotbeincluded.IfyouarereferencinganactualHTMLfilethatwillnotbeavailable,itcannotbeincludedintheproject,andyoushouldsetthe

fileavailable. tocattributeto"no"onyourtopicrefelement.Otherwise,checktobesureyourHTMLfilewasincludedintheCHM;ifitwasnot,youwillneedtoplaceitinthecorrectlocationwithyourotheroutputfilesandrecompile.

DOTX049I InformationalReferencestonon-ditafileswillbeignoredbythePDF,ODT,andRTFoutputtransforms.

ThePDF,ODT,andRTFoutputprocessescannotautomaticallyconvertnon-DITAcontentintoDITAinordertomergeitwiththerestofyourcontent.Thereferenceditemsareignored.

DOTX050WWarning

Defaultid"org.sample.help.doc"isusedforEclipseplug-in.Ifyouwanttouseyourownplug-inid,pleasespecifyitusingtheidattributeonyourmap.

EclipserequiresthatanIDbespecifiedwhencreatinganEclipseHelpproject;thetoolkitexpectstolocatethatIDontherootelementofyourinputmap.

DOTX052WWarningNostringnamed'%1'wasfoundwhencreatinggeneratedtext;usingthevalue'%1'inyouroutputfile.

Thetoolkitisattemptingtoaddgeneratedtext,suchasthestring"Relatedinformation"thatappearsabovelinks.Therequestedstringcouldnotbefoundinanylanguage.Youroutputmaycontainameaningfulstring,oritmaycontainacodethatwasintendedtomaptoastring.Thislikelyindicatesanerrorinaplug-inorXSLoverride;eitherthestringwasrequestedincorrectly,oryouwillneedtoprovideamappingforthestringinallofthelanguagesyourequire.

Aelementthatreferencesanothermapindirectlyincludesitself,whichresultsin

Thiswilloccurifamapreferencesanothermap,andthenthatsecondmap(oranotherfurthernestedmap)

DOTX053E Error aninfiniteloop.Theoriginalmapreferenceisto'%1'.

referencestheoriginalmap.Theresultisaninfinitenestingofmaps;pleasecorrectthechainofmapreferencestoremovecircularreference.

DOTX054WWarning

ConflicttextstyleisappliedonthecurrentelementbasedonDITAVALflaggingrules.Pleasecheckditavalandditasourcetomakesurethereisnostyleconflictontheelementwhichneedstobeflagged.

ThiswilloccurwhenaDITAVALfilecontainsmultiplestylingrulesthatapplytothesameelement.

DOTX055WWarning

Customizedstylesheetusesdeprecatedtemplate"flagit".Conditionalprocessingisnolongersupportedusingthistemplate.Pleaseupdateyourstylesheettousetemplate"start-flagit"insteadofdeprecatedtemplate"flagit".

The"flagit"deprecatedinDITA-OTversion1.4,whentheOASISstandardformalizedtheDITAVALsyntax.ThetemplateisremovedinDITA-OT1.6.Stylesheetsthatusedthistemplateneedtobeupdated.

DOTX056WWarning Thefile'%1'isnotavailabletoresolvelinkinformation.

Thebuildattemptedtoaccessthespecifiedfileinordertoretriveatitleorshortdescription,butthefilecouldnotbefound.Ifthefileexists,itispossiblethataDITAVALfilewasusedtoremovethefile'scontentsfromthebuild.Anotherpossibilityisthatthefileislocatedoutsideofthescopeofthemaininputdirectory,andwasnotavailablebecausetheonlytopic.in.map/onlytopicinmapspecified.Beawarethatthepathinformationabovemaynotmatchthelinkinyourtopic.

Thelinkorcrossreferencetarget'%1'cannotbefound,whichmaycauseerrors

ThelinkappearstousevalidsyntaxtoreferenceaDITAelement,butthatelement

DOTX057WWarning creatinglinksorcrossreferencesinyouroutputfile.

cannotbefound.Pleaseverifythattheelementexists,andisnotremovedfromthebuildbyDITAVALbasedfiltering.

DOTX058WWarning

Noglossaryentrywasfoundassociatedwithkey'%1'on%2element.Thebuildwilltrytodeterminethebestdisplaytextandhovertextfortermsandabbreviations.

Processingforterms,acronyms,orabbreviatedformswillassociatethekeyfromtheelement'skeyrefattributewithaglossentry(glossaryentry)topic.Thismessagewillappearifthekeywasdefined,butwasnotassociatedwithaglossentrytopic.Theprocesswilltrytousethebestavailablefallback(usuallythetitleofthereferencedtopic).

DOTX060WWarning

Key'%1'wasusedinanabbreviated-formelement,butthekeyisnotassociatedwithaglossaryentry.Abbreviated-formshouldONLYbeusedtoreferencetoaglossaryentry.

Processingforabbreviatedformelementswillassociatethekeyfromtheelement'skeyrefattributewithaglossentry(glossaryentry)topic.Thismessagewillappearifthekeywasdefined,butwasnotassociatedwithaglossentrytopic.Thiselementisonlysupportedwithkeysthatareassociatedwithglossarytopics;theelementwillnotgenerateanyoutput.Pleasecorrectthereference,oruseadifferentelementtoreferenceyourtopic.

DOTX061WWarning

ID'%1'wasusedintopicreftagbutdidnotreferenceatopicelement.Thehrefattributeonatopicrefelementshouldonly

AccordingtotheDITASpecification,referencesfrommapsshouldeithergotoDITAMaps,DITATopics,DITAresource.Referencesbelowthetopiclevelshouldonlybemadefromcrossreferences

referencetopiclevelelements. (using<xref>orsimilar)insideofatopic.Fordetails,seethehrefattributedescriptionintheOASISstandard'sdefinitionofthetopicrefelement

Itappearsthatthisdocumentusesconstraints,buttheconrefprocessorcannotvalidatethatthetargetofaconrefisvalid.Toenableconstraintchecking,pleaseupgradetoanXSLT2.0processor.

DOTX063WWarning

Theditadocument'%1'islinkedtofromyourcontent,butisnotreferencedbyatopicreftagintheditamapfile.Includethetopicinyourmaptoavoidabrokenlink.

ThiswillappearwhengeneratingPDForODToutputthatincludesalinktoalocaltopic,butthereferencedtopicisnotpartofthemapitself.Thiswillresultinabrokenlink.Youshouldincludethetopicinyourmaporremovethelinkfromthebuild.

DOTX064WWarningThecopy-toattribute[copy-to="%1"]usesthenameofafilethatalreadyexists,sothisattributeisignored.

Thecopy-toattributeisusedtocopyatopicoveradocumentthatalreadyexists.Pleasemakesurethatanycopy-toattributesuseauniquenamesothatthecopywillnotoverwriteexistingcontent.

DOTX065WWarning

Twouniquesourcefileseachspecifycopy-to="%2",whichresultsinacollision.Thevalueassociatedwithhref="%1"isignored.

Twodifferenttopicsarecopiedtothesamelocationusingcopy-to;asaresult,oneofthesefileswouldbeover-written.Onlythefirstinstanceofthiscopy-tovaluewillberecognized.Pleasecorrecttheuseofcopy-toattributes.

Template"%1"isdeprecated.Remove

ThismessageindicatesthatyourcustomXSLTorplug-insrelyontemplatesthatwillberemovedinanupcoming

DOTX066WWarning referencestothistemplatefromyourcustomXSLTorplug-ins.

release.Typicallythisoccurswhenanamedtemplatehasbeenconvertedtoamodetemplate;anycodethatusesthedeprecatedtemplateshouldbeupdated.

DOTX067E ErrorNostringnamed'%1'wasfoundforlanguage'%2'.Addamappingforthestring'%1'.

ThisPDFbuildusesgeneratedtext,suchasthephrase"Relatedinformation"(whichisgeneratedabovemanylinkgroups).Thetoolkitwasunabletolocatethestringspecifiedlanguage,sothestringwillappearinthedefaultlanguage.Thisgenerallyindicatesthatthetoolkit'sstringsneedstobeupdatedtosupportyourlanguage,orthatyourlanguagesettingisincorrect.

DOTX068WWarningAtopicrefelementthatreferencesamapcontainschildtopicrefelements.Childtopicrefelementsareignored.

PDFJ001E Error Indexentry'%1'isdropped,becausecorrespondinggroupisnotfound.

PDFJ002E ErrorBuildstopped.ProblemsoccuredduringIndexpreprocesstask.Pleasecheckthemessagesabove.

PDFX001W Warning ThereisnoindexentryfoundwhichclosingrangeforID="%1".

PDFX002W Warning

TherearemultipleindexentryfoundwhichisopeningrangeforID="%1"butthereisonlyonewhichcloseitorrangesareoverlapping.

PDFX003W Warning TherearemultipleindexentryfoundwhichclosingrangeforID="%1".

PDFX004F FatalEmptyhrefwasspecifiedforsometopicreference.Pleasecorrectyourditamaporbookmapfile.

PDFX005F FatalTopicreference(href:%1)notfound.Referencemaybeincorrect.Pleasecorrectyourditamaporbookmapfile.

PDFX006E Error Numberofcolumnsmustbespecified.

PDFX007W Warning ThereisnoindexentryfoundwhichopeningrangeforID="%1".

PDFX008W Warning Fontdefinitionnotfoundforthelogicalnameoralias'%1'.

PDFX009E Error Attributesetreflectioncan'thandleXSLTelement%1.

PDFX010W Warning IndexgenerationisnotsupportedinFOP.

PDFX011E ErrorBothindex-seeand%1definedforindexentry'%2'.Recoveringbytreatingtheindex-seeasanindex-see-also.

PDFX012F FatalUnrecognizedPDFformatter'%1'.Use"fop"forFOP,"xep"forRenderXXEP,or"ah"forAHFormatter.

XEPJ001W Warning %1 XEPJ002E Error %1 XEPJ003E Error %1

Parenttopic:Errormessagesandtroubleshooting

OthererrormessagesInadditiontoerrormessagesgeneratedbytheDITAOpenToolkit,youmightalsoencountererrormessagesgeneratedbyJavaorothertools.

OutofMemoryerror

Insomecases,youmightreceiveamessagestatingthebuildhasfailedduetoanOutofMemoryerror.Trythefollowingapproachestoresolvetheproblem:

1. IncreasethememoryavailabletoJava;seeIncreasingJavamemoryallocation.

2. Reducememoryconsumptionbysettingthegenerate-debug-attributesoptiontofalse.Thisoptionissetinthelib/configuration.propertiesfile.Thiswilldisabledebugattributegeneration(usedtotraceDITA-OTerrormessagesbacktosourcefiles)andwillreducememoryconsumption.

3. Setdita.preprocess.reloadstylesheetAntpropertytotrue.ThiswillallowtheXSLTprocessortoreleasememorywhenconvertingmultiplefiles.

4. Runthetransformationagain.

java.io.IOException:Can'tstoreDocument

AfterrunningaJavaHelptransformation,youmayreceiveajava.io.IOException:Can'tstoreDocumentmessage.

ThisproblemoccurswhenHTMLfilesunrelatedtothecurrenttransformationarefoundintheoutputdirectory.Deletethecontentoftheoutputdirectoryandrunthetransformationagain.

StackOverflowerror

Ifyoureceiveanerroraboutastackmemoryoverflow,increasetheJVMandrunthetransformationagain.SeeIncreasingJavamemoryallocation.

LogfilesWhenyouruntheDITA-OT,keyinformationisloggedonthescreen.Thisinformationcanalsobewrittentoalogfile.Ifyouencounteraproblem,youcananalyzethisinformationtodeterminethesourceoftheproblemandthentakeactiontoresolveit.

Theloggingbehaviorvariesdependingonwhetheryouusetheditacommand,DITA-OTcommand-linetool,orAnttoinvokeatoolkitbuild.

ditacommand

Bydefault,onlywarninganderrormessagesarewrittentothescreen.Ifyouusethe-voption,loggingwillbemoreverboseandinformativemessagesarealsowrittenout.The-loptioncanbeusedtowritethelogmessagesintoafile.

Bydefault,statusinformationiswrittentothescreen.Ifyouissuethe-lparameter,thebuildrunssilentlyandtheinformationiswrittentoalogfilewiththenameandlocationthatyouspecified.(YoualsocanuseotherAntloggers;seetheAntdocumentationformoreinformation.)

Command-linetool

Statusinformationiswrittentothescreenandthelogfile.Thelogfilenamecontainstheinputfilenameandtransformationtype;bydefault,itislocatedintheoutputdirectory.Ifyouissuethe/logdirparameter,youcanspecifyadifferentlocationforwherethelogfileiswritten.

Accessinghelpfromthecommand-linetoolYoucanaccessalistofsupportedparametersforthecommand-linetoolbyissuingthe-helpparameter.

Procedure

java-jarlib/dost.jar-help

Results

Youcanseethebriefdescriptionofthesupportedparametersinthecommand-linewindow.

DetermingtheversionoftheDITAOpenToolkitYoucanusethecommand-linetooltodeterminetheversionoftheDITAOT.

Procedure

java-jarlib/dost.jar-version

EnablingdebugmodeWhenthedebugmodeisenabled,additionaldiagnosticinformationiswrittentothelogfile.Thisinformation,whichincludesenvironmentvariablesandstacktracedata,canhelpyoudeterminetherootcauseofaproblem.

Procedure

Fromthecommandprompt,addthefollowingparameters:

Application Parametersditacommand -dor-debugAnt -v-Dargs.debug=yes

Command-linetool/dor-debug

Youalsocanadda<property>elementtoanAnttargetinyourbuildfile,forexample:

<propertyname="args.debug"value="yes"/>

IncreasingJavamemoryallocationIfyouareworkingwithlargedocumentswithextensivemetadataorkeyreferences,youwillneedtoincreasethememoryallocationfortheJavaprocess.Youcandothisfromthecommand-linepromptforaspecificsession,oryoucanincreasethevalueoftheANT_OPTSenvironmentalvariable.

Procedure

Tochangethevalueforanspecificsession,fromthecommandprompt,issuethefollowingcommand:

Platform CommandWindows setANT_OPTS=%ANT_OPTS%-Xmx1024M

Linux/OSXexportANT_OPTS=$ANT_OPTS-Xmx1024M

ThisincreasestheJVMmemoryallocationto1024megabytes.Theamountofmemorywhichcanbeallocatedislimitedbyavailablesystemmemoryandtheoperatingsystem.

Topersistentlychangethevalue,changethevalueallocatedtotheANT_OPTSenvironmentvariableonyoursystem.IfyouusethestartcmdfilefromtheFullEasyInstalltosetupatoolkitsession,editthatfiletochangethevalue.

ReferenceThissectionisdesignedtohelpuserstolocateinformationeasilyandquickly.ItincludesdocumentationfortheDITAOpenToolkit(DITA-OT)parametersandconfigurationproperties.

AntparametersCertainparametersapplytoallDITA-OTtransformations.OtherparametersarecommontotheHTML-basedtransformations.Finally,someparametersapplyonlytothespecifictransformationtypes.

ditacommandargumentsandoptionsTheditacommandtakesmandatoryargumentstoprocessDITA,manageplug-in,orprintinformationaboutthecommand.Optionscanbeusedmodifythecommandbehaviourorprovideadditionalconfiguration.

Command-linetoolparametersCertainparametersapplytoallDITA-OTtransformations.OtherparametersarecommontotheHTML-basedtransformations.Finally,someparametersapplyonlytothespecifictransformationtypes.

lib/configuration.propertiesfileThelib/configuration.propertiesfilecontrolscertaincommonproperties,aswellassomepropertiesthatcontrolPDFprocessing.

AntparametersCertainparametersapplytoallDITA-OTtransformations.OtherparametersarecommontotheHTML-basedtransformations.Finally,someparametersapplyonlytothespecifictransformationtypes.

Antparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.

Antparameters:CommonHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsehelp,HTMLHelp,JavaHelp,TocJS,HTML5,andXHTML.

Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Antparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.

Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.

Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Antparameters:OtherTheseAntparametersenableyoutoreloadstylesheetsthattheDITA-OTusesforspecificpre-processingstages.

Antparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.

Antparameters:HTML5andXHTMLtransformation

CertainparametersarespecifictotheHTML5andXHTMLtransformation.

Parenttopic:Reference

RelatedconceptsAnt

RelatedtasksPublishingDITAcontentfromAnt

Antparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.

Figure1.Antparameters:Alltransformations

args.debug

Specifieswhetherdebugginginformationisincludedinthelog.Theallowedvaluesareyesandno;thedefaultvalueisno.

args.draft

Specifieswhetherthecontentof<draft-comment>and<required-cleanup>elementsisincludedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstoXSLTparameterDRAFTinmostXSLTmodules.

Tip:ForPDFoutput,settingtheargs.draftparametertoyescausesthecontentsofthe<titlealts>elementtoberenderedbelowthetitle.

args.figurelink.style

Specifieshowcrossreferencestofiguresarestyledinoutput.TheallowedvaluesareNUMBERandTITLE.SpecifyingNUMBERresultsin"Figure5";specifyingTITLEresultsinthetitleofthefigure.CorrespondstotheXSLTparameterFIGURELINK.

Note:SupportforPDFwasaddedinDITA-OT2.0.BydefaultPDFusesthevalueNUMTITLE,whichisnotsupportedforothertransformtypes;thisresultsin"Figure5.Title".

args.filter

Specifiesafilterfiletobeusedtoinclude,exclude,orflag

content.

args.grammar.cache

Specifieswhetherthegrammar-cachingfeatureoftheXMLparserisused.Theallowedvaluesareyesandno;thedefaultvalueisno.

Note:Thisoptiondramaticallyspeedsupprocessingtime.However,thereisaknownproblemwithusingthisfeaturefordocumentsthatuseXMLentities.Ifyourbuildfailswithparsererrorsaboutentityresolution,setthisparametertono.

args.input

Specifiesthemasterfileforyourdocumentationproject.TypicallythisisaDITAmap,howeveritalsocanbeaDITAtopicifyouwanttotransformasingleDITAfile.Thepathcanbeabsolute,relativetoargs.input.dir,orrelativetothedirectorywhereyourproject'santbuildscriptresidesifargs.input.dirisnotdefined.

args.input.dir

Specifiesthebasedirectoryforyourdocumentationproject.Thedefaultvalueistheparentdirectoryofthefilespecifiedbyargs.input.

args.logdir

SpecifiesthelocationwheretheDITA-OTplaceslogfilesforyourproject.

args.rellinks

Specifieswhichlinkstoincludeintheoutput.Thefollowingvaluesaresupported:

none–Nolinksareincluded.

all–Alllinksareincluded.

nofamily–Parent,child,next,andpreviouslinksarenotincluded.

Defaultvaluedependsonthetransformationtype.

args.tablelink.style

Specifieshowcrossreferencestotablesarestyled.SpecifyingNUMBERresultsin"Table5";specifyingTITLEresultsinthetitleofthetable.CorrespondstotheXSLTparameterTABLELINK.

Note:SupportforPDFwasaddedinDITA-OT2.0.BydefaultPDFusesthevalueNUMTITLE,whichisnotsupportedforothertransformtypes;thisresultsin"Table5.Title".

clean.temp

SpecifieswhethertheDITA-OTdeletesthefilesinthetemporarydirectoryafteritfinishesabuild.Theallowedvaluesareyesandno;thedefaultvalueisyes.

dita.dir

SpecifieswheretheDITA-OTisinstalled.

dita.temp.dir

Specifiesthelocationofthetemporarydirectory.ThetemporarydirectoryiswheretheDITA-OTwritestemporaryfilesthataregeneratedduringthetransformationprocess.

dita.input.valfile

Specifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.Filterfilesmusthavea.ditavalor.DITAVALextension.

Note:Deprecatedinfavoroftheargs.filterparameter.

generate.copy.outer

SpecifieswhethertogenerateoutputfilesforcontentthatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:

1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory.

3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.

Seegenerate.outer.copyparameterformoreinformation.

onlytopic.in.map

Specifieswhetherfilesthatarelinkedto,orreferencedwitha@conrefattribute,generateoutput.Ifsettoyes,onlyfilesthatarereferenceddirectlyfromthemapwillgenerateoutput.

outer.control

SpecifieshowtheDITAOThandlescontentfilesthatarelocatedinorbelowthedirectorycontainingthemasterDITAmap.Thefollowingvaluesaresupported:

fail–Failquicklyiffilesaregoingtobegeneratedorcopiedoutsideofthedirectory

warn(default)–Completetheoperationiffileswillbegeneratedorcopiedoutsideofthedirectory,butlogawarning

quiet–Quietlyfinishwithonlythosefiles;donotgeneratewarningsorerrors.

Thegen-list-without-flaggingAnttaskgeneratesaharmlesswarningforcontentthatislocatedoutsidethemapdirectory;youcansuppressthesewarningsbysettingthepropertytoquiet.

Warning:MicrosoftHTMLHelpCompilercannotproduceHTMLHelpfordocumentationprojectsthatuseoutercontent.ThecontentfilesmustresideinorbelowthedirectorycontainingthemasterDITAmapfile,andthemapfilecannotspecify".."atthestartofthe@hrefattributesfor<topicref>elements.

output.dir

Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.

transtype

Specifiestheoutputformat.Youcancreateplug-instoaddnewvaluesforthisparameter;bydefault,thefollowingvaluesareavailable:

docbook

eclipsehelp

eclipsecontent

htmlhelp

javahelp

wordrtf

validate

SpecifieswhethertheDITA-OTvalidatesthecontent.Theallowedvaluesaretrueandfalse;thedefaultvalueistrue.

Parenttopic:Antparameters

Antparameters:CommonHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsehelp,HTMLHelp,JavaHelp,TocJS,HTML5,andXHTML.

Figure1.Antparameters:HTML-basedtransformations

args.artlbl

Specifieswhethertogeneratealabelforeachimage;thelabelwillcontaintheimagefilename.Theallowedvaluesareyesandno;thedefaultvalueisno.

args.breadcrumbs

Specifieswhethertogeneratebreadcrumblinks.Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstotheXSLTparameterBREADCRUMBS.

args.copycss

Specifieswhethertocopythecustom.cssfiletotheoutputdirectory.

args.css

Specifiesthenameofacustom.cssfile.

args.csspath

Specifiesthelocationofacopied.cssfilerelativetotheoutputdirectory.CorrespondstoXSLTparameterCSSPATH.

args.cssroot

Specifiesthedirectorythatcontainsthecustom.cssfile.DITA-OTwillcopythefilefromthislocation.

args.dita.locale

Specifiesthelanguagelocalefiletouseforsortingindexentries.

Note:ThisparameterisnotavailablefortheXHTMLtransformation.

args.ftr

SpecifiesanXMLfilethatcontainscontentforarunningfooter.CorrespondstoXSLTparameterFTR.

Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.

args.gen.default.meta

Specifieswhethertogenerateextrametadatathattargetsparentalcontrolscanners,metaelementswithname="security"andname="Robots".Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstotheXSLTparametergenDefMeta.

args.gen.task.lbl

Specifieswhethertogenerateheadingsforsectionswithintasktopics.TheallowedvaluesareYESandNO;thedefaultvalueisNO.CorrespondstotheXSLTparameterGENERATE-TASK-LABELS.

args.hdf

SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.

args.hdr

SpecifiesanXMLfilethatcontainscontentforarunningheader.CorrespondstotheXSLTparameterHDR.

args.hide.parent.link

SpecifieswhethertohidelinkstoparenttopicsintheHTMLorXHTMLoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstotheXSLTparameterNOPARENTLINK.

Note:Thisparameterisdeprecatedinfavoroftheargs.rellinksparameter.

args.indexshow

Specifieswhetherthecontentof<indexterm>elementsarerenderedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.

args.outext

SpecifiesthefileextensionforHTMLorXHTMLoutput.Thedefaultvalueishtml.CorrespondstoXSLTparameterOUTEXT.

args.xhtml.classattr

SpecifieswhethertoincludetheDITAclassancestryinsidetheXHTMLelements.Forexample,the<prereq>element(whichisspecializedfromsection)wouldgenerateclass="sectionprereq.Theallowedvaluesareyesandno;thedefaultvalueisyes.CorrespondstotheXSLTparameterPRESERVE-DITA-CLASS.

Note:BeginningwithDITAOTrelease1.5.2,thedefaultvalueisyes.Forrelease1.5and1.5.1,thedefaultvaluewasno.

args.xsl

SpecifiesacustomXSLfiletobeusedinsteadofthedefaultXSLtransformation(xsl\dita2xhtml.xsl).Theparametermustspecifyafullyqualifiedfilename.

generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.

RelatedreferenceAntparameters:EclipsecontenttransformationAntparameters:EclipsehelptransformationAntparameters:HTMLHelptransformationAntparameters:JavaHelptransformationAntparameters:HTML5andXHTMLtransformation

Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Figure1.Antparameters:Eclipsecontenttransformation

args.eclipsecontent.toc

SpecifiesthenameoftheTOCfile

RelatedconceptsEclipsecontenttransformation

RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations

Antparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.

Figure1.Antparameters:Eclipsehelptransformation

args.eclipsehelp.toc

SpecifiesthenameoftheTOCfile.

args.eclipse.country

Specifiestheregionforthelanguagethatisspecifiedbytheargs.eclipse.languageparameter.Forexample,us,ca,andgbwouldclarifyavalueofensetfortheargs.eclipse.languageparameter.ThecontentwillbemovedintotheappropriatedirectorystructureforanEclipsefragment.

args.eclipse.language

Specifiesthebaselanguagefortranslatedcontent,suchasenforEnglish.Thisparameterisaprerequisitefortheargs.eclipse.countryparameter.ThecontentwillbemovedintotheappropriatedirectorystructureforanEclipsefragment.

args.eclipse.provider

SpecifiesthenameofthepersonororganizationthatprovidestheEclipsehelp.ThedefaultvalueisDITA.

Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.

args.eclipse.version

Specifiestheversionnumbertoincludeintheoutput.Thedefaultvalueis0.0.0.

args.eclipse.symbolic.name

Specifiesthesymbolicname(akapluginID)intheoutputforanEclipseHelpproject.The@idvaluefromtheDITAmaportheEclipsemapcollection(Eclipsehelpspecialization)isthesymbolicnamefortheplugininEclipse.Thedefaultvalueisorg.sample.help.doc.

RelatedconceptsEclipsehelptransformation

Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.

Figure1.Antparameters:HTMLHelptransformation

args.htmlhelp.includefile

SpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.

RelatedconceptsHTMLhelptransformation

Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Figure1.Antparameters:JavaHelptransformation

args.javahelp.map

SpecifiesthenameoftheditamapfileforaJavaHelpproject.

args.javahelp.toc

SpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.

RelatedconceptsJavaHelptransformation

Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Figure1.Antparameters:ODTtransformation

args.odt.img.embed

DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.

RelatedconceptsODTtransformation

RelatedreferenceAntparameters:Alltransformations

Antparameters:OtherTheseAntparametersenableyoutoreloadstylesheetsthattheDITA-OTusesforspecificpre-processingstages.

Figure1.Antparameters:Other

dita.preprocess.reloadstylesheetdita.preprocess.reloadstylesheet.conrefdita.preprocess.reloadstylesheet.maprefdita.preprocess.reloadstylesheet.mappulldita.preprocess.reloadstylesheet.maplinkdita.preprocess.reloadstylesheet.topicpull

SpecifieswhethertheDITA-OTreloadstheXSLstylesheetsthatareusedforthetransformation.Theallowedvaluesaretrueandfalse;thedefaultvalueisfalse.

Tip:Settheparametertotrueifyouwanttousemorethanonesetofstylesheetstoprocessacollectionoftopics.TheparameteralsoisusefulforlargeprojectsthatgenerateJavaout-of-memoryerrorsduringtransformation.Alternatively,youcanadjustthesizeofyourJavamemoryheapifsettingdita.preprocess.reloadstylesheetforthisreason.

Antparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.

Figure1.Antparameters:PDFtransformation

args.bookmap-order

Specifiesifthefrontmatterandbackmattercontentorderisretainedinbookmap.Theallowedvaluesareretainanddiscard;thedefaultvalueisdiscard.

args.fo.userconfig

SpecifiestheuserconfigurationfileforFOP.

args.gen.task.lbl

Specifieswhethertogenerateheadingsforsectionswithintasktopics.TheallowedvaluesareYESandNO;thedefaultvalueisNO.CorrespondstotheXSLTparameterGENERATE-TASK-LABELS.

args.rellinks

Specifieswhichlinkstoincludeintheoutput.Thefollowingvaluesaresupported:

none–Nolinksareincluded.

all–Alllinksareincluded.

nofamily–Parent,child,next,andpreviouslinksarenotincluded.

Defaultvaluedependsonthetransformationtype.

args.xsl.pdf

SpecifiesanXSLfilethatisusedtooverridethedefaultXSLtransformation

(plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xsl).Youmustspecifythefullyqualifiedfilename.

custom.xep.config

SpecifiestheuserconfigurationfileforRenderX.

customization.dir

Specifiesthecustomizationdirectory.

pdf.formatter

SpecifiestheXSLprocessor.Thefollowingvaluesaresupported:

ah–AntennaHouseFormatter

fop(default)–ApacheFOP

xep–RenderXXEPEngine

Thefull-easy-installpackagecomeswithApacheFOP;otherXSLprocessorsmustbeseparatelyinstalled.

publish.required.cleanup

Specifieswhetherdraft-commentandrequired-cleanupelementsareincludedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisthevalueoftheargs.draftparameter.CorrespondstoXSLTparameterpublishRequiredCleanup.

Note:Thisparameterisdeprecatedinfavoroftheargs.draftparameter.

retain.topic.fo

SpecifieswhethertoretainthegeneratedFOfile.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheconfigurationpropertyorg.dita.pdf2.use-out-tempissetto

false,thisparameterisignored.

RelatedconceptsPDFtransformation

RelatedreferenceAntparameters:Alltransformations

Antparameters:HTML5andXHTMLtransformationCertainparametersarespecifictotheHTML5andXHTMLtransformation.

Figure1.Antparameters:HTML5andXHTMLtransformation

args.xhtml.contenttarget

Specifiesthevalueofthe@targetattributeonthe<base>elementintheTOCfile.Thedefaultvalueiscontentwin.

args.xhtml.toc

SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.

args.xhtml.toc.class

Specifiesthevalueofthe@classattributeonthe<body>elementintheTOCfile.Foundinmap2htmltoc.xsl.

RelatedconceptsXHTMLtransformationHTML5transformation

ditacommandargumentsandoptionsTheditacommandtakesmandatoryargumentstoprocessDITA,manageplug-in,orprintinformationaboutthecommand.Optionscanbeusedmodifythecommandbehaviourorprovideadditionalconfiguration.

dita-fname-ifile[options]

dita-install{file|url}

dita-uninstallid

dita-help

dita-version

Arguments

-f,-formatname

docbook

eclipsehelp

eclipsecontent

htmlhelp

javahelp

wordrtf

-i,-inputfile

-installfile-installurl

Installplug-infromalocalZIPfileorfromaURL.

-uninstallid

Uninstallplug-inwiththeID.

-h,-help

Printcommandusagehelp.

-version

Printversioninformationandexit.

Options

-o,-outputdir

Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentooutsubdirectoryofthecurrentdirectory.

-filterfile

Specifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.

-tempdir

-v,-verbose

Verboselogging.

-d,-debug

Debuglogging.

-l,-logfilefile

Outputloggingmessagesintoafile.

-Dproperty=value

Specifyavalueforaproperty.SupportedpropertiesarethesameasAntparametersandaretransformationtypespecific.

-propertyfilefile

Loadallpropertiesfromafile.Propertiesspecifiedwith-Doptiontakeprecedence.

Command-linetoolparametersCertainparametersapplytoallDITA-OTtransformations.OtherparametersarecommontotheHTML-basedtransformations.Finally,someparametersapplyonlytothespecifictransformationtypes.

Youmustsupplytheparameterstothecommand-linetoolusingthefollowingsyntax:

/parameter:value

Command-linetoolparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.

Command-linetoolparameters:AllHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsecontent,Eclipsehelp,HTML5,HTMLHelp,JavaHelp,TocJS,andXHTML.

Command-linetoolparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Command-linetoolparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.

Command-linetoolparameters:HTMLhelptransformationCertainparametersarespecifictotheHTMLhelptransformation.

Command-linetoolparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Command-linetoolparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Command-linetoolparameters:PDFtransformation

CertainparametersarespecifictothePDF2transformation.

Command-linetoolparameters:HTML5andXHTMLtransformationCertainparametersarespecifictotheHTML5andXHTMLtransformation.

RelatedtasksPublishingDITAcontentfromthecommand-linetool

Command-linetoolparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.

Figure1.Command-linetoolparameters:Alltransformations

basedir

Thedirectorywhereyourproject'santbuildscriptresides.TheDITA-OTwilllookforyour.ditafilesrelativetothisdirectory.DITA-OT'sdefaultbuildscriptsetsthisasanattributeoftheproject,butyoucanalsodefineitasaprojectproperty.

cleantemp

SpecifieswhethertheDITA-OTdeletesthefilesinthetemporarydirectoryafteritfinishesabuild.Theallowedvaluesareyesandno;thedefaultvalueisyes.

Specifieswhetherdebugginginformationisincludedinthelog.Theallowedvaluesareyesandno;thedefaultvalueisno.

ditadir

SpecifieswheretheDITA-OTisinstalled.

ditalocale

Specifiesthelanguagelocalefiletouseforsortingindexentries.

Note:ThisparameterisnotavailablefortheXHTMLtransformation.

Specifieswhetherthecontentof<draft-comment>and<required-cleanup>elementsisincludedintheoutput.The

allowedvaluesareyesandno;thedefaultvalueisno.CorrespondstoXSLTparameterDRAFTinmostXSLTmodules.

Tip:ForPDFoutput,settingtheargs.draftparametertoyescausesthecontentsofthe<titlealts>elementtoberenderedbelowthetitle.

filter

Specifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.Filterfilesmusthavea.ditavalor.DITAVALextension.

Note:Deprecatedinfavoroftheargs.filterparameter.

grammarcache

Specifieswhetherthegrammar-cachingfeatureoftheXMLparserisused.Theallowedvaluesareyesandno;thedefaultvalueisno.

Note:Thisoptiondramaticallyspeedsupprocessingtime.However,thereisaknownproblemwithusingthisfeaturefordocumentsthatuseXMLentities.Ifyourbuildfailswithparsererrorsaboutentityresolution,setthisparametertono.

logdir

SpecifiesthelocationwheretheDITA-OTplaceslogfilesforyourproject.

outdir

Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.

tempdir

transtype

docbook

eclipsehelp

eclipsecontent

htmlhelp

javahelp

wordrtf

validate

SpecifieswhethertheDITA-OTvalidatesthecontent.Theallowedvaluesaretrueandfalse;thedefaultvalueistrue.

Parenttopic:Command-linetoolparameters

Command-linetoolparameters:AllHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsecontent,Eclipsehelp,HTML5,HTMLHelp,JavaHelp,TocJS,andXHTML.

Note:Youmustspecifyanabsolutepathasthevalueforthefollowingparameters:

Figure1.Command-linetoolparameters:AllHTML-basedtransformations

args.css

Specifiesthenameofacustom.cssfile.

artlbl

Specifieswhethertogeneratealabelforeachimage;thelabelwillcontaintheimagefilename.Theallowedvaluesareyesandno;thedefaultvalueisno.

copycss

Specifieswhethertocopythecustom.cssfiletotheoutputdirectory.

csspath

Specifiesthelocationofacopied.cssfilerelativetotheoutputdirectory.CorrespondstoXSLTparameterCSSPATH.

cssroot

Specifiesthedirectorythatcontainsthecustom.cssfile.DITA-OTwillcopythefilefromthislocation.

SpecifiesanXMLfilethatcontainscontentforarunningfooter.CorrespondstoXSLTparameterFTR.

generateouter

SpecifieswhethertogenerateoutputfilesforcontentthatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:

1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory.

3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.

Seegenerate.outer.copyparameterformoreinformation.

SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.

SpecifiesanXMLfilethatcontainscontentforarunningheader.CorrespondstotheXSLTparameterHDR.

indexshow

Specifieswhetherthecontentof<indexterm>elementsare

renderedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.

onlytopicinmap

Specifieswhetherfilesthatarelinkedto,orreferencedwitha@conrefattribute,generateoutput.Ifsettoyes,onlyfilesthatarereferenceddirectlyfromthemapwillgenerateoutput.

outercontrol

SpecifieshowtheDITAOThandlescontentfilesthatarelocatedinorbelowthedirectorycontainingthemasterDITAmap.Thefollowingvaluesaresupported:

fail–Failquicklyiffilesaregoingtobegeneratedorcopiedoutsideofthedirectory

warn(default)–Completetheoperationiffileswillbegeneratedorcopiedoutsideofthedirectory,butlogawarning

quiet–Quietlyfinishwithonlythosefiles;donotgeneratewarningsorerrors.

Thegen-list-without-flaggingAnttaskgeneratesaharmlesswarningforcontentthatislocatedoutsidethemapdirectory;youcansuppressthesewarningsbysettingthepropertytoquiet.

Warning:MicrosoftHTMLHelpCompilercannotproduceHTMLHelpfordocumentationprojectsthatuseoutercontent.ThecontentfilesmustresideinorbelowthedirectorycontainingthemasterDITAmapfile,andthemapfilecannotspecify".."atthestartofthe@hrefattributesfor<topicref>elements.

usetasklabels

Specifieswhethertogenerateheadingsforsectionswithintask

topics.TheallowedvaluesareYESandNO;thedefaultvalueisNO.CorrespondstotheXSLTparameterGENERATE-TASK-LABELS.

xhtmlclass

SpecifieswhethertoincludetheDITAclassancestryinsidetheXHTMLelements.Forexample,the<prereq>element(whichisspecializedfromsection)wouldgenerateclass="sectionprereq.Theallowedvaluesareyesandno;thedefaultvalueisyes.CorrespondstotheXSLTparameterPRESERVE-DITA-CLASS.

Note:BeginningwithDITAOTrelease1.5.2,thedefaultvalueisyes.Forrelease1.5and1.5.1,thedefaultvaluewasno.

SpecifiesacustomXSLfiletobeusedinsteadofthedefaultXSLtransformation(xsl\dita2xhtml.xsl).Theparametermustspecifyafullyqualifiedfilename.

RelatedreferenceCommand-linetoolparameters:EclipsecontenttransformationCommand-linetoolparameters:EclipsehelptransformationCommand-linetoolparameters:HTMLhelptransformationCommand-linetoolparameters:JavaHelptransformationCommand-linetoolparameters:HTML5andXHTMLtransformation

Command-linetoolparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Figure1.Command-linetoolparameters:Eclipsecontenttransformation

eclipsecontenttoc

SpecifiesthenameoftheTOCfile

RelatedconceptsEclipsecontenttransformation

RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations

Command-linetoolparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.

Figure1.Command-linetoolparameters:Eclipsehelptransformation

eclipsehelptoc

SpecifiesthenameoftheTOCfile.

provider

SpecifiesthenameofthepersonororganizationthatprovidestheEclipsehelp.ThedefaultvalueisDITA.

version

Specifiestheversionnumbertoincludeintheoutput.Thedefaultvalueis0.0.0.

RelatedconceptsEclipsehelptransformation

Command-linetoolparameters:HTMLhelptransformationCertainparametersarespecifictotheHTMLhelptransformation.

Figure1.Command-linetoolparameters:HTMLhelptransformation

htmlhelpincludefile

SpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.

RelatedconceptsHTMLhelptransformation

Command-linetoolparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Figure1.Command-linetoolparameters:JavaHelptransformation

javahelpmap

SpecifiesthenameoftheditamapfileforaJavaHelpproject.

javahelptoc

SpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.

RelatedconceptsJavaHelptransformation

Command-linetoolparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Figure1.Command-linetoolparameters:ODTtransformation

odtimgembed

DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.

RelatedconceptsODTtransformation

RelatedreferenceCommand-linetoolparameters:Alltransformations

Command-linetoolparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.

Figure1.Command-linetoolparameters:PDFtransformation

fooutputrellinks

Specifieswhethertorenderrelatedlinksintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheargs.fo.include.rellinksparameterisspecified,thisparameterisignored.

fouserconfig

SpecifiestheuserconfigurationfileforFOP.

retaintopicfo

SpecifieswhethertoretainthegeneratedFOfile.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheconfigurationpropertyorg.dita.pdf2.use-out-tempissettofalse,thisparameterisignored.

xslpdf

SpecifiesanXSLfilethatisusedtooverridethedefaultXSLtransformation(plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xsl).Youmustspecifythefullyqualifiedfilename.

RelatedconceptsPDFtransformation

RelatedreferenceCommand-linetoolparameters:Alltransformations

Command-linetoolparameters:HTML5andXHTMLtransformationCertainparametersarespecifictotheHTML5andXHTMLtransformation.

Figure1.Command-linetoolparameters:HTML5andXHTMLtransformation

xhtmltoc

SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.

RelatedconceptsXHTMLtransformationHTML5transformation

lib/configuration.propertiesfileThelib/configuration.propertiesfilecontrolscertaincommonproperties,aswellassomepropertiesthatcontrolPDFprocessing.

Table1.Propertiessetinthelib/configuration.propertiesfileProperty Description

default.language

Specifiesthelanguagethatisusediftheinputfiledoesnothavethe@xml:langattributesetontherootelement.Bydefault,thisissettoen.TheallowedvaluesarethosethataredefinedinIETFBCP47,TagsfortheIdentificationofLanguages.

generate-debug-attributes

Specifieswhetherthe@xtrfand@xtrcdebuggingattributesaregeneratedinthetemporaryfiles.Thefollowingvaluesareallowed:

true(default)—Enablesgenerationofdebuggingattributes

false—Disablesgenerationofdebuggingattributes

Note:Disablingdebuggingattributesreducesthesizeoftemporaryfilesandthusreducesmemoryconsumption.However,thelogmessagesnolongerhavethesourceinformationavailableandthustheabilitytodebugproblemsmightdeteriorate.

SpecifieshowtheDITA-OThandleserrorsanderrorrecovery.Thefollowingvaluesareallowed:

strict—Whenanerrorisencountered,theDITA-OTstopsprocessing.

processing-mode lax(default)—Whenanerrorisencountered,theDITA-OTattemptstorecoverfromit.

skip—Whenanerrorisencountered,theDITAcontinuesprocessingbutdoesnotattempterrorrecovery.

org.dita.pdf2.i18n.enabled

(PDFtransformationonly)EnablesI18Nfontprocessing.Thefollowingvaluesareallowed:

true(default)—EnablesI18Nprocessing

false—DisablesI18Nprocessing

org.dita.pdf2.use-out-temp

(PDFtransformationonly)SpecifieswhethertheXSL-FOprocessingwritestheintermediatefiles(forexample,thetopic.fofile)totheoutputdirectory.Thefollowingvaluesareallowed:

true—Writeintermediatefilestotheoutputdirectory

false(default)—Writeintermediatefilestothetemporarydirectory

plugindirs

Asemicolon-separatedlistofdirectorypathsthattheDITA-OTsearchesforplug-instointegrate;anyrelativepathsareresolvedagainsttheDITA-OTbasedirectory.Anyimmediatesubdirectorythatcontainsaplugin.xmlfileisintegrated

plugin.ignoresAsemicolon-separatedlistofdirectorynamestobeignoredduringplug-inintegration;anyrelativepathsareresolvedagainsttheDITA-OTbasedirectory.

DITAOpenToolkitDeveloperReferenceTheDITAOpenToolkitDeveloperReferenceisdesignedtoprovidemoreadvancedinformationabouttheDITA-OT.ItisgearedtoanaudiencethatneedsinformationabouttheDITA-OTarchitecture,configuringandextendingtheDITA-OT,andcreatingDITA-OTplug-ins.

ArchitectureoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISspecificationfortheDarwinInformationTypingArchitecture(DITA).ThetoolkitusesAnt,XSLT,andJavatotransformDITAcontent(mapsandtopics)intodifferentdeliverableformats.

ExtendingtheDITAOpenToolkitThereareseveralmethodsthatcanbeusedtoextendthetoolkit;notallofthemarerecommendedorsupported.Thebestwaytocreatemostextensionsiswithaplug-in;extendeddocumentationforcreatingplug-insisprovidedinthenextsection.

ConfiguringtheDITAOpenToolkitTheDITAOTuses.propertiesfilesthatstoreconfigurationsettingsfortheDITAOTanditsplug-ins.TheconfigurationpropertiesareavailabletobothAntandJavaprocesses,butunlikeargumentproperties,theycannotbesetatruntime.

CreatingDITA-OTplug-insTheDITAOpenToolkitcomeswithabuiltinmechanismforaddinginextensionsthroughplug-ins.Theseplug-insmaydoawidevarietyofthings,suchasaddingsupportforspecializedDITADTDsorSchemas,integratingprocessingoverrides,orevenprovidingentirelynewoutputtransforms.Plug-insarethebestwaytoextendthetoolkitinawaythatisconsistent,easilysharable,andeasytopreservethroughtoolkitupgrades.

CustomizingPDFoutputYoucanbuildaDITA-OTplug-inthatcontainsacustomizedPDF

transformation.

InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.

Implementationdependentfeatures

Extendedfunctionality

ArchitectureoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISspecificationfortheDarwinInformationTypingArchitecture(DITA).ThetoolkitusesAnt,XSLT,andJavatotransformDITAcontent(mapsandtopics)intodifferentdeliverableformats.

DITA-OTprocessingstructureTheDITA-OTimplementsamulti-stage,map-drivenarchitecturetoprocessDITAcontent.Eachstageintheprocessexaminessomeorallofthecontent;somestagesresultintemporaryfilesthatareusedbylatersteps,whileothersstagesresultinupdatedcopiesoftheDITAcontent.Mostoftheprocessingtakesplaceinatemporaryworkingdirectory;thesourcefilesthemselvesarenevermodified.

DITA-OTprocessingmodulesTheDITA-OTprocessingpipelineisimplementedusingAnt.IndividualmoduleswithintheAntscriptareimplementedineitherJavaorXSLT,dependingonsuchfactorsasperformanceorrequirementsforcustomization.VirtuallyallAntandXSLTmodulescanbeextendedbyaddingaplug-intothetoolkit;newAnttargetsmaybeinsertedbeforeoraftercommonprocessing,andnewrulesmaybeimportedintocommonXSLTmodulestooverridedefaultprocessing.

DITA-OTprocessingorderTheorderofprocessingisoftensignificantwhenevaluatingDITAcontent.AlthoughtheDITAspecificationdoesnotmandateaspecificorderforprocessing,theDITA-OThasdeterminedthatperformingfilteringbeforeconrefresolutionbestmeetsuserexpectations.Switchingtheorderofprocessing,whilelegal,maygivedifferentresults.

Pre-processingmodulesThepre-processingoperationisasetofstepsthattypicallyrunsatthebeginningofeveryDITA-OTtransformation.Eachsteporstage

correspondstoanAnttargetinthebuildpipeline;thepreprocesstargetcallstheentiresetofsteps.

HTML-basedprocessingmodulesTheDITA-OTshipswithseveralvarietiesofHTMLoutput,eachofwhichfollowsroughlythesamepaththroughtheprocessingpipeline.AllHTML-basedtransformationbeginwiththesamecalltothepre-processingmodule,afterwhichtheygenerateHTMLfilesandthenbranchtocreatethetransformation-specificnavigationfiles.

PDFprocessingmodulesThePDF(formerlyknownasPDF2)transformationprocessrunsthepre-processingroutineandfollowsitbyaseriesofadditionaltargets.Thesestepsworktogethertocreateamergedsetofcontent,convertthemergedcontenttoXSL-FO,andthenformattheXSL-FOfiletoPDF.

OpenDocumentFormatprocessingmodulesTheodttransformationcreatesabinaryfileusingtheOASISOpenDocumentFormat.

Parenttopic:DITAOpenToolkitDeveloperReference

DITA-OTprocessingstructureTheDITA-OTimplementsamulti-stage,map-drivenarchitecturetoprocessDITAcontent.Eachstageintheprocessexaminessomeorallofthecontent;somestagesresultintemporaryfilesthatareusedbylatersteps,whileothersstagesresultinupdatedcopiesoftheDITAcontent.Mostoftheprocessingtakesplaceinatemporaryworkingdirectory;thesourcefilesthemselvesarenevermodified.

TheDITA-OTisdesignedasapipeline.Mostofthepipelineiscommontoalloutputformats;itisknownasthepre-processingstage.Ingeneral,anyDITAprocessbeginswiththiscommonsetofpre-processingroutines.Oncethepre-processingiscompleted,thepipelinedivergesbasedontherequestedoutputformat.Someprocessingisstillcommontomultipleoutputformats;forexample,EclipseHelpandHTMLHelpbothusethesameroutinestogenerateXHTMLtopics,afterwhichthetwopipelinesbranchtocreatedifferentsetsofnavigationfiles.

Thefollowingimageillustrateshowthepipelineworksforsomecommonoutputtypes:Docbook,PDF,EclipseHelp,XHTML,JavaHelp,andHTMLHelp.

Parenttopic:ArchitectureoftheDITAOpenToolkit

DITA-OTprocessingmodulesTheDITA-OTprocessingpipelineisimplementedusingAnt.IndividualmoduleswithintheAntscriptareimplementedineitherJavaorXSLT,dependingonsuchfactorsasperformanceorrequirementsforcustomization.VirtuallyallAntandXSLTmodulescanbeextendedbyaddingaplug-intothetoolkit;newAnttargetsmaybeinsertedbeforeoraftercommonprocessing,andnewrulesmaybeimportedintocommonXSLTmodulestooverridedefaultprocessing.

XSLTmodules

TheXSLTmodulesuseshellfiles.Typically,eachshellfilebeginsbyimportingcommonrulesthatapplytoalltopics.Thissetofcommonprocessingrulesmayinturnimportadditionalcommonmodules,suchasthoseusedforreportingerrorsordeterminingthedocumentlocale.Afterthecommonrulesareimported,additionalimportscanbeincludedinordertosupportprocessingforDITAspecializations.

Forexample,XHTMLprocessingiscontrolledbythexsl\dita2xhtml.xslfile.Theshellbeginsbyimportingcommonrulesthatareapplicabletoallgeneraltopics:xslhtml\dita2htmlImpl.xsl.Afterthat,additionalXSLToverridesareimportedforspecializationsthatrequiremodifiedprocessing.Forexample,anoverrideforreferencetopicsisimportedinordertoadddefaultheaderstopropertytables.Additionalmodulesareimportedfortasks,forthehighlightingdomain,andforseveralotherstandardspecializations.AfterthestandardXSLToverridesoccur,plug-insmayaddinadditionalprocessingrulesforlocalstylesorforadditionalspecializations.

Javamodules

JavamodulesaretypicallyusedwhenXSLTisapoorfit,suchasforprocessesthatmakeuseofstandardJavalibraries(likethoseusedforindexsorting).Javamodulesarealsousedinmanycaseswhereastepinvolvescopyingfiles,suchastheinitialprocesswheresourcefilesareparsedandcopiedtoatemporaryprocessingdirectory.

DITA-OTprocessingorderTheorderofprocessingisoftensignificantwhenevaluatingDITAcontent.AlthoughtheDITAspecificationdoesnotmandateaspecificorderforprocessing,theDITA-OThasdeterminedthatperformingfilteringbeforeconrefresolutionbestmeetsuserexpectations.Switchingtheorderofprocessing,whilelegal,maygivedifferentresults.

TheDITA-OTprojecthasfoundthatfilteringfirstprovidesseveralbenefits.Considerthefollowingsamplethatcontainsa<note>elementthatbothusesconrefandcontainsa@productattribute:

<noteconref="documentA.dita#doc/note"product="MyProd"/>

Ifthe@conrefattributeisevaluatedfirst,thendocumentAmustbeparsedinordertoretrievethenotecontent.Thatcontentisthenstoredinthecurrentdocument(orinarepresentationofthatdocumentinmemory).However,ifallcontentwithproduct="MyProd"isfilteredout,thenthatworkisalldiscardedlaterinthebuild.

Ifthefilteringisdonefirst(asintheDITA-OT),thiselementisdiscardedimmediately,anddocumentAisneverexamined.Thisprovidesseveralimportantbenefits:

Timeissavedbydiscardingunusedcontentasearlyaspossible;allfuturestepscanloadthedocumentwithoutthisextracontent.

Additionaltimeissavedcasebynotevaluatingthe@conrefattribute;infact,documentAdoesnotevenneedtobeparsed.

AnyuserreproducingthisbuilddoesnotneeddocumentA.Ifthecontentissenttoatranslationteam,thatteamcanreproduceanerror-freebuildwithoutdocumentA;thismeansdocumentAcanbekeptbackfromtranslation,preventingaccidentaltranslationandincreasedcosts.

Iftheorderofthesetwostepsisreversed,sothatconrefisevaluatedfirst,itispossiblethatresultswilldiffer.Forexample,inthecodesampleabove,the@productattributewilloverridetheproductsettingonthe

referencingnote.Assumethatthe<note>elementsindocumentAisdefinedasfollows:

<noteid="note"product="SomeOtherProduct">Thisisanimportantnote!</note>

Aprocessthatfiltersoutproduct="SomeOtherProduct"willremovethetargetoftheoriginalconrefbeforethatconrefiseverevaluated,whichwillresultinabrokenreference.Evaluatingconreffirstwouldresolvethereference,andonlylaterfilteroutthetargetoftheconref.Whilesomeusecasescanbefoundwherethisisthedesiredbehavior,benefitssuchasthosedescribedaboveresultedinthecurrentprocessingorderusedbytheDITA-OT..

Pre-processingmodulesThepre-processingoperationisasetofstepsthattypicallyrunsatthebeginningofeveryDITA-OTtransformation.EachsteporstagecorrespondstoanAnttargetinthebuildpipeline;thepreprocesstargetcallstheentiresetofsteps.

1. Generatelists(gen-list)Thegen-liststepexaminestheinputfilesandcreateslistsoftopics,images,documentproperties,orothercontent.Theselistsareusedbylaterstepsinthepipeline.Forexample,onelistincludesalltopicsthatmakeuseoftheconrefattribute;onlythosefilesareprocessedduringtheconrefstageofthebuild.ThisstepisimplementedinJava.

2. Debugandfilter(debug-filter)Thedebug-filterstepprocessesallreferencedDITAcontentandcreatescopiesinatemporarydirectory.AstheDITAcontentiscopied,filteringisperformed,debugginginformationisinserted,andtablecolumnnamesareadjusted.ThisstepisimplementedinJava.

3. Copyrelatedfiles(copy-files)Thecopy-filesstepcopiesnon-DITAresourcestotheoutputdirectory,suchasHTMLfilesthatarereferencedinamaporimagesthatarereferencedbyaDITAVALfile.

4. Resolvekeyref(keyref)ThekeyrefstepexaminesallthekeysthataredefinedintheDITAsourceandresolvedthekeyreferences.Linksthatmakeuseofkeysareupdatedsothatany@hrefvalueisreplacedbytheappropriatetarget;key-basedtextreplacementisalsoperformed.ThisstepisimplementedinJava.

5. Conrefpush(conrefpush)Theconrefpushstepresolves"conrefpush"references.Thissteponlyprocessesdocumentsthatuseconrefpushorthatareupdatedduetothepushaction.ThisstepisimplementedinJava.

6. Conref(conref)Theconrefstepresolvesconrefattributes,processingonlytheDITAmapsortopicsthatusethe@conrefattribute.ThisstepisimplementedinXSLT.

7. Movemetadata(move-meta-entries)Themove-meta-entriessteppushesmetadatabackandforthbetweenmapsandtopics.Forexample,indexentriesandcopyrightsinthemaparepushedintoaffectedtopics,sothatthetopicscanbeprocessedlaterinisolationwhileretainingallrelevantmetadata.ThisstepisimplementedinJava.

8. Resolvecodereferences(codref)Thecoderefstepresolvesreferencesmadewiththe<coderef>element.ThisstepisimplementedinJava.

9. Resolvemapreferences(mapref)ThemaprefstepresolvesreferencesfromoneDITAmaptoanother.ThisstepisimplementedinXSLT.

10. Pullcontentintomaps(mappull)Themappullsteppullscontentfromreferencedtopicsintomaps,andthencascadesdatawithinmaps.ThisstepisimplementedinXSLT.

11. Chunktopics(chunk)ThechunkstepbreaksapartandassemblesreferencedDITAcontentbasedonthe@chunkattributeinmaps.ThisstepisimplementedinJava.

12. Mapbasedlinking(maplinkandmove-links)Thesetwostepsworktogethertocreatelinksbasedonamapandmovethoselinksintothereferencedtopics.ThelinksarecreatedbasedonhierarchyintheDITAmap,the@collection-typeattribute,andrelationshiptables.ThisstepisimplementedinXSLTandJava.

13. Pullcontentintotopics(topicpull)

Thetopicpullsteppullscontentinto<xref>and<link>elements.ThisstepisimplementedinXSLT.

14. FlagginginthetoolkitBeginningwithDITA-OT1.7,flaggingsupportisimplementedasacommonpreprocessmodule.ThemoduleevaluatestheDITAVALagainstallflaggingattributes,andaddsDITA-OTspecifichintsintothetopicwhenflagsareactive.AnyextendedtransformtypemayusethesehintstosupportflaggingwithoutaddinglogictointerprettheDITAVAL.

Generatelists(gen-list)Thegen-liststepexaminestheinputfilesandcreateslistsoftopics,images,documentproperties,orothercontent.Theselistsareusedbylaterstepsinthepipeline.Forexample,onelistincludesalltopicsthatmakeuseoftheconrefattribute;onlythosefilesareprocessedduringtheconrefstageofthebuild.ThisstepisimplementedinJava.

Theresultofthislistisasetofseverallistfilesinthetemporarydirectory,includingdita.listanddita.xml.properties.

Listfileproperty Listfile Listpropertycanditopicsfile canditopics.list canditopicslist

codereffile coderef.list codereflist

conreffile conref.list conreflist

conrefpushfile conrefpush.list conrefpushlistconreftargetsfile conreftargets.list conreftargetslistcopytosourcefile copytosource.list copytosourcelistcopytotarget2sourcemapfile copytotarget2sourcemap.list copytotarget2sourcemaplistflagimagefile flagimage.list flagimagelist

fullditamapandtopicfile fullditamapandtopic.list fullditamapandtopiclist

fullditamapfile fullditamap.list fullditamaplist

fullditatopicfile fullditatopic.list fullditatopiclist

hrefditatopicfile hrefditatopic.list hrefditatopiclist

hreftargetsfile hreftargets.list hreftargetslisthtmlfile html.list htmllist

imagefile image.list imagelist

keyreffile keyref.list keyreflist

outditafilesfile outditafiles.list outditafileslistrelflagimagefile relflagimage.list relflagimagelistresourceonlyfile resourceonly.list resourceonlylistskipchunkfile skipchunk.list skipchunklistsubjectschemefile subjectscheme.list subjectschemelistsubtargetsfile subtargets.list subtargetslisttempdirToinputmapdir.relative.value uplevels

user.input.dir

user.input.file.listfile

user.input.file

Parenttopic:Pre-processingmodules

Nexttopic:Debugandfilter(debug-filter)

Debugandfilter(debug-filter)Thedebug-filterstepprocessesallreferencedDITAcontentandcreatescopiesinatemporarydirectory.AstheDITAcontentiscopied,filteringisperformed,debugginginformationisinserted,andtablecolumnnamesareadjusted.ThisstepisimplementedinJava.

ThefollowingmodificationsaremadetotheDITAsource:

IfaDITAVALfileisspecified,theDITAsourceisfilteredaccordingtotheentriesintheDITAVALfile.

Debuginformationisinsertedintoeachelementusingthe@xtrfand@xtrcattributes.Thevaluesoftheseattributesenablemessageslaterinthebuildtoreliablyindicatetheoriginalsourceoftheerror.Forexample,amessagemighttracebacktothefifth<ph>elementinaspecificDITAtopic.Withouttheseattributes,thatcountmightnolongerbeavailableduetofilteringandotherprocessing.

Thetablecolumnnamesareadjustedtouseacommonnamingscheme.Thisisdoneonlytosimplifylaterconrefprocessing.Forexample,ifatablerowispulledintoanothertable,thisensuresthatareferenceto"column5properties"willcontinuetoworkinthefifthcolumnofthenewtable.

Parenttopic:Pre-processingmodulesPrevioustopic:Generatelists(gen-list)Nexttopic:Copyrelatedfiles(copy-files)

Copyrelatedfiles(copy-files)Thecopy-filesstepcopiesnon-DITAresourcestotheoutputdirectory,suchasHTMLfilesthatarereferencedinamaporimagesthatarereferencedbyaDITAVALfile.

Parenttopic:Pre-processingmodulesPrevioustopic:Debugandfilter(debug-filter)Nexttopic:Resolvekeyref(keyref)

Resolvekeyref(keyref)ThekeyrefstepexaminesallthekeysthataredefinedintheDITAsourceandresolvedthekeyreferences.Linksthatmakeuseofkeysareupdatedsothatany@hrefvalueisreplacedbytheappropriatetarget;key-basedtextreplacementisalsoperformed.ThisstepisimplementedinJava.

Parenttopic:Pre-processingmodulesPrevioustopic:Copyrelatedfiles(copy-files)Nexttopic:Conrefpush(conrefpush)

Conrefpush(conrefpush)Theconrefpushstepresolves"conrefpush"references.Thissteponlyprocessesdocumentsthatuseconrefpushorthatareupdatedduetothepushaction.ThisstepisimplementedinJava.

Parenttopic:Pre-processingmodulesPrevioustopic:Resolvekeyref(keyref)Nexttopic:Conref(conref)

Conref(conref)Theconrefstepresolvesconrefattributes,processingonlytheDITAmapsortopicsthatusethe@conrefattribute.ThisstepisimplementedinXSLT.

Thevaluesofthe@idattributeonreferencedcontentarechangedastheelementsarepulledintothenewlocations.Thisensuresthatthevaluesofthe@idattributewithinthereferencingtopicremainunique.

Ifanelementispulledintoanewcontextalongwithacrossreferencethatreferencesthetarget,boththevaluesofthe@idand@xrefattributesareupdatedsothattheyremainvalidinthenewlocation.Forexample,areferencedtopicmightincludeasectionasinthefollowingexample:Figure1.Referencedtopicthatcontainsasectionandcrossreference

<topicid="referenced_topic">

<body>

<sectionid="sect"><title>Samplesection</title>

<p>Figure<xrefhref="#referenced_topic/fig"/>containsancodesamplethatdemonstrates....</p>

<figid="fig"><title>Codesample</title>

</fig>

</section>

</body>

</topic>

Whenthesectionisreferencedusinga@conrefattribute,thevalueofthe@idattributeonthe<fig>elementismodifiedtoensurethatitremainsuniqueinthenewcontext.Atthesametime,the<xref>elementisalsomodifiedsothatitremainsvalidasalocalreference.Forexample,ifthereferencingtopichasan@idsetto"new_topic",thentheconrefed<section>elementmaylooklikethisintheintermediatedocument.Figure2.Resolvedconrefed<section>elementaftertheconrefstep

<sectionid="sect"><title>Samplesection</title>

<p>Figure<xrefhref="#new_topic/d1e25"/>containsancodesamplethatdemonstrates....</p>

<figid="d1e25"><title>Codesample</title>

</fig>

</section>

Inthiscase,thevalueofthe@idattributeonthe<fig>elementhasbeenchangedtoageneratedvalueof"d1e25".Atthesametime,the<xref>elementhasbeenupdatedtousethatnewgeneratedID,sothatthecrossreferenceremainsvalid.

Parenttopic:Pre-processingmodulesPrevioustopic:Conrefpush(conrefpush)Nexttopic:Movemetadata(move-meta-entries)

Movemetadata(move-meta-entries)Themove-meta-entriessteppushesmetadatabackandforthbetweenmapsandtopics.Forexample,indexentriesandcopyrightsinthemaparepushedintoaffectedtopics,sothatthetopicscanbeprocessedlaterinisolationwhileretainingallrelevantmetadata.ThisstepisimplementedinJava.

Parenttopic:Pre-processingmodulesPrevioustopic:Conref(conref)Nexttopic:Resolvecodereferences(codref)

Resolvecodereferences(codref)Thecoderefstepresolvesreferencesmadewiththe<coderef>element.ThisstepisimplementedinJava.

The<coderef>isusedtoreferencecodestoredexternallyinnon-XMLdocuments.Duringthepre-processingstep,thereferencedcontentispulledintothecontaining<codeblock>element.

Parenttopic:Pre-processingmodulesPrevioustopic:Movemetadata(move-meta-entries)Nexttopic:Resolvemapreferences(mapref)

Resolvemapreferences(mapref)ThemaprefstepresolvesreferencesfromoneDITAmaptoanother.ThisstepisimplementedinXSLT.

Mapsreferenceothermapsbyusingthefollowingsortsofmarkup:<topicrefhref="other.ditamap"format="ditamap"/>

<maprefhref="other.ditamap"/>

Asaresultofthemaprefstep,theelementthatreferencesanothermapisreplacedbythetopicreferencesfromtheothermap.Relationshiptablesarepulledintothereferencingmapasachildoftherootelement(<map>oraspecializationof<map>).

Parenttopic:Pre-processingmodulesPrevioustopic:Resolvecodereferences(codref)Nexttopic:Pullcontentintomaps(mappull)

Pullcontentintomaps(mappull)Themappullsteppullscontentfromreferencedtopicsintomaps,andthencascadesdatawithinmaps.ThisstepisimplementedinXSLT.

ThemappullstepmakesthefollowingchangestotheDITAmap:

TitlesarepulledfromreferencedDITAtopics.Unlessthe@locktitleattributeissetto"yes",thepulledtitlesreplacethenavigationtitlesspecifiedonthe<topicref>elements.

The<linktext>elementissetbasedonthetitleofthereferencedtopic,unlessitisalreadyspecifiedlocally.

The<shortdesc>elementissetbasedontheshortdescriptionofthereferencedtopic,unlessitisalreadyspecifiedlocally.

The@typeattributeisseton<topicref>elementsthatreferencelocalDITAtopics.Thevalueofthe@typeattributeissettovalueoftherootelementofthetopic;forexample,a<topicref>elementthatreferencesatasktopicisgivena@typeattributesetto"task"".

Attributesthatcascade,suchas@tocandprint,aremadeexplicitonanychild<topicref>elements.Thisallowsfuturestepstoworkwiththeattributesdirectly,withoutreevaluatingthecascadingbehavior.

Parenttopic:Pre-processingmodulesPrevioustopic:Resolvemapreferences(mapref)Nexttopic:Chunktopics(chunk)

Chunktopics(chunk)ThechunkstepbreaksapartandassemblesreferencedDITAcontentbasedonthe@chunkattributeinmaps.ThisstepisimplementedinJava.

TheDITA-OThasimplementedprocessingforthefollowingvaluesofthe@chunkattribute:

select-topic

select-document

select-branch

by-topic

by-document

to-content

to-navigation

Parenttopic:Pre-processingmodulesPrevioustopic:Pullcontentintomaps(mappull)Nexttopic:Mapbasedlinking(maplinkandmove-links)

RelatedinformationChunkingdefinitionintheDITA1.2specification

Mapbasedlinking(maplinkandmove-links)Thesetwostepsworktogethertocreatelinksbasedonamapandmovethoselinksintothereferencedtopics.ThelinksarecreatedbasedonhierarchyintheDITAmap,the@collection-typeattribute,andrelationshiptables.ThisstepisimplementedinXSLTandJava.

ThemaplinkmodulerunsanXSLTprogramthatevaluatesthemap;itplacesallthegeneratedlinksintoasinglefileinthetemporarydirectory.Themove-linksmodulethenrunsaJavaprogramthatpushesthegeneratedlinksintotheapplicabletopics.

Parenttopic:Pre-processingmodulesPrevioustopic:Chunktopics(chunk)Nexttopic:

Pullcontentintotopics(topicpull)Thetopicpullsteppullscontentinto<xref>and<link>elements.ThisstepisimplementedinXSLT.

Ifan<xref>elementdoesnotcontainlinktext,thetargetisexaminedandthelinktextispulled.Forexample,areferencetoatopicpullsthetitleofthetopic;areferencetoalistitempullsthenumberoftheitem.Ifthe<xref>elementreferencesatopicthathasashortdescription,andthe<xref>elementdoesnotalreadycontainachild<desc>element,a<desc>elementiscreatedthatcontainsthetextfromthetopicshortdescription.

Theprocessissimilarfor<link>elements.Ifthe<link>elementdoesnothaveachild<linktext>element,oneiscreatedwiththeappropriatelinktext.Similarly,ifthe<link>elementdoesnothaveachild<desc>element,andtheshortdescriptionofthetargetcanbedetermined,a<desc>elementiscreatedthatcontainsthetextfromthetopicshortdescription.

Parenttopic:Pre-processingmodulesPrevioustopic:Mapbasedlinking(maplinkandmove-links)Nexttopic:Flagginginthetoolkit

FlagginginthetoolkitBeginningwithDITA-OT1.7,flaggingsupportisimplementedasacommonpreprocessmodule.ThemoduleevaluatestheDITAVALagainstallflaggingattributes,andaddsDITA-OTspecifichintsintothetopicwhenflagsareactive.AnyextendedtransformtypemayusethesehintstosupportflaggingwithoutaddinglogictointerprettheDITAVAL.

EvaluatingtheDITAVALflags

Flaggingisimplementedasareusablemoduleduringthepreprocessstage.IfaDITAVALfileisnotusedwithabuild,thisstepisskippedwithnochangetothefile.

Whenaflagisactive,relevantsectionsoftheDITAVALitselfarecopiedintothetopicasasub-elementofthecurrenttopic.Theactiveflagsareenclosedinapseudo-specializationofthe<foreign>element(referredtoasapseudo-specializationbecauseitisusedonlyunderthecovers,withalltopictypes;itisnotintegratedintoanyshippeddocumenttypes).

<ditaval-startprop>

Whenanyflagisactiveonanelement,a<ditaval-startprop>elementwillbecreatedasthefirstchildoftheflaggedelement:

<ditaval-startpropclass="+topic/foreignditaot-d/ditaval-startprop">

The<ditaval-startprop>elementwillcontainthefollowing:

Iftheactiveflagsshouldcreateanewstyle,thatstyleisincludedusingstandardCSSmarkuponthe@outputclassattribute.OutputtypesthatmakeuseofCSS,suchasXHTML,canusethisvalueas-is.

Ifstylesconflict,anda<style-conflict>elementexistsintheDITAVAL,itwillbecopiedasachildof<ditaval-startprop>.

Any<prop>or<revprop>elementsthatdefineactiveflagswillbecopiedinaschildrenofthe<ditaval-startprop>element.Any<startflag>childrenofthepropertieswillbeincluded,but<endflag>childrenwillnot.

<ditaval-endprop>

Whenanyflagisactiveonanelement,a<ditaval-endprop>elementwillbecreatedasthelastchildoftheflaggedelement:

<ditaval-endpropclass="+topic/foreignditaot-d/ditaval-endprop">

CSSvaluesand<styleconflict>elementsarenotincludedonthiselement.

Any<prop>or<revprop>elementsthatdefineactiveflagswillbecopiedinaschildrenof<ditaval-prop>.Any<endflag>childrenofthepropertieswillbeincluded,but<startflag>childrenwillnot.

Supportingflagsinoverridesorcustomtransformtypes

Formosttransformtypes,the<foreign>elementshouldbeignoredbydefault,becausearbitrarynon-DITAcontentmaynotmixwellunlesscodedforaheadoftime.Ifthe<foreign>elementisignoredbydefault,orifaruleisaddedtospecificallyignore<ditaval-startprop>and<ditaval-endprop>,thentheaddedelementswillhavenoimpactonatransform.Ifdesired,flaggingsupportmaybeintegratedatanytimeinthefuture.

Theprocessingdescribedaboverunsaspartofthecommonpreprocess,soanytransformthatusesthedefaultpreprocesswillgetthetopicupdates.Tosupportgeneratingflagsasimages,XSLTbasedtransformscanusedefaultfallthroughprocessinginmostcases.Forexample,ifaparagraphisflagged,thefirstchildof<p>willcontainthestartflaginformation;addingaruletohandleimagesin<ditaval-startprop>willcausetheimagetoappearatthestartoftheparagraphcontent.

Insomecasesfallthroughprocessingwillnotresultinvalidoutput;forthosecases,theflagsmustbeexplicitlyprocessed.ThisisdoneintheXHTMLtransformforelementslike<ol>,becausefallthroughprocessingwouldplaceimagesinbetween<ol>and<li>.Tohandlethis,thecodeprocesses<ditaval-startprop>beforestartingtheelement,and<ditaval-endprop>attheend.Fallthroughprocessingisthendisabledforthoseelementsaschildrenof<ol>.

ExampleDITAVAL

AssumethefollowingDITAVALfileisinuseduringabuild.ThisDITAVALwillbeusedforeachofthefollowingcontentexamples.

<propaction="flag"att="audience"style="underline"val="user"backcolor="green"/>

<propaction="flag"att="platform"style="overline"val="win"backcolor="blue"/>

<propaction="flag"att="platform"val="linux"style="overline"backcolor="blue">

<startflagimageref="startlin.png"><alt-text>Startlinux</alt-text></startflag>

<endflagimageref="endlin.png"><alt-text>Endlinux</alt-text></endflag>

</prop>

<revpropaction="flag"style="double-underline"val="rev2">

<startflagimageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>

<endflagimageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>

</revprop>

</val>

Contentexample1:addingstyle

Nowassumethefollowingparagraphexistsinatopic.Classattributesareincluded,astheywouldnormallybeinthemiddleofthepreprocessroutine;@xtrfand@xtrcareleftoffforclarity.

<paudience="user">Simpleuser;includesstylebutnoimages</p>

BasedontheDITAVALabove,audience="user"resultsinastylewithunderliningandwithagreenbackground.TheinterpretedCSSvalueisaddedto@outputclasson<ditaval-startprop>,andtheactualpropertydefinitionisincludedatthestartandendoftheelement.Theoutputfromtheflaggingsteplookslikethis(withnewlinesaddedforclarity,andclassattributesaddedastheywouldappearinthetemporaryfile):

Theresultingfileaftertheflaggingsteplookslikethis;forclarity,newlinesareadded,while@xtrfand@xtrcareremoved:

<paudience="user"class="-topic/p">

<ditaval-startpropclass="+topic/foreignditaot-d/ditaval-startprop"

outputclass="background-color:green;text-decoration:underline;">

</ditaval-startprop>

Simpleuser;includesstylebutnoimages

</ditaval-endprop>

Contentexample2:conflictingstyles

Thisexampleincludesaparagraphwithconflictingstyles.Whentheaudienceandplatformattributesarebothevaluated,theDITAVALindicatesthatthebackgroundcolorisbothgreenandblue.Inthissituation,the<style-conflict>elementisevaluatedtodeterminehowtostylethecontent.

<paudience="user"platform="win">Conflictingstyles(stillnoimages)</p>

The<style-conflict>elementresultsinabackgroundcolorofred,sothisvalueisaddedto@outputclasson<ditaval-startprop>.Asabove,activepropertiesarecopiedintothegeneratedelements;the<style-conflict>elementitselfisalsocopiedintothegenerated<ditaval-startprop>element.

<paudience="user"platform="win"class="-topic/p">

outputclass="background-color:red;">

Conflictingstyles(stillnoimages)

</ditaval-endprop>

Contentexample3:addingimageflags

Thisexampleincludesimageflagsforboth@platformand@rev,whicharedefinedinDITAVAL<prop>and<revprop>elements.

<olplatform="linux"rev="rev2">

<li>Generateimagesforplatform="linux"andrev="2"</li>

Asabove,the<ditaval-startprop>and<ditaval-endprop>nesttheactivepropertydefinitions,withthecalculatedCSSvalueon@outputclass.The<ditaval-startprop>dropstheendingimage,and<ditaval-endprop>dropsthestartingimage.Tomakedocument-orderprocessingmoreconsistent,propertyflagsarealwaysincludedbeforerevisionsin<ditaval-startprop>,andtheorderisreversedfor<ditaval-endprop>.

<olplatform="linux"rev="rev2"class="-topic/ol">

outputclass="background-color:blue;text-decoration:underline;text-decoration:overline;">

<startflagimageref="startlin.png"><alt-text>Startlinux</alt-text></startflag>

</prop>

<startflagimageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>

</revprop>

<liclass="-topic/li">Generateimagesforplatform="linux"andrev="2"</li>

<endflagimageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>

</revprop>

<endflagimageref="endlin.png"><alt-text>Endlinux</alt-text></endflag>

</prop>

</ditaval-endprop>

Parenttopic:Pre-processingmodules

Previoustopic:

HTML-basedprocessingmodulesTheDITA-OTshipswithseveralvarietiesofHTMLoutput,eachofwhichfollowsroughlythesamepaththroughtheprocessingpipeline.AllHTML-basedtransformationbeginwiththesamecalltothepre-processingmodule,afterwhichtheygenerateHTMLfilesandthenbranchtocreatethetransformation-specificnavigationfiles.

CommonHTML-basedprocessingAfterthepre-processingoperationruns,HTML-basedbuildseachrunacommonseriesofAnttargetstogenerateHTMLfile.Navigationmaybecreatedbeforeorafterthissetofcommonroutines.

XHTMLprocessingAftertheXHTMLfilesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythexhtmltransformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.

HTML5processingAftertheHTML5filesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythehtml5transformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.

EclipsehelpprocessingTheeclipsehelptransformationgeneratesXHTML-basedoutputandfilesthatareneedingtocreateanEclipseHelpsystemplug-in.OncethenormalXHTMLprocesshasrun,thedita.map.eclipsetargetisusedtocreateasetofcontrolfilesandnavigationfiles.

TocJSprocessingThetocjstransformationwasoriginallycreatedasaplug-inthatdistributedoutsideofthetoolkit,butitnowshipsbundledinthedefaultpackages.ThisHTML5-basedoutputtypecreatesaJavaScriptbasedframesetwithTOCentriesthatexpandand

collapse.

HTMLHelpprocessingThehtmlhelptransformationcreatedHTMLHelpcontrolfiles.IfthebuildrunsonasystemthathastheHTMLHelpcompilerinstalled,thecontrolfilesarecompiledintoaCHMfile.

JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.

CommonHTML-basedprocessingAfterthepre-processingoperationruns,HTML-basedbuildseachrunacommonseriesofAnttargetstogenerateHTMLfile.Navigationmaybecreatedbeforeorafterthissetofcommonroutines.

Afterthepre-processingiscompleted,thefollowingtargetsarerunforalloftheHTML-basedbuilds:

Ifthearg.cssparameterispassedtothebuildtoaddaCSSfile,thecopy-csstargetcopiestheCSSfilefromitssourcelocationtotherelativelocationintheoutputdirectory.

IfaDITAVALfileisused,thecopy-revflagtargetcopiesthedefaultstart-andend-revisionflagsintotheoutputdirectory.

TheDITAtopicsareconvertedtoHTMLfiles.Unlessthe@chunkattributewasspecified,eachDITAtopicinthetemporarydirectorynowcorrespondstooneHTMLfile.Thedita.inner.topics.xhtmltargetisusedtoprocessdocumentsthatareinthemapdirectory(orsubdirectoriesofthemapdirectory).Thedita.outer.topics.xhtmltargetisusedtoprocessdocumentsthatareoutsideofthescopeofthemap,andthusmightendupoutsideofthedesignatedoutputdirectory.VariousDITA-OTparameterscontrolhowdocumentsprocessedbythedita.outer.topics.xhtmltargetarehandled.

Parenttopic:HTML-basedprocessingmodules

XHTMLprocessingAftertheXHTMLfilesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythexhtmltransformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.

HTML5processingAftertheHTML5filesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythehtml5transformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.

EclipsehelpprocessingTheeclipsehelptransformationgeneratesXHTML-basedoutputandfilesthatareneedingtocreateanEclipseHelpsystemplug-in.OncethenormalXHTMLprocesshasrun,thedita.map.eclipsetargetisusedtocreateasetofcontrolfilesandnavigationfiles.

Eclipseusemultiplefilestocontroltheplug-inbehavior.Someofthesecontrolfilesaregeneratedbythebuild,whileothersmightbecreatedmanually.ThefollowingAnttargetscontroltheEclipsehelpprocessing:

dita.map.eclipse.init

Setsupvariousdefaultproperties

dita.map.eclipse.toc

CreatestheXMLfilethatdefinesanEclipsetableofcontents

dita.map.eclipse.index

CreatesthesortedXMLfilethatdefinesanEclipseindex

dita.map.eclipse.plugin

Createstheplugin.xmlfilethatcontrolsthebehaviorofanEclipseplug-in

dita.map.eclipse.plugin.properties

CreatesaJavapropertiesfilethatsetspropertiesfortheplug-in,suchasnameandversioninformation

dita.map.eclipse.manifest.file

CreatesaMANIFEST.MFfilethatcontainsadditionalinformationusedbyEclipse

copy-plugin-files

Checksforthepresenceofcertaincontrolfilesinthesource

directory,andcopiesthosefoundtotheoutputdirectory

dita.map.eclipse.fragment.language.init

Worksinconjunctionwiththedita.map.eclipse.fragment.language.country.initanddita.map.eclipse.fragment.errortargetstocontrolEclipsefragmentfiles,whichareusedforversionsofaplug-increatedforanewlanguageorlocale

Severalofthetargetslistedabovehavematchingtemplatesforprocessingcontentthatislocatedoutsideofthescopeofthemapdirectory,suchasdita.out.map.eclipse.toc.

TocJSprocessingThetocjstransformationwasoriginallycreatedasaplug-inthatdistributedoutsideofthetoolkit,butitnowshipsbundledinthedefaultpackages.ThisHTML5-basedoutputtypecreatesaJavaScriptbasedframesetwithTOCentriesthatexpandandcollapse.

ThefollowingAnttargetscontrolmostoftheTocJSprocessing:

tocjsInit

Setsupdefaultproperties.ThistargetdetectswhetherbuildshavealreadyspecifiedanameforJavaScriptcontrolfile;ifnot,thedefaultnametoctree.jsisused.

map2tocjs

Callsthedita.map.tocjstarget,whichgeneratesthecontentsframeforTocJSoutput.

tocjsDefaultOutput

EnsuresthattheHTML5processingmoduleisrun.Ifscriptsaremissingrequiredinformation,suchasanameforthedefaultframeset,thistargetcopiesdefaultstyleandcontrolfiles.ThistargetwasaddtotheDITA-OTinversion1.5.4;earlierversionsoftheTocJStransformationcreatedonlytheJavaScriptcontrolfilebydefault.

HTMLHelpprocessingThehtmlhelptransformationcreatedHTMLHelpcontrolfiles.IfthebuildrunsonasystemthathastheHTMLHelpcompilerinstalled,thecontrolfilesarecompiledintoaCHMfile.

Oncethepre-processingandXHTMLprocessesarecompleted,mostoftheHTMLHelpprocessingishandledbythefollowingtargets:

dita.map.htmlhelp

CreatetheHHP,HHC,andHHKfiles.TheHHKfileissortedbasedonthelanguageofthemap.

dita.htmlhelp.convertlang

Ensuresthatthecontentcanbeprocessedcorrectlybythecompiler,andthattheappropriatecodepagesandlanguagesareused.

compile.HTML.Help

AttemptstodetecttheHTMLHelpcompiler.Ifthecompilerisfound,thefullprojectiscompiledintoasingleCHMfile.

JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.

TherearetwoprimaryAnttargets:

dita.map.javahelp

CreatesallofthefilesthatareneededtocompileJavaHelp,includingatableofcontents,sortedindex,andhelpmapfile.

compile.Java.Help

SearchesforaJavaHelpcompileronthesystem.Ifacompilerisfound,thehelpprojectiscompiled.

PDFprocessingmodulesThePDF(formerlyknownasPDF2)transformationprocessrunsthepre-processingroutineandfollowsitbyaseriesofadditionaltargets.Thesestepsworktogethertocreateamergedsetofcontent,convertthemergedcontenttoXSL-FO,andthenformattheXSL-FOfiletoPDF.

ThePDFprocessincludesmanyAnttargets.DuringatypicalconversionfrommaptoPDF,thefollowingtargetsaremostsignificant.

map2pdf2

CreatesamergedfilebycallingacommonJavamergemodule.Itthencallsthepublish.map.pdftargettodotheremainderofthework.

publish.map.pdf

Performssomeinitializationandthencallsthetransform.topic2pdftargettodotheremainderofprocessing.

transform.topic2pdf

ConvertsthemergedfiletoXSL-FO,generatesthePDF,anddeletesthetopic.fofile,unlessinstructedtokeepit.Usesthefollowingtargetstoperformthosetasks:

transform.topic2fo

ConvertthemergedfiletoanXSL-FOfile.ThisprocessiscomposedofseveralAnttargets.

Anttarget Description

transform.topic2fo.index

RunsaJavaprocesstosetupindexprocessing,basedonthedocumentlanguage.Thisstepgeneratesthefilestage1.xmlinthe

temporaryprocessingdirectory.

transform.topic2fo.flagging

SetsuppreprocessingforflaggingbasedonaDITAVALfile.Thisstepgeneratesthefilestage1a.xmlinthetemporaryprocessingdirectory.

transform.topic2fo.main

DoesthebulkoftheconversionfromDITAtoXSL-FO.ItrunstheXSLTbasedprocessthatcreatesstage2.fointhetemporaryprocessingdirectory

transform.topic2fo.i18n

DoesadditionallocalizationprocessingontheFOfile;itrunsaJavaprocessthatconvertsstage2.fointostage3.fo,followedbyanXSLTprocessthatconvertsstage3.fointotopic.fo.

transform.fo2pdf

Convertsthetopic.fofileintoPDFusingthespecifiedFOprocessor(AntennaHouse,XEP,orApacheFOP).

delete.fo2pdf.topic.fo

Deletesthetopic.fofile,unlessotherwisespecifiedbysettinganAntpropertyorcommand-lineoption.

OpenDocumentFormatprocessingmodulesTheodttransformationcreatesabinaryfileusingtheOASISOpenDocumentFormat.

Theodttransformationbeginswithpre-processing.Itthenrunseitherthedita.odt.package.topicordita.odt.package.maptarget,dependingonwhethertheinputtothetransformationisaDITAtopicoraDITAmap.Thefollowingdescriptionfocusesonthemapprocess,whichismadeupofthefollowingtargets:

dita.map.odt

ConvertsthemapintoamergedXMLfileusingtheJava-basedtopicmergemodule.ThenanXSLTprocessconvertsthemergedfileintothecontent.xmlfile.

dita.map.odt.stylesfile

ReadstheinputDITAmap,andthenusesXSLTtocreateastyles.xmlfileinthetemporarydirectory.

dita.out.odt.manifest.file

Createsthemanifest.xmlfile

Oncethesetargetshaverun,thegeneratedfilesarezippeduptogetherwithotherrequiredfilestocreatetheoutputODTfile.

ExtendingtheDITAOpenToolkitThereareseveralmethodsthatcanbeusedtoextendthetoolkit;notallofthemarerecommendedorsupported.Thebestwaytocreatemostextensionsiswithaplug-in;extendeddocumentationforcreatingplug-insisprovidedinthenextsection.

Creatingaplug-incanbeverysimpletoverycomplex,andisgenerallythebestmethodforchangingorextendingthetoolkit.Plug-inscanbeusedtoaccomplishalmostanymodificationthatisneededfortoolkitprocessing,fromminorstyletweakstoextensive,complicatednewoutputformats.

ThePDFprocesswasinitiallydevelopedindependentlyofthetoolkit,andcreateditsownextensionmechanismusingcustomizationdirectories.Many(butnotquiteall)ofthecapabilitiesavailablethroughPDFcustomizationdirectoriesarenowavailablethroughplug-ins.

UsingasingleXSLfileasanoverridebypassingitinasaparameter.Forexample,whenbuildingXHTMLcontent,theXSLparameterallowsuserstospecifyasinglelocalXSLfile(insideoroutsideofthetoolkit)thatiscalledinplaceofthedefaultXHTMLcode.Typically,thiscodeimportsthedefaultprocessingcode,andoverridesacoupleofprocessingroutines.Thisapproachisbestwhentheoverrideisveryminimal,orwhenthestylevariesfrombuildtobuild.However,anyextensionmadewiththissortofoverrideisalsopossiblewithaplug-in.

EditingDITA-OTcodedirectlymayworkinsomecases,butisnotadvised.Modifyingthecodedirectlysignificantlyincreasestheworkandriskinvolvedwithfutureupgrades.Itisalsolikelythatsuchmodificationswillbreakplug-insprovidedbyothers,limitingthefunctionavailabletothetoolkit.

Manuallyinstallingplug-insPlug-insaregenerallydistributedaszipfiles.Therearetwostepstoinstallingaplug-in:unzippingand

integrating.

Manuallyremovingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.

RebuildingtheDITA-OTdocumentationTheDITA-OTshipswithAntscriptsthatenableyoutorebuildthetoolkitdocumentation.Thisisespeciallyhelpfulifyourenvironmentcontainsplug-insthatintegrateadditionalmessagesintothetoolkit.

RelatedtasksInstallingplug-insRemovingplug-ins

Manuallyinstallingplug-insPlug-insaregenerallydistributedaszipfiles.Therearetwostepstoinstallingaplug-in:unzippingandintegrating.

Aboutthistask

Itispossibletodefineaplug-insothatitmaybeinstalledanywhere,althoughmostexpecttobeplacedinplugins/directoryinsideoftheDITA-OT.Mostplug-insdonotrequireaspecificinstalldirectoryandcangoineitherofthedefaultlocations,butsomemaycomewithinstructionsforaparticularinstalldirectory.

Procedure

1. Theunziptheplug-infiletopluginssubdirectory.Theplug-indirectoryshouldbenamedafterplug-inIDandversion,forexampleplugins/com.example.xhtml_1.0.0.

2. Runplug-inintegrationprocess.

Fromthetoolkitdirectory,runthefollowingcommandtointegrateallinstalledplug-ins:

ant-fintegrator.xml

AnybuildthatusestheJavacommandlineinterfaceautomaticallyrunstheintegratorbeforeprocessingbegins.

Antbasedbuildsmayimporttheintegrator.xmlfile,andaddintegratetothestartofthedependencychainforthebuild.

Note:Theintegrationprocessinconsideredpartoftheinstallationprocessandrunningitbeforeeachconversionwillincuraperformancepenalty.

Theintegrationprocesshastwomodes,laxandstrict.Inthestrictmodetheintegrationprocesswillimmediatelyfailifitencounterserrorsinplug-inconfigurationsorinstallationprocess.Inthelaxmode,theintegrationprocesswillcontinuetofinishregardlessoferrors;thelaxmodedoesnotimplyerrorrecoveryandmayleavetheDITA-OTinstallationintoabrokenstate.Thedefaultmodeislaxduetobackwardscompatibility,toruntheintegrationinstrictmode:

ant-fintegrator.xmlstrict

Togetmoreinformationabouttheintegrationprocess,runAntinverbosemode:

ant-fintegrator.xml-verbosestrict

Manuallyremovingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.

Procedure

1. Removeplug-ininstallationdirectory.

2. Runintegrationprocess.

ant-fintegrator.xml

RebuildingtheDITA-OTdocumentationTheDITA-OTshipswithAntscriptsthatenableyoutorebuildthetoolkitdocumentation.Thisisespeciallyhelpfulifyourenvironmentcontainsplug-insthatintegrateadditionalmessagesintothetoolkit.

Procedure

1. Changetothedocdirectory.

2. Runthefollowingcommand:

ant-fbuild.xmltarget

Thetargetparameterisoptionalandspecifiesaspecifictransformationtype.Ittakesthefollowingvalues:

build-html

build-htmlhelp

build-pdf

IfyoudonotspecifyanAnttarget,allthreeoutputformats(HTML5,HTMLhelp,andPDF)aregenerated.

ConfiguringtheDITAOpenToolkitTheDITAOTuses.propertiesfilesthatstoreconfigurationsettingsfortheDITAOTanditsplug-ins.TheconfigurationpropertiesareavailabletobothAntandJavaprocesses,butunlikeargumentproperties,theycannotbesetatruntime.

plugin.propertiesfileTheplugin.propertiesfileisusedtostoreconfigurationpropertiesthataresetbytheintegrationprocess.Thefileislocatedinthelib\org.dita.dost.platformdirectory;itisregeneratedeachtimetheintegrationprocessisrunandsoshouldnotbeeditedmanually.

Parenttopic:ConfiguringtheDITAOpenToolkit

CreatingDITA-OTplug-insTheDITAOpenToolkitcomeswithabuiltinmechanismforaddinginextensionsthroughplug-ins.Theseplug-insmaydoawidevarietyofthings,suchasaddingsupportforspecializedDITADTDsorSchemas,integratingprocessingoverrides,orevenprovidingentirelynewoutputtransforms.Plug-insarethebestwaytoextendthetoolkitinawaythatisconsistent,easilysharable,andeasytopreservethroughtoolkitupgrades.

Aplug-inconsistsofadirectory,typicallystoreddirectlywithintheplugins/directoryinsideoftheDITA-OT.Everyplug-iniscontrolledbyafilenamedplugin.xml,locatedintheplug-in'srootdirectory.

Benefitsofextendingthetoolkitthroughplug-insinclude:

Plug-insareeasilysharablewithotherusers,teams,orcompanies;typically,allthatisneededistounzipandrunasingleintegrationstep.Withmanybuilds,eventhatintegrationstepisautomatic.

Allowsoverridesorcustomizationstogrowfromsimpletocomplexovertime,withnoincreasedcomplexitytotheextensionmechanism.

Plug-inscanbemovedfromversiontoversionwithanupgradedtoolkitsimplybyunzippingagain,orbycopyingthedirectoryfromoneinstalltoanother;thereisnoneedtore-integratecodebasedonupdatestothecoreprocessing.

Plug-inscanbuilduponeachother.Ifyoulikeaplug-inprovidedbyoneuser,simplyinstallthatplug-in,andthencreateyourownthatbuildsonthatextension.Thetwoplug-inscanthenbedistributedtoyourteamasaunit,oryoucanevenshareyourownextensionswiththeoriginalprovider.

Plug-inconfigurationfileTheplugin.xmlcontrolsallaspectsofaplug-in,makingeachextensionvisibletotherestofthetoolkit.Thefileusespre-definedextensionpointstolocatechanges,andintegratesthosechangesintothecorecode.

ExtendingtheXMLCatalogTheXMLCatalogsextensionpointisusedtoupdatetheXMLCatalogsusedtoresolveDTDorSchemadocumenttypes,ortoaddURImappings.ThisisrequiredinordertosupportDITAspecializationsornewDITAdocumenttypeshells.

AddingnewtargetstotheAntbuildprocessTheAntconductorextensionpointisusedtomakenewtargetsavailabletotheAntprocessingpipeline.Thismaybedoneaspartofcreatinganewtransform,extendingpre-processing,orsimplytoprovideAnttargetsfortheuseofotherplug-ins.

AddingAnttargetstothepre-processpipelineEverystepinthepre-processpipelinedefinesanextensionpointbeforeandafterthestep,toallowplug-instointegrateadditionalprocessing.Thisallowsaplug-intoinsertanewstepbeforeanypre-processingstep,aswellasbeforeoraftertheentirepreprocesspipeline.

IntegratinganewtransformtypePlug-insmayintegrateanentirenewtransformtype.Thenewtransformtypecanbeverysimple,suchasanXHTMLbuildthatcreatesanadditionalcontrolfile;itcanalsobeverycomplex,addinganynumberofnewprocessingsteps.

OverridestyleswithXSLTTheXSLTimportextensionpointsareusedtooverridevariousstepsofXSLTprocessing.Forthis,theextensionattributeindicatesthestepthattheoverrideappliesto;thefileattributeisarelativepathtotheoverridewithinthecurrentplugin.TheplugininstallerwilladdanXSLimportstatementtothedefaultcodesothatyouroverridebecomesapartofthenormalbuild.

ModifyingoraddinggeneratedtextGeneratedtextisthetermforstringsthatareautomaticallyaddedbythebuild,suchas"Note"beforethecontentsofa<note>element.

PassingparameterstoexistingXSLTstepsPlug-inscandefinenewparameterstobepassedfromtheAntbuildintoexistingXSLTpipelinestages,usuallytohavethoseparametersavailableasglobal<xsl:param>valueswithinXSLToverrides.

AddingJavalibrariestotheclasspathIfyourAntorXSLTextensionsrequireadditionalJavalibrariesintheclasspath,youcanaddthemtotheglobalDITA-OTclasspathwiththefollowingfeature.

AddingdiagnosticmessagesPlug-inspecificwarninganderrormessagescanbeaddedtothesetofmessagessuppliedbytheDITA-OT.ThesemessagescanthenbeusedbyanyXSLToverride.

Managingplug-independenciesThe<require>elementinaplugin.xmlfileisusedtocreateadependencyonanotherplug-in.The<require>elementrequiresthepluginattributeinordertoreferencethedependency.

VersionandsupportinformationThefollowingextensionpointsareusedbyconventiontodefineversionandsupportinfowithinaplug-in.

Creatinganewplug-inextensionpointIfyourplug-inneedstodefineitsownextensionpointinanXMLfile,addthestring"_template"tothefilenamebeforethefilesuffix.Duringintegration,thisfilewillbeprocessedlikethebuilt-inDITA-OTtemplates.

Exampleplugin.xmlfileThefollowingisasampleofaplugin.xmlfile.ThisfileaddssupportforanewsetofspecializedDTDs,andincludesanoverridefortheXHTMLoutputprocessor.

Plug-inconfigurationfileTheplugin.xmlcontrolsallaspectsofaplug-in,makingeachextensionvisibletotherestofthetoolkit.Thefileusespre-definedextensionpointstolocatechanges,andintegratesthosechangesintothecorecode.

Therootelementoftheplugin.xmlfileis<plugin>,andmustspecifyanidattribute.Theidattributeisusedtoidentifytheplug-in,aswellastoidentifywhetherpre-requisiteplug-insareavailable.Theidattributeshouldfollowthesyntaxrules:

id::=token('.'token)*

token::=([0..9]|[a..zA..Z]|’_’|’-’)+

The<plugin>elementsupportsthefollowingchildelements:

<feature>definesanextensiontocontributetoadefinedextensionpoint.Thefollowingattributesaresupported:

Attribute Description Requiredextension extensionpointidentifier yes

valuecommaseparatedstringvalueoftheextension

eithervalueorfile

file filepathvalueoftheextension,relativetoplugin.xml

eithervalueorfile

type typeofthevalueattribute no

extension-pointdefinesnewaextensionpointthatcanbeusedbyotherplug-ins.Thefollowingattributesaresupported:

Attribute Description Requiredid extensionpointidentifier yesname extensionpointname no

<require>definesplug-independencies.Thefollowingattributesaresupported:

Attribute Description Required

pluginverticalbarseparatedlistofplug-insthatarerequired yes

importance flagwhetherplug-inisrequiredoroptional no

<template>definesfilesthatshouldbetreatedastemplates.Thefollowingattributesaresupported:

Attribute Description Requiredfile filepathtothetemplate,relativetoplugin.xml yes

Attribute Description Requiredtype metadatanameyesvalue metadatavalue yes

AnyextensionthatisnotrecognizedbytheDITA-OTisignored;allelementsotherthan<plugin>areoptional.Sinceversion1.5.3multipleextensiondefinitionswithinaplug-inconfigurationfilearecombined;inolderversionsonlythelastextensiondefinitionisused.

Parenttopic:CreatingDITA-OTplug-ins

ExtendingtheXMLCatalogTheXMLCatalogsextensionpointisusedtoupdatetheXMLCatalogsusedtoresolveDTDorSchemadocumenttypes,ortoaddURImappings.ThisisrequiredinordertosupportDITAspecializationsornewDITAdocumenttypeshells.

Todothis,firstcreateacatalogwithonlyyournewvalues,usingtheOASISCatalogformat,andplacethatinyourplug-in.Localfilereferencesinthecatalogshouldberelativetothelocationofthecatalog.Thefollowingextensionpointsareavailabletoworkwithcatalogs.

dita.specialization.catalog.relative

dita.specialization.catalog

AddsthecontentofthecatalogfiledefinedinfileattributetomainDITA-OTcatalogfile.

Remember:Thedita.specialization.catalogextensionisdeprecated.Usedita.specialization.catalog.relativeinstead.

org.dita.pdf2.catalog.relative

AddsthecontentofthecatalogfiledefinedinfileattributetomainPDFplug-incatalogfile.

Example

Thisexampleassumesthat"catalog-dita.xml"containsanOASIScatalogforanyDTDsorSchemasinsidethisplug-in.Thecatalogentriesinsideofcatalog-dita.xmlarerelativetothecatalogitself;whentheplug-inisintegrated,theywillbeaddedtothecoreDITA-OTcatalog(withthecorrectpath).

<pluginid="com.example.catalog">

<featureextension="dita.specialization.catalog.relative"file="catalog-dita.xml"/>

</plugin>

AddingnewtargetstotheAntbuildprocessTheAntconductorextensionpointisusedtomakenewtargetsavailabletotheAntprocessingpipeline.Thismaybedoneaspartofcreatinganewtransform,extendingpre-processing,orsimplytoprovideAnttargetsfortheuseofotherplug-ins.

dita.conductor.target.relative

dita.conductor.target

AddAntimporttomainAntbuildfile.

Remember:Thedita.conductor.targetextensionisdeprecated.Usedita.conductor.target.relativeinstead.

Example

ToextendAndprocessing,firstplaceyourextensionsinanAntprojectfilewithinyourplug-in,suchasmyAntStuff.xml.Next,createasmallwrapperfilemyAntStuffWrapper.xmlinthesamedirectory:

Thencreatethefollowingfeature:

<pluginid="com.example.ant">

<featureextension="dita.conductor.target.relative"file="myAntStuffWrapper.xml"/>

</plugin>

Whentheplug-inisintegrated,theimportsfrommyAntStuffWrapper.xmlwillbecopiedintobuild.xml(usingthecorrectpath).ThismakestargetsinmyAntStuff.xmlavailabletoanyotherprocessing.

AddingAnttargetstothepre-processpipelineEverystepinthepre-processpipelinedefinesanextensionpointbeforeandafterthestep,toallowplug-instointegrateadditionalprocessing.Thisallowsaplug-intoinsertanewstepbeforeanypre-processingstep,aswellasbeforeoraftertheentirepreprocesspipeline.

Thegroupofpreprocessingstepsdefinesextensionpointsbeforeandafterthefullpreprocessingchain.

depend.preprocess.pre

Preprocessingpre-target;extendingthistargetrunsyourAnttargetbeforethefullpreprocessroutinebegins.

depend.preprocess.post

Preprocessingpost-target;extendingthistargetrunsyourAnttargetafterthefullpreprocessroutinecompletes.

Inaddition,thereareextensionpointstoexecuteanAnttargetbeforeindividualpreprocessingsteps.

depend.preprocess.clean-temp.pre

Cleantemppre-target

depend.preprocess.gen-list.pre

Generatelistpre-target

depend.preprocess.debug-filter.pre

Debugandfilterpre-target

depend.preprocess.conrefpush.pre

Contentreferencepushpre-target

depend.preprocess.move-meta-entries.pre

Movemetaentriespre-target

depend.preprocess.conref.pre

Contentreferencepre-target

depend.preprocess.coderef.pre

Codereferencepre-target

depend.preprocess.mapref.pre

Mapreferencepre-target

depend.preprocess.keyref.pre

Resolvekeyreferencepre-target

depend.preprocess.mappull.pre

Mappullpre-target

depend.preprocess.chunk.pre

Chunkingpre-target

depend.preprocess.maplink.pre

Maplinkpre-target

depend.preprocess.move-links.pre

Movelinkspre-target

depend.preprocess.topicpull.pre

Topicpullpre-target

depend.preprocess.copy-files.pre

Copyfilespre-target

depend.preprocess.copy-image.pre

Copyimagespre-target

depend.preprocess.copy-html.pre

CopyHTMLpre-target

depend.preprocess.copy-flag.pre

Copyflagpre-target

depend.preprocess.copy-subsidiary.pre

Copysubsidiarypre-target

depend.preprocess.copy-generated-files.pre

Copygeneratedfilespre-target

Example

Thefollowingfeatureadds"myAntTargetBeforeChunk"Anttargettobeexecutedbeforethechunkstepinpreprocessing.ItassumesthatanAntfiledefiningthattargethasalreadybeenintegrated.

<pluginid="com.example.extendchunk">

<featureextension="depend.preprocess.chunk.pre"value="myAntTargetBeforeChunk"/>

</plugin>

Whenintegrated,theAnttarget"myAntTargetBeforeChunk"willbeaddedtotheAntdependencylistsothatitalwaysrunsimmediatelybeforetheChunkstep.

IntegratinganewtransformtypePlug-insmayintegrateanentirenewtransformtype.Thenewtransformtypecanbeverysimple,suchasanXHTMLbuildthatcreatesanadditionalcontrolfile;itcanalsobeverycomplex,addinganynumberofnewprocessingsteps.

Thetranstypeextensionpointisusedtodefineanew"transtype",ortransformtype,whichmakesuseoftargetsinyourAntextensions.Whenatransformtypeisdefined,thebuildexpectsAntcodetobeintegratedtodefinethetransformprocess.TheAntcodemustdefineatargetbasedonthenameofthetransformtype;ifthetransformtypeis"mystuff",theAntcodemustdefineatargetnameddita2mystuff.

dita.conductor.transtype.check

Addnewvaluetolistofvalidtransformationtypenames.

dita.transtype.print

Declaretranstypeasaprinttype.

Example

Thefollowingfeaturedefinesatransformtypeof"newtext"anddeclaresitasaprinttype;usingthistransformtypewillcausethebuildtolookforatargetdita2newtext,definedinarelatedAntextensionfromthethirdfeature:

<pluginid="com.example.newtext">

<featureextension="dita.conductor.transtype.check"value="newtext"/>

<featureextension="dita.transtype.print"value="newtext"/>

<featureextension="dita.conductor.target.relative"file="antWrapper.xml"/>

</plugin>

OverridestyleswithXSLTTheXSLTimportextensionpointsareusedtooverridevariousstepsofXSLTprocessing.Forthis,theextensionattributeindicatesthestepthattheoverrideappliesto;thefileattributeisarelativepathtotheoverridewithinthecurrentplugin.TheplugininstallerwilladdanXSLimportstatementtothedefaultcodesothatyouroverridebecomesapartofthenormalbuild.

ThefollowingXSLTstepsareavailabletooverrideinthecoretoolkit:

dita.xsl.xhtml

Overridesdefault(X)HTMLoutput(includingHTMLHelpandEclipseHelp).ThereferencedfileisintegrateddirectlyintotheXSLTstepthatgeneratesXHTML.

dita.xsl.xslfo

OverridesdefaultPDFoutput(formerlyknownasPDF2).ThereferencedfileisintegrateddirectlyintotheXSLTstepthatgeneratesXSL-FOforPDF.

dita.xsl.docbook

OverridesdefaultDocBookoutput.

dita.xsl.rtf

OverridesdefaultRTFoutput.

dita.xsl.eclipse.plugin

Overridesthestepthatgeneratesplugin.xmlforEclipse.

dita.xsl.conref

Overridesthepreprocessstepthatresolvesconref.

dita.xsl.topicpull

Overridesthepreprocessstep"topicpull"(thestepthatpullstextinto<xref>elements,amongotherthings).

dita.xsl.mapref

Overridesthepreprocessstep"mapref"(thestepthatresolvesreferencestoothermaps).

dita.xsl.mappull

Overridesthepreprocessstep"mappull"(thestepthatupdatesnavtitlesinmapsandcausesattributestocascade).

dita.xsl.maplink

Overridesthepreprocessstep"maplink"(thestepthatgeneratesmap-basedlinks).

Example

Thefollowingtwofilesrepresentacomplete,simplestyleplug-in.Theplugin.xmlfiledeclaresanXSLTfilethatextendsXHTMLprocessing;theXSLTfileoverridesdefaultheaderprocessingtoprovidea(theoretical)banner.

plugin.xml:

<pluginid="com.example.brandheader">

<featureextension="dita.xsl.xhtml"file="xsl/header.xsl"/>

</plugin>

xsl/header.xsl:

<xsl:stylesheetversion="1.0"

xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:templatename="gen-user-header">

<div><imgsrc="http://www.example.com/company_banner.jpg"

alt="ExampleCompanyBanner"/></div>

</xsl:template>

</xsl:stylesheet>

ModifyingoraddinggeneratedtextGeneratedtextisthetermforstringsthatareautomaticallyaddedbythebuild,suchas"Note"beforethecontentsofa<note>element.

Thegeneratedtextextensionpointisusedtoaddnewstringstothedefaultsetofgeneratedtext.Thereareseveralreasonsyoumaywanttousethis:

Itcanbeusedtoaddnewtextforyourownprocessingextensions;forexample,itcouldbeusedtoaddlocalizedversionsofthestring"Userresponse"toaidinrenderingtroubleshootinginformation.

Itcanbeusedtooverridethedefaultstringsinthetoolkit;forexample,itcouldbeusedtoresettheEnglishstring"Figure"to"Fig".

Itcanbeusedtoaddsupportfornewlanguages(fornon-PDFtransformsonly;PDFrequiresmorecomplicatedlocalizationsupport).Forexample,itcouldbeusedtoaddsupportforVietnameseorGaelic;itcouldalsobeusedtosupportanewvariantofapreviouslysupportedlanguage,suchasAustralianEnglish.

dita.xsl.strings

Addnewstringstogeneratedtextfile.

Example:addingnewstrings

Firstcopythefilexsl/common/strings.xmltoyourplug-in,andeditittocontainthelanguagesthatyouareprovidingtranslationsfor("en-us"mustbepresent).Forthissample,copythefileintoyourplug-inasxsl/my-new-strings.xml.Thenewstringsfilewilllooksomethinglikethis:

<!--Providestringsformyplug-in;thisplug-insupports

English,Icelandic,andRussian.-->

<langxml:lang="en"filename="mystring-en-us.xml"/>

<langxml:lang="en-us"filename="mystring-en-us.xml"/>

<langxml:lang="is"filename="mystring-is-is.xml"/>

<langxml:lang="is-is"filename="mystring-is-is.xml"/>

<langxml:lang="ru"filename="mystring-ru-ru.xml"/>

<langxml:lang="ru-ru"filename="mystring-ru-ru.xml"/>

</langlist>

Next,copythefilexsl/common/strings-en-us.xmltoyourplug-in,andreplacethecontentwithyourownstrings(besuretogivethemuniquenameattributes).Dothesameforeachlanguagethatyouareprovidingatranslationfor.Forexample,thefilemystring-en-us.xmlmightcontain:

<stringsxml:lang="en-us">

<strname="String1">Englishgeneratedtext</str>

<strname="AnotherString">AnotherStringinEnglish</str>

</strings>

Usethefollowingextensioncodetoincludeyourstringsinthesetofgeneratedtext:

<pluginid="com.example.strings">

<featureextension="dita.xsl.strings"file="xsl/my-new-strings.xml"/>

</plugin>

Thestringisnowavailabletothe"getString"templateusedinmanyDITA-OTXSLTfiles.Forexample,ifprocessinginacontextwherethexml:langvalueis"en-us",thefollowingcallwouldreturn"AnotherStringinEnglish":

<xsl:call-templatename="getString">

<xsl:with-paramname="stringName"select="'AnotherString'"/>

</xsl:call-template>

Note:Iftwoplug-insdefinethesamestring,theresultswillbenon-deterministic,somultipleplug-insshouldnottrytocreatethesamegeneratedtextstring.OnecommonwaytoavoidthisproblemistoensurethenameattributesusedtolookupthestringvaluearerelatedtotheIDorpurposeofyourplug-in.

Example:modifyingexistingstrings

Theprocessformodifyingexistinggeneratedtextisexactlythesameasforaddingnewtext,exceptthatthestringsyouprovideoverridevaluesthatalreadyexist.Tobegin,setupthexsl/my-new-strings.xmlfileinyourplug-inasinthepreviousexample.

Next,copythefilexsl/common/strings-en-us.xmltoyourplug-in,andchoosethestringsyouwishtochange(besuretoleavethenameattributeunchanged,becausethisisthekeyusedtolookupthestring).Createastringsfileforeachlanguagethatneedstomodifyexistingstrings.Forexample,thenewfilemystring-en-us.xmlmightcontain:

<stringsxml:lang="en-us">

<strname="Figure">Fig</str>

<strname="Draftcomment">ADDRESSTHISDRAFTCOMMENT</str>

</strings>

Tointegratethenewstrings,usethesamemethodasabovetoaddthesestringstoyourplugin.xmlfile.Oncethisplug-inisintegrated,whereXHTMLoutputpreviouslygeneratedtheterm"Figure",itwillnowgenerate"Fig";whereitpreviouslygenerated"Draftcomment",itwillnowgenerate"ADDRESSTHISDRAFTCOMMENT".Thesamestringsinotherlanguageswillnotbemodifiedunlessyoualsoprovidenewversionsforthoselanguages.

Note:Iftwoplug-insoverridethesamestringinthesamelanguage,theresultswillbenon-deterministic(eitherstringmaybeusedunderdifferentconditions).Multipleplug-insshouldnotoverridethesamegeneratedtextstringforasinglelanguage.

Example:addinganewlanguage

Theprocessforaddinganewlanguageisexactlythesameasforaddingnewtext,exceptyouareeffectivelyjusttranslatinganexistingstringsfile.Tobegin,setupthexsl/my-new-strings.xmlfileinyourplug-inasinthepreviousexamples.Inthiscase,theonlydifferenceisthatyouareaddingamappingtonewlanguages;forexample,thefollowingfilewouldbeusedtosetupsupportforVietnamese:

<!--Maplanguageswithxml:lang="vi"orxml:lang="vi-vn"

tothetranslationsinthisplug-in.-->

<langxml:lang="vi"filename="strings-vi.xml"/>

<langxml:lang="vi-vn"filename="strings-vi.xml"/>

</langlist>

Next,copythefilexsl/common/strings-en-us.xmltoyourplug-in,andrenameittomatchthelanguageyouwishtoadd.Forexample,tosupportVietnamesestringsyoumaywanttopickanamelikestrings-vi.xml.Inthatfile,changethexml:langattributeontherootelementtomatchyournewlanguage.

Oncethefileisready,translatethecontentsofeach<str>element(besuretoleavethenameattributeunchanged).Repeatthisprocessforeachnewlanguageyouwishtoadd.

Tointegratethenewlanguages,usethesamemethodasabovetoaddthesestringstoyourplugin.xmlfile.Oncethisplug-inisintegrated,non-PDFbuildswillincludesupportforVietnamese;insteadofgeneratingtheEnglishword"Caution",theelement<notetype="caution"xml:lang="vi">maygeneratesomethinglike"chúý".

Note:Iftwoplug-insaddsupportforthesamelanguageusingdifferentvalues,theresultswillbenon-deterministic(translationsfromeitherplug-inmaybepickedupunderdifferentconditions).

RelatedreferenceLanguagessupportedbythecoretoolkit

PassingparameterstoexistingXSLTstepsPlug-inscandefinenewparameterstobepassedfromtheAntbuildintoexistingXSLTpipelinestages,usuallytohavethoseparametersavailableasglobal<xsl:param>valueswithinXSLToverrides.

Tocreatenewparameters,createafileinsertParameters.xmlwhichcontainsoneormoreAnt<param>elements.Italsoneedsa<dummy>wrapperelementaroundtheparameters.Forexample,thefollowingparameterwillbepassedintotheXSLTfilewithavalueof${antProperty},butonlyifthatparameterisdefined:

<dummy>

<paramname="paramNameinXSLT"expression="${antProperty}"if="antProperty"/>

</dummy>

Passthevalueusingthefollowingextensions:

dita.conductor.html.param

PassparameterstoHTMLandHTMLHelpXSLT

dita.conductor.xhtml.param

PassparameterstoXHTMLandEclipseHelpXSLT

dita.conductor.xhtml.toc.param

PassparameterstoXHTMLTOCXSLT

dita.conductor.eclipse.toc.param

PassparameterstoEclipseHelpTOCXSLT

dita.preprocess.conref.param

PassparameterstoconrefXSLT

dita.preprocess.mapref.param

PassparameterstomaprefXSLT

dita.preprocess.mappull.param

PassparameterstomappullXSLT

dita.preprocess.maplink.param

PassparameterstomaplinkXSLT

dita.preprocess.topicpull.param

PassparameterstotopicpullXSLT

dita.conductor.pdf2.param

PassparameterstoPDF2XSLT

Example

Thefollowingplug-inwillpasstheparametersdefinedinsideofinsertParameter.xmlasinputtotheXHTMLprocess.Generally,anadditionalXSLToverridewillmakeuseoftheparametertodosomethingnewwiththegeneratedcontent.

<pluginid="com.example.newparam">

<featureextension="dita.conductor.xhtml.param"file="insertParameters.xml"/>

</plugin>

AddingJavalibrariestotheclasspathIfyourAntorXSLTextensionsrequireadditionalJavalibrariesintheclasspath,youcanaddthemtotheglobalDITA-OTclasspathwiththefollowingfeature.

dita.conductor.lib.import

AddJavalibrariestoDITA-OTclasspath.

Example

Thefollowingplug-inaddsthecompiledJavacodefrommyJavaLibrary.jarintotheglobalDITA-OTclasspath.XSLTorAntcodecanthenmakeuseoftheaddedcode.

<pluginid="com.example.addjar">

<featureextension="dita.conductor.lib.import"file="myJavaLibrary.jar"/>

</plugin>

NowassumethatinthiscasemyJavaLibrary.jarperformssomevalidationstepinthemiddleofprocessing,andyoualwayswantittorunimmediatelybeforetheconrefstep.Inthatcaseyouneedtomakeuseofseveralfeaturesinthisplug-in

TheJARfilemustbeaddedtotheclasspath.

AnAnttargetmustbecreatedthatusesthisclass,andtheAntwrapperintegratedintothecode.

TheAnttargetmustbeaddedtothedependencychainforconref.

Inthisextendedexample,thefilesmightlooksomethinglikethis.

plugin.xml:

<pluginid="com.example.samplejava">

<featureextension="dita.conductor.lib.import"file="com.example.sampleValidation.jar"/>

<featureextension="dita.conductor.target.relative"file="antWrapper.xml"/>

<featureextension="depend.preprocess.conref.pre"value="validateWithJava"/>

</plugin>

antWrapper.xmlimportsthenewAntcode:

<dummy>

<importfile="calljava-antcode.xml"/>

</dummy>

calljava-antcode.xml:

<projectdefault="validateWithJava">

<targetname="validateWithJava">

<javaclassname="com.example.sampleValidation">

<classpathrefid="dost.class.path"/>

</java>

</target>

</project>

AddingdiagnosticmessagesPlug-inspecificwarninganderrormessagescanbeaddedtothesetofmessagessuppliedbytheDITA-OT.ThesemessagescanthenbeusedbyanyXSLToverride.

dita.xsl.messages

Addnewmessagestodiagnosticmessagefile.

Example

Toaddyourownmessages,createthenewmessagesinanXMLfilesuchasmyMessages.xml:

<dummy>

<messageid="DOTXmy-msg-numW"type="WARN">

<reason>Messagetext</reason>

<response>Howtoresolve</response>

</message>

</dummy>

TherearethreecomponentstothemessageID:

1. TheprefixDOTXisusedbyallDITA-OTXSLTtransforms,andmustbepartoftheID.

2. Thisisfollowedbythemessagenumber("my-msg-num"inthesampleabove).Byconvention,thisshouldbeathreedigitinteger.

3. Finally,alettercorrespondstotheseverity.Thisshouldbeoneof:

I=Informational,usedwithtype="INFO"

W=Warning,usedwithtype="WARN"

E=Error,usedwithtype="ERROR"

F=Fatal,usedwithtype="FATAL"

Oncethemessagefileisdefined,itisincorporatedwiththisextension:

<pluginid="com.example.newmsg">

<featureextension="dita.xsl.messages"file="myMessages.xml"/>

</plugin>

XSLTmodulescanthengeneratethemessageusingthefollowingcall:

<xsl:call-templatename="output-message">

<xsl:with-paramname="msgnum">my-msg-num</xsl:with-param>

<xsl:with-paramname="msgsev">W</xsl:with-param>

</xsl:call-template>

Managingplug-independenciesThe<require>elementinaplugin.xmlfileisusedtocreateadependencyonanotherplug-in.The<require>elementrequiresthepluginattributeinordertoreferencethedependency.

Ifthecurrentplug-inrequiresaplug-inwithid="plugin-id"beforeitcanbeinstalled,itwouldincludethefollowing:

<requireplugin="plugin-id">

Prerequisiteplug-insareintegratedbeforethecurrentplug-inisintegrated.ThisdoestherightthingwithrespecttoXSLToverrides.Ifyourplug-inisaspecializationofaspecialization,itshould<require>itsbaseplug-ins,inorderfromgeneraltospecific.

Ifaprerequisiteplug-inismissing,awarningwillbeprintedduringintegration.Tosuppressthis,butkeeptheintegrationorderifbothplug-insarepresent,addimportance="optional"tothe<require>element.

Ifyourplug-incandependonanyoneofseveraloptionalplug-ins,separatetheplug-inidswithaverticalbar.Thisismostusefulwhencombinedwithimportance="optional":

Example

Thefollowingplug-inwillonlybeinstallediftheplug-inwithid="com.example.primary"isavailable.Ifthatoneisnotavailable,awarningwillbegeneratedduringtheintegrationprocess.

<pluginid="com.example.builds-on-primary">

<requireplugin="com.example.primary"/>

</plugin>

Thefollowingplug-inwillonlybeinstalledifeithertheplug-inwithid="pluginA"ortheplug-inwithid="pluginB"areavailable.Ifneitherofthoseareinstalled,thecurrentplug-inwillbeignored.

<pluginid="pluginC">

<requireplugin="pluginA|pluginB"importance="optional"/>

</plugin>

VersionandsupportinformationThefollowingextensionpointsareusedbyconventiontodefineversionandsupportinfowithinaplug-in.

package.support.name

package.support.email

package.version

Thetoolkitdoesnotcurrentlydoanythingwiththesevalues,butmaydosointhefuture.

Thepackage.versionvalueshouldfollowthesyntaxrules:

version::=major('.'minor('.'micro('.'qualifier)?)?)?

major::=number

minor::=number

micro::=number

qualifier::=([0..9]|[a..zA..Z]|’_’|'-')+

Thedefaultvalueis0.0.0.

Example<pluginid="com.example.WithSupportInfo">

<featureextension="package.support.name"value="JoetheAuthor"/>

<featureextension="package.support.email"value="joe@example.com"/>

<featureextension="package.version"value="1.2.3"/>

</plugin>

Creatinganewplug-inextensionpointIfyourplug-inneedstodefineitsownextensionpointinanXMLfile,addthestring"_template"tothefilenamebeforethefilesuffix.Duringintegration,thisfilewillbeprocessedlikethebuilt-inDITA-OTtemplates.

TemplatefilesareusedtointegratemostDITA-OTextensions.Forexample,thefiledita2xhtml_template.xslcontainsallofthedefaultrulesforconvertingDITAtopicstoXHTML,alongwithanintegrationpointforplug-inextensions.Whentheintegratorruns,thefiledita2xhtml.xslisrecreated,andtheintegrationpointisreplacedwithreferencestoallappropriateplug-ins.

Tomarkanewfileasatemplatefile,usethe<template>element.

ThetemplateextensionnamespacehastheURIhttp://dita-ot.sourceforge.net.Itisusedtoidentifyelementsandattributesthathaveaspecialmeaningintemplateprocessing.Thisdocumentationusesaprefixofdita:forreferringtoelementsinthetemplateextensionnamespace.However,templatefilesarefreetouseanyprefix,providedthatthereisanamespacedeclarationthatbindstheprefixtotheURIofthetemplateextensionnamespace.

dita:extensionelement

Thedita:extensionelementsareusedtoinsertgeneratedcontentduringintegrationprocess.Therearetworequiredattributes:

TheidattributedefinestheextensionpointIDwhichprovidestheargumentdata.

Thebehaviourattributedefineswhichprocessingactionisused.

Supportedvaluesforbehaviorattribute:

org.dita.dost.platform.CheckTranstypeAction

CreateAntconditionelementstocheckif${transtype}propertyvalueequalsasupportedtranstypevalue.

org.dita.dost.platform.ImportAntLibAction

CreateAntpathelementelementsforlibraryimportedextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.ImportPluginCatalogAction

Includeplug-inmetadatacatalogcontent.

org.dita.dost.platform.ImportPluginInfoAction

Createplug-inmetadataAntproperties.

org.dita.dost.platform.ImportStringsAction

Includeplug-instringfilecontentbaseongeneratedtextextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.ImportXSLAction

Createxsl:importelementsbasedonXSLTimportextension

point.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.InsertAction

Includeplug-inconductorcontentbasedonAntimportextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.InsertAntActionRelative

Includeplug-inconductorcontentbasedonrelativeAntimportextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.InsertCatalogActionRelative

Includeplug-incatalogcontentbasedoncatalogimportextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.ListTranstypeAction

Createapipedelimitedlistofsupportedtranstypes.

dita:extensionattribute

Thedita:extensionattributeisusedtoprocessattributesinelementswhicharenotintemplateextensionnamespace.Thevalueoftheattributeisaspacedelimitedtuple,wherethefirstitemisthenameoftheattributetoprocessandtheseconditemistheactionID.

Supportedvalues:

dependsorg.dita.dost.platform.InsertDependsAction

Anttargetdependencylistisprocessedtoreplacealltargetnameswhichstartwithanopencurlybracketandendwithaclosecurlybracket.ThevalueoftheextensionpointistheIDbetweenthecurlybrackets.

Example

Thefollowingplug-indefinesmyBuildFile_template.xmlasanewtemplateforextensions,andtwonewextensionpoints.

<pluginid="com.example.new-extensions">

<extension-pointid="com.example.new-extensions.pre"

name="Customtargetpreprocess"/>

<extension-pointid="com.example.new-extensions.content"

name="Customtargetcontent"/>

<templatefile="myBuildFile_template.xml"/>

</plugin>

Whentheintegratorruns,thiswillbeusedtorecreatemyBuildFile.xml,replacingAntfilecontentbasedonextensionpointuse.

<projectxmlns:dita="http://dita-ot.sourceforge.net">

<targetname="dita2custom"

depends="dita2custom.init,

{com.example.new-extensions.pre},

dita2xhtml"

dita:extension="dependsorg.dita.dost.platform.InsertDependsAction">

<dita:extensionid="com.example.new-extensions.content"

behaviour="org.dita.dost.platform.InsertAction"/>

</project>

Exampleplugin.xmlfileThefollowingisasampleofaplugin.xmlfile.ThisfileaddssupportforanewsetofspecializedDTDs,andincludesanoverridefortheXHTMLoutputprocessor.

Thisplugin.xmlfilewouldgointoadirectorysuchasDITA-OT\plugins\music\andreferencedsupportingfileswouldalsoexistinthatdirectory.Amoreextensivesampleusingthesevaluesisavailableintheactualmusicplug-in,availableattheDITA-OTdownloadpageatSourceForge

<pluginid="org.metadita.specialization.music">

<featureextension="dita.specialization.catalog.relative"file="catalog-dita.xml">

<featureextension="dita.xsl.xhtml"file="xsl/music2xhtml.xsl"/>

</plugin>

XHTMLmigrationforflaggingupdatesinDITA-OT1.7ThistopicisprimarilyofinteresttodeveloperswithXHTMLtransformoverrideswrittenpriortoDITA-OT1.7.Duetosignificantchangesintheflaggingprocesswiththe1.7release,somechangesmaybeneededtomakeoverridesworkproperlywithDITAVALbasedflagging.Thenewdesignissignificantlysimplerthantheolddesign;inmanycases,migrationwillconsistofdeletingoldcodethatisnolongerneeded.

WhichXHTMLoverridesneedtomigrate?

IfyouroverridedoesnotcontainanycoderelatedtoDITAVALflagging,thenthereisnothingtomigrate.

IfyourbuildsdonotmakeuseofDITAVALbasedflagging,butcallsthedeprecatedflaggingtemplates,thenyoushouldoverridebutthereislittleurgency.Youwillnotseeanydifferenceintheoutput,butthosetemplateswillberemovedinafuturerelease.

IfyoudomakeuseofDITAVALbasedflagging,tryusingyouroverridewith1.7.Checktheelementsyouoverride:

1. Insomecasesflagsmaybedoubled.Thiswillbethecaseifyoucallroutinessuchas"start-flagit".

2. Insomecasesflagsmayberemoved.Thiswillbethecaseifyoucallshortcutroutinessuchas"revtext"or"revblock".

3. Inothercases,flagsmaystillappearproperly,inwhichcasemigrationislessurgent

Foranymigrationthatneedsmigration,pleaseseetheinstructionsthatfollow.

DeprecatedtemplatesinDITA-OT1.7

AlloftheoldDITAVALbasedtemplatesaredeprecatedinDITA-OT1.7.Ifyouroverridesincludeanyofthefollowingtemplates,theyshouldbemigratedforthenewrelease;inmanycasesthetemplatesbelowwillnothaveanyeffectonyouroutput,butallinstancesshouldbemigrated.

The"gen-style"templateusedtoaddCSSstyling

The"start-flagit"and"end-flagit"templatesusedtogenerateimageflagsbasedonpropertyattributeslike@audience

The"start-revflag"and"end-revflag"templates,usedtogenerateimagesforactiverevisions

Shortcuttemplatesthatgroupthesetemplatesintoasinglecall,suchas:

"start-flags-and-rev"and"end-flags-and-rev",usedtocombineflagsandrevisionsintoonecall

"revblock"and"revtext",bothusedtooutputstartrevisions,elementcontent,andendrevisions

Themodes"outputContentsWithFlags"and"outputContentsWithFlagsAndStyle",bothusedtocombineprocessingforproperty/revisionflagswithcontentprocessing

Allothertemplatesthatmakeuseofthe$flagrulesvariable,whichisnolongerusedinanyoftheDITA-OT1.7code

Alltemplateswithinflag.xslthatwerecalledfromthetemplateslistedabove

Elementprocessinghandledwithmode="elementname-fmt",suchasmode="ul-fmt"forprocessingunorderedlistsandmode="section-fmt"forsections.

Whatreplacesthetemplates?

ThenewflaggingdesigndescribedinthepreprocessdesignsectionnowaddsliteralcopiesofrelevantDITAVALelements,alongwithCSSbasedflagginginformation,intotherelevantsectionofthetopic.Thisallowsmostflagstobeprocessedindocumentorder;inaddition,thereisneveraneedtoreadtheDITAVAL,interpretCSS,orevaluateflagginglogic.Thehtmlflag.xslfilecontainsafewrulestomatchandprocessthestart/endflags;inmostcases,allcodetoexplicitlyprocessflagscanbedeleted.

Forexample,thecommonlogicformostelementrulesbeforeDITA-OT1.7couldbeboileddowntothefollowing:

MatchelementCreate"flagrules"variablebyreadingDITAVALforactiveflagsOutputstarttagsuchas<div>or<span>Call"commonattributes"andIDprocessingCall"gen-style"with$flagrules,tocreateDITAVALbasedCSSCall"start-flagit"with$flagrules,tocreatestartflagimagesCall"start-revflag"with$flagrules,tocreatestartrevisionimagesOutputcontentsCall"end-revflag"with$flagrules,tocreateendrevisionimagesCall"end-flagit"with$flagrules,tocreateendflagimagesOutputendtagsuchas</div>or</span>

InDITA-OT1.7,styleandimagesaretypicallyhandledwithXSLTfallthroughprocessing.Thisremovesvirtuallyallspecialflagcodingfromelementrules,becauseflagsarealreadypartofthedocumentandprocessedindocumentorder.Thesampleaboveisreducedto:

MatchelementOutputstarttagsuchas<div>or<span>Call"commonattributes"andIDprocessingOutputcontents

Outputendtagsuchas</div>or</span>

Migrating"gen-style"namedtemplate

Callstothe"gen-style"templateshouldbedeleted.Thereisnoneedtoreplacethiscallformostelements.

The"gen-style"templatewasdesignedtoreadaDITAVALfile,findactivestyle-basedflagging(suchascoloredorboldtext),andaddittothegenerated@styleattributeinHTML.

WithDITA-OT1.7,thestyleiscalculatedinthepre-processflaggingmodule.Theresultiscreatedas@outputclassona<ditaval-startprop>sub-element.The"commonattributes"templatenowincludesalinetoprocessthatvalue;theresultisthatforeveryelementthatcalls"commonattributes",DITAVALstylewillbeprocessedwhenneeded.Becausevirtuallyeveryelementincludesacalltothiscommontemplate,thereislittlechancethatyouroverrideneedstoexplicitlyprocessthestyle.Thenewlinein"commonattributes"thathandlesthestyleis:

<xsl:apply-templatesselect="*[contains(@class,'ditaot-d/ditaval-startprop')]/@outputclass"mode="add-ditaval-style"/>

Migrating"start-flagit","start-revflag","end-flagit",and"end-flagit"namedtemplates

Callstothesetemplatesfallintotwogeneralgroups.

Iftheflowofyourelementruleistocreateastarttaglike<div>,"start-flagit"/"start-revflag",processcontents,"end-revflag"/"end-flagit",endtag-youjustneedtodeletethecallstothesetemplates.Flagswillbegeneratedsimplybyprocessingtheelementcontentsindocumentorder.

Iftheflowofyourelementruleprocessesflagsoutsideofthenormaldocument-order.Therearegenerallytworeasonsthisisdone.Thefirstcaseisforelementslike<ol>,whereflagsmustappearbeforethe<ol>inordertocreatevalidXHTML.Thesecondisforelementslike<section>,wherestartflagsarecreated,followedbythetitleorsomegeneratedtext,elementcontents,andfinallyendflags.Ineitherofthesecases,supportforprocessingflagsindocumentorderisdisabled,sotheymustbeexplicitlyprocessedout-of-line.Thisisdonewiththefollowingtwolines(oneforstartflag/revision,oneforendflag/revision):

Createstartingflagandrevisionimages:

<xsl:apply-templatesselect="*[contains(@class,'ditaot-d/ditaval-startprop')]"mode="out-of-line"/>

Createendingflagandrevisionimages:

<xsl:apply-templatesselect="*[contains(@class,'ditaot-d/ditaval-endprop')]"mode="out-of-line"/>

Forexample,thefollowinglinesareusedinDITA-OT1.7toprocessthe<ul>element(replacingthe29linesusedinDITA-OT1.6):

<xsl:templatematch="*[contains(@class,'topic/ul')]">

<xsl:apply-templatesselect="*[contains(@class,'ditaot-d/ditaval-startprop')]"mode="out-of-line"/>

<xsl:call-templatename="setaname"/>

<xsl:call-templatename="commonattributes"/>

<xsl:apply-templatesselect="@compact"/>

<xsl:call-templatename="setid"/>

<xsl:apply-templates/>

<xsl:apply-templatesselect="*[contains(@class,'ditaot-d/ditaval-endprop')]"mode="out-of-line"/>

<xsl:value-ofselect="$newline"/>

</xsl:template>

Migrating"start-flags-and-rev"and"end-flags-and-rev"

"start-flags-and-rev"isequivalenttocalling"start-flagit"followedby"start-revflag";itshouldbemigratedasintheprevioussection.

"end-flags-and-rev"isequivalenttocalling"end-revflag"followedby"end-flagit";itshouldbemigratedasintheprevioussection.

Migrating"revblock"and"revtext"

Callstothesetwotemplatescanbereplacedwithasimplecallto<xsl:apply-templates/>.

Migratingmodes"outputContentsWithFlags"and"outputContentsWithFlagsAndStyle"

Processinganelementwitheitherofthesemodescanbereplacedwithasimplecallto<xsl:apply-templates/>.

Migratingmode="elementname-fmt"

PriortoDITA-OT1.7,manyelementswereprocessedwiththefollowinglogic:

Matchelement

Setvariabletodetermineifrevisionsareactiveand$DRAFTison

Ifactive

createdivisionwithrevstyle

processelementwithmode="elementname-fmt"

enddivision

processelementwithmode="elementname-fmt"

Matchelementwithmode="elementname-fmt"

Processasneeded

BeginningwithDITA-OT1.7,stylingfromrevisionsishandledautomaticallywiththe"commonattributes"template.Thismeansthereisnoneedfortheextratesting,ortheindirectiontomode="elementname-fmt".Thesetemplatesaredeprecated,andelementprocessingwillmoveintothemainelementrule.Overridesthatincludethisindirectionmayremoveit;overridesshouldalsobesuretomatchthedefaultrule,ratherthanmatchingwithmode="elementname-fmt".

CustomizingPDFoutputYoucanbuildaDITA-OTplug-inthatcontainsacustomizedPDFtransformation.

Aboutthistask

Thistopicdemonstratestheprocessofbuildingaplug-in(com.example.print-pdf)thatcreatesanewtransformationtype:print-pdf.Theprint-pdftransformationhasthefollowingcharacteristics:

UsesA4paper

Rendersfigureswithatitleatthetopandadescriptionatthebottom

Useemdashesasthesymbolsforunorderedlists

Procedure

1. Inthepluginsdirectory,createadirectorynamedcom.example.print-pdf.

2. Inthenewcom.example.print-pdfdirectory,createaplug-inconfigurationfile(plugin.xml)thatdeclaresthenewprint-pdftransformationanditsdependencies.Figure1.plugin.xmlfile

<?xmlversion='1.0'encoding='UTF-8'?>

<pluginid="com.example.print-pdf">

<requireplugin="org.dita.pdf2"/>

<featureextension="dita.conductor.transtype.check"value="print-pdf"/>

<featureextension="dita.transtype.print"value="print-pdf"/>

<featureextension="dita.conductor.target.relative"file="integrator.xml"/>

</plugin>

3. AddanAntscript(integrator.xml)todefinethetransformationtype.Figure2.integrator.xmlfile

<?xmlversion='1.0'encoding='UTF-8'?>

<projectname="com.example.print-pdf">

<targetname="dita2print-pdf.init">

<propertyname="customization.dir"location="${dita.plugin.com.example.print-pdf.dir}/cfg"/>

</target>

<targetname="dita2print-pdf"depends="dita2print-pdf.init,dita2pdf2"/>

</project>

4. Inthenewplug-indirectory,addacfg/catalog.xmlfilethatspecifiesthecustomXSLTstylesheets.Figure3.cfg/catalog.xmlfile

<catalogprefer="system"xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

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

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

</catalog>

5. Createthecfg/fo/attrs/custom.xslfile,andaddattributeandvariableoverridestoit.Forexample,addthecontenthighlightedwithboldtochangethepagesizetoA4.Figure4.cfg/fo/attrs/custom.xslfile

<xsl:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform"

version="2.0">

<xsl:variablename="page-width">210mm</xsl:variable>

<xsl:variablename="page-height">297mm</xsl:variable>

</xsl:stylesheet>

6. Createthecfg/fo/xsl/custom.xslfile,andaddXSLToverridestoit.Forexample,thefollowingcodechangestherenderingof<figure>elements.Figure5.cfg/fo/xsl/custom.xslfile

<xsl:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:fo="http://www.w3.org/1999/XSL/Format"

version="2.0">

<xsl:templatematch="*[contains(@class,'topic/fig')]">

<fo:blockxsl:use-attribute-sets="fig">

<xsl:call-templatename="commonattributes"/>

<xsl:iftest="not(@id)">

<xsl:attributename="id">

<xsl:call-templatename="get-id"/>

</xsl:attribute>

</xsl:if>

<xsl:apply-templatesselect="*[contains(@class,'topic/title')]"/>

<xsl:apply-templatesselect="*[not(contains(@class,'topic/title')orcontains(@class,'topic/desc'))]"/>

<xsl:apply-templatesselect="*[contains(@class,'topic/desc')]"/>

</fo:block>

</xsl:template>

</xsl:stylesheet>

7. CreateanEnglish-languagevariable-definitionfile(cfg/common/vars/en.xml)andmakeanynecessarymodificationstoit.Forexample,thefollowingcoderemovestheperiodafterthenumberforanordered-listitem;italsospecifiesthatthebulletforanunorderedlistitemshouldbeanemdash.Figure6.cfg/common/vars/en.xmlfile

<varsxmlns="http://www.idiominc.com/opentopic/vars">

<variableid="OrderedListNumber"><paramref-name="number"/></variable>

<variableid="UnorderedListbullet">—</variable>

</vars>

Results

Thenewplug-indirectoryhasthefollowinglayoutandfiles:

com.example.print-pdf/

common/

en.xml

attrs/

custom.xsl

catalog.xml

integrator.xml

plugin.xml

Whattodonext

Runtheintegrationprocesstoinstalltheplug-inandmaketheprint-pdftransformationavailable.

InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.

include.rellinks

Spaceseparatedlistoflinkrolestobeoutput;valuetoken#defaultdenotesdefaultrolevalue.Propertydefaultvaluedependsontransformationtype.Definedbyargs.rellinks,butmaybeoverriddendirectly.

Implementationdependentfeatures

Chunking

Supportedchunkingmethods:

select-topic

select-document

select-branch

by-topic

by-document

to-content

to-navigation.

Whennochunkattributevaluesaregiven,nochunkingisperformed.

Note:Ineffect,forHTMLbasedtransformationtypesthisisequivalenttoselect-documentandby-documentdefaults.

Errorrecovery:

Whentwotokensfromthesamecategoryareused,noerrororwarningisthrown.

Whenanunrecognizedchunkingmethodisused,noerrororwarningisthrown.

Filtering

Errorrecovery:

Whentherearemultiplerevpropelementswiththesamevalattribute,noerrororwarningisthrown

Whenmultiplepropelementsdefineaduplicateattributeandvaluecombination,attributedefault,orfall-backbehaviour,DOTJ007Eerroristhrown.

Debugattributes

Thedebugattributesarepopulatedasfollows:

absolutesystempathofthesourcedocument

elementcounterthatusestheformat

element-name":"integer-counter";"line-number":"column-number

Imagescaling

Ifbothheightandwidthattributesaregiven,imageisscalednon-uniformly.

Ifscaleattributeisnotanunsignedinteger,noerrororwarningisthrownduringpreprocessing.

Mapprocessing

Whenatopicrefelementthatreferencesamapcontainschildtopicrefelements,DOTX068Werroristhrownandthechildtopicrefelementsareignored.

Linkprocessing

WhenthevalueofhrefattributeisnotavalidURIreference,DOTJ054Eerroristhrown.Dependingonerrorrecovermode,errorrecovermaybeattempted.

Copy-toprocessing

Whenthecopy-toattributeisspecifiedonatopicref,thecontentoftheshortdescelementisnotusedtooverridetheshortdescriptionofthetopic.

ExtendedfunctionalityParenttopic:DITAOpenToolkitDeveloperReference

Codereferenceprocessing

Charsetdefinition

DITA-OTsupportsdefiningthecodereferencetargetfileencodingusingtheformatattribute.Thesupportedformatis:

format(";"space*"charset="charset)?

Ifcharsetisnotdefinedsystemdefaultcharsetwillbeused.Ifcharsetisnotrecognizedorsupported,DOTJ052Eerroristhrownandsystemdefaultcharsetisusedasafall-back.

<coderefhref="unicode.txt"format="txt;charset=UTF-8"/>

Linerangeextraction

Codereferencecanextractonlyagivenlinerangeswithline-rangepointerintheURIfragment.Theformatis:

uri("#line-range("start(","end)?")")?

Startandendlinenumbersstartfrom1andareinclusive.Ifendrangeisomitted,rangeendsinlastlineofthefile.

<coderefhref="Parser.scala#line-range(5,10)"format="scala"/>

Onlylinesfrom5to10willbeincludedintheoutput.

RFC5147

DITA-OTimplementslinepositionandrangefromRFC5147.Theformatforlinerangeis:

uri("#line="start?","end?)?

Startandendlinenumbersstartfrom0andareinclusiveandexclusive,respectively.Ifthestartrangeisomitted,rangestartsfromthefirstline;ifendrangeisomitted,rangeendsinlastlineofthefile.Theformatforline

positionis:

uri("#line="position)?

Positionlinenumberstartsfrom0.

<coderefhref="Parser.scala#line=4,10"format="scala"/>

Onlylinesfrom5to10willbeincludedintheoutput.

DITAandDITA-OTresourcesInadditiontotheDITA-OTdocumentation,thereareotherresourcesaboutDITAandtheDITA-OTthatyoumightfindhelpful.

DITA-OTprojectpageatdita.xml.orgTheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.

Yahoo!dita-usersgroupThislist-servisavitalresourcefortheDITAcommunity.Peoplepostregularly,bothaskingforandofferinghelp.Whilethearchivedmessagescanbedifficulttosearch,thisisatreasuretroveofinformation.

HomepagefortheOASISDITATechnicalCommitteeTheOASISDITATechnicalCommitteedevelopstheDITAstandard.

Web-basedresourcesTherearemanyvitalDITAresourcesonline,includingtheYahoo!dita-usersgroupandtheDITA-OTprojectpageatdita.xml.org.

developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.

Web-basedresourcesTherearemanyvitalDITAresourcesonline,includingtheYahoo!dita-usersgroupandtheDITA-OTprojectpageatdita.xml.org.

DITA-OTprojectpageatdita.xml.org

TheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.

Yahoo!dita-usersgroup

TheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.

HomepagefortheOASISDITATechnicalCommittee

TheOASISDITATechnicalCommitteedevelopstheDITAstandard.

Parenttopic:DITAandDITA-OTresources

developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.

IntroductiontotheDarwinInformationTypingArchitecture

SpecializingtopictypesinDITA

SpecializingdomainsinDITA

FrequentlyAskedQuestionsabouttheDarwinInformationTypingArchitecture

WhyuseDITAtoproduceHTMLdeliverables?

DesignpatternsforinformationarchitecturewithDITAmapdomains

MigratingHTMLtoDITA,Part1:SimplestepstomovefromHTMLtoDITA

MigratingHTMLtoDITA,Part2:Extendthemigrationformorerobustresults

TransformEclipsenavigationfilestoDITAnavigationfiles

Parenttopic:DITAandDITA-OTresources

generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.

Background

Thisisanissueinthefollowingsituations:

TheDITAmapisinadirectorythatisapeertodirectoriesthatcontainreferencedobjects.

TheDITAmapisinadirectorythatisbelowthedirectoriesthatcontainthereferencedobjects.

Let'sassumethatthedirectorystructurefortheDITAcontentlookslikethefollowing:

topics

images

TheDITAmapisinthemapsdirectory,thetopicsareinthetopicsdirectory,andtheimagesareintheimagesdirectory.

Settingthegenerate.outer.copyparameterto1

Let'sassumethatyouruntheHTML5transformationandspecifyanoutputdirectoryofC:\A-test.Bydefault,TheDITA-OTusesthegenerate.outer.copyparameterwithavalueof1.Outputisnotbuiltforthetopics.Youreceiveonlythefollowingoutput:

C:\A-test

---index.html

---commonltr.css

---commonrtl.css

Theindex.htmlfilecontainsthenavigationstructure,butallthelinksarebroken,sincenoHTML5fileswerebuiltforthetopics.

Howdoyoufixthis?Byspecifyingavalueof3forthegenerate.outer.copyparameter.

Settingthegenerate.outer.copyparameterto3

Nowyouroutputdirectorystructurelookslikethis:

C:\A-test

---images\

---maps\

---topics\

Theindex.htmlfileisinthemapsdirectory,andtheCSSandotherfilesarelocatedintheoutputdirectory,C:\A-test.Copyingtheoutputdirectoryissimplified.

Parenttopic:Antparameters:CommonHTML-basedtransformations

DITA Open Toolkit 2 - documentation.help · The DITA Open Toolkit (DITA-OT) is an open-source...

Documents

Transcript of DITA Open Toolkit 2 - documentation.help · The DITA Open Toolkit (DITA-OT) is an open-source...

The Adoption and Evolution of the OASIS DITA Standard

DITA Feature Article: Short Descriptions Shouldn't Be a ... · PDF fileAn OASIS DITA Adoption Technical Committee Publication DITA Feature Article: Short Descriptions Shouldn't Be

PDFs from the DITA Open Toolkit - Oxygen XML Editor · PDFs from the DITA Open Toolkit The Easy and the Not So Easy Leigh White DITA Specialist leigh.white@Ixiasoft.com Presented

Implementing an Information Architecture using OASIS DITAxml.coverpages.org/NokiaDITA-ISTC2004.pdf · OASIS DITA A Nokia Case Study Indi Liepa, Senior Information Architect, Nokia

DITA-to-PDF (Dita2pdf): there is more than the DITA Open Toolkit

DITA Open Toolkit Deployment with XMetaL Author Enterprise 6

OASIS Darwin Information Typing Architecture (DITA ...

OASIS Darwin Information Typing Architecture (DITA ...docs.oasis-open.org/dita/v1.0/dita-v1.0-spec-os-Architectural... · • The language reference that provides explanations for

OASIS DITA Language Specification Commitee Draft 01xml.coverpages.org/DITA-CD11428-LangSpec.pdf · 2005-02-15 · Chapter 1. DITA elements alt The alt element provides an element

OASIS Open Standards Day Singapore

DITA Specification draft - OASIS Open · elements from domains. The term ″document type″ is used for compatibility with existing standards, since this is the point at which DITA’s

31-07-2012 – TC OASIS DITA Presentation to Dita TC R&D work of convergence between S1000D and Dita Jean-Jacques Thomasson representing the French Group.

DITA Open Toolkit 1.8 - documentation.helpThe DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA Technical

OASIS DITA Pharma · DITA Pharma SC Welcome The OASIS DITA Pharmaceutical Content Subcommittee (DITA Pharma SC) will define DITA topics, maps, associated metadata properties and terminology

OASIS CGM Open WebCGM V2.0 - OASIS Open Library

OASIS DITA BusDocs Subcommittee€¦ · Web viewBackground Members of the DITA for Enterprise Business Documents (BusDocs) subcommittee have conducted a range of activities over the

Www.oasis-open.org Learn about the new features of DITA 1.3 Presented by: The OASIS DITA Technical Committee and The OASIS DITA Adoption Technical Committee.

OASIS Open Document Essentials

FrameMaker and the DITA Open Toolkit

Open by Design - OASIS