DITA Open Toolkit 2 - documentation.help · The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS DITA specification, which is developed by the OASIS DITA

DITAOpenToolkit2.0ThisdocumentdescribestheDITAOpenToolkitproject—whattheprojectis,andhowtousethesite.

WhatistheDITAOpenToolkit?

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

Note:WhiletheDITAStandarditselfisownedanddevelopedbyOASIS,theDITAOpenToolkitisanindependent,opensourceimplementationofthestandard.

Keyoutputformatsforthetoolkitinclude:

XHTML

PDF(formerlyknownasPDF2)

ODT(OpenDocumentFormat)

EclipseHelp

TocJS(XHTMLwithaJavaScriptframeset)

HTMLHelp

JavaHelp

EclipseContent(normalizedDITAplusEclipseprojectfiles)

WordRTF(withsomelimitations)

Docbook

Troff

http://www.opensource.org/licenses/cpl1.0.php

http://www.apache.org/licenses/LICENSE-2.0

Toolkitdocumentation

Therearetwoprimarysourcesfordocumentationaboutthetoolkit.

Stabledocumentationabouttoolkitusage,parameters,andprojectmanagementcanbefoundonthispage,usingthenavigationpanelontheleft.

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

RelatedconceptsDistributionpackages

RelatedinformationMainDITA-OTpageatdita.xml.orgProjectNewsforDITAOpenToolkit

ShortcutstoimportantinformationDITA-OTstablereleaseDITA-OTlatestdevelopmentbuild

http://dita.xml.org/wiki/the-dita-open-toolkit

http://sourceforge.net/news/?group_id=132728

http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release/

http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Latest%20Test%20Build/

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

http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release/DITA%20Open%20Toolkit%201.8/

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

http://opensource.org/licenses/cpl1.0.php

http://www.apache.org/licenses/LICENSE-2.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)

https://github.com/dita-ot/dita-ot/issues

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

Bugs

#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

http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html

http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.pdf

http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.zip

http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec-chm.zip

http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita-adoption

http://dita.xml.org/wiki/dita-12-specification-building-specification-subsets

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

JDK

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

https://sourceforge.net/projects/dita-ot/files

https://github.com/dita-ot/dita-ot

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/.

http://www.oracle.com/technetwork/java/javase/downloads/index.html

http://ant.apache.org/

http://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.


http://www.icu-project.org/download/

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

http://xmlgraphics.apache.org/fop/download.html

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

FOP

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

ODT

JavaHelp

PDF

TocJS

TROFF

XHTML


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

FOP

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

ODT

JavaHelp

PDF

TocJS

TROFF

XHTML


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

http://eclipse.org

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.


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

http://ant.apache.org/manual/index.html

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

http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/translation.html

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

https://github.com/dita-ot/dita-ot/issues

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

http://docs.oasis-open.org/dita/v1.2/os/spec/common/theconactionattribute.html


http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/uri-based-addressing.html


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".

http://docs.oasis-open.org/dita/v1.2/os/spec/common/theconkeyrefattribute.html

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

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicref.html

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.

Ant

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

html5

htmlhelp

javahelp

odt

pdf

wordrtf

troff

xhtml

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.

Usage

dita-fname-ifile[options]

dita-install{file|url}

dita-uninstallid

dita-help

dita-version

Arguments

-f,-formatname


docbook

eclipsehelp

eclipsecontent

html5

htmlhelp

javahelp

odt

pdf

wordrtf

troff

xhtml

-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.

debug

Specifieswhetherdebugginginformationisincludedinthelog.Theallowedvaluesareyesandno;thedefaultvalueisno.

ditadir

SpecifieswheretheDITA-OTisinstalled.

ditalocale

Specifiesthelanguagelocalefiletouseforsortingindexentries.

Note:ThisparameterisnotavailablefortheXHTMLtransformation.

draft

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.

i


logdir

SpecifiesthelocationwheretheDITA-OTplaceslogfilesforyourproject.

outdir

Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.

tempdir


transtype


docbook

eclipsehelp

eclipsecontent

html5

htmlhelp

javahelp

odt

pdf

wordrtf

troff

xhtml

validate

SpecifieswhethertheDITA-OTvalidatesthecontent.Theallowedvaluesaretrueandfalse;thedefaultvalueistrue.

Parenttopic:Command-linetoolparameters

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

Note:Youmustspecifyanabsolutepathasthevalueforthefollowingparameters:

ftr

hdr

hdf

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.

ftr

SpecifiesanXMLfilethatcontainscontentforarunningfooter.CorrespondstoXSLTparameterFTR.


generateouter

SpecifieswhethertogenerateoutputfilesforcontentthatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:

1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory.

3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.

Seegenerate.outer.copyparameterformoreinformation.

hdf

SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.

hdr

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.

xsl

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.

https://tools.ietf.org/html/bcp47

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">

<title>...</title>

<body>

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

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

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

<codeblock>....</codeblock>

</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>

<codeblock>....</codeblock>

</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

http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/chunking.html

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.


<val>



<style-conflictbackground-conflict-color="red"/>



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

</p>

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;">

<style-conflictbackground-conflict-color="red"/>




Conflictingstyles(stillnoimages)




</ditaval-endprop>

</p>

Contentexample3:addingimageflags

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

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

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

</ol>

Asabove,the<ditaval-startprop>and<ditaval-endprop>nesttheactivepropertydefinitions,[email protected]<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>

</ol>

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.


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

<meta>definesmetadata.Thefollowingattributesaresupported:

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:

<dummy><importfile="myAntStuff.xml"/></dummy>

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:



<langlist>

<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:



<langlist>

<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

Note:

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="[email protected]"/>

<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"/>

<target>

</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>


http://sourceforge.net/projects/dita-ot/files/

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"/>

<ul>

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

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

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

<xsl:apply-templates/>

</ul>

<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

Else

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/

cfg/

common/

vars/

en.xml

fo/

attrs/

custom.xsl

xsl/

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:

xtrf

absolutesystempathofthesourcedocument

xtrc

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

http://tools.ietf.org/html/rfc5147

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.


http://groups.yahoo.com/group/dita-users/

http://www.oasis-open.org/committees/dita/

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


http://groups.yahoo.com/group/dita-users/

http://www.oasis-open.org/committees/dita/

developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.

IntroductiontotheDarwinInformationTypingArchitecture

SpecializingtopictypesinDITA

SpecializingdomainsinDITA

FrequentlyAskedQuestionsabouttheDarwinInformationTypingArchitecture

WhyuseDITAtoproduceHTMLdeliverables?

DesignpatternsforinformationarchitecturewithDITAmapdomains

MigratingHTMLtoDITA,Part1:SimplestepstomovefromHTMLtoDITA

MigratingHTMLtoDITA,Part2:Extendthemigrationformorerobustresults

TransformEclipsenavigationfilestoDITAnavigationfiles

Parenttopic:DITAandDITA-OTresources

http://www-128.ibm.com/developerworks/xml/library/x-dita1/

http://www-128.ibm.com/developerworks/xml/library/x-dita2/index.html





http://www-128.ibm.com/developerworks/xml/library/x-dita8a/

http://www-128.ibm.com/developerworks/xml/library/x-dita8b/

http://www-128.ibm.com/developerworks/xml/library/x-ecldita/

generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.

Background

Thisisanissueinthefollowingsituations:

TheDITAmapisinadirectorythatisapeertodirectoriesthatcontainreferencedobjects.

TheDITAmapisinadirectorythatisbelowthedirectoriesthatcontainthereferencedobjects.

Let'sassumethatthedirectorystructurefortheDITAcontentlookslikethefollowing:

maps

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 implementation of the OASIS DITA specification, which is developed by the OASIS DITA

Documents